diff options
author | Rich Trott <rtrott@gmail.com> | 2021-10-11 07:55:04 +0300 |
---|---|---|
committer | Antoine du Hamel <duhamelantoine1995@gmail.com> | 2021-10-20 12:59:11 +0300 |
commit | d0b58c0287e67a139137aa906819d95f8314b093 (patch) | |
tree | e9a92870138d89b608b1c6e6568611744c32c4f2 /doc/api/crypto.md | |
parent | a7c17e08de658cbc0beefd8e9583803b5a62ac7e (diff) |
doc: format doc/api/*.md with markdown formatter
PR-URL: https://github.com/nodejs/node/pull/40403
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Zijian Liu <lxxyxzj@gmail.com>
Reviewed-By: Michaƫl Zasso <targos@protonmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Diffstat (limited to 'doc/api/crypto.md')
-rw-r--r-- | doc/api/crypto.md | 186 |
1 files changed, 174 insertions, 12 deletions
diff --git a/doc/api/crypto.md b/doc/api/crypto.md index b01203493b0..7a64303fd65 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -52,7 +52,7 @@ try { When using the lexical ESM `import` keyword, the error can only be caught if a handler for `process.on('uncaughtException')` is registered -*before* any attempt to load the module is made -- using, for instance, +_before_ any attempt to load the module is made -- using, for instance, a preload module. When using ESM, if there is a chance that the code may be run on a build @@ -69,6 +69,7 @@ try { ``` ## Class: `Certificate` + <!-- YAML added: v0.11.8 --> @@ -84,6 +85,7 @@ data. The most common usage is handling output generated by the HTML5 `<keygen>` element. Node.js uses [OpenSSL's SPKAC implementation][] internally. ### Static method: `Certificate.exportChallenge(spkac[, encoding])` + <!-- YAML added: v9.0.0 changes: @@ -115,6 +117,7 @@ console.log(challenge.toString('utf8')); ``` ### Static method: `Certificate.exportPublicKey(spkac[, encoding])` + <!-- YAML added: v9.0.0 changes: @@ -146,6 +149,7 @@ console.log(publicKey); ``` ### Static method: `Certificate.verifySpkac(spkac[, encoding])` + <!-- YAML added: v9.0.0 changes: @@ -206,6 +210,7 @@ const cert2 = Certificate(); ``` #### `certificate.exportChallenge(spkac[, encoding])` + <!-- YAML added: v0.11.8 --> @@ -234,6 +239,7 @@ console.log(challenge.toString('utf8')); ``` #### `certificate.exportPublicKey(spkac[, encoding])` + <!-- YAML added: v0.11.8 --> @@ -262,6 +268,7 @@ console.log(publicKey); ``` #### `certificate.verifySpkac(spkac[, encoding])` + <!-- YAML added: v0.11.8 --> @@ -292,6 +299,7 @@ console.log(cert.verifySpkac(Buffer.from(spkac))); ``` ## Class: `Cipher` + <!-- YAML added: v0.1.94 --> @@ -515,6 +523,7 @@ scrypt(password, 'salt', 24, (err, key) => { ``` ### `cipher.final([outputEncoding])` + <!-- YAML added: v0.1.94 --> @@ -529,6 +538,7 @@ longer be used to encrypt data. Attempts to call `cipher.final()` more than once will result in an error being thrown. ### `cipher.getAuthTag()` + <!-- YAML added: v1.0.0 --> @@ -542,6 +552,7 @@ The `cipher.getAuthTag()` method should only be called after encryption has been completed using the [`cipher.final()`][] method. ### `cipher.setAAD(buffer[, options])` + <!-- YAML added: v1.0.0 --> @@ -563,6 +574,7 @@ length of the plaintext in bytes. See [CCM mode][]. The `cipher.setAAD()` method must be called before [`cipher.update()`][]. ### `cipher.setAutoPadding([autoPadding])` + <!-- YAML added: v0.7.1 --> @@ -583,6 +595,7 @@ The `cipher.setAutoPadding()` method must be called before [`cipher.final()`][]. ### `cipher.update(data[, inputEncoding][, outputEncoding])` + <!-- YAML added: v0.1.94 changes: @@ -613,6 +626,7 @@ The `cipher.update()` method can be called multiple times with new data until [`cipher.final()`][] will result in an error being thrown. ## Class: `Decipher` + <!-- YAML added: v0.1.94 --> @@ -812,6 +826,7 @@ console.log(decrypted); ``` ### `decipher.final([outputEncoding])` + <!-- YAML added: v0.1.94 --> @@ -826,6 +841,7 @@ 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[, options])` + <!-- YAML added: v1.0.0 changes: @@ -858,6 +874,7 @@ When passing a string as the `buffer`, please consider [caveats when using strings as inputs to cryptographic APIs][]. ### `decipher.setAuthTag(buffer[, encoding])` + <!-- YAML added: v1.0.0 changes: @@ -893,6 +910,7 @@ When passing a string as the authentication tag, please consider [caveats when using strings as inputs to cryptographic APIs][]. ### `decipher.setAutoPadding([autoPadding])` + <!-- YAML added: v0.7.1 --> @@ -911,6 +929,7 @@ The `decipher.setAutoPadding()` method must be called before [`decipher.final()`][]. ### `decipher.update(data[, inputEncoding][, outputEncoding])` + <!-- YAML added: v0.1.94 changes: @@ -940,6 +959,7 @@ The `decipher.update()` method can be called multiple times with new data until [`decipher.final()`][] will result in an error being thrown. ## Class: `DiffieHellman` + <!-- YAML added: v0.5.0 --> @@ -997,6 +1017,7 @@ assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex')); ``` ### `diffieHellman.computeSecret(otherPublicKey[, inputEncoding][, outputEncoding])` + <!-- YAML added: v0.5.0 --> @@ -1018,6 +1039,7 @@ If `outputEncoding` is given a string is returned; otherwise, a [`Buffer`][] is returned. ### `diffieHellman.generateKeys([encoding])` + <!-- YAML added: v0.5.0 --> @@ -1032,6 +1054,7 @@ If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. ### `diffieHellman.getGenerator([encoding])` + <!-- YAML added: v0.5.0 --> @@ -1044,6 +1067,7 @@ If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. ### `diffieHellman.getPrime([encoding])` + <!-- YAML added: v0.5.0 --> @@ -1056,6 +1080,7 @@ If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. ### `diffieHellman.getPrivateKey([encoding])` + <!-- YAML added: v0.5.0 --> @@ -1068,6 +1093,7 @@ If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. ### `diffieHellman.getPublicKey([encoding])` + <!-- YAML added: v0.5.0 --> @@ -1080,6 +1106,7 @@ If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. ### `diffieHellman.setPrivateKey(privateKey[, encoding])` + <!-- YAML added: v0.5.0 --> @@ -1093,6 +1120,7 @@ to be a string. If no `encoding` is provided, `privateKey` is expected to be a [`Buffer`][], `TypedArray`, or `DataView`. ### `diffieHellman.setPublicKey(publicKey[, encoding])` + <!-- YAML added: v0.5.0 --> @@ -1106,6 +1134,7 @@ to be a string. If no `encoding` is provided, `publicKey` is expected to be a [`Buffer`][], `TypedArray`, or `DataView`. ### `diffieHellman.verifyError` + <!-- YAML added: v0.11.12 --> @@ -1122,6 +1151,7 @@ module): * `DH_NOT_SUITABLE_GENERATOR` ## Class: `DiffieHellmanGroup` + <!-- YAML added: v0.7.5 --> @@ -1157,6 +1187,7 @@ modp18 ``` ## Class: `ECDH` + <!-- YAML added: v0.11.14 --> @@ -1214,6 +1245,7 @@ assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex')); ``` ### Static method: `ECDH.convertKey(key, curve[, inputEncoding[, outputEncoding[, format]]])` + <!-- YAML added: v10.0.0 --> @@ -1286,6 +1318,7 @@ console.log(uncompressedKey === ecdh.getPublicKey('hex')); ``` ### `ecdh.computeSecret(otherPublicKey[, inputEncoding][, outputEncoding])` + <!-- YAML added: v0.11.14 changes: @@ -1321,6 +1354,7 @@ usually supplied from a remote user over an insecure network, be sure to handle this exception accordingly. ### `ecdh.generateKeys([encoding[, format]])` + <!-- YAML added: v0.11.14 --> @@ -1341,6 +1375,7 @@ If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. ### `ecdh.getPrivateKey([encoding])` + <!-- YAML added: v0.11.14 --> @@ -1352,6 +1387,7 @@ If `encoding` is specified, a string is returned; otherwise a [`Buffer`][] is returned. ### `ecdh.getPublicKey([encoding][, format])` + <!-- YAML added: v0.11.14 --> @@ -1369,6 +1405,7 @@ If `encoding` is specified, a string is returned; otherwise a [`Buffer`][] is returned. ### `ecdh.setPrivateKey(privateKey[, encoding])` + <!-- YAML added: v0.11.14 --> @@ -1386,6 +1423,7 @@ 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(publicKey[, encoding])` + <!-- YAML added: v0.11.14 deprecated: v5.2.0 @@ -1464,6 +1502,7 @@ console.log(aliceSecret === bobSecret); ``` ## Class: `Hash` + <!-- YAML added: v0.1.92 --> @@ -1580,6 +1619,7 @@ console.log(hash.digest('hex')); ``` ### `hash.copy([options])` + <!-- YAML added: v13.1.0 --> @@ -1638,6 +1678,7 @@ console.log(hash.copy().digest('hex')); ``` ### `hash.digest([encoding])` + <!-- YAML added: v0.1.92 --> @@ -1654,6 +1695,7 @@ 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[, inputEncoding])` + <!-- YAML added: v0.1.92 changes: @@ -1674,6 +1716,7 @@ encoding of `'utf8'` is enforced. If `data` is a [`Buffer`][], `TypedArray`, or This can be called many times with new data as it is streamed. ## Class: `Hmac` + <!-- YAML added: v0.1.94 --> @@ -1796,6 +1839,7 @@ console.log(hmac.digest('hex')); ``` ### `hmac.digest([encoding])` + <!-- YAML added: v0.1.94 --> @@ -1811,6 +1855,7 @@ 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[, inputEncoding])` + <!-- YAML added: v0.1.94 changes: @@ -1831,6 +1876,7 @@ encoding of `'utf8'` is enforced. If `data` is a [`Buffer`][], `TypedArray`, or This can be called many times with new data as it is streamed. ## Class: `KeyObject` + <!-- YAML added: v11.6.0 changes: @@ -1860,6 +1906,7 @@ The receiver obtains a cloned `KeyObject`, and the `KeyObject` does not need to be listed in the `transferList` argument. ### Static method: `KeyObject.from(key)` + <!-- YAML added: v15.0.0 --> @@ -1906,6 +1953,7 @@ const { ``` ### `keyObject.asymmetricKeyDetails` + <!-- YAML added: v15.7.0 changes: @@ -1937,6 +1985,7 @@ set. Other key details might be exposed via this API using additional attributes. ### `keyObject.asymmetricKeyType` + <!-- YAML added: v11.6.0 changes: @@ -1979,6 +2028,7 @@ This property is `undefined` for unrecognized `KeyObject` types and symmetric keys. ### `keyObject.export([options])` + <!-- YAML added: v11.6.0 changes: @@ -2005,8 +2055,8 @@ For private keys, the following encoding options can be used: `'sec1'` (EC only). * `format`: {string} Must be `'pem'`, `'der'`, or `'jwk'`. * `cipher`: {string} If specified, the private key will be encrypted with - the given `cipher` and `passphrase` using PKCS#5 v2.0 password based - encryption. + the given `cipher` and `passphrase` using PKCS#5 v2.0 password based + encryption. * `passphrase`: {string | Buffer} The passphrase to use for encryption, see `cipher`. @@ -2028,6 +2078,7 @@ a PKCS#8 key. See [RFC 5208][] for PKCS#8 encryption and [RFC 1421][] for PKCS#1 and SEC1 encryption. ### `keyObject.symmetricKeySize` + <!-- YAML added: v11.6.0 --> @@ -2038,6 +2089,7 @@ For secret keys, this property represents the size of the key in bytes. This property is `undefined` for asymmetric keys. ### `keyObject.type` + <!-- YAML added: v11.6.0 --> @@ -2049,6 +2101,7 @@ Depending on the type of this `KeyObject`, this property is either or `'private'` for private (asymmetric) keys. ## Class: `Sign` + <!-- YAML added: v0.1.92 --> @@ -2164,6 +2217,7 @@ console.log(verify.verify(publicKey, signature)); ``` ### `sign.sign(privateKey[, outputEncoding])` + <!-- YAML added: v0.1.92 changes: @@ -2187,12 +2241,14 @@ changes: --> <!--lint disable maximum-line-length remark-lint--> + * `privateKey` {Object|string|ArrayBuffer|Buffer|TypedArray|DataView|KeyObject|CryptoKey} * `dsaEncoding` {string} * `padding` {integer} * `saltLength` {integer} * `outputEncoding` {string} The [encoding][] of the return value. * Returns: {Buffer | string} + <!--lint enable maximum-line-length remark-lint--> Calculates the signature on all the data passed through using either @@ -2207,6 +2263,7 @@ object, the following additional properties can be passed: * `'der'` (default): DER-encoded ASN.1 signature structure encoding `(r, s)`. * `'ieee-p1363'`: Signature format `r || s` as proposed in IEEE-P1363. * `padding` {integer} Optional padding value for RSA, one of the following: + * `crypto.constants.RSA_PKCS1_PADDING` (default) * `crypto.constants.RSA_PKCS1_PSS_PADDING` @@ -2227,6 +2284,7 @@ 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[, inputEncoding])` + <!-- YAML added: v0.1.92 changes: @@ -2247,6 +2305,7 @@ encoding of `'utf8'` is enforced. If `data` is a [`Buffer`][], `TypedArray`, or This can be called many times with new data as it is streamed. ## Class: `Verify` + <!-- YAML added: v0.1.92 --> @@ -2267,6 +2326,7 @@ The [`crypto.createVerify()`][] method is used to create `Verify` instances. See [`Sign`][] for examples. ### `verify.update(data[, inputEncoding])` + <!-- YAML added: v0.1.92 changes: @@ -2287,6 +2347,7 @@ encoding of `'utf8'` is enforced. If `data` is a [`Buffer`][], `TypedArray`, or This can be called many times with new data as it is streamed. ### `verify.verify(object, signature[, signatureEncoding])` + <!-- YAML added: v0.1.92 changes: @@ -2310,6 +2371,7 @@ changes: --> <!--lint disable maximum-line-length remark-lint--> + * `object` {Object|string|ArrayBuffer|Buffer|TypedArray|DataView|KeyObject|CryptoKey} * `dsaEncoding` {string} * `padding` {integer} @@ -2318,6 +2380,7 @@ changes: * `signatureEncoding` {string} The [encoding][] of the `signature` string. * Returns: {boolean} `true` or `false` depending on the validity of the signature for the data and public key. + <!--lint enable maximum-line-length remark-lint--> Verifies the provided data using the given `object` and `signature`. @@ -2331,6 +2394,7 @@ object, the following additional properties can be passed: * `'der'` (default): DER-encoded ASN.1 signature structure encoding `(r, s)`. * `'ieee-p1363'`: Signature format `r || s` as proposed in IEEE-P1363. * `padding` {integer} Optional padding value for RSA, one of the following: + * `crypto.constants.RSA_PKCS1_PADDING` (default) * `crypto.constants.RSA_PKCS1_PSS_PADDING` @@ -2358,6 +2422,7 @@ Because public keys can be derived from private keys, a private key may be passed instead of a public key. ## Class: `X509Certificate` + <!-- YAML added: v15.6.0 --> @@ -2382,6 +2447,7 @@ console.log(x509.subject); ``` ### `new X509Certificate(buffer)` + <!-- YAML added: v15.6.0 --> @@ -2390,6 +2456,7 @@ added: v15.6.0 X509 Certificate. ### `x509.ca` + <!-- YAML added: v15.6.0 --> @@ -2398,6 +2465,7 @@ added: v15.6.0 certificate. ### `x509.checkEmail(email[, options])` + <!-- YAML added: v15.6.0 --> @@ -2415,6 +2483,7 @@ added: v15.6.0 Checks whether the certificate matches the given email address. ### `x509.checkHost(name[, options])` + <!-- YAML added: v15.6.0 --> @@ -2432,6 +2501,7 @@ added: v15.6.0 Checks whether the certificate matches the given host name. ### `x509.checkIP(ip[, options])` + <!-- YAML added: v15.6.0 --> @@ -2449,6 +2519,7 @@ added: v15.6.0 Checks whether the certificate matches the given IP address (IPv4 or IPv6). ### `x509.checkIssued(otherCert)` + <!-- YAML added: v15.6.0 --> @@ -2459,6 +2530,7 @@ added: v15.6.0 Checks whether this certificate was issued by the given `otherCert`. ### `x509.checkPrivateKey(privateKey)` + <!-- YAML added: v15.6.0 --> @@ -2470,6 +2542,7 @@ Checks whether the public key for this certificate is consistent with the given private key. ### `x509.fingerprint` + <!-- YAML added: v15.6.0 --> @@ -2479,6 +2552,7 @@ added: v15.6.0 The SHA-1 fingerprint of this certificate. ### `x509.fingerprint256` + <!-- YAML added: v15.6.0 --> @@ -2488,6 +2562,7 @@ added: v15.6.0 The SHA-256 fingerprint of this certificate. ### `x509.infoAccess` + <!-- YAML added: v15.6.0 --> @@ -2497,6 +2572,7 @@ added: v15.6.0 The information access content of this certificate. ### `x509.issuer` + <!-- YAML added: v15.6.0 --> @@ -2506,6 +2582,7 @@ added: v15.6.0 The issuer identification included in this certificate. ### `x509.issuerCertificate` + <!-- YAML added: v15.9.0 --> @@ -2516,15 +2593,17 @@ The issuer certificate or `undefined` if the issuer certificate is not available. ### `x509.keyUsage` + <!-- YAML added: v15.6.0 --> -* Type: {string[]} +* Type: {string\[]} An array detailing the key usages for this certificate. ### `x509.publicKey` + <!-- YAML added: v15.6.0 --> @@ -2534,6 +2613,7 @@ added: v15.6.0 The public key {KeyObject} for this certificate. ### `x509.raw` + <!-- YAML added: v15.6.0 --> @@ -2543,6 +2623,7 @@ added: v15.6.0 A `Buffer` containing the DER encoding of this certificate. ### `x509.serialNumber` + <!-- YAML added: v15.6.0 --> @@ -2552,6 +2633,7 @@ added: v15.6.0 The serial number of this certificate. ### `x509.subject` + <!-- YAML added: v15.6.0 --> @@ -2561,6 +2643,7 @@ added: v15.6.0 The complete subject of this certificate. ### `x509.subjectAltName` + <!-- YAML added: v15.6.0 --> @@ -2570,6 +2653,7 @@ added: v15.6.0 The subject alternative name specified for this certificate. ### `x509.toJSON()` + <!-- YAML added: v15.6.0 --> @@ -2581,6 +2665,7 @@ There is no standard JSON encoding for X509 certificates. The certificate. ### `x509.toLegacyObject()` + <!-- YAML added: v15.6.0 --> @@ -2591,6 +2676,7 @@ Returns information about this certificate using the legacy [certificate object][] encoding. ### `x509.toString()` + <!-- YAML added: v15.6.0 --> @@ -2600,6 +2686,7 @@ added: v15.6.0 Returns the PEM-encoded certificate. ### `x509.validFrom` + <!-- YAML added: v15.6.0 --> @@ -2609,6 +2696,7 @@ added: v15.6.0 The date/time from which this certificate is considered valid. ### `x509.validTo` + <!-- YAML added: v15.6.0 --> @@ -2618,6 +2706,7 @@ added: v15.6.0 The date/time until which this certificate is considered valid. ### `x509.verify(publicKey)` + <!-- YAML added: v15.6.0 --> @@ -2631,6 +2720,7 @@ Does not perform any other validation checks on the certificate. ## `crypto` module methods and properties ### `crypto.constants` + <!-- YAML added: v6.3.0 --> @@ -2640,6 +2730,7 @@ added: v6.3.0 described in [Crypto constants][]. ### `crypto.DEFAULT_ENCODING` + <!-- YAML added: v0.9.3 deprecated: v10.0.0 @@ -2659,6 +2750,7 @@ New applications should expect the default to be `'buffer'`. This property is deprecated. ### `crypto.fips` + <!-- YAML added: v6.0.0 deprecated: v10.0.0 @@ -2673,6 +2765,7 @@ This property is deprecated. Please use `crypto.setFips()` and `crypto.getFips()` instead. ### `crypto.checkPrime(candidate[, options, [callback]])` + <!-- YAML added: v15.8.0 --> @@ -2695,6 +2788,7 @@ added: v15.8.0 Checks the primality of the `candidate`. ### `crypto.checkPrimeSync(candidate[, options])` + <!-- YAML added: v15.8.0 --> @@ -2715,6 +2809,7 @@ added: v15.8.0 Checks the primality of the `candidate`. ### `crypto.createCipher(algorithm, password[, options])` + <!-- YAML added: v0.1.94 deprecated: v10.0.0 @@ -2775,6 +2870,7 @@ vulnerabilities. For the case when IV is reused in GCM, see [Nonce-Disrespecting Adversaries][] for details. ### `crypto.createCipheriv(algorithm, key, iv[, options])` + <!-- YAML added: v0.1.94 changes: @@ -2841,6 +2937,7 @@ remember that an attacker must not be able to predict ahead of time what a given IV will be. ### `crypto.createDecipher(algorithm, password[, options])` + <!-- YAML added: v0.1.94 deprecated: v10.0.0 @@ -2878,6 +2975,7 @@ their own using [`crypto.scrypt()`][] and to use [`crypto.createDecipheriv()`][] to create the `Decipher` object. ### `crypto.createDecipheriv(algorithm, key, iv[, options])` + <!-- YAML added: v0.1.94 changes: @@ -2940,6 +3038,7 @@ remember that an attacker must not be able to predict ahead of time what a given IV will be. ### `crypto.createDiffieHellman(prime[, primeEncoding][, generator][, generatorEncoding])` + <!-- YAML added: v0.11.12 changes: @@ -2975,6 +3074,7 @@ If `generatorEncoding` is specified, `generator` is expected to be a string; otherwise a number, [`Buffer`][], `TypedArray`, or `DataView` is expected. ### `crypto.createDiffieHellman(primeLength[, generator])` + <!-- YAML added: v0.5.0 --> @@ -2988,6 +3088,7 @@ Creates a `DiffieHellman` key exchange object and generates a prime of If `generator` is not specified, the value `2` is used. ### `crypto.createDiffieHellmanGroup(name)` + <!-- YAML added: v0.9.3 --> @@ -2998,6 +3099,7 @@ added: v0.9.3 An alias for [`crypto.getDiffieHellman()`][] ### `crypto.createECDH(curveName)` + <!-- YAML added: v0.11.14 --> @@ -3012,6 +3114,7 @@ OpenSSL releases, `openssl ecparam -list_curves` will also display the name and description of each available elliptic curve. ### `crypto.createHash(algorithm[, options])` + <!-- YAML added: v0.1.92 changes: @@ -3090,6 +3193,7 @@ input.on('readable', () => { ``` ### `crypto.createHmac(algorithm, key[, options])` + <!-- YAML added: v0.1.94 changes: @@ -3176,6 +3280,7 @@ input.on('readable', () => { ``` ### `crypto.createPrivateKey(key)` + <!-- YAML added: v11.6.0 changes: @@ -3189,16 +3294,18 @@ changes: --> <!--lint disable maximum-line-length remark-lint--> + * `key` {Object|string|ArrayBuffer|Buffer|TypedArray|DataView} * `key`: {string|ArrayBuffer|Buffer|TypedArray|DataView|Object} The key material, either in PEM, DER, or JWK format. * `format`: {string} Must be `'pem'`, `'der'`, or '`'jwk'`. **Default:** `'pem'`. * `type`: {string} Must be `'pkcs1'`, `'pkcs8'` or `'sec1'`. This option is - required only if the `format` is `'der'` and ignored otherwise. + required only if the `format` is `'der'` and ignored otherwise. * `passphrase`: {string | Buffer} The passphrase to use for decryption. * `encoding`: {string} The string encoding to use when `key` is a string. * Returns: {KeyObject} + <!--lint enable maximum-line-length remark-lint--> Creates and returns a new key object containing a private key. If `key` is a @@ -3209,6 +3316,7 @@ If the private key is encrypted, a `passphrase` must be specified. The length of the passphrase is limited to 1024 bytes. ### `crypto.createPublicKey(key)` + <!-- YAML added: v11.6.0 changes: @@ -3229,15 +3337,17 @@ changes: --> <!--lint disable maximum-line-length remark-lint--> + * `key` {Object|string|ArrayBuffer|Buffer|TypedArray|DataView} * `key`: {string|ArrayBuffer|Buffer|TypedArray|DataView|Object} The key material, either in PEM, DER, or JWK format. * `format`: {string} Must be `'pem'`, `'der'`, or `'jwk'`. **Default:** `'pem'`. * `type`: {string} Must be `'pkcs1'` or `'spki'`. This option is - required only if the `format` is `'der'` and ignored otherwise. + required only if the `format` is `'der'` and ignored otherwise. * `encoding` {string} The string encoding to use when `key` is a string. * Returns: {KeyObject} + <!--lint enable maximum-line-length remark-lint--> Creates and returns a new key object containing a public key. If `key` is a @@ -3256,6 +3366,7 @@ extracted from the returned `KeyObject`. Similarly, if a `KeyObject` with type and it will be impossible to extract the private key from the returned object. ### `crypto.createSecretKey(key[, encoding])` + <!-- YAML added: v11.6.0 changes: @@ -3274,6 +3385,7 @@ Creates and returns a new key object containing a secret key for symmetric encryption or `Hmac`. ### `crypto.createSign(algorithm[, options])` + <!-- YAML added: v0.1.92 --> @@ -3293,6 +3405,7 @@ algorithms, such as `'ecdsa-with-SHA256'`, so it is best to always use digest algorithm names. ### `crypto.createVerify(algorithm[, options])` + <!-- YAML added: v0.1.92 --> @@ -3313,6 +3426,7 @@ algorithms, such as `'ecdsa-with-SHA256'`, so it is best to always use digest algorithm names. ### `crypto.diffieHellman(options)` + <!-- YAML added: - v13.9.0 @@ -3329,6 +3443,7 @@ Both keys must have the same `asymmetricKeyType`, which must be one of `'dh'` (for Diffie-Hellman), `'ec'` (for ECDH), `'x448'`, or `'x25519'` (for ECDH-ES). ### `crypto.generateKey(type, options, callback)` + <!-- YAML added: v15.0.0 --> @@ -3372,6 +3487,7 @@ generateKey('hmac', { length: 64 }, (err, key) => { ``` ### `crypto.generateKeyPair(type, options, callback)` + <!-- YAML added: v10.12.0 changes: @@ -3483,6 +3599,7 @@ If this method is invoked as its [`util.promisify()`][]ed version, it returns a `Promise` for an `Object` with `publicKey` and `privateKey` properties. ### `crypto.generateKeyPairSync(type, options)` + <!-- YAML added: v10.12.0 changes: @@ -3594,6 +3711,7 @@ When PEM encoding was selected, the respective key will be a string, otherwise it will be a buffer containing the data encoded as DER. ### `crypto.generateKeySync(type, options)` + <!-- YAML added: v15.0.0 --> @@ -3630,6 +3748,7 @@ console.log(key.export().toString('hex')); // e89..........41e ``` ### `crypto.generatePrime(size[, options[, callback]])` + <!-- YAML added: v15.8.0 --> @@ -3672,6 +3791,7 @@ in an {ArrayBuffer}. If the `bigint` option is `true`, then a {bigint} is provided. ### `crypto.generatePrimeSync(size[, options])` + <!-- YAML added: v15.8.0 --> @@ -3712,6 +3832,7 @@ in an {ArrayBuffer}. If the `bigint` option is `true`, then a {bigint} is provided. ### `crypto.getCipherInfo(nameOrNid[, options])` + <!-- YAML added: v15.0.0 --> @@ -3741,11 +3862,12 @@ cipher, use the `keyLength` and `ivLength` options. If the given values are unacceptable, `undefined` will be returned. ### `crypto.getCiphers()` + <!-- YAML added: v0.9.3 --> -* Returns: {string[]} An array with the names of the supported cipher +* Returns: {string\[]} An array with the names of the supported cipher algorithms. ```mjs @@ -3765,11 +3887,12 @@ console.log(getCiphers()); // ['aes-128-cbc', 'aes-128-ccm', ...] ``` ### `crypto.getCurves()` + <!-- YAML added: v2.3.0 --> -* Returns: {string[]} An array with the names of the supported elliptic curves. +* Returns: {string\[]} An array with the names of the supported elliptic curves. ```mjs const { @@ -3788,6 +3911,7 @@ console.log(getCurves()); // ['Oakley-EC2N-3', 'Oakley-EC2N-4', ...] ``` ### `crypto.getDiffieHellman(groupName)` + <!-- YAML added: v0.7.5 --> @@ -3844,6 +3968,7 @@ console.log(aliceSecret === bobSecret); ``` ### `crypto.getFips()` + <!-- YAML added: v10.0.0 --> @@ -3853,11 +3978,12 @@ added: v10.0.0 the return type of this API to a {boolean}. ### `crypto.getHashes()` + <!-- YAML added: v0.9.3 --> -* Returns: {string[]} An array of the names of the supported hash algorithms, +* Returns: {string\[]} An array of the names of the supported hash algorithms, such as `'RSA-SHA256'`. Hash algorithms are also called "digest" algorithms. ```mjs @@ -3877,6 +4003,7 @@ console.log(getHashes()); // ['DSA', 'DSA-SHA', 'DSA-SHA1', ...] ``` ### `crypto.hkdf(digest, ikm, salt, info, keylen, callback)` + <!-- YAML added: v15.0.0 --> @@ -3930,6 +4057,7 @@ hkdf('sha512', 'key', 'salt', 'info', 64, (err, derivedKey) => { ``` ### `crypto.hkdfSync(digest, ikm, salt, info, keylen)` + <!-- YAML added: v15.0.0 --> @@ -3977,6 +4105,7 @@ console.log(Buffer.from(derivedKey).toString('hex')); // '24156e2...5391653' ``` ### `crypto.pbkdf2(password, salt, iterations, keylen, digest, callback)` + <!-- YAML added: v0.5.5 changes: @@ -4086,6 +4215,7 @@ negative performance implications for some applications; see the [`UV_THREADPOOL_SIZE`][] documentation for more information. ### `crypto.pbkdf2Sync(password, salt, iterations, keylen, digest)` + <!-- YAML added: v0.9.3 changes: @@ -4171,6 +4301,7 @@ An array of supported digest functions can be retrieved using [`crypto.getHashes()`][]. ### `crypto.privateDecrypt(privateKey, buffer)` + <!-- YAML added: v0.11.14 changes: @@ -4192,17 +4323,19 @@ changes: --> <!--lint disable maximum-line-length remark-lint--> + * `privateKey` {Object|string|ArrayBuffer|Buffer|TypedArray|DataView|KeyObject|CryptoKey} * `oaepHash` {string} The hash function to use for OAEP padding and MGF1. **Default:** `'sha1'` * `oaepLabel` {string|ArrayBuffer|Buffer|TypedArray|DataView} The label to - use for OAEP padding. If not specified, no label is used. + use for OAEP padding. If not specified, no label is used. * `padding` {crypto.constants} An optional padding value defined in `crypto.constants`, which may be: `crypto.constants.RSA_NO_PADDING`, `crypto.constants.RSA_PKCS1_PADDING`, or `crypto.constants.RSA_PKCS1_OAEP_PADDING`. * `buffer` {string|ArrayBuffer|Buffer|TypedArray|DataView} * Returns: {Buffer} A new `Buffer` with the decrypted content. + <!--lint enable maximum-line-length remark-lint--> Decrypts `buffer` with `privateKey`. `buffer` was previously encrypted using @@ -4214,6 +4347,7 @@ object, the `padding` property can be passed. Otherwise, this function uses `RSA_PKCS1_OAEP_PADDING`. ### `crypto.privateEncrypt(privateKey, buffer)` + <!-- YAML added: v1.1.0 changes: @@ -4229,6 +4363,7 @@ changes: --> <!--lint disable maximum-line-length remark-lint--> + * `privateKey` {Object|string|ArrayBuffer|Buffer|TypedArray|DataView|KeyObject|CryptoKey} * `key` {string|ArrayBuffer|Buffer|TypedArray|DataView|KeyObject|CryptoKey} A PEM encoded private key. @@ -4241,6 +4376,7 @@ changes: or `passphrase` are strings. * `buffer` {string|ArrayBuffer|Buffer|TypedArray|DataView} * Returns: {Buffer} A new `Buffer` with the encrypted content. + <!--lint enable maximum-line-length remark-lint--> Encrypts `buffer` with `privateKey`. The returned data can be decrypted using @@ -4252,6 +4388,7 @@ object, the `padding` property can be passed. Otherwise, this function uses `RSA_PKCS1_PADDING`. ### `crypto.publicDecrypt(key, buffer)` + <!-- YAML added: v1.1.0 changes: @@ -4267,6 +4404,7 @@ changes: --> <!--lint disable maximum-line-length remark-lint--> + * `key` {Object|string|ArrayBuffer|Buffer|TypedArray|DataView|KeyObject|CryptoKey} * `passphrase` {string|ArrayBuffer|Buffer|TypedArray|DataView} An optional passphrase for the private key. @@ -4277,6 +4415,7 @@ changes: or `passphrase` are strings. * `buffer` {string|ArrayBuffer|Buffer|TypedArray|DataView} * Returns: {Buffer} A new `Buffer` with the decrypted content. + <!--lint enable maximum-line-length remark-lint--> Decrypts `buffer` with `key`.`buffer` was previously encrypted using @@ -4291,6 +4430,7 @@ Because RSA public keys can be derived from private keys, a private key may be passed instead of a public key. ### `crypto.publicEncrypt(key, buffer)` + <!-- YAML added: v0.11.14 changes: @@ -4312,6 +4452,7 @@ changes: --> <!--lint disable maximum-line-length remark-lint--> + * `key` {Object|string|ArrayBuffer|Buffer|TypedArray|DataView|KeyObject|CryptoKey} * `key` {string|ArrayBuffer|Buffer|TypedArray|DataView|KeyObject|CryptoKey} A PEM encoded public or private key, {KeyObject}, or {CryptoKey}. @@ -4329,6 +4470,7 @@ changes: `oaepLabel`, or `passphrase` are strings. * `buffer` {string|ArrayBuffer|Buffer|TypedArray|DataView} * Returns: {Buffer} A new `Buffer` with the encrypted content. + <!--lint enable maximum-line-length remark-lint--> Encrypts the content of `buffer` with `key` and returns a new @@ -4344,6 +4486,7 @@ Because RSA public keys can be derived from private keys, a private key may be passed instead of a public key. ### `crypto.randomBytes(size[, callback])` + <!-- YAML added: v0.5.8 changes: @@ -4434,6 +4577,7 @@ large `randomBytes` requests when doing so as part of fulfilling a client request. ### `crypto.randomFillSync(buffer[, offset][, size])` + <!-- YAML added: - v7.10.0 @@ -4520,6 +4664,7 @@ console.log(Buffer.from(randomFillSync(c)).toString('hex')); ``` ### `crypto.randomFill(buffer[, offset][, size], callback)` + <!-- YAML added: - v7.10.0 @@ -4656,6 +4801,7 @@ large `randomFill` requests when doing so as part of fulfilling a client request. ### `crypto.randomInt([min, ]max[, callback])` + <!-- YAML added: - v14.10.0 @@ -4740,6 +4886,7 @@ console.log(`The dice rolled: ${n}`); ``` ### `crypto.randomUUID([options])` + <!-- YAML added: - v15.6.0 @@ -4758,6 +4905,7 @@ Generates a random [RFC 4122][] version 4 UUID. The UUID is generated using a cryptographic pseudorandom number generator. ### `crypto.scrypt(password, salt, keylen[, options], callback)` + <!-- YAML added: v10.5.0 changes: @@ -4845,6 +4993,7 @@ scrypt('password', 'salt', 64, { N: 1024 }, (err, derivedKey) => { ``` ### `crypto.scryptSync(password, salt, keylen[, options])` + <!-- YAML added: v10.5.0 changes: @@ -4917,6 +5066,7 @@ console.log(key2.toString('hex')); // '3745e48...aa39b34' ``` ### `crypto.secureHeapUsed()` + <!-- YAML added: v15.6.0 --> @@ -4932,6 +5082,7 @@ added: v15.6.0 allocated bytes. ### `crypto.setEngine(engine[, flags])` + <!-- YAML added: v0.11.11 --> @@ -4966,6 +5117,7 @@ The flags below are deprecated in OpenSSL-1.1.0. * `crypto.constants.ENGINE_METHOD_STORE` ### `crypto.setFips(bool)` + <!-- YAML added: v10.0.0 --> @@ -4976,6 +5128,7 @@ Enables the FIPS compliant crypto provider in a FIPS-enabled Node.js build. Throws an error if FIPS mode is not available. ### `crypto.sign(algorithm, data, key[, callback])` + <!-- YAML added: v12.0.0 changes: @@ -4990,6 +5143,7 @@ changes: --> <!--lint disable maximum-line-length remark-lint--> + * `algorithm` {string | null | undefined} * `data` {ArrayBuffer|Buffer|TypedArray|DataView} * `key` {Object|string|ArrayBuffer|Buffer|TypedArray|DataView|KeyObject|CryptoKey} @@ -4997,6 +5151,7 @@ changes: * `err` {Error} * `signature` {Buffer} * Returns: {Buffer} if the `callback` function is not provided. + <!--lint enable maximum-line-length remark-lint--> Calculates and returns the signature for `data` using the given private key and @@ -5012,6 +5167,7 @@ additional properties can be passed: * `'der'` (default): DER-encoded ASN.1 signature structure encoding `(r, s)`. * `'ieee-p1363'`: Signature format `r || s` as proposed in IEEE-P1363. * `padding` {integer} Optional padding value for RSA, one of the following: + * `crypto.constants.RSA_PKCS1_PADDING` (default) * `crypto.constants.RSA_PKCS1_PSS_PADDING` @@ -5026,6 +5182,7 @@ additional properties can be passed: If the `callback` function is provided this function uses libuv's threadpool. ### `crypto.timingSafeEqual(a, b)` + <!-- YAML added: v6.6.0 changes: @@ -5051,11 +5208,12 @@ If at least one of `a` and `b` is a `TypedArray` with more than one byte per entry, such as `Uint16Array`, the result will be computed using the platform byte order. -Use of `crypto.timingSafeEqual` does not guarantee that the *surrounding* code +Use of `crypto.timingSafeEqual` does not guarantee that the _surrounding_ code is timing-safe. Care should be taken to ensure that the surrounding code does not introduce timing vulnerabilities. ### `crypto.verify(algorithm, data, key, signature[, callback])` + <!-- YAML added: v12.0.0 changes: @@ -5073,6 +5231,7 @@ changes: --> <!--lint disable maximum-line-length remark-lint--> + * `algorithm` {string|null|undefined} * `data` {ArrayBuffer| Buffer|TypedArray|DataView} * `key` {Object|string|ArrayBuffer|Buffer|TypedArray|DataView|KeyObject|CryptoKey} @@ -5083,6 +5242,7 @@ changes: * Returns: {boolean} `true` or `false` depending on the validity of the signature for the data and public key if the `callback` function is not provided. + <!--lint enable maximum-line-length remark-lint--> Verifies the given signature for `data` using the given key and algorithm. If @@ -5098,6 +5258,7 @@ additional properties can be passed: * `'der'` (default): DER-encoded ASN.1 signature structure encoding `(r, s)`. * `'ieee-p1363'`: Signature format `r || s` as proposed in IEEE-P1363. * `padding` {integer} Optional padding value for RSA, one of the following: + * `crypto.constants.RSA_PKCS1_PADDING` (default) * `crypto.constants.RSA_PKCS1_PSS_PADDING` @@ -5117,6 +5278,7 @@ key may be passed for `key`. If the `callback` function is provided this function uses libuv's threadpool. ### `crypto.webcrypto` + <!-- YAML added: v15.0.0 --> @@ -5244,7 +5406,7 @@ mode must adhere to certain restrictions when using the cipher API: * As CCM processes the whole message at once, `update()` must be called exactly once. * Even though calling `update()` is sufficient to encrypt/decrypt the message, - applications *must* call `final()` to compute or verify the + applications _must_ call `final()` to compute or verify the authentication tag. ```mjs |