From 7123167e31177428a479de496b09a291bc356944 Mon Sep 17 00:00:00 2001 From: Sam Roberts Date: Fri, 11 Jan 2019 11:43:58 -0800 Subject: [PATCH] doc: improve Sign/Verify examples and docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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: https://github.com/nodejs/node/pull/25452 Reviewed-By: Vse Mozhet Byt Reviewed-By: Tobias Nießen Reviewed-By: James M Snell --- doc/api/crypto.md | 109 +++++++++++++++++++--------------------------- 1 file changed, 45 insertions(+), 64 deletions(-) diff --git a/doc/api/crypto.md b/doc/api/crypto.md index 54bbf7794e1750..b387c2684239a9 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -1018,7 +1018,7 @@ This can be called many times with new data as it is streamed. added: v0.1.94 --> -The `Hmac` Class is a utility for creating cryptographic HMAC digests. It can +The `Hmac` class is a utility for creating cryptographic HMAC digests. It can be used in one of two ways: - As a [stream][] that is both readable and writable, where data is written @@ -1196,7 +1196,7 @@ or `'private'` for private (asymmetric) keys. added: v0.1.92 --> -The `Sign` Class is a utility for generating signatures. It can be used in one +The `Sign` class is a utility for generating signatures. It can be used in one of two ways: - 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 argument is the string name of the hash function to use. `Sign` objects are not to be created directly using the `new` keyword. -Example: Using `Sign` objects as streams: +Example: Using `Sign` and [`Verify`][] objects as streams: ```js const crypto = require('crypto'); -const sign = crypto.createSign('SHA256'); +const { privateKey, publicKey } = crypto.generateKeyPairSync('ec', { + namedCurve: 'sect239k1' +}); + +const sign = crypto.createSign('SHA256'); sign.write('some data to sign'); sign.end(); +const signature = sign.sign(privateKey, 'hex'); -const privateKey = getPrivateKeySomehow(); -console.log(sign.sign(privateKey, 'hex')); -// Prints: the calculated signature using the specified private key and -// SHA-256. For RSA keys, the algorithm is RSASSA-PKCS1-v1_5 (see padding -// parameter below for RSASSA-PSS). For EC keys, the algorithm is ECDSA. +const verify = crypto.createVerify('SHA256'); +verify.write('some data to sign'); +verify.end(); +console.log(verify.verify(publicKey, signature)); +// Prints: true or false ``` -Example: Using the [`sign.update()`][] and [`sign.sign()`][] methods: +Example: Using the [`sign.update()`][] and [`verify.update()`][] methods: ```js const crypto = require('crypto'); -const sign = crypto.createSign('SHA256'); - -sign.update('some data to sign'); - -const privateKey = getPrivateKeySomehow(); -console.log(sign.sign(privateKey, 'hex')); -// Prints: the calculated signature -``` - -In some cases, a `Sign` instance can also be created by passing in a signature -algorithm name, such as 'RSA-SHA256'. This will use the corresponding digest -algorithm. This does not work for all signature algorithms, such as -'ecdsa-with-SHA256'. Use digest names instead. -Example: signing using legacy signature algorithm name - -```js -const crypto = require('crypto'); -const sign = crypto.createSign('RSA-SHA256'); +const { privateKey, publicKey } = crypto.generateKeyPairSync('rsa', { + modulusLength: 2048, +}); +const sign = crypto.createSign('SHA256'); sign.update('some data to sign'); +sign.end(); +const signature = sign.sign(privateKey); -const privateKey = getPrivateKeySomehow(); -console.log(sign.sign(privateKey, 'hex')); -// Prints: the calculated signature +const verify = crypto.createVerify('SHA256'); +verify.update('some data to sign'); +verify.end(); +console.log(verify.verify(publicKey, signature)); +// Prints: true ``` ### sign.sign(privateKey[, outputEncoding]) @@ -1332,34 +1327,7 @@ of two ways: The [`crypto.createVerify()`][] method is used to create `Verify` instances. `Verify` objects are not to be created directly using the `new` keyword. -Example: Using `Verify` objects as streams: - -```js -const crypto = require('crypto'); -const verify = crypto.createVerify('SHA256'); - -verify.write('some data to sign'); -verify.end(); - -const publicKey = getPublicKeySomehow(); -const signature = getSignatureToVerify(); -console.log(verify.verify(publicKey, signature)); -// Prints: true or false -``` - -Example: Using the [`verify.update()`][] and [`verify.verify()`][] methods: - -```js -const crypto = require('crypto'); -const verify = crypto.createVerify('SHA256'); - -verify.update('some data to sign'); - -const publicKey = getPublicKeySomehow(); -const signature = getSignatureToVerify(); -console.log(verify.verify(publicKey, signature)); -// Prints: true or false -``` +See [`Sign`][] for examples. ### verify.update(data[, inputEncoding]) * Returns: {string[]} An array of the names of the supported hash algorithms, - such as `'RSA-SHA256'`. + such as `'RSA-SHA256'`. Hash algorithms are also called "digest" algorithms. ```js const hashes = crypto.getHashes(); @@ -3103,7 +3082,9 @@ the `crypto`, `tls`, and `https` modules and are generally specific to OpenSSL. [`Buffer`]: buffer.html [`EVP_BytesToKey`]: https://www.openssl.org/docs/man1.1.0/crypto/EVP_BytesToKey.html [`KeyObject`]: #crypto_class_keyobject +[`Sign`]: #crypto_class_sign [`UV_THREADPOOL_SIZE`]: cli.html#cli_uv_threadpool_size_size +[`Verify`]: #crypto_class_verify [`cipher.final()`]: #crypto_cipher_final_outputencoding [`cipher.update()`]: #crypto_cipher_update_data_inputencoding_outputencoding [`crypto.createCipher()`]: #crypto_crypto_createcipher_algorithm_password_options