Commit 281dfaf
doc: improve HMAC key recommendations
Add a reference to potential problems with using strings as HMAC keys.
Also advise against exceeding the underlying hash function's block size
when generating HMAC keys from a cryptographically secure source of
entropy.
Refs: #48052
Refs: #37248
PR-URL: #48121
Reviewed-By: Marco Ippolito <marcoippolito54@gmail.com>
Reviewed-By: Filip Skokan <panva.ip@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>1 parent 45c3782 commit 281dfaf
1 file changed
Lines changed: 12 additions & 1 deletion
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -3391,7 +3391,11 @@ On recent releases of OpenSSL, `openssl list -digest-algorithms` will | |||
| 3391 | 3391 | display the available digest algorithms. | |
| 3392 | 3392 | ||
| 3393 | 3393 | The `key` is the HMAC key used to generate the cryptographic HMAC hash. If it is | |
| 3394 | - a [`KeyObject`][], its type must be `secret`. | ||
| 3394 | + a [`KeyObject`][], its type must be `secret`. If it is a string, please consider | ||
| 3395 | + [caveats when using strings as inputs to cryptographic APIs][]. If it was | ||
| 3396 | + obtained from a cryptographically secure source of entropy, such as | ||
| 3397 | + [`crypto.randomBytes()`][] or [`crypto.generateKey()`][], its length should not | ||
| 3398 | + exceed the block size of `algorithm` (e.g., 512 bits for SHA-256). | ||
| 3395 | 3399 | ||
| 3396 | 3400 | Example: generating the sha256 HMAC of a file | |
| 3397 | 3401 | ||
@@ -3665,6 +3669,9 @@ generateKey('hmac', { length: 512 }, (err, key) => { | |||
| 3665 | 3669 | }); | |
| 3666 | 3670 | ``` | |
| 3667 | 3671 | ||
| 3672 | + The size of a generated HMAC key should not exceed the block size of the | ||
| 3673 | + underlying hash function. See [`crypto.createHmac()`][] for more information. | ||
| 3674 | + | ||
| 3668 | 3675 | ### `crypto.generateKeyPair(type, options, callback)` | |
| 3669 | 3676 | ||
| 3670 | 3677 | <!-- YAML | |
@@ -3935,6 +3942,9 @@ const key = generateKeySync('hmac', { length: 512 }); | |||
| 3935 | 3942 | console.log(key.export().toString('hex')); // e89..........41e | |
| 3936 | 3943 | ``` | |
| 3937 | 3944 | ||
| 3945 | + The size of a generated HMAC key should not exceed the block size of the | ||
| 3946 | + underlying hash function. See [`crypto.createHmac()`][] for more information. | ||
| 3947 | + | ||
| 3938 | 3948 | ### `crypto.generatePrime(size[, options[, callback]])` | |
| 3939 | 3949 | ||
| 3940 | 3950 | <!-- YAML | |
@@ -6030,6 +6040,7 @@ See the [list of SSL OP Flags][] for details. | |||
| 6030 | 6040 | [`crypto.createSecretKey()`]: #cryptocreatesecretkeykey-encoding | |
| 6031 | 6041 | [`crypto.createSign()`]: #cryptocreatesignalgorithm-options | |
| 6032 | 6042 | [`crypto.createVerify()`]: #cryptocreateverifyalgorithm-options | |
| 6043 | + [`crypto.generateKey()`]: #cryptogeneratekeytype-options-callback | ||
| 6033 | 6044 | [`crypto.getCurves()`]: #cryptogetcurves | |
| 6034 | 6045 | [`crypto.getDiffieHellman()`]: #cryptogetdiffiehellmangroupname | |
| 6035 | 6046 | [`crypto.getHashes()`]: #cryptogethashes | |
0 commit comments