FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

doc: improve Sign/Verify examples and docs · nodejs/node@7123167 · GitHub

/ node Public

Commit 7123167

Browse files
sam-github
authored and
addaleax
committed
doc: improve Sign/Verify examples and docs
- Use complete examples that can be pasted and run as-is - Move note about algorithm to the functions it applies to - Uncapitalize inconsistence use of "Class" - Use both EC and RSA keys in the examples - Note that hash and digest are two names for the same algorithms PR-URL: #25452 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Tobias Nießen <tniessen@tnie.de> Reviewed-By: James M Snell <jasnell@gmail.com>
1 parent 3afb481 commit 7123167

1 file changed

Lines changed: 45 additions & 64 deletions

File tree

‎doc/api/crypto.md‎

Lines changed: 45 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -1018,7 +1018,7 @@ This can be called many times with new data as it is streamed.
10181018
added: v0.1.94
10191019
-->
10201020

1021-
The `Hmac` Class is a utility for creating cryptographic HMAC digests. It can
1021+
The `Hmac` class is a utility for creating cryptographic HMAC digests. It can
10221022
be used in one of two ways:
10231023

10241024
- As a [stream][] that is both readable and writable, where data is written
@@ -1196,7 +1196,7 @@ or `'private'` for private (asymmetric) keys.
11961196
added: v0.1.92
11971197
-->
11981198

1199-
The `Sign` Class is a utility for generating signatures. It can be used in one
1199+
The `Sign` class is a utility for generating signatures. It can be used in one
12001200
of two ways:
12011201

12021202
- As a writable [stream][], where data to be signed is written and the
@@ -1208,51 +1208,46 @@ The [`crypto.createSign()`][] method is used to create `Sign` instances. The
12081208
argument is the string name of the hash function to use. `Sign` objects are not
12091209
to be created directly using the `new` keyword.
12101210

1211-
Example: Using `Sign` objects as streams:
1211+
Example: Using `Sign` and [`Verify`][] objects as streams:
12121212

12131213
```js
12141214
const crypto = require('crypto');
1215-
const sign = crypto.createSign('SHA256');
12161215

1216+
const { privateKey, publicKey } = crypto.generateKeyPairSync('ec', {
1217+
namedCurve: 'sect239k1'
1218+
});
1219+
1220+
const sign = crypto.createSign('SHA256');
12171221
sign.write('some data to sign');
12181222
sign.end();
1223+
const signature = sign.sign(privateKey, 'hex');
12191224

1220-
const privateKey = getPrivateKeySomehow();
1221-
console.log(sign.sign(privateKey, 'hex'));
1222-
// Prints: the calculated signature using the specified private key and
1223-
// SHA-256. For RSA keys, the algorithm is RSASSA-PKCS1-v1_5 (see padding
1224-
// parameter below for RSASSA-PSS). For EC keys, the algorithm is ECDSA.
1225+
const verify = crypto.createVerify('SHA256');
1226+
verify.write('some data to sign');
1227+
verify.end();
1228+
console.log(verify.verify(publicKey, signature));
1229+
// Prints: true or false
12251230
```
12261231

1227-
Example: Using the [`sign.update()`][] and [`sign.sign()`][] methods:
1232+
Example: Using the [`sign.update()`][] and [`verify.update()`][] methods:
12281233

12291234
```js
12301235
const crypto = require('crypto');
1231-
const sign = crypto.createSign('SHA256');
1232-
1233-
sign.update('some data to sign');
1234-
1235-
const privateKey = getPrivateKeySomehow();
1236-
console.log(sign.sign(privateKey, 'hex'));
1237-
// Prints: the calculated signature
1238-
```
1239-
1240-
In some cases, a `Sign` instance can also be created by passing in a signature
1241-
algorithm name, such as 'RSA-SHA256'. This will use the corresponding digest
1242-
algorithm. This does not work for all signature algorithms, such as
1243-
'ecdsa-with-SHA256'. Use digest names instead.
12441236

1245-
Example: signing using legacy signature algorithm name
1246-
1247-
```js
1248-
const crypto = require('crypto');
1249-
const sign = crypto.createSign('RSA-SHA256');
1237+
const { privateKey, publicKey } = crypto.generateKeyPairSync('rsa', {
1238+
modulusLength: 2048,
1239+
});
12501240

1241+
const sign = crypto.createSign('SHA256');
12511242
sign.update('some data to sign');
1243+
sign.end();
1244+
const signature = sign.sign(privateKey);
12521245

1253-
const privateKey = getPrivateKeySomehow();
1254-
console.log(sign.sign(privateKey, 'hex'));
1255-
// Prints: the calculated signature
1246+
const verify = crypto.createVerify('SHA256');
1247+
verify.update('some data to sign');
1248+
verify.end();
1249+
console.log(verify.verify(publicKey, signature));
1250+
// Prints: true
12561251
```
12571252

12581253
### sign.sign(privateKey[, outputEncoding])
@@ -1332,34 +1327,7 @@ of two ways:
13321327
The [`crypto.createVerify()`][] method is used to create `Verify` instances.
13331328
`Verify` objects are not to be created directly using the `new` keyword.
13341329

1335-
Example: Using `Verify` objects as streams:
1336-
1337-
```js
1338-
const crypto = require('crypto');
1339-
const verify = crypto.createVerify('SHA256');
1340-
1341-
verify.write('some data to sign');
1342-
verify.end();
1343-
1344-
const publicKey = getPublicKeySomehow();
1345-
const signature = getSignatureToVerify();
1346-
console.log(verify.verify(publicKey, signature));
1347-
// Prints: true or false
1348-
```
1349-
1350-
Example: Using the [`verify.update()`][] and [`verify.verify()`][] methods:
1351-
1352-
```js
1353-
const crypto = require('crypto');
1354-
const verify = crypto.createVerify('SHA256');
1355-
1356-
verify.update('some data to sign');
1357-
1358-
const publicKey = getPublicKeySomehow();
1359-
const signature = getSignatureToVerify();
1360-
console.log(verify.verify(publicKey, signature));
1361-
// Prints: true or false
1362-
```
1330+
See [`Sign`][] for examples.
13631331

13641332
### verify.update(data[, inputEncoding])
13651333
<!-- YAML
@@ -1886,10 +1854,15 @@ added: v0.1.92
18861854
* `options` {Object} [`stream.Writable` options][]
18871855
* Returns: {Sign}
18881856

1889-
Creates and returns a `Sign` object that uses the given `algorithm`.
1890-
Use [`crypto.getHashes()`][] to obtain an array of names of the available
1891-
signing algorithms. Optional `options` argument controls the
1892-
`stream.Writable` behavior.
1857+
Creates and returns a `Sign` object that uses the given `algorithm`. Use
1858+
[`crypto.getHashes()`][] to obtain the names of the available digest algorithms.
1859+
Optional `options` argument controls the `stream.Writable` behavior.
1860+
1861+
In some cases, a `Sign` instance can be created using the name of a signature
1862+
algorithm, such as `'RSA-SHA256'`, instead of a digest algorithm. This will use
1863+
the corresponding digest algorithm. This does not work for all signature
1864+
algorithms, such as `'ecdsa-with-SHA256'`, so it is best to always use digest
1865+
algorithm names.
18931866

18941867
### crypto.createVerify(algorithm[, options])
18951868
<!-- YAML
@@ -1904,6 +1877,12 @@ Use [`crypto.getHashes()`][] to obtain an array of names of the available
19041877
signing algorithms. Optional `options` argument controls the
19051878
`stream.Writable` behavior.
19061879

1880+
In some cases, a `Verify` instance can be created using the name of a signature
1881+
algorithm, such as `'RSA-SHA256'`, instead of a digest algorithm. This will use
1882+
the corresponding digest algorithm. This does not work for all signature
1883+
algorithms, such as `'ecdsa-with-SHA256'`, so it is best to always use digest
1884+
algorithm names.
1885+
19071886
### crypto.generateKeyPair(type, options, callback)
19081887
<!-- YAML
19091888
added: v10.12.0
@@ -2084,7 +2063,7 @@ added: v10.0.0
20842063
added: v0.9.3
20852064
-->
20862065
* Returns: {string[]} An array of the names of the supported hash algorithms,
2087-
such as `'RSA-SHA256'`.
2066+
such as `'RSA-SHA256'`. Hash algorithms are also called "digest" algorithms.
20882067

20892068
```js
20902069
const hashes = crypto.getHashes();
@@ -3103,7 +3082,9 @@ the `crypto`, `tls`, and `https` modules and are generally specific to OpenSSL.
31033082
[`Buffer`]: buffer.html
31043083
[`EVP_BytesToKey`]: https://www.openssl.org/docs/man1.1.0/crypto/EVP_BytesToKey.html
31053084
[`KeyObject`]: #crypto_class_keyobject
3085+
[`Sign`]: #crypto_class_sign
31063086
[`UV_THREADPOOL_SIZE`]: cli.html#cli_uv_threadpool_size_size
3087+
[`Verify`]: #crypto_class_verify
31073088
[`cipher.final()`]: #crypto_cipher_final_outputencoding
31083089
[`cipher.update()`]: #crypto_cipher_update_data_inputencoding_outputencoding
31093090
[`crypto.createCipher()`]: #crypto_crypto_createcipher_algorithm_password_options

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL