X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=doc%2Fapi%2Fcrypto.markdown;h=04d7af6a16833427d12db9bcf2aab3c0fd5ca6f3;hb=4be432862ae5fc48dfd3814b1af389a4c2dfc390;hp=d862f371a58b357cb43f808dc471f7216f392769;hpb=6561274d2377d9fd9c55fa3ce2eb2e53c14d898e;p=platform%2Fupstream%2Fnodejs.git diff --git a/doc/api/crypto.markdown b/doc/api/crypto.markdown index d862f37..04d7af6 100644 --- a/doc/api/crypto.markdown +++ b/doc/api/crypto.markdown @@ -1,7 +1,6 @@ # Crypto - Stability: 2 - Unstable; API changes are being discussed for - future versions. Breaking changes will be minimized. See below. + Stability: 2 - Stable Use `require('crypto')` to access this module. @@ -16,7 +15,7 @@ decipher, sign and verify methods. 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. +`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): @@ -43,7 +42,7 @@ Returns an array with the names of the supported ciphers. Example: var ciphers = crypto.getCiphers(); - console.log(ciphers); // ['AES-128-CBC', 'AES-128-CBC-HMAC-SHA1', ...] + console.log(ciphers); // ['aes-128-cbc', 'aes-128-ccm', ...] ## crypto.getHashes() @@ -56,9 +55,19 @@ Example: console.log(hashes); // ['sha', 'sha1', 'sha1WithRSAEncryption', ...] +## crypto.getCurves() + +Returns an array with the names of the supported elliptic curves. + +Example: + + var curves = crypto.getCurves(); + console.log(curves); // ['secp256k1', 'secp384r1', ...] + + ## 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: @@ -77,7 +86,7 @@ dictionary with keys: for details on the format. -If no 'ca' details are given, then node.js will use the default +If no 'ca' details are given, then Node.js will use the default publicly trusted list of CAs as given in . @@ -126,7 +135,7 @@ Returned by `crypto.createHash`. 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 +`'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. @@ -314,7 +323,7 @@ called. You can disable auto padding if the data has been encrypted without standard block padding to prevent `decipher.final` from checking and -removing it. Can only work if the input data's length is a multiple of +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`. @@ -529,8 +538,11 @@ Example (obtaining a shared secret): ## crypto.createECDH(curve_name) -Creates a Elliptic Curve (EC) Diffie-Hellman key exchange object using a -predefined curve specified by `curve_name` string. +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 @@ -609,13 +621,13 @@ Example (obtaining a shared 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, +(default: SHA1) to derive a key of the requested byte 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) { + crypto.pbkdf2('secret', 'salt', 4096, 64, 'sha256', function(err, key) { if (err) throw err; console.log(key.toString('hex')); // 'c5e478d...1469e50' @@ -639,13 +651,8 @@ Generates cryptographically strong pseudo-random data. Usage: }); // sync - try { - var buf = crypto.randomBytes(256); - console.log('Have %d bytes of random data: %s', buf.length, buf); - } catch (ex) { - // handle error - // most likely, entropy sources are drained - } + 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 @@ -692,6 +699,11 @@ 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`. @@ -715,11 +727,6 @@ NOTE: All paddings are defined in `constants` module. 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 @@ -733,12 +740,12 @@ as a temporary measure. ## Recent API Changes -The Crypto module was added to Node before there was the concept of a +The Crypto module was added to Node.js before there was the concept of a unified Stream API, and before there were Buffer objects for handling binary data. As such, the streaming classes don't have the typical methods found on -other Node classes, and many methods accepted and returned +other Node.js classes, and many methods accepted and returned Binary-encoded strings by default rather than Buffers. This was changed to use Buffers by default instead. @@ -764,10 +771,11 @@ temporary measure. [createCipher()]: #crypto_crypto_createcipher_algorithm_password [createCipheriv()]: #crypto_crypto_createcipheriv_algorithm_key_iv -[crypto.createDiffieHellman()]: #crypto_crypto_creatediffiehellman_prime_encoding +[getCurves()]: #crypto_crypto_getcurves +[crypto.createDiffieHellman()]: #crypto_crypto_creatediffiehellman_prime_prime_encoding_generator_generator_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 +[crypto.pbkdf2]: #crypto_crypto_pbkdf2_password_salt_iterations_keylen_digest_callback [EVP_BytesToKey]: https://www.openssl.org/docs/crypto/EVP_BytesToKey.html