decipher, sign and verify methods.
+## 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 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()
Returns an array with the names of the supported ciphers.
Example:
var ciphers = crypto.getCiphers();
- console.log(ciphers); // ['AES128-SHA', 'AES256-SHA', ...]
+ console.log(ciphers); // ['AES-128-CBC', 'AES-128-CBC-HMAC-SHA1', ...]
## crypto.getHashes()
## crypto.createCredentials(details)
+ Stability: 0 - Deprecated. Use [tls.createSecureContext][] instead.
+
Creates a credentials object, with the optional details being a
dictionary with keys:
Returned by `crypto.createHash`.
-### hash.update(data, [input_encoding])
+### 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
-`'binary'`. If no encoding is provided, then a buffer is expected.
+`'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.
This can be called many times with new data as it is streamed.
`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 been
+Note: `hash` object can not be used after `digest()` method has been
called.
`encoding` can be `'hex'`, `'binary'` or `'base64'`. If no encoding
is provided, then a buffer is returned.
-Note: `hmac` object can not be used after `digest()` method been
+Note: `hmac` object can not be used after `digest()` method has been
called.
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.
+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)
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 the readable side. The legacy `update` and
-`final` methods are also supported.
+encrypted data on the readable side. The legacy `update` and `final`
+methods are also supported.
-### cipher.update(data, [input_encoding], [output_encoding])
+### cipher.update(data[, 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.
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 iis returned.
+provided, then a buffer is returned.
Returns the enciphered contents, and can be called many times with new
data as it is streamed.
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 been
+Note: `cipher` object can not be used after `final()` method has been
called.
### cipher.setAutoPadding(auto_padding=true)
non-standard padding, e.g. using `0x0` instead of PKCS padding. You
must call this before `cipher.final`.
+### cipher.getAuthTag()
+
+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!
+
+### cipher.setAAD(buffer)
+
+For authenticated encryption modes (currently supported: GCM), this
+method sets the value used for the additional authenticated data (AAD) input
+parameter.
+
## crypto.createDecipher(algorithm, password)
plain-text data on the the readable side. The legacy `update` and
`final` methods are also supported.
-### decipher.update(data, [input_encoding], [output_encoding])
+### 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.
The `output_decoding` specifies in what format to return the
deciphered plaintext: `'binary'`, `'ascii'` or `'utf8'`. If no
`output_encoding` being one of: `'binary'`, `'ascii'` or `'utf8'`. If
no encoding is provided, then a buffer is returned.
-Note: `decipher` object can not be used after `final()` method been
+Note: `decipher` object can not be used after `final()` method has been
called.
### decipher.setAutoPadding(auto_padding=true)
the ciphers block size. You must call this before streaming data to
`decipher.update`.
+### decipher.setAuthTag(buffer)
+
+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.
+
+### decipher.setAAD(buffer)
+
+For authenticated encryption modes (currently supported: GCM), this
+method sets the value used for the additional authenticated data (AAD) input
+parameter.
+
+
## crypto.createSign(algorithm)
Creates and returns a signing object, with the given algorithm. On
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])
+### sign.sign(private_key[, output_format])
Calculates the signature on all the updated data passed through the
-sign. `private_key` is a string containing the PEM encoded private
-key for signing.
+sign.
+
+`private_key` can be an object or a string. If `private_key` is a string, it is
+treated as the key with no passphrase.
+
+`private_key`:
+
+* `key` : A string holding the PEM encoded private key
+* `passphrase` : A string of passphrase for the private key
Returns the signature in `output_format` which can be `'binary'`,
`'hex'` or `'base64'`. If no encoding is provided, then a buffer is
returned.
-Note: `sign` object can not be used after `sign()` method been
+Note: `sign` object can not be used after `sign()` method has been
called.
## crypto.createVerify(algorithm)
Updates the verifier object with data. This can be called many times
with new data as it is streamed.
-### verifier.verify(object, signature, [signature_format])
+### verifier.verify(object, signature[, signature_format])
Verifies the signed data by using the `object` and `signature`.
`object` is a string containing a PEM encoded object, which can be
Returns true or false depending on the validity of the signature for
the data and public key.
-Note: `verifier` object can not be used after `verify()` method been
+Note: `verifier` object can not be used after `verify()` method has been
called.
-## crypto.createDiffieHellman(prime_length)
+## crypto.createDiffieHellman(prime_length[, generator])
Creates a Diffie-Hellman key exchange object and generates a prime of
-the given bit length. The generator used is `2`.
+`prime_length` bits and using an optional specific numeric `generator`.
+If no `generator` is specified, then `2` is used.
-## crypto.createDiffieHellman(prime, [encoding])
+## crypto.createDiffieHellman(prime[, prime_encoding][, generator][, generator_encoding])
-Creates a Diffie-Hellman key exchange object using the supplied prime.
-The generator used is `2`. Encoding can be `'binary'`, `'hex'`, or
-`'base64'`. If no encoding is specified, then a buffer is expected.
+Creates a Diffie-Hellman key exchange object using the supplied `prime` and an
+optional specific `generator`.
+`generator` can be a number, string, or Buffer.
+If no `generator` is specified, then `2` is used.
+`prime_encoding` and `generator_encoding` can be `'binary'`, `'hex'`, or `'base64'`.
+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
Returned by `crypto.createDiffieHellman`.
+### diffieHellman.verifyError
+
+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):
+
+* `DH_CHECK_P_NOT_SAFE_PRIME`
+* `DH_CHECK_P_NOT_PRIME`
+* `DH_UNABLE_TO_CHECK_GENERATOR`
+* `DH_NOT_SUITABLE_GENERATOR`
+
### diffieHellman.generateKeys([encoding])
Generates private and public Diffie-Hellman key values, and returns
transferred to the other party. Encoding can be `'binary'`, `'hex'`,
or `'base64'`. If no encoding is provided, then a buffer is returned.
-### diffieHellman.computeSecret(other_public_key, [input_encoding], [output_encoding])
+### 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. Supplied
### diffieHellman.getGenerator([encoding])
-Returns the Diffie-Hellman prime in the specified encoding, which can
+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.
which can be `'binary'`, `'hex'`, or `'base64'`. If no encoding is
provided, then a buffer is returned.
-### diffieHellman.setPublicKey(public_key, [encoding])
+### diffieHellman.setPublicKey(public_key[, encoding])
Sets the Diffie-Hellman public key. Key encoding can be `'binary'`,
`'hex'` or `'base64'`. If no encoding is provided, then a buffer is
expected.
-### diffieHellman.setPrivateKey(private_key, [encoding])
+### diffieHellman.setPrivateKey(private_key[, encoding])
Sets the Diffie-Hellman private key. Key encoding can be `'binary'`,
`'hex'` or `'base64'`. If no encoding is provided, then a buffer is
/* alice_secret and bob_secret should be the same */
console.log(alice_secret == bob_secret);
-## crypto.pbkdf2(password, salt, iterations, keylen, callback)
+## crypto.createECDH(curve_name)
+
+Creates a Elliptic Curve (EC) Diffie-Hellman key exchange object using a
+predefined curve specified by `curve_name` string.
+
+## 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]])
-Asynchronous PBKDF2 applies pseudorandom function HMAC-SHA1 to derive
-a key of given length from the given password, salt and iterations.
-The callback gets two arguments `(err, derivedKey)`.
+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.
-## crypto.pbkdf2Sync(password, salt, iterations, keylen)
+### 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');
+
+ alice.generateKeys();
+ bob.generateKeys();
+
+ var alice_secret = alice.computeSecret(bob.getPublicKey(), null, 'hex');
+ var bob_secret = bob.computeSecret(alice.getPublicKey(), null, 'hex');
+
+ /* alice_secret and bob_secret should be the same */
+ console.log(alice_secret == bob_secret);
+
+## crypto.pbkdf2(password, salt, iterations, keylen[, digest], callback)
+
+Asynchronous PBKDF2 function. Applies the selected HMAC digest function
+(default: SHA1) to derive a key of the requested length from the password,
+salt and number of iterations. The callback gets two arguments:
+`(err, derivedKey)`.
+
+Example:
+
+ crypto.pbkdf2('secret', 'salt', 4096, 512, 'sha256', function(err, key) {
+ if (err)
+ throw err;
+ console.log(key.toString('hex')); // 'c5e478d...1469e50'
+ });
+
+You can get a list of supported digest functions with
+[crypto.getHashes()](#crypto_crypto_gethashes).
+
+## crypto.pbkdf2Sync(password, salt, iterations, keylen[, digest])
Synchronous PBKDF2 function. Returns derivedKey or throws error.
-## crypto.randomBytes(size, [callback])
+## crypto.randomBytes(size[, callback])
Generates cryptographically strong pseudo-random data. Usage:
console.log('Have %d bytes of random data: %s', buf.length, buf);
} catch (ex) {
// handle error
+ // most likely, entropy sources are drained
}
+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.
+
+## Class: Certificate
+
+The class used for working with signed public key & challenges. The most
+common usage for this series of functions is when dealing with the `<keygen>`
+element. http://www.openssl.org/docs/apps/spkac.html
+
+Returned by `crypto.Certificate`.
+
+### Certificate.verifySpkac(spkac)
+
+Returns true of false based on the validity of the SPKAC.
+
+### Certificate.exportChallenge(spkac)
+
+Exports the encoded public key from the supplied SPKAC.
+
+### Certificate.exportPublicKey(spkac)
+
+Exports the encoded challenge associated with the SPKAC.
+
+## crypto.publicEncrypt(public_key, buffer)
+
+Encrypts `buffer` with `public_key`. Only RSA is currently supported.
+
+`public_key` can be an object or a string. If `public_key` is a string, it is
+treated as the key with no passphrase and will use `RSA_PKCS1_OAEP_PADDING`.
+
+`public_key`:
+
+* `key` : A string holding the PEM encoded private key
+* `padding` : An optional padding value, one of the following:
+ * `constants.RSA_NO_PADDING`
+ * `constants.RSA_PKCS1_PADDING`
+ * `constants.RSA_PKCS1_OAEP_PADDING`
+
+NOTE: All paddings are defined in `constants` module.
+
+## crypto.privateDecrypt(private_key, buffer)
+
+Decrypts `buffer` with `private_key`.
+
+`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`.
+
+`private_key`:
+
+* `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`
+
+NOTE: All paddings are defined in `constants` module.
+
+## crypto.privateEncrypt(private_key, buffer)
+
+See above for details. Has the same API as `crypto.privateDecrypt`.
+Default padding is `RSA_PKCS1_PADDING`.
+
+## crypto.publicDecrypt(public_key, buffer)
+
+See above for details. Has the same API as `crypto.publicEncrypt`. Default
+padding is `RSA_PKCS1_PADDING`.
+
## crypto.DEFAULT_ENCODING
The default encoding to use for functions that can take either strings
[createCipher()]: #crypto_crypto_createcipher_algorithm_password
[createCipheriv()]: #crypto_crypto_createcipheriv_algorithm_key_iv
[crypto.createDiffieHellman()]: #crypto_crypto_creatediffiehellman_prime_encoding
+[tls.createSecureContext]: tls.html#tls_tls_createsecurecontext_details
[diffieHellman.setPublicKey()]: #crypto_diffiehellman_setpublickey_public_key_encoding
[RFC 2412]: http://www.rfc-editor.org/rfc/rfc2412.txt
[RFC 3526]: http://www.rfc-editor.org/rfc/rfc3526.txt
+[crypto.pbkdf2]: #crypto_crypto_pbkdf2_password_salt_iterations_keylen_callback
+[EVP_BytesToKey]: https://www.openssl.org/docs/crypto/EVP_BytesToKey.html
projects / platform / upstream / nodejs.git / blobdiff