From d14018ed9909867b8a7d41e8458e26947222905d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tobias=20Nie=C3=9Fen?= Date: Wed, 24 May 2023 22:21:07 +0200 Subject: [PATCH] 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: https://github.com/nodejs/node/pull/48052 Refs: https://github.com/nodejs/node/pull/37248 PR-URL: https://github.com/nodejs/node/pull/48121 Reviewed-By: Marco Ippolito Reviewed-By: Filip Skokan Reviewed-By: Luigi Pinca --- doc/api/crypto.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/doc/api/crypto.md b/doc/api/crypto.md index 155f4d5a7cc982..c6d5bc101b40cf 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -3410,7 +3410,11 @@ On recent releases of OpenSSL, `openssl list -digest-algorithms` will display the available digest algorithms. The `key` is the HMAC key used to generate the cryptographic HMAC hash. If it is -a [`KeyObject`][], its type must be `secret`. +a [`KeyObject`][], its type must be `secret`. If it is a string, please consider +[caveats when using strings as inputs to cryptographic APIs][]. If it was +obtained from a cryptographically secure source of entropy, such as +[`crypto.randomBytes()`][] or [`crypto.generateKey()`][], its length should not +exceed the block size of `algorithm` (e.g., 512 bits for SHA-256). Example: generating the sha256 HMAC of a file @@ -3682,6 +3686,9 @@ generateKey('hmac', { length: 512 }, (err, key) => { }); ``` +The size of a generated HMAC key should not exceed the block size of the +underlying hash function. See [`crypto.createHmac()`][] for more information. + ### `crypto.generateKeyPair(type, options, callback)`