crypto: add getCipherInfo method

Simple method for retrieving basic information about a cipher
(such as block length, expected or default iv length, key length,
etc)

Signed-off-by: James M Snell <jasnell@gmail.com>
Fixes: https://github.com/nodejs/node/issues/22304

PR-URL: https://github.com/nodejs/node/pull/35368
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>

1 files changed, 29 insertions, 0 deletions

diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index 32e90ca030b..2e1744910b9 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -2424,6 +2424,35 @@ const ciphers = crypto.getCiphers();
 console.log(ciphers); // ['aes-128-cbc', 'aes-128-ccm', ...]
 ```
 
+### `crypto.getCipherInfo(nameOrNid[, options])`
+<!-- YAML
+added: REPLACEME
+-->
+
+* `nameOrNid`: {string|number} The name or nid of the cipher to query.
+* `options`: {Object}
+  * `keyLength`: {number} A test key length.
+  * `ivLength`: {number} A test IV length.
+* Returns: {Object}
+  * `name` {string} The name of the cipher
+  * `nid` {number} The nid of the cipher
+  * `blockSize` {number} The block size of the cipher in bytes. This property
+    is omitted when `mode` is `'stream'`.
+  * `ivLength` {number} The expected or default initialization vector length in
+    bytes. This property is omitted if the cipher does not use an initialization
+    vector.
+  * `keyLength` {number} The expected or default key length in bytes.
+  * `mode` {string} The cipher mode. One of `'cbc'`, `'ccm'`, `'cfb'`, `'ctr'`,
+    `'ecb'`, `'gcm'`, `'ocb'`, `'ofb'`, `'stream'`, `'wrap'`, `'xts'`.
+
+Returns information about a given cipher.
+
+Some ciphers accept variable length keys and initialization vectors. By default,
+the `crypto.getCipherInfo()` method will return the default values for these
+ciphers. To test if a given key length or iv length is acceptable for given
+cipher, use the `keyLenth` and `ivLenth` options. If the given values are
+unacceptable, `undefined` will be returned.
+
 ### `crypto.getCurves()`
 <!-- YAML
 added: v2.3.0