crypto: add argon2() and argon2Sync() methods

crypto: add argon2() and argon2Sync() methods · nodejs/node@d3afc63

@@ -2970,6 +2970,171 @@ Does not perform any other validation checks on the certificate.

2970297029712971## `node:crypto` module methods and properties297229722973+### `crypto.argon2(algorithm, parameters, callback)`2974+2975+2978+2979+> Stability: 1.2 - Release candidate2980+2981+* `algorithm` {string} Variant of Argon2, one of `"argon2d"`, `"argon2i"` or `"argon2id"`.2982+* `parameters` {Object}2983+* `message` {string|ArrayBuffer|Buffer|TypedArray|DataView} REQUIRED, this is the password for password2984+ hashing applications of Argon2.2985+* `nonce` {string|ArrayBuffer|Buffer|TypedArray|DataView} REQUIRED, must be at2986+ least 8 bytes long. This is the salt for password hashing applications of Argon2.2987+* `parallelism` {number} REQUIRED, degree of parallelism determines how many computational chains (lanes)2988+ can be run. Must be greater than 1 and less than `2**24-1`.2989+* `tagLength` {number} REQUIRED, the length of the key to generate. Must be greater than 4 and2990+ less than `2**32-1`.2991+* `memory` {number} REQUIRED, memory cost in 1KiB blocks. Must be greater than2992+`8 * parallelism` and less than `2**32-1`. The actual number of blocks is rounded2993+ down to the nearest multiple of `4 * parallelism`.2994+* `passes` {number} REQUIRED, number of passes (iterations). Must be greater than 1 and less2995+ than `2**32-1`.2996+* `secret` {string|ArrayBuffer|Buffer|TypedArray|DataView|undefined} OPTIONAL, Random additional input,2997+ similar to the salt, that should **NOT** be stored with the derived key. This is known as pepper in2998+ password hashing applications. If used, must have a length not greater than `2**32-1` bytes.2999+* `associatedData` {string|ArrayBuffer|Buffer|TypedArray|DataView|undefined} OPTIONAL, Additional data to3000+ be added to the hash, functionally equivalent to salt or secret, but meant for3001+ non-random data. If used, must have a length not greater than `2**32-1` bytes.3002+* `callback` {Function}3003+* `err` {Error}3004+* `derivedKey` {Buffer}3005+3006+Provides an asynchronous [Argon2][] implementation. Argon2 is a password-based3007+key derivation function that is designed to be expensive computationally and3008+memory-wise in order to make brute-force attacks unrewarding.3009+3010+The `nonce` should be as unique as possible. It is recommended that a nonce is3011+random and at least 16 bytes long. See [NIST SP 800-132][] for details.3012+3013+When passing strings for `message`, `nonce`, `secret` or `associatedData`, please3014+consider [caveats when using strings as inputs to cryptographic APIs][].3015+3016+The `callback` function is called with two arguments: `err` and `derivedKey`.3017+`err` is an exception object when key derivation fails, otherwise `err` is3018+`null`. `derivedKey` is passed to the callback as a [`Buffer`][].3019+3020+An exception is thrown when any of the input arguments specify invalid values3021+or types.3022+3023+```mjs3024+const { argon2, randomBytes } = await import('node:crypto');3025+3026+const parameters = {3027+ message: 'password',3028+ nonce: randomBytes(16),3029+ parallelism: 4,3030+ tagLength: 64,3031+ memory: 65536,3032+ passes: 3,3033+};3034+3035+argon2('argon2id', parameters, (err, derivedKey) => {3036+if (err) throw err;3037+console.log(derivedKey.toString('hex')); // 'af91dad...9520f15'3038+});3039+```3040+3041+```cjs3042+const { argon2, randomBytes } = require('node:crypto');3043+3044+const parameters = {3045+ message: 'password',3046+ nonce: randomBytes(16),3047+ parallelism: 4,3048+ tagLength: 64,3049+ memory: 65536,3050+ passes: 3,3051+};3052+3053+argon2('argon2id', parameters, (err, derivedKey) => {3054+if (err) throw err;3055+console.log(derivedKey.toString('hex')); // 'af91dad...9520f15'3056+});3057+```3058+3059+### `crypto.argon2Sync(algorithm, parameters)`3060+3061+3064+3065+> Stability: 1.2 - Release candidate3066+3067+* `algorithm` {string} Variant of Argon2, one of `"argon2d"`, `"argon2i"` or `"argon2id"`.3068+* `parameters` {Object}3069+* `message` {string|ArrayBuffer|Buffer|TypedArray|DataView} REQUIRED, this is the password for password3070+ hashing applications of Argon2.3071+* `nonce` {string|ArrayBuffer|Buffer|TypedArray|DataView} REQUIRED, must be at3072+ least 8 bytes long. This is the salt for password hashing applications of Argon2.3073+* `parallelism` {number} REQUIRED, degree of parallelism determines how many computational chains (lanes)3074+ can be run. Must be greater than 1 and less than `2**24-1`.3075+* `tagLength` {number} REQUIRED, the length of the key to generate. Must be greater than 4 and3076+ less than `2**32-1`.3077+* `memory` {number} REQUIRED, memory cost in 1KiB blocks. Must be greater than3078+`8 * parallelism` and less than `2**32-1`. The actual number of blocks is rounded3079+ down to the nearest multiple of `4 * parallelism`.3080+* `passes` {number} REQUIRED, number of passes (iterations). Must be greater than 1 and less3081+ than `2**32-1`.3082+* `secret` {string|ArrayBuffer|Buffer|TypedArray|DataView|undefined} OPTIONAL, Random additional input,3083+ similar to the salt, that should **NOT** be stored with the derived key. This is known as pepper in3084+ password hashing applications. If used, must have a length not greater than `2**32-1` bytes.3085+* `associatedData` {string|ArrayBuffer|Buffer|TypedArray|DataView|undefined} OPTIONAL, Additional data to3086+ be added to the hash, functionally equivalent to salt or secret, but meant for3087+ non-random data. If used, must have a length not greater than `2**32-1` bytes.3088+* Returns: {Buffer}3089+3090+Provides a synchronous [Argon2][] implementation. Argon2 is a password-based3091+key derivation function that is designed to be expensive computationally and3092+memory-wise in order to make brute-force attacks unrewarding.3093+3094+The `nonce` should be as unique as possible. It is recommended that a nonce is3095+random and at least 16 bytes long. See [NIST SP 800-132][] for details.3096+3097+When passing strings for `message`, `nonce`, `secret` or `associatedData`, please3098+consider [caveats when using strings as inputs to cryptographic APIs][].3099+3100+An exception is thrown when key derivation fails, otherwise the derived key is3101+returned as a [`Buffer`][].3102+3103+An exception is thrown when any of the input arguments specify invalid values3104+or types.3105+3106+```mjs3107+const { argon2Sync, randomBytes } = await import('node:crypto');3108+3109+const parameters = {3110+ message: 'password',3111+ nonce: randomBytes(16),3112+ parallelism: 4,3113+ tagLength: 64,3114+ memory: 65536,3115+ passes: 3,3116+};3117+3118+const derivedKey = argon2Sync('argon2id', parameters);3119+console.log(derivedKey.toString('hex')); // 'af91dad...9520f15'3120+```3121+3122+```cjs3123+const { argon2Sync, randomBytes } = require('node:crypto');3124+3125+const parameters = {3126+ message: 'password',3127+ nonce: randomBytes(16),3128+ parallelism: 4,3129+ tagLength: 64,3130+ memory: 65536,3131+ passes: 3,3132+};3133+3134+const derivedKey = argon2Sync('argon2id', parameters);3135+console.log(derivedKey.toString('hex')); // 'af91dad...9520f15'3136+```3137+29733138### `crypto.checkPrime(candidate[, options], callback)`2974313929753140<!-- YAML

@@ -6284,6 +6449,7 @@ See the [list of SSL OP Flags][] for details.

62846449[`verify.verify()`]: #verifyverifyobject-signature-signatureencoding62856450[`x509.fingerprint256`]: #x509fingerprint25662866451[`x509.verify(publicKey)`]: #x509verifypublickey6452+[argon2]: https://www.rfc-editor.org/rfc/rfc9106.html62876453[asymmetric key types]: #asymmetric-key-types62886454[caveats when using strings as inputs to cryptographic APIs]: #using-strings-as-inputs-to-cryptographic-apis62896455[certificate object]: tls.md#certificate-object