From e1c357e881c803ffe18c04f63f0f130c4b673a9d Mon Sep 17 00:00:00 2001 From: Tristian Flanagan Date: Wed, 4 Nov 2015 11:23:03 -0500 Subject: [PATCH] doc: sort crypto alphabetically Reorders, with no contextual changes, the crypto documentation alphabetically. PR-URL: https://github.com/nodejs/node/pull/3662 Reviewed-By: Evan Lucas Reviewed-By: James M Snell Reviewed-By: Jeremiah Senkpiel --- doc/api/crypto.markdown | 846 ++++++++++++++++++++-------------------- 1 file changed, 418 insertions(+), 428 deletions(-) diff --git a/doc/api/crypto.markdown b/doc/api/crypto.markdown index b1da67818c..113593a113 100644 --- a/doc/api/crypto.markdown +++ b/doc/api/crypto.markdown @@ -10,343 +10,328 @@ used as part of a secure HTTPS net or http connection. It also offers a set of wrappers for OpenSSL's hash, hmac, cipher, decipher, sign and verify methods. +## Class: Certificate -## crypto.setEngine(engine[, flags]) - -Load and set engine for some/all OpenSSL functions (selected by flags). - -`engine` could be either an id or a path to the engine's shared library. - -`flags` is optional and has `ENGINE_METHOD_ALL` value by default. It could take -one of or mix of following flags (defined in `constants` module): - -* `ENGINE_METHOD_RSA` -* `ENGINE_METHOD_DSA` -* `ENGINE_METHOD_DH` -* `ENGINE_METHOD_RAND` -* `ENGINE_METHOD_ECDH` -* `ENGINE_METHOD_ECDSA` -* `ENGINE_METHOD_CIPHERS` -* `ENGINE_METHOD_DIGESTS` -* `ENGINE_METHOD_STORE` -* `ENGINE_METHOD_PKEY_METH` -* `ENGINE_METHOD_PKEY_ASN1_METH` -* `ENGINE_METHOD_ALL` -* `ENGINE_METHOD_NONE` - - -## crypto.getCiphers() +The class used for working with signed public key & challenges. The most +common usage for this series of functions is when dealing with the `` +element. http://www.openssl.org/docs/apps/spkac.html -Returns an array with the names of the supported ciphers. +Returned by `crypto.Certificate`. -Example: +### Certificate.exportChallenge(spkac) - var ciphers = crypto.getCiphers(); - console.log(ciphers); // ['aes-128-cbc', 'aes-128-ccm', ...] +Exports the encoded challenge associated with the SPKAC. +### Certificate.exportPublicKey(spkac) -## crypto.getHashes() +Exports the encoded public key from the supplied SPKAC. -Returns an array with the names of the supported hash algorithms. +### Certificate.verifySpkac(spkac) -Example: +Returns true of false based on the validity of the SPKAC. - var hashes = crypto.getHashes(); - console.log(hashes); // ['sha', 'sha1', 'sha1WithRSAEncryption', ...] +## Class: Cipher +Class for encrypting data. -## crypto.getCurves() +Returned by `crypto.createCipher` and `crypto.createCipheriv`. -Returns an array with the names of the supported elliptic curves. +Cipher objects are [streams](stream.html) that are both readable and +writable. The written plain text data is used to produce the +encrypted data on the readable side. The legacy `update` and `final` +methods are also supported. -Example: +### cipher.final([output_encoding]) - var curves = crypto.getCurves(); - console.log(curves); // ['secp256k1', 'secp384r1', ...] +Returns any remaining enciphered contents, with `output_encoding` +being one of: `'binary'`, `'base64'` or `'hex'`. If no encoding is +provided, then a buffer is returned. +Note: `cipher` object can not be used after `final()` method has been +called. -## crypto.createCredentials(details) +### cipher.getAuthTag() - Stability: 0 - Deprecated: Use [tls.createSecureContext][] instead. +For authenticated encryption modes (currently supported: GCM), this +method returns a `Buffer` that represents the _authentication tag_ that +has been computed from the given data. Should be called after +encryption has been completed using the `final` method! -Creates a credentials object, with the optional details being a -dictionary with keys: +### cipher.setAAD(buffer) -* `pfx` : A string or buffer holding the PFX or PKCS12 encoded private - key, certificate and CA certificates -* `key` : A string holding the PEM encoded private key -* `passphrase` : A string of passphrase for the private key or pfx -* `cert` : A string holding the PEM encoded certificate -* `ca` : Either a string or list of strings of PEM encoded CA - certificates to trust. -* `crl` : Either a string or list of strings of PEM encoded CRLs - (Certificate Revocation List) -* `ciphers`: A string describing the ciphers to use or exclude. - Consult - - for details on the format. +For authenticated encryption modes (currently supported: GCM), this +method sets the value used for the additional authenticated data (AAD) input +parameter. -If no 'ca' details are given, then Node.js will use the default -publicly trusted list of CAs as given in -. +### cipher.setAutoPadding(auto_padding=true) +You can disable automatic padding of the input data to block size. If +`auto_padding` is false, the length of the entire input data must be a +multiple of the cipher's block size or `final` will fail. Useful for +non-standard padding, e.g. using `0x0` instead of PKCS padding. You +must call this before `cipher.final`. -## crypto.createHash(algorithm) +### cipher.update(data[, input_encoding][, output_encoding]) -Creates and returns a hash object, a cryptographic hash with the given -algorithm which can be used to generate hash digests. +Updates the cipher with `data`, the encoding of which is given in +`input_encoding` and can be `'utf8'`, `'ascii'` or `'binary'`. If no +encoding is provided, then a buffer is expected. +If `data` is a `Buffer` then `input_encoding` is ignored. -`algorithm` is dependent on the available algorithms supported by the -version of OpenSSL on the platform. Examples are `'sha256'`, -`'sha512'`, etc. On recent releases, `openssl -list-message-digest-algorithms` will display the available digest -algorithms. +The `output_encoding` specifies the output format of the enciphered +data, and can be `'binary'`, `'base64'` or `'hex'`. If no encoding is +provided, then a buffer is returned. -Example: this program that takes the sha256 sum of a file +Returns the enciphered contents, and can be called many times with new +data as it is streamed. - var filename = process.argv[2]; - var crypto = require('crypto'); - var fs = require('fs'); +## Class: Decipher - var shasum = crypto.createHash('sha256'); +Class for decrypting data. - var s = fs.ReadStream(filename); - s.on('data', function(d) { - shasum.update(d); - }); +Returned by `crypto.createDecipher` and `crypto.createDecipheriv`. - s.on('end', function() { - var d = shasum.digest('hex'); - console.log(d + ' ' + filename); - }); +Decipher objects are [streams](stream.html) that are both readable and +writable. The written enciphered data is used to produce the +plain-text data on the the readable side. The legacy `update` and +`final` methods are also supported. -## Class: Hash +### decipher.final([output_encoding]) -The class for creating hash digests of data. +Returns any remaining plaintext which is deciphered, with +`output_encoding` being one of: `'binary'`, `'ascii'` or `'utf8'`. If +no encoding is provided, then a buffer is returned. -It is a [stream](stream.html) that is both readable and writable. The -written data is used to compute the hash. Once the writable side of -the stream is ended, use the `read()` method to get the computed hash -digest. The legacy `update` and `digest` methods are also supported. +Note: `decipher` object can not be used after `final()` method has been +called. -Returned by `crypto.createHash`. +### decipher.setAAD(buffer) -### hash.update(data[, input_encoding]) +For authenticated encryption modes (currently supported: GCM), this +method sets the value used for the additional authenticated data (AAD) input +parameter. -Updates the hash content with the given `data`, the encoding of which -is given in `input_encoding` and can be `'utf8'`, `'ascii'` or -`'binary'`. If no encoding is provided, and the input is a string, an -encoding of `'binary'` is enforced. If `data` is a `Buffer` then -`input_encoding` is ignored. +### decipher.setAuthTag(buffer) -This can be called many times with new data as it is streamed. +For authenticated encryption modes (currently supported: GCM), this +method must be used to pass in the received _authentication tag_. +If no tag is provided or if the ciphertext has been tampered with, +`final` will throw, thus indicating that the ciphertext should +be discarded due to failed authentication. -### hash.digest([encoding]) +### decipher.setAutoPadding(auto_padding=true) -Calculates the digest of all of the passed data to be hashed. The -`encoding` can be `'hex'`, `'binary'` or `'base64'`. If no encoding -is provided, then a buffer is returned. +You can disable auto padding if the data has been encrypted without +standard block padding to prevent `decipher.final` from checking and +removing it. This will only work if the input data's length is a multiple of +the ciphers block size. You must call this before streaming data to +`decipher.update`. -Note: `hash` object can not be used after `digest()` method has been -called. +### decipher.update(data[, input_encoding][, output_encoding]) +Updates the decipher with `data`, which is encoded in `'binary'`, +`'base64'` or `'hex'`. If no encoding is provided, then a buffer is +expected. +If `data` is a `Buffer` then `input_encoding` is ignored. -## crypto.createHmac(algorithm, key) +The `output_decoding` specifies in what format to return the +deciphered plaintext: `'binary'`, `'ascii'` or `'utf8'`. If no +encoding is provided, then a buffer is returned. -Creates and returns a hmac object, a cryptographic hmac with the given -algorithm and key. +## Class: DiffieHellman -It is a [stream](stream.html) that is both readable and writable. The -written data is used to compute the hmac. Once the writable side of -the stream is ended, use the `read()` method to get the computed -digest. The legacy `update` and `digest` methods are also supported. +The class for creating Diffie-Hellman key exchanges. -`algorithm` is dependent on the available algorithms supported by -OpenSSL - see createHash above. `key` is the hmac key to be used. +Returned by `crypto.createDiffieHellman`. -## Class: Hmac +### diffieHellman.computeSecret(other_public_key[, input_encoding][, output_encoding]) -Class for creating cryptographic hmac content. +Computes the shared secret using `other_public_key` as the other +party's public key and returns the computed shared secret. Supplied +key is interpreted using specified `input_encoding`, and secret is +encoded using specified `output_encoding`. Encodings can be +`'binary'`, `'hex'`, or `'base64'`. If the input encoding is not +provided, then a buffer is expected. -Returned by `crypto.createHmac`. +If no output encoding is given, then a buffer is returned. -### hmac.update(data) +### diffieHellman.generateKeys([encoding]) -Update the hmac content with the given `data`. This can be called -many times with new data as it is streamed. +Generates private and public Diffie-Hellman key values, and returns +the public key in the specified encoding. This key should be +transferred to the other party. Encoding can be `'binary'`, `'hex'`, +or `'base64'`. If no encoding is provided, then a buffer is returned. -### hmac.digest([encoding]) +### diffieHellman.getGenerator([encoding]) -Calculates the digest of all of the passed data to the hmac. The -`encoding` can be `'hex'`, `'binary'` or `'base64'`. If no encoding -is provided, then a buffer is returned. +Returns the Diffie-Hellman generator in the specified encoding, which can +be `'binary'`, `'hex'`, or `'base64'`. If no encoding is provided, +then a buffer is returned. -Note: `hmac` object can not be used after `digest()` method has been -called. +### diffieHellman.getPrime([encoding]) +Returns the Diffie-Hellman prime in the specified encoding, which can +be `'binary'`, `'hex'`, or `'base64'`. If no encoding is provided, +then a buffer is returned. -## crypto.createCipher(algorithm, password) +### diffieHellman.getPrivateKey([encoding]) -Creates and returns a cipher object, with the given algorithm and -password. +Returns the Diffie-Hellman private key in the specified encoding, +which can be `'binary'`, `'hex'`, or `'base64'`. If no encoding is +provided, then a buffer is returned. -`algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On -recent releases, `openssl list-cipher-algorithms` will display the -available cipher algorithms. `password` is used to derive key and IV, -which must be a `'binary'` encoded string or a [buffer](buffer.html). +### diffieHellman.getPublicKey([encoding]) -It is a [stream](stream.html) that is both readable and writable. The -written data is used to compute the hash. Once the writable side of -the stream is ended, use the `read()` method to get the enciphered -contents. The legacy `update` and `final` methods are also supported. +Returns the Diffie-Hellman public key in the specified encoding, which +can be `'binary'`, `'hex'`, or `'base64'`. If no encoding is provided, +then a buffer is returned. -Note: `createCipher` derives keys with the OpenSSL function [EVP_BytesToKey][] -with the digest algorithm set to MD5, one iteration, and no salt. The lack of -salt allows dictionary attacks as the same password always creates the same key. -The low iteration count and non-cryptographically secure hash algorithm allow -passwords to be tested very rapidly. +### diffieHellman.setPrivateKey(private_key[, encoding]) -In line with OpenSSL's recommendation to use pbkdf2 instead of EVP_BytesToKey it -is recommended you derive a key and iv yourself with [crypto.pbkdf2][] and to -then use [createCipheriv()][] to create the cipher stream. +Sets the Diffie-Hellman private key. Key encoding can be `'binary'`, +`'hex'` or `'base64'`. If no encoding is provided, then a buffer is +expected. -## crypto.createCipheriv(algorithm, key, iv) +### diffieHellman.setPublicKey(public_key[, encoding]) -Creates and returns a cipher object, with the given algorithm, key and -iv. +Sets the Diffie-Hellman public key. Key encoding can be `'binary'`, +`'hex'` or `'base64'`. If no encoding is provided, then a buffer is +expected. -`algorithm` is the same as the argument to `createCipher()`. `key` is -the raw key used by the algorithm. `iv` is an [initialization -vector](http://en.wikipedia.org/wiki/Initialization_vector). +### diffieHellman.verifyError -`key` and `iv` must be `'binary'` encoded strings or -[buffers](buffer.html). +A bit field containing any warnings and/or errors as a result of a check performed +during initialization. The following values are valid for this property +(defined in `constants` module): -## Class: Cipher +* `DH_CHECK_P_NOT_SAFE_PRIME` +* `DH_CHECK_P_NOT_PRIME` +* `DH_UNABLE_TO_CHECK_GENERATOR` +* `DH_NOT_SUITABLE_GENERATOR` -Class for encrypting data. +## Class: ECDH -Returned by `crypto.createCipher` and `crypto.createCipheriv`. +The class for creating EC Diffie-Hellman key exchanges. -Cipher objects are [streams](stream.html) that are both readable and -writable. The written plain text data is used to produce the -encrypted data on the readable side. The legacy `update` and `final` -methods are also supported. +Returned by `crypto.createECDH`. -### cipher.update(data[, input_encoding][, output_encoding]) +### ECDH.computeSecret(other_public_key[, input_encoding][, output_encoding]) -Updates the cipher with `data`, the encoding of which is given in -`input_encoding` and can be `'utf8'`, `'ascii'` or `'binary'`. If no -encoding is provided, then a buffer is expected. -If `data` is a `Buffer` then `input_encoding` is ignored. +Computes the shared secret using `other_public_key` as the other +party's public key and returns the computed shared secret. Supplied +key is interpreted using specified `input_encoding`, and secret is +encoded using specified `output_encoding`. Encodings can be +`'binary'`, `'hex'`, or `'base64'`. If the input encoding is not +provided, then a buffer is expected. -The `output_encoding` specifies the output format of the enciphered -data, and can be `'binary'`, `'base64'` or `'hex'`. If no encoding is -provided, then a buffer is returned. +If no output encoding is given, then a buffer is returned. -Returns the enciphered contents, and can be called many times with new -data as it is streamed. +### ECDH.generateKeys([encoding[, format]]) -### cipher.final([output_encoding]) +Generates private and public EC Diffie-Hellman key values, and returns +the public key in the specified format and encoding. This key should be +transferred to the other party. -Returns any remaining enciphered contents, with `output_encoding` -being one of: `'binary'`, `'base64'` or `'hex'`. If no encoding is -provided, then a buffer is returned. +Format specifies point encoding and can be `'compressed'`, `'uncompressed'`, or +`'hybrid'`. If no format is provided - the point will be returned in +`'uncompressed'` format. -Note: `cipher` object can not be used after `final()` method has been -called. +Encoding can be `'binary'`, `'hex'`, or `'base64'`. If no encoding is provided, +then a buffer is returned. -### cipher.setAutoPadding(auto_padding=true) +### ECDH.getPrivateKey([encoding]) -You can disable automatic padding of the input data to block size. If -`auto_padding` is false, the length of the entire input data must be a -multiple of the cipher's block size or `final` will fail. Useful for -non-standard padding, e.g. using `0x0` instead of PKCS padding. You -must call this before `cipher.final`. +Returns the EC Diffie-Hellman private key in the specified encoding, +which can be `'binary'`, `'hex'`, or `'base64'`. If no encoding is +provided, then a buffer is returned. -### cipher.getAuthTag() +### ECDH.getPublicKey([encoding[, format]]) -For authenticated encryption modes (currently supported: GCM), this -method returns a `Buffer` that represents the _authentication tag_ that -has been computed from the given data. Should be called after -encryption has been completed using the `final` method! +Returns the EC Diffie-Hellman public key in the specified encoding and format. -### cipher.setAAD(buffer) +Format specifies point encoding and can be `'compressed'`, `'uncompressed'`, or +`'hybrid'`. If no format is provided - the point will be returned in +`'uncompressed'` format. -For authenticated encryption modes (currently supported: GCM), this -method sets the value used for the additional authenticated data (AAD) input -parameter. +Encoding can be `'binary'`, `'hex'`, or `'base64'`. If no encoding is provided, +then a buffer is returned. +### ECDH.setPrivateKey(private_key[, encoding]) -## crypto.createDecipher(algorithm, password) +Sets the EC Diffie-Hellman private key. Key encoding can be `'binary'`, +`'hex'` or `'base64'`. If no encoding is provided, then a buffer is +expected. -Creates and returns a decipher object, with the given algorithm and -key. This is the mirror of the [createCipher()][] above. +Example (obtaining a shared secret): -## crypto.createDecipheriv(algorithm, key, iv) + var crypto = require('crypto'); + var alice = crypto.createECDH('secp256k1'); + var bob = crypto.createECDH('secp256k1'); -Creates and returns a decipher object, with the given algorithm, key -and iv. This is the mirror of the [createCipheriv()][] above. + alice.generateKeys(); + bob.generateKeys(); -## Class: Decipher + var alice_secret = alice.computeSecret(bob.getPublicKey(), null, 'hex'); + var bob_secret = bob.computeSecret(alice.getPublicKey(), null, 'hex'); -Class for decrypting data. + /* alice_secret and bob_secret should be the same */ + console.log(alice_secret == bob_secret); -Returned by `crypto.createDecipher` and `crypto.createDecipheriv`. +### ECDH.setPublicKey(public_key[, encoding]) -Decipher objects are [streams](stream.html) that are both readable and -writable. The written enciphered data is used to produce the -plain-text data on the the readable side. The legacy `update` and -`final` methods are also supported. +Sets the EC Diffie-Hellman public key. Key encoding can be `'binary'`, +`'hex'` or `'base64'`. If no encoding is provided, then a buffer is +expected. -### decipher.update(data[, input_encoding][, output_encoding]) +## Class: Hash -Updates the decipher with `data`, which is encoded in `'binary'`, -`'base64'` or `'hex'`. If no encoding is provided, then a buffer is -expected. -If `data` is a `Buffer` then `input_encoding` is ignored. +The class for creating hash digests of data. -The `output_decoding` specifies in what format to return the -deciphered plaintext: `'binary'`, `'ascii'` or `'utf8'`. If no -encoding is provided, then a buffer is returned. +It is a [stream](stream.html) that is both readable and writable. The +written data is used to compute the hash. Once the writable side of +the stream is ended, use the `read()` method to get the computed hash +digest. The legacy `update` and `digest` methods are also supported. -### decipher.final([output_encoding]) +Returned by `crypto.createHash`. -Returns any remaining plaintext which is deciphered, with -`output_encoding` being one of: `'binary'`, `'ascii'` or `'utf8'`. If -no encoding is provided, then a buffer is returned. +### hash.digest([encoding]) -Note: `decipher` object can not be used after `final()` method has been +Calculates the digest of all of the passed data to be hashed. The +`encoding` can be `'hex'`, `'binary'` or `'base64'`. If no encoding +is provided, then a buffer is returned. + +Note: `hash` object can not be used after `digest()` method has been called. -### decipher.setAutoPadding(auto_padding=true) +### hash.update(data[, input_encoding]) -You can disable auto padding if the data has been encrypted without -standard block padding to prevent `decipher.final` from checking and -removing it. This will only work if the input data's length is a multiple of -the ciphers block size. You must call this before streaming data to -`decipher.update`. +Updates the hash content with the given `data`, the encoding of which +is given in `input_encoding` and can be `'utf8'`, `'ascii'` or +`'binary'`. If no encoding is provided, and the input is a string, an +encoding of `'binary'` is enforced. If `data` is a `Buffer` then +`input_encoding` is ignored. -### decipher.setAuthTag(buffer) +This can be called many times with new data as it is streamed. -For authenticated encryption modes (currently supported: GCM), this -method must be used to pass in the received _authentication tag_. -If no tag is provided or if the ciphertext has been tampered with, -`final` will throw, thus indicating that the ciphertext should -be discarded due to failed authentication. +## Class: Hmac -### decipher.setAAD(buffer) +Class for creating cryptographic hmac content. -For authenticated encryption modes (currently supported: GCM), this -method sets the value used for the additional authenticated data (AAD) input -parameter. +Returned by `crypto.createHmac`. +### hmac.digest([encoding]) -## crypto.createSign(algorithm) +Calculates the digest of all of the passed data to the hmac. The +`encoding` can be `'hex'`, `'binary'` or `'base64'`. If no encoding +is provided, then a buffer is returned. -Creates and returns a signing object, with the given algorithm. On -recent OpenSSL releases, `openssl list-public-key-algorithms` will -display the available signing algorithms. Examples are `'RSA-SHA256'`. +Note: `hmac` object can not be used after `digest()` method has been +called. + +### hmac.update(data) + +Update the hmac content with the given `data`. This can be called +many times with new data as it is streamed. ## Class: Sign @@ -359,11 +344,6 @@ used to generate the signature. Once all of the data has been written, the `sign` method will return the signature. The legacy `update` method is also supported. -### sign.update(data) - -Updates the sign object with data. This can be called many times -with new data as it is streamed. - ### sign.sign(private_key[, output_format]) Calculates the signature on all the updated data passed through the @@ -384,10 +364,10 @@ returned. Note: `sign` object can not be used after `sign()` method has been called. -## crypto.createVerify(algorithm) +### sign.update(data) -Creates and returns a verification object, with the given algorithm. -This is the mirror of the signing object above. +Updates the sign object with data. This can be called many times +with new data as it is streamed. ## Class: Verify @@ -421,11 +401,88 @@ the data and public key. Note: `verifier` object can not be used after `verify()` method has been called. -## crypto.createDiffieHellman(prime_length[, generator]) +## crypto.DEFAULT_ENCODING -Creates a Diffie-Hellman key exchange object and generates a prime of -`prime_length` bits and using an optional specific numeric `generator`. -If no `generator` is specified, then `2` is used. +The default encoding to use for functions that can take either strings +or buffers. The default value is `'buffer'`, which makes it default +to using Buffer objects. This is here to make the crypto module more +easily compatible with legacy programs that expected `'binary'` to be +the default encoding. + +Note that new programs will probably expect buffers, so only use this +as a temporary measure. + +## crypto.createCipher(algorithm, password) + +Creates and returns a cipher object, with the given algorithm and +password. + +`algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On +recent releases, `openssl list-cipher-algorithms` will display the +available cipher algorithms. `password` is used to derive key and IV, +which must be a `'binary'` encoded string or a [buffer](buffer.html). + +It is a [stream](stream.html) that is both readable and writable. The +written data is used to compute the hash. Once the writable side of +the stream is ended, use the `read()` method to get the enciphered +contents. The legacy `update` and `final` methods are also supported. + +Note: `createCipher` derives keys with the OpenSSL function [EVP_BytesToKey][] +with the digest algorithm set to MD5, one iteration, and no salt. The lack of +salt allows dictionary attacks as the same password always creates the same key. +The low iteration count and non-cryptographically secure hash algorithm allow +passwords to be tested very rapidly. + +In line with OpenSSL's recommendation to use pbkdf2 instead of EVP_BytesToKey it +is recommended you derive a key and iv yourself with [crypto.pbkdf2][] and to +then use [createCipheriv()][] to create the cipher stream. + +## crypto.createCipheriv(algorithm, key, iv) + +Creates and returns a cipher object, with the given algorithm, key and +iv. + +`algorithm` is the same as the argument to `createCipher()`. `key` is +the raw key used by the algorithm. `iv` is an [initialization +vector](http://en.wikipedia.org/wiki/Initialization_vector). + +`key` and `iv` must be `'binary'` encoded strings or +[buffers](buffer.html). + +## crypto.createCredentials(details) + + Stability: 0 - Deprecated: Use [tls.createSecureContext][] instead. + +Creates a credentials object, with the optional details being a +dictionary with keys: + +* `pfx` : A string or buffer holding the PFX or PKCS12 encoded private + key, certificate and CA certificates +* `key` : A string holding the PEM encoded private key +* `passphrase` : A string of passphrase for the private key or pfx +* `cert` : A string holding the PEM encoded certificate +* `ca` : Either a string or list of strings of PEM encoded CA + certificates to trust. +* `crl` : Either a string or list of strings of PEM encoded CRLs + (Certificate Revocation List) +* `ciphers`: A string describing the ciphers to use or exclude. + Consult + + for details on the format. + +If no 'ca' details are given, then Node.js will use the default +publicly trusted list of CAs as given in +. + +## crypto.createDecipher(algorithm, password) + +Creates and returns a decipher object, with the given algorithm and +key. This is the mirror of the [createCipher()][] above. + +## crypto.createDecipheriv(algorithm, key, iv) + +Creates and returns a decipher object, with the given algorithm, key +and iv. This is the mirror of the [createCipheriv()][] above. ## crypto.createDiffieHellman(prime[, prime_encoding][, generator][, generator_encoding]) @@ -437,76 +494,90 @@ If no `generator` is specified, then `2` is used. If no `prime_encoding` is specified, then a Buffer is expected for `prime`. If no `generator_encoding` is specified, then a Buffer is expected for `generator`. -## Class: DiffieHellman +## crypto.createDiffieHellman(prime_length[, generator]) -The class for creating Diffie-Hellman key exchanges. +Creates a Diffie-Hellman key exchange object and generates a prime of +`prime_length` bits and using an optional specific numeric `generator`. +If no `generator` is specified, then `2` is used. -Returned by `crypto.createDiffieHellman`. +## crypto.createECDH(curve_name) -### diffieHellman.verifyError +Creates an Elliptic Curve (EC) Diffie-Hellman key exchange object using a +predefined curve specified by the `curve_name` string. Use [getCurves()][] to +obtain a list of available curve names. On recent releases, +`openssl ecparam -list_curves` will also display the name and description of +each available elliptic curve. -A bit field containing any warnings and/or errors as a result of a check performed -during initialization. The following values are valid for this property -(defined in `constants` module): +## crypto.createHash(algorithm) -* `DH_CHECK_P_NOT_SAFE_PRIME` -* `DH_CHECK_P_NOT_PRIME` -* `DH_UNABLE_TO_CHECK_GENERATOR` -* `DH_NOT_SUITABLE_GENERATOR` +Creates and returns a hash object, a cryptographic hash with the given +algorithm which can be used to generate hash digests. -### diffieHellman.generateKeys([encoding]) +`algorithm` is dependent on the available algorithms supported by the +version of OpenSSL on the platform. Examples are `'sha256'`, +`'sha512'`, etc. On recent releases, `openssl +list-message-digest-algorithms` will display the available digest +algorithms. + +Example: this program that takes the sha256 sum of a file + + var filename = process.argv[2]; + var crypto = require('crypto'); + var fs = require('fs'); + + var shasum = crypto.createHash('sha256'); + + var s = fs.ReadStream(filename); + s.on('data', function(d) { + shasum.update(d); + }); + + s.on('end', function() { + var d = shasum.digest('hex'); + console.log(d + ' ' + filename); + }); -Generates private and public Diffie-Hellman key values, and returns -the public key in the specified encoding. This key should be -transferred to the other party. Encoding can be `'binary'`, `'hex'`, -or `'base64'`. If no encoding is provided, then a buffer is returned. +## crypto.createHmac(algorithm, key) -### diffieHellman.computeSecret(other_public_key[, input_encoding][, output_encoding]) +Creates and returns a hmac object, a cryptographic hmac with the given +algorithm and key. -Computes the shared secret using `other_public_key` as the other -party's public key and returns the computed shared secret. Supplied -key is interpreted using specified `input_encoding`, and secret is -encoded using specified `output_encoding`. Encodings can be -`'binary'`, `'hex'`, or `'base64'`. If the input encoding is not -provided, then a buffer is expected. +It is a [stream](stream.html) that is both readable and writable. The +written data is used to compute the hmac. Once the writable side of +the stream is ended, use the `read()` method to get the computed +digest. The legacy `update` and `digest` methods are also supported. -If no output encoding is given, then a buffer is returned. +`algorithm` is dependent on the available algorithms supported by +OpenSSL - see createHash above. `key` is the hmac key to be used. -### diffieHellman.getPrime([encoding]) +## crypto.createSign(algorithm) -Returns the Diffie-Hellman prime in the specified encoding, which can -be `'binary'`, `'hex'`, or `'base64'`. If no encoding is provided, -then a buffer is returned. +Creates and returns a signing object, with the given algorithm. On +recent OpenSSL releases, `openssl list-public-key-algorithms` will +display the available signing algorithms. Examples are `'RSA-SHA256'`. -### diffieHellman.getGenerator([encoding]) +## crypto.createVerify(algorithm) -Returns the Diffie-Hellman generator in the specified encoding, which can -be `'binary'`, `'hex'`, or `'base64'`. If no encoding is provided, -then a buffer is returned. +Creates and returns a verification object, with the given algorithm. +This is the mirror of the signing object above. -### diffieHellman.getPublicKey([encoding]) +## crypto.getCiphers() -Returns the Diffie-Hellman public key in the specified encoding, which -can be `'binary'`, `'hex'`, or `'base64'`. If no encoding is provided, -then a buffer is returned. +Returns an array with the names of the supported ciphers. -### diffieHellman.getPrivateKey([encoding]) +Example: -Returns the Diffie-Hellman private key in the specified encoding, -which can be `'binary'`, `'hex'`, or `'base64'`. If no encoding is -provided, then a buffer is returned. + var ciphers = crypto.getCiphers(); + console.log(ciphers); // ['aes-128-cbc', 'aes-128-ccm', ...] -### diffieHellman.setPublicKey(public_key[, encoding]) +## crypto.getCurves() -Sets the Diffie-Hellman public key. Key encoding can be `'binary'`, -`'hex'` or `'base64'`. If no encoding is provided, then a buffer is -expected. +Returns an array with the names of the supported elliptic curves. -### diffieHellman.setPrivateKey(private_key[, encoding]) +Example: -Sets the Diffie-Hellman private key. Key encoding can be `'binary'`, -`'hex'` or `'base64'`. If no encoding is provided, then a buffer is -expected. + var curves = crypto.getCurves(); + console.log(curves); // ['secp256k1', 'secp384r1', ...] ## crypto.getDiffieHellman(group_name) @@ -536,87 +607,14 @@ Example (obtaining a shared secret): /* alice_secret and bob_secret should be the same */ console.log(alice_secret == bob_secret); -## crypto.createECDH(curve_name) - -Creates an Elliptic Curve (EC) Diffie-Hellman key exchange object using a -predefined curve specified by the `curve_name` string. Use [getCurves()][] to -obtain a list of available curve names. On recent releases, -`openssl ecparam -list_curves` will also display the name and description of -each available elliptic curve. - -## Class: ECDH - -The class for creating EC Diffie-Hellman key exchanges. - -Returned by `crypto.createECDH`. - -### 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 -transferred to the other party. - -Format specifies point encoding and can be `'compressed'`, `'uncompressed'`, or -`'hybrid'`. If no format is provided - the point will be returned in -`'uncompressed'` format. - -Encoding can be `'binary'`, `'hex'`, or `'base64'`. If no encoding is provided, -then a buffer is returned. - -### 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. Supplied -key is interpreted using specified `input_encoding`, and secret is -encoded using specified `output_encoding`. Encodings can be -`'binary'`, `'hex'`, or `'base64'`. If the input encoding is not -provided, then a buffer is expected. - -If no output encoding is given, then a buffer is returned. - -### ECDH.getPublicKey([encoding[, format]]) - -Returns the EC Diffie-Hellman public key in the specified encoding and format. - -Format specifies point encoding and can be `'compressed'`, `'uncompressed'`, or -`'hybrid'`. If no format is provided - the point will be returned in -`'uncompressed'` format. - -Encoding can be `'binary'`, `'hex'`, or `'base64'`. If no encoding is provided, -then a buffer is returned. - -### ECDH.getPrivateKey([encoding]) - -Returns the EC Diffie-Hellman private key in the specified encoding, -which can be `'binary'`, `'hex'`, or `'base64'`. If no encoding is -provided, then a buffer is returned. - -### ECDH.setPublicKey(public_key[, encoding]) - -Sets the EC Diffie-Hellman public key. Key encoding can be `'binary'`, -`'hex'` or `'base64'`. If no encoding is provided, then a buffer is -expected. - -### ECDH.setPrivateKey(private_key[, encoding]) - -Sets the EC Diffie-Hellman private key. Key encoding can be `'binary'`, -`'hex'` or `'base64'`. If no encoding is provided, then a buffer is -expected. - -Example (obtaining a shared secret): - - var crypto = require('crypto'); - var alice = crypto.createECDH('secp256k1'); - var bob = crypto.createECDH('secp256k1'); +## crypto.getHashes() - alice.generateKeys(); - bob.generateKeys(); +Returns an array with the names of the supported hash algorithms. - var alice_secret = alice.computeSecret(bob.getPublicKey(), null, 'hex'); - var bob_secret = bob.computeSecret(alice.getPublicKey(), null, 'hex'); +Example: - /* alice_secret and bob_secret should be the same */ - console.log(alice_secret == bob_secret); + var hashes = crypto.getHashes(); + console.log(hashes); // ['sha', 'sha1', 'sha1WithRSAEncryption', ...] ## crypto.pbkdf2(password, salt, iterations, keylen[, digest], callback) @@ -640,44 +638,33 @@ You can get a list of supported digest functions with Synchronous PBKDF2 function. Returns derivedKey or throws error. -## crypto.randomBytes(size[, callback]) - -Generates cryptographically strong pseudo-random data. Usage: - - // async - crypto.randomBytes(256, function(ex, buf) { - if (ex) throw ex; - console.log('Have %d bytes of random data: %s', buf.length, buf); - }); - - // sync - const buf = crypto.randomBytes(256); - console.log('Have %d bytes of random data: %s', buf.length, buf); - -NOTE: This will block if there is insufficient entropy, although it should -normally never take longer than a few milliseconds. The only time when this -may conceivably block is right after boot, when the whole system is still -low on entropy. +## crypto.privateDecrypt(private_key, buffer) -## Class: Certificate +Decrypts `buffer` with `private_key`. -The class used for working with signed public key & challenges. The most -common usage for this series of functions is when dealing with the `` -element. http://www.openssl.org/docs/apps/spkac.html +`private_key` can be an object or a string. If `private_key` is a string, it is +treated as the key with no passphrase and will use `RSA_PKCS1_OAEP_PADDING`. -Returned by `crypto.Certificate`. +`private_key`: -### Certificate.verifySpkac(spkac) +* `key` : A string holding the PEM encoded private key +* `passphrase` : An optional string of passphrase for the private key +* `padding` : An optional padding value, one of the following: + * `constants.RSA_NO_PADDING` + * `constants.RSA_PKCS1_PADDING` + * `constants.RSA_PKCS1_OAEP_PADDING` -Returns true of false based on the validity of the SPKAC. +NOTE: All paddings are defined in `constants` module. -### Certificate.exportChallenge(spkac) +## crypto.privateEncrypt(private_key, buffer) -Exports the encoded challenge associated with the SPKAC. +See above for details. Has the same API as `crypto.privateDecrypt`. +Default padding is `RSA_PKCS1_PADDING`. -### Certificate.exportPublicKey(spkac) +## crypto.publicDecrypt(public_key, buffer) -Exports the encoded public key from the supplied SPKAC. +See above for details. Has the same API as `crypto.publicEncrypt`. Default +padding is `RSA_PKCS1_PADDING`. ## crypto.publicEncrypt(public_key, buffer) @@ -699,44 +686,47 @@ key to this method. NOTE: All paddings are defined in `constants` module. -## crypto.publicDecrypt(public_key, buffer) - -See above for details. Has the same API as `crypto.publicEncrypt`. Default -padding is `RSA_PKCS1_PADDING`. - -## crypto.privateDecrypt(private_key, buffer) - -Decrypts `buffer` with `private_key`. +## crypto.randomBytes(size[, callback]) -`private_key` can be an object or a string. If `private_key` is a string, it is -treated as the key with no passphrase and will use `RSA_PKCS1_OAEP_PADDING`. +Generates cryptographically strong pseudo-random data. Usage: -`private_key`: + // async + crypto.randomBytes(256, function(ex, buf) { + if (ex) throw ex; + console.log('Have %d bytes of random data: %s', buf.length, buf); + }); -* `key` : A string holding the PEM encoded private key -* `passphrase` : An optional string of passphrase for the private key -* `padding` : An optional padding value, one of the following: - * `constants.RSA_NO_PADDING` - * `constants.RSA_PKCS1_PADDING` - * `constants.RSA_PKCS1_OAEP_PADDING` + // sync + const buf = crypto.randomBytes(256); + console.log('Have %d bytes of random data: %s', buf.length, buf); -NOTE: All paddings are defined in `constants` module. +NOTE: This will block if there is insufficient entropy, although it should +normally never take longer than a few milliseconds. The only time when this +may conceivably block is right after boot, when the whole system is still +low on entropy. -## crypto.privateEncrypt(private_key, buffer) +## crypto.setEngine(engine[, flags]) -See above for details. Has the same API as `crypto.privateDecrypt`. -Default padding is `RSA_PKCS1_PADDING`. +Load and set engine for some/all OpenSSL functions (selected by flags). -## crypto.DEFAULT_ENCODING +`engine` could be either an id or a path to the engine's shared library. -The default encoding to use for functions that can take either strings -or buffers. The default value is `'buffer'`, which makes it default -to using Buffer objects. This is here to make the crypto module more -easily compatible with legacy programs that expected `'binary'` to be -the default encoding. +`flags` is optional and has `ENGINE_METHOD_ALL` value by default. It could take +one of or mix of following flags (defined in `constants` module): -Note that new programs will probably expect buffers, so only use this -as a temporary measure. +* `ENGINE_METHOD_RSA` +* `ENGINE_METHOD_DSA` +* `ENGINE_METHOD_DH` +* `ENGINE_METHOD_RAND` +* `ENGINE_METHOD_ECDH` +* `ENGINE_METHOD_ECDSA` +* `ENGINE_METHOD_CIPHERS` +* `ENGINE_METHOD_DIGESTS` +* `ENGINE_METHOD_STORE` +* `ENGINE_METHOD_PKEY_METH` +* `ENGINE_METHOD_PKEY_ASN1_METH` +* `ENGINE_METHOD_ALL` +* `ENGINE_METHOD_NONE` ## Recent API Changes