docs: add note about default padding in crypto

[platform/upstream/nodejs.git] / doc / api / crypto.markdown

diff --git a/doc/api/crypto.markdown b/doc/api/crypto.markdown
index 0359d9a..2c8714f 100644 (file)
--- a/doc/api/crypto.markdown
+++ b/doc/api/crypto.markdown
@@ -58,7 +58,7 @@ Example:
 
 ## crypto.createCredentials(details)
 
-Stability: 0 - Deprecated. Use [tls.createSecureContext][] instead.
+    Stability: 0 - Deprecated. Use [tls.createSecureContext][] instead.
 
 Creates a credentials object, with the optional details being a
 dictionary with keys:
@@ -191,6 +191,16 @@ 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
@@ -214,7 +224,7 @@ 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.
 
-### 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
@@ -280,7 +290,7 @@ 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.
 
-### 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
@@ -408,7 +418,7 @@ 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.
 
-## crypto.createDiffieHellman(prime[, prime_encoding]\[, generator]\[, generator_encoding])
+## crypto.createDiffieHellman(prime[, prime_encoding][, generator][, generator_encoding])
 
 Creates a Diffie-Hellman key exchange object using the supplied `prime` and an
 optional specific `generator`.
@@ -442,7 +452,7 @@ 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.
 
-### 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
@@ -541,7 +551,7 @@ Format specifies point encoding and can be `'compressed'`, `'uncompressed'`, or
 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])
+### 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
@@ -637,20 +647,10 @@ Generates cryptographically strong pseudo-random data. Usage:
       // most likely, entropy sources are drained
     }
 
-NOTE: Will throw error or invoke callback with error, if there is not enough
-accumulated entropy to generate cryptographically strong data. In other words,
-`crypto.randomBytes` without callback will not block even if all entropy sources
-are drained.
-
-## crypto.pseudoRandomBytes(size[, callback])
-
-Generates *non*-cryptographically strong pseudo-random data. The data
-returned will be unique if it is sufficiently long, but is not
-necessarily unpredictable. For this reason, the output of this
-function should never be used where unpredictability is important,
-such as in the generation of encryption keys.
-
-Usage is otherwise identical to `crypto.randomBytes`.
+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
 
@@ -707,6 +707,16 @@ treated as the key with no passphrase and will use `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
@@ -756,3 +766,5 @@ temporary measure.
 [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