From 2fd78afd20f73bd77179ebabc5edf966a7140b3e Mon Sep 17 00:00:00 2001 From: Luigi Pinca Date: Fri, 26 Aug 2016 17:07:20 +0200 Subject: [PATCH] doc: add `added:` information for crypto Ref: https://github.com/nodejs/node/pull/8885 PR-URL: https://github.com/nodejs/node/pull/8281 Reviewed-By: Benjamin Gruenbaum Reviewed-By: Anna Henningsen Reviewed-By: James M Snell --- doc/api/crypto.md | 209 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 209 insertions(+) diff --git a/doc/api/crypto.md b/doc/api/crypto.md index 568c6a5d213cda..49cbef787ca0f3 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -20,6 +20,9 @@ console.log(hash); ``` ## Class: Certificate + SPKAC is a Certificate Signing Request mechanism originally implemented by Netscape and now specified formally as part of [HTML5's `keygen` element][]. @@ -41,6 +44,9 @@ const cert2 = crypto.Certificate(); ``` ### certificate.exportChallenge(spkac) + The `spkac` data structure includes a public key and a challenge. The `certificate.exportChallenge()` returns the challenge component in the @@ -56,6 +62,9 @@ console.log(challenge.toString('utf8')); ``` ### certificate.exportPublicKey(spkac) + The `spkac` data structure includes a public key and a challenge. The `certificate.exportPublicKey()` returns the public key component in the @@ -71,6 +80,9 @@ console.log(publicKey); ``` ### certificate.verifySpkac(spkac) + Returns `true` if the given `spkac` data structure is valid, `false` otherwise. The `spkac` argument must be a Node.js [`Buffer`][]. @@ -83,6 +95,9 @@ console.log(cert.verifySpkac(new Buffer(spkac))); ``` ## Class: Cipher + Instances of the `Cipher` class are used to encrypt data. The class can be used in one of two ways: @@ -143,6 +158,9 @@ console.log(encrypted); ``` ### cipher.final([output_encoding]) + Returns any remaining enciphered contents. If `output_encoding` parameter is one of `'binary'`, `'base64'` or `'hex'`, a string is returned. @@ -153,12 +171,18 @@ longer be used to encrypt data. Attempts to call `cipher.final()` more than once will result in an error being thrown. ### cipher.setAAD(buffer) + When using an authenticated encryption mode (only `GCM` is currently supported), the `cipher.setAAD()` method sets the value used for the _additional authenticated data_ (AAD) input parameter. ### cipher.getAuthTag() + When using an authenticated encryption mode (only `GCM` is currently supported), the `cipher.getAuthTag()` method returns a [`Buffer`][] containing @@ -168,6 +192,9 @@ The `cipher.getAuthTag()` method should only be called after encryption has been completed using the [`cipher.final()`][] method. ### cipher.setAutoPadding(auto_padding=true) + When using block encryption algorithms, the `Cipher` class will automatically add padding to the input data to the appropriate block size. To disable the @@ -181,6 +208,9 @@ using `0x0` instead of PKCS padding. The `cipher.setAutoPadding()` method must be called before [`cipher.final()`][]. ### cipher.update(data[, input_encoding][, output_encoding]) + Updates the cipher with `data`. If the `input_encoding` argument is given, it's value must be one of `'utf8'`, `'ascii'`, or `'binary'` and the `data` @@ -198,6 +228,9 @@ The `cipher.update()` method can be called multiple times with new data until [`cipher.final()`][] will result in an error being thrown. ## Class: Decipher + Instances of the `Decipher` class are used to decrypt data. The class can be used in one of two ways: @@ -260,6 +293,9 @@ console.log(decrypted); ``` ### decipher.final([output_encoding]) + Returns any remaining deciphered contents. If `output_encoding` parameter is one of `'binary'`, `'base64'` or `'hex'`, a string is returned. @@ -270,12 +306,18 @@ no longer be used to decrypt data. Attempts to call `decipher.final()` more than once will result in an error being thrown. ### decipher.setAAD(buffer) + When using an authenticated encryption mode (only `GCM` is currently supported), the `cipher.setAAD()` method sets the value used for the _additional authenticated data_ (AAD) input parameter. ### decipher.setAuthTag(buffer) + When using an authenticated encryption mode (only `GCM` is currently supported), the `decipher.setAuthTag()` method is used to pass in the @@ -284,6 +326,9 @@ has been tampered with, [`decipher.final()`][] with throw, indicating that the cipher text should be discarded due to failed authentication. ### decipher.setAutoPadding(auto_padding=true) + When data has been encrypted without standard block padding, calling `decipher.setAutoPadding(false)` will disable automatic padding to prevent @@ -296,6 +341,9 @@ The `decipher.setAutoPadding()` method must be called before [`decipher.update()`][]. ### decipher.update(data[, input_encoding][, output_encoding]) + Updates the decipher with `data`. If the `input_encoding` argument is given, it's value must be one of `'binary'`, `'base64'`, or `'hex'` and the `data` @@ -313,6 +361,9 @@ The `decipher.update()` method can be called multiple times with new data until [`decipher.final()`][] will result in an error being thrown. ## Class: DiffieHellman + The `DiffieHellman` class is a utility for creating Diffie-Hellman key exchanges. @@ -341,6 +392,9 @@ assert.equal(alice_secret.toString('hex'), bob_secret.toString('hex')); ``` ### diffieHellman.computeSecret(other_public_key[, input_encoding][, output_encoding]) + Computes the shared secret using `other_public_key` as the other party's public key and returns the computed shared secret. The supplied @@ -353,6 +407,9 @@ If `output_encoding` is given a string is returned; otherwise, a [`Buffer`][] is returned. ### diffieHellman.generateKeys([encoding]) + Generates private and public Diffie-Hellman key values, and returns the public key in the specified `encoding`. This key should be @@ -361,30 +418,45 @@ or `'base64'`. If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. ### diffieHellman.getGenerator([encoding]) + Returns the Diffie-Hellman generator in the specified `encoding`, which can be `'binary'`, `'hex'`, or `'base64'`. If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. ### diffieHellman.getPrime([encoding]) + Returns the Diffie-Hellman prime in the specified `encoding`, which can be `'binary'`, `'hex'`, or `'base64'`. If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. ### diffieHellman.getPrivateKey([encoding]) + Returns the Diffie-Hellman private key in the specified `encoding`, which can be `'binary'`, `'hex'`, or `'base64'`. If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. ### diffieHellman.getPublicKey([encoding]) + Returns the Diffie-Hellman public key in the specified `encoding`, which can be `'binary'`, `'hex'`, or `'base64'`. If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. ### diffieHellman.setPrivateKey(private_key[, encoding]) + Sets the Diffie-Hellman private key. If the `encoding` argument is provided and is either `'binary'`, `'hex'`, or `'base64'`, `private_key` is expected @@ -392,6 +464,9 @@ to be a string. If no `encoding` is provided, `private_key` is expected to be a [`Buffer`][]. ### diffieHellman.setPublicKey(public_key[, encoding]) + Sets the Diffie-Hellman public key. If the `encoding` argument is provided and is either `'binary'`, `'hex'` or `'base64'`, `public_key` is expected @@ -399,6 +474,9 @@ to be a string. If no `encoding` is provided, `public_key` is expected to be a [`Buffer`][]. ### diffieHellman.verifyError + A bit field containing any warnings and/or errors resulting from a check performed during initialization of the `DiffieHellman` object. @@ -412,6 +490,9 @@ module): * `DH_NOT_SUITABLE_GENERATOR` ## Class: ECDH + The `ECDH` class is a utility for creating Elliptic Curve Diffie-Hellman (ECDH) key exchanges. @@ -440,6 +521,9 @@ assert(alice_secret, bob_secret); ``` ### ecdh.computeSecret(other_public_key[, input_encoding][, output_encoding]) + Computes the shared secret using `other_public_key` as the other party's public key and returns the computed shared secret. The supplied @@ -452,6 +536,9 @@ If `output_encoding` is given a string will be returned; otherwise a [`Buffer`][] is returned. ### ecdh.generateKeys([encoding[, format]]) + Generates private and public EC Diffie-Hellman key values, and returns the public key in the specified `format` and `encoding`. This key should be @@ -466,12 +553,18 @@ The `encoding` argument can be `'binary'`, `'hex'`, or `'base64'`. If is returned. ### ecdh.getPrivateKey([encoding]) + Returns the EC Diffie-Hellman private key in the specified `encoding`, which can be `'binary'`, `'hex'`, or `'base64'`. If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. ### ecdh.getPublicKey([encoding[, format]]) + Returns the EC Diffie-Hellman public key in the specified `encoding` and `format`. @@ -485,6 +578,9 @@ The `encoding` argument can be `'binary'`, `'hex'`, or `'base64'`. If returned. ### ecdh.setPrivateKey(private_key[, encoding]) + Sets the EC Diffie-Hellman private key. The `encoding` can be `'binary'`, `'hex'` or `'base64'`. If `encoding` is provided, `private_key` is expected @@ -494,6 +590,10 @@ created, an error is thrown. Upon setting the private key, the associated public point (key) is also generated and set in the ECDH object. ### ecdh.setPublicKey(public_key[, encoding]) + > Stability: 0 - Deprecated @@ -533,6 +633,9 @@ console.log(alice_secret === bob_secret); ``` ## Class: Hash + The `Hash` class is a utility for creating hash digests of data. It can be used in one of two ways: @@ -587,6 +690,9 @@ console.log(hash.digest('hex')); ``` ### hash.digest([encoding]) + Calculates the digest of all of the data passed to be hashed (using the [`hash.update()`][] method). The `encoding` can be `'hex'`, `'binary'` or @@ -597,6 +703,9 @@ The `Hash` object can not be used again after `hash.digest()` method has been called. Multiple calls will cause an error to be thrown. ### hash.update(data[, input_encoding]) + Updates the hash content with the given `data`, the encoding of which is given in `input_encoding` and can be `'utf8'`, `'ascii'` or @@ -607,6 +716,9 @@ encoding of `'binary'` is enforced. If `data` is a [`Buffer`][] then This can be called many times with new data as it is streamed. ## Class: Hmac + The `Hmac` Class is a utility for creating cryptographic HMAC digests. It can be used in one of two ways: @@ -661,6 +773,9 @@ console.log(hmac.digest('hex')); ``` ### hmac.digest([encoding]) + Calculates the HMAC digest of all of the data passed using [`hmac.update()`][]. The `encoding` can be `'hex'`, `'binary'` or `'base64'`. If `encoding` is @@ -670,6 +785,9 @@ The `Hmac` object can not be used again after `hmac.digest()` has been called. Multiple calls to `hmac.digest()` will result in an error being thrown. ### hmac.update(data[, input_encoding]) + Updates the `Hmac` content with the given `data`, the encoding of which is given in `input_encoding` and can be `'utf8'`, `'ascii'` or @@ -680,6 +798,9 @@ encoding of `'utf8'` is enforced. If `data` is a [`Buffer`][] then This can be called many times with new data as it is streamed. ## Class: Sign + The `Sign` Class is a utility for generating signatures. It can be used in one of two ways: @@ -742,6 +863,9 @@ console.log(sign.sign(private_key).toString('hex')); ``` ### sign.sign(private_key[, output_format]) + Calculates the signature on all the data passed through using either [`sign.update()`][] or [`sign.write()`][stream-writable-write]. @@ -761,6 +885,9 @@ The `Sign` object can not be again used after `sign.sign()` method has been called. Multiple calls to `sign.sign()` will result in an error being thrown. ### sign.update(data[, input_encoding]) + Updates the `Sign` content with the given `data`, the encoding of which is given in `input_encoding` and can be `'utf8'`, `'ascii'` or @@ -771,6 +898,9 @@ encoding of `'utf8'` is enforced. If `data` is a [`Buffer`][] then This can be called many times with new data as it is streamed. ## Class: Verify + The `Verify` class is a utility for verifying signatures. It can be used in one of two ways: @@ -813,6 +943,9 @@ console.log(verify.verify(public_key, signature)); ``` ### verifier.update(data[, input_encoding]) + Updates the `Verify` content with the given `data`, the encoding of which is given in `input_encoding` and can be `'utf8'`, `'ascii'` or @@ -823,6 +956,9 @@ encoding of `'utf8'` is enforced. If `data` is a [`Buffer`][] then This can be called many times with new data as it is streamed. ### verifier.verify(object, signature[, signature_format]) + Verifies the provided data using the given `object` and `signature`. The `object` argument is a string containing a PEM encoded object, which can be @@ -842,6 +978,9 @@ thrown. ## `crypto` module methods and properties ### crypto.DEFAULT_ENCODING + The default encoding to use for functions that can take either strings or [buffers][`Buffer`]. The default value is `'buffer'`, which makes methods @@ -854,6 +993,9 @@ New applications should expect the default to be `'buffer'`. This property may become deprecated in a future Node.js release. ### crypto.createCipher(algorithm, password) + Creates and returns a `Cipher` object that uses the given `algorithm` and `password`. @@ -891,6 +1033,10 @@ The `key` is the raw key used by the `algorithm` and `iv` is an [buffers][`Buffer`]. ### crypto.createCredentials(details) + > Stability: 0 - Deprecated: Use [`tls.createSecureContext()`][] instead. @@ -916,6 +1062,9 @@ If no 'ca' details are given, Node.js will use Mozilla's default [publicly trusted list of CAs][]. ### crypto.createDecipher(algorithm, password) + Creates and returns a `Decipher` object that uses the given `algorithm` and `password` (key). @@ -933,6 +1082,9 @@ their own using [`crypto.pbkdf2()`][] and to use [`crypto.createDecipheriv()`][] to create the `Decipher` object. ### crypto.createDecipheriv(algorithm, key, iv) + Creates and returns a `Decipher` object that uses the given `algorithm`, `key` and initialization vector (`iv`). @@ -946,6 +1098,9 @@ The `key` is the raw key used by the `algorithm` and `iv` is an [buffers][`Buffer`]. ### crypto.createDiffieHellman(prime[, prime_encoding][, generator][, generator_encoding]) + Creates a `DiffieHellman` key exchange object using the supplied `prime` and an optional specific `generator`. @@ -963,12 +1118,18 @@ If `generator_encoding` is specified, `generator` is expected to be a string; otherwise either a number or [`Buffer`][] is expected. ### crypto.createDiffieHellman(prime_length[, generator]) + Creates a `DiffieHellman` key exchange object and generates a prime of `prime_length` bits using an optional specific numeric `generator`. If `generator` is not specified, the value `2` is used. ### crypto.createECDH(curve_name) + Creates an Elliptic Curve Diffie-Hellman (`ECDH`) key exchange object using a predefined curve specified by the `curve_name` string. Use @@ -977,6 +1138,9 @@ OpenSSL releases, `openssl ecparam -list_curves` will also display the name and description of each available elliptic curve. ### crypto.createHash(algorithm) + Creates and returns a `Hash` object that can be used to generate hash digests using the given `algorithm`. @@ -1007,6 +1171,9 @@ input.on('readable', () => { ``` ### crypto.createHmac(algorithm, key) + Creates and returns an `Hmac` object that uses the given `algorithm` and `key`. @@ -1038,18 +1205,27 @@ input.on('readable', () => { ``` ### crypto.createSign(algorithm) + Creates and returns a `Sign` object that uses the given `algorithm`. On recent OpenSSL releases, `openssl list-public-key-algorithms` will display the available signing algorithms. One example is `'RSA-SHA256'`. ### crypto.createVerify(algorithm) + Creates and returns a `Verify` object that uses the given algorithm. On recent OpenSSL releases, `openssl list-public-key-algorithms` will display the available signing algorithms. One example is `'RSA-SHA256'`. ### crypto.getCiphers() + Returns an array with the names of the supported cipher algorithms. @@ -1061,6 +1237,9 @@ console.log(ciphers); // ['aes-128-cbc', 'aes-128-ccm', ...] ``` ### crypto.getCurves() + Returns an array with the names of the supported elliptic curves. @@ -1072,6 +1251,9 @@ console.log(curves); // ['secp256k1', 'secp384r1', ...] ``` ### crypto.getDiffieHellman(group_name) + Creates a predefined `DiffieHellman` key exchange object. The supported groups are: `'modp1'`, `'modp2'`, `'modp5'` (defined in @@ -1102,6 +1284,9 @@ console.log(alice_secret == bob_secret); ``` ### crypto.getHashes() + Returns an array with the names of the supported hash algorithms. @@ -1113,6 +1298,9 @@ console.log(hashes); // ['sha', 'sha1', 'sha1WithRSAEncryption', ...] ``` ### crypto.pbkdf2(password, salt, iterations, keylen[, digest], callback) + Provides an asynchronous Password-Based Key Derivation Function 2 (PBKDF2) implementation. A selected HMAC digest algorithm specified by `digest` is @@ -1146,6 +1334,9 @@ An array of supported digest functions can be retrieved using [`crypto.getHashes()`][]. ### crypto.pbkdf2Sync(password, salt, iterations, keylen[, digest]) + Provides a synchronous Password-Based Key Derivation Function 2 (PBKDF2) implementation. A selected HMAC digest algorithm specified by `digest` is @@ -1176,6 +1367,9 @@ An array of supported digest functions can be retrieved using [`crypto.getHashes()`][]. ### crypto.privateDecrypt(private_key, buffer) + Decrypts `buffer` with `private_key`. @@ -1194,6 +1388,9 @@ keys: All paddings are defined in the `constants` module. ### crypto.privateEncrypt(private_key, buffer) + Encrypts `buffer` with `private_key`. @@ -1212,6 +1409,9 @@ keys: All paddings are defined in the `constants` module. ### crypto.publicDecrypt(public_key, buffer) + Decrypts `buffer` with `public_key`. @@ -1233,6 +1433,9 @@ be passed instead of a public key. All paddings are defined in the `constants` module. ### crypto.publicEncrypt(public_key, buffer) + Encrypts `buffer` with `public_key`. @@ -1254,6 +1457,9 @@ be passed instead of a public key. All paddings are defined in the `constants` module. ### crypto.randomBytes(size[, callback]) + Generates cryptographically strong pseudo-random data. The `size` argument is a number indicating the number of bytes to generate. @@ -1289,6 +1495,9 @@ when generating the random bytes may conceivably block for a longer period of time is right after boot, when the whole system is still low on entropy. ### crypto.setEngine(engine[, flags]) + Load and set the `engine` for some or all OpenSSL functions (selected by flags).