Commit d14018e
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 e9d4baf commit d14018e
1 file changed
Lines changed: 12 additions & 1 deletion
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -3410,7 +3410,11 @@ On recent releases of OpenSSL, `openssl list -digest-algorithms` will | |||
| 3410 | 3410 | display the available digest algorithms. | |
| 3411 | 3411 | ||
| 3412 | 3412 | The `key` is the HMAC key used to generate the cryptographic HMAC hash. If it is | |
| 3413 | - a [`KeyObject`][], its type must be `secret`. | ||
| 3413 | + a [`KeyObject`][], its type must be `secret`. If it is a string, please consider | ||
| 3414 | + [caveats when using strings as inputs to cryptographic APIs][]. If it was | ||
| 3415 | + obtained from a cryptographically secure source of entropy, such as | ||
| 3416 | + [`crypto.randomBytes()`][] or [`crypto.generateKey()`][], its length should not | ||
| 3417 | + exceed the block size of `algorithm` (e.g., 512 bits for SHA-256). | ||
| 3414 | 3418 | ||
| 3415 | 3419 | Example: generating the sha256 HMAC of a file | |
| 3416 | 3420 | ||
@@ -3682,6 +3686,9 @@ generateKey('hmac', { length: 512 }, (err, key) => { | |||
| 3682 | 3686 | }); | |
| 3683 | 3687 | ``` | |
| 3684 | 3688 | ||
| 3689 | + The size of a generated HMAC key should not exceed the block size of the | ||
| 3690 | + underlying hash function. See [`crypto.createHmac()`][] for more information. | ||
| 3691 | + | ||
| 3685 | 3692 | ### `crypto.generateKeyPair(type, options, callback)` | |
| 3686 | 3693 | ||
| 3687 | 3694 | <!-- YAML | |
@@ -3952,6 +3959,9 @@ const key = generateKeySync('hmac', { length: 512 }); | |||
| 3952 | 3959 | console.log(key.export().toString('hex')); // e89..........41e | |
| 3953 | 3960 | ``` | |
| 3954 | 3961 | ||
| 3962 | + The size of a generated HMAC key should not exceed the block size of the | ||
| 3963 | + underlying hash function. See [`crypto.createHmac()`][] for more information. | ||
| 3964 | + | ||
| 3955 | 3965 | ### `crypto.generatePrime(size[, options[, callback]])` | |
| 3956 | 3966 | ||
| 3957 | 3967 | <!-- YAML | |
@@ -6048,6 +6058,7 @@ See the [list of SSL OP Flags][] for details. | |||
| 6048 | 6058 | [`crypto.createSecretKey()`]: #cryptocreatesecretkeykey-encoding | |
| 6049 | 6059 | [`crypto.createSign()`]: #cryptocreatesignalgorithm-options | |
| 6050 | 6060 | [`crypto.createVerify()`]: #cryptocreateverifyalgorithm-options | |
| 6061 | + [`crypto.generateKey()`]: #cryptogeneratekeytype-options-callback | ||
| 6051 | 6062 | [`crypto.getCurves()`]: #cryptogetcurves | |
| 6052 | 6063 | [`crypto.getDiffieHellman()`]: #cryptogetdiffiehellmangroupname | |
| 6053 | 6064 | [`crypto.getHashes()`]: #cryptogethashes | |
0 commit comments