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 <[email protected]>
Reviewed-By: Filip Skokan <[email protected]>
Reviewed-By: Luigi Pinca <[email protected]>

doc/api/crypto.md

@@ -3391,7 +3391,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
 
@@ -3665,6 +3669,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)`
 
 <!-- YAML
@@ -3935,6 +3942,9 @@ const key = generateKeySync('hmac', { length: 512 });
 console.log(key.export().toString('hex'));  // e89..........41e
 ```
 
+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.generatePrime(size[, options[, callback]])`
 
 <!-- YAML
@@ -6030,6 +6040,7 @@ See the [list of SSL OP Flags][] for details.
 [`crypto.createSecretKey()`]: #cryptocreatesecretkeykey-encoding
 [`crypto.createSign()`]: #cryptocreatesignalgorithm-options
 [`crypto.createVerify()`]: #cryptocreateverifyalgorithm-options
+[`crypto.generateKey()`]: #cryptogeneratekeytype-options-callback
 [`crypto.getCurves()`]: #cryptogetcurves
 [`crypto.getDiffieHellman()`]: #cryptogetdiffiehellmangroupname
 [`crypto.getHashes()`]: #cryptogethashes