From 0515f3d958b3ed863210525826e2b6d31813e797 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 PR-URL: https://github.com/nodejs/node/pull/8281 --- doc/api/crypto.md | 215 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 215 insertions(+) diff --git a/doc/api/crypto.md b/doc/api/crypto.md index 1d4b451be0d682..89866dc0c49125 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -35,6 +35,9 @@ try { ``` ## Class: Certificate + SPKAC is a Certificate Signing Request mechanism originally implemented by Netscape and now specified formally as part of [HTML5's `keygen` element][]. @@ -56,6 +59,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 @@ -71,6 +77,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 @@ -86,6 +95,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`][]. @@ -98,6 +110,9 @@ console.log(cert.verifySpkac(Buffer.from(spkac))); ``` ## Class: Cipher + Instances of the `Cipher` class are used to encrypt data. The class can be used in one of two ways: @@ -158,6 +173,9 @@ console.log(encrypted); ``` ### cipher.final([output_encoding]) + Returns any remaining enciphered contents. If `output_encoding` parameter is one of `'latin1'`, `'base64'` or `'hex'`, a string is returned. @@ -168,12 +186,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 @@ -183,6 +207,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 @@ -196,6 +223,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 `'latin1'` and the `data` @@ -213,6 +243,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: @@ -275,6 +308,9 @@ console.log(decrypted); ``` ### decipher.final([output_encoding]) + Returns any remaining deciphered contents. If `output_encoding` parameter is one of `'latin1'`, `'base64'` or `'hex'`, a string is returned. @@ -285,12 +321,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 @@ -299,6 +341,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 @@ -311,6 +356,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 `'latin1'`, `'base64'`, or `'hex'` and the `data` @@ -328,6 +376,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. @@ -356,6 +407,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 @@ -368,6 +422,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 @@ -376,30 +433,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 `'latin1'`, `'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 `'latin1'`, `'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 `'latin1'`, `'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 `'latin1'`, `'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 `'latin1'`, `'hex'`, or `'base64'`, `private_key` is expected @@ -407,6 +479,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 `'latin1'`, `'hex'` or `'base64'`, `public_key` is expected @@ -414,6 +489,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. @@ -427,6 +505,9 @@ module): * `DH_NOT_SUITABLE_GENERATOR` ## Class: ECDH + The `ECDH` class is a utility for creating Elliptic Curve Diffie-Hellman (ECDH) key exchanges. @@ -455,6 +536,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 @@ -467,6 +551,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 @@ -481,12 +568,18 @@ The `encoding` argument can be `'latin1'`, `'hex'`, or `'base64'`. If is returned. ### ecdh.getPrivateKey([encoding]) + Returns the EC Diffie-Hellman private key in the specified `encoding`, which can be `'latin1'`, `'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`. @@ -500,6 +593,9 @@ The `encoding` argument can be `'latin1'`, `'hex'`, or `'base64'`. If returned. ### ecdh.setPrivateKey(private_key[, encoding]) + Sets the EC Diffie-Hellman private key. The `encoding` can be `'latin1'`, `'hex'` or `'base64'`. If `encoding` is provided, `private_key` is expected @@ -509,6 +605,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 @@ -548,6 +648,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: @@ -602,6 +705,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'`, `'latin1'` or @@ -612,6 +718,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 @@ -622,6 +731,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: Hmac + The `Hmac` Class is a utility for creating cryptographic HMAC digests. It can be used in one of two ways: @@ -676,6 +788,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'`, `'latin1'` or `'base64'`. If `encoding` is @@ -685,6 +800,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 @@ -695,6 +813,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: @@ -757,6 +878,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]. @@ -776,6 +900,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 @@ -786,6 +913,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: @@ -828,6 +958,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 @@ -838,6 +971,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 @@ -857,12 +993,18 @@ thrown. ## `crypto` module methods and properties ## crypto.constants + Returns an object containing commonly used constants for crypto and security related operations. The specific constants currently defined are described in [Crypto Constants][]. ### 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 @@ -875,11 +1017,17 @@ New applications should expect the default to be `'buffer'`. This property may become deprecated in a future Node.js release. ### crypto.fips + Property for checking and controlling whether a FIPS compliant crypto provider is currently in use. Setting to true requires a FIPS build of Node.js. ### crypto.createCipher(algorithm, password) + Creates and returns a `Cipher` object that uses the given `algorithm` and `password`. @@ -917,6 +1065,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. @@ -942,6 +1094,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). @@ -959,6 +1114,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`). @@ -972,6 +1130,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`. @@ -989,12 +1150,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 @@ -1003,6 +1170,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`. @@ -1033,6 +1203,9 @@ input.on('readable', () => { ``` ### crypto.createHmac(algorithm, key) + Creates and returns an `Hmac` object that uses the given `algorithm` and `key`. @@ -1064,18 +1237,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. @@ -1087,6 +1269,9 @@ console.log(ciphers); // ['aes-128-cbc', 'aes-128-ccm', ...] ``` ### crypto.getCurves() + Returns an array with the names of the supported elliptic curves. @@ -1098,6 +1283,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 @@ -1128,6 +1316,9 @@ console.log(alice_secret == bob_secret); ``` ### crypto.getHashes() + Returns an array with the names of the supported hash algorithms. @@ -1139,6 +1330,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 @@ -1171,6 +1365,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 @@ -1200,6 +1397,9 @@ An array of supported digest functions can be retrieved using [`crypto.getHashes()`][]. ### crypto.privateDecrypt(private_key, buffer) + Decrypts `buffer` with `private_key`. @@ -1218,6 +1418,9 @@ keys: All paddings are defined in `crypto.constants`. ### crypto.privateEncrypt(private_key, buffer) + Encrypts `buffer` with `private_key`. @@ -1236,6 +1439,9 @@ keys: All paddings are defined in `crypto.constants`. ### crypto.publicDecrypt(public_key, buffer) + Decrypts `buffer` with `public_key`. @@ -1257,6 +1463,9 @@ be passed instead of a public key. All paddings are defined in `crypto.constants`. ### crypto.publicEncrypt(public_key, buffer) + Encrypts `buffer` with `public_key`. @@ -1278,6 +1487,9 @@ be passed instead of a public key. All paddings are defined in `crypto.constants`. ### crypto.randomBytes(size[, callback]) + Generates cryptographically strong pseudo-random data. The `size` argument is a number indicating the number of bytes to generate. @@ -1313,6 +1525,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).