diff options
author | Tobias Nießen <tniessen@tnie.de> | 2022-03-21 19:41:39 +0300 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-03-21 19:41:39 +0300 |
commit | 655926155647ad39236220b094c7d1f391ce02ed (patch) | |
tree | c0e2b9d4253bc6e8a3ee73352de7b563b94c3334 /doc | |
parent | df39fd64b330e8f0db6892c2984983d0d1da9250 (diff) |
doc,test: clarify ChaCha20-Poly1305 usage
PR-URL: https://github.com/nodejs/node/pull/42323
Reviewed-By: James M Snell <jasnell@gmail.com>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/api/crypto.md | 27 |
1 files changed, 18 insertions, 9 deletions
diff --git a/doc/api/crypto.md b/doc/api/crypto.md index 3d291df3e3b..99b6fe8ed62 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -546,7 +546,8 @@ added: v1.0.0 --> * Returns: {Buffer} When using an authenticated encryption mode (`GCM`, `CCM`, - and `OCB` are currently supported), the `cipher.getAuthTag()` method returns a + `OCB`, and `chacha20-poly1305` are currently supported), the + `cipher.getAuthTag()` method returns a [`Buffer`][] containing the _authentication tag_ that has been computed from the given data. @@ -568,7 +569,8 @@ added: v1.0.0 * `encoding` {string} The string encoding to use when `buffer` is a string. * Returns: {Cipher} for method chaining. -When using an authenticated encryption mode (`GCM`, `CCM`, and `OCB` are +When using an authenticated encryption mode (`GCM`, `CCM`, `OCB`, and +`chacha20-poly1305` are currently supported), the `cipher.setAAD()` method sets the value used for the _additional authenticated data_ (AAD) input parameter. @@ -865,7 +867,8 @@ changes: * `encoding` {string} String encoding to use when `buffer` is a string. * Returns: {Decipher} for method chaining. -When using an authenticated encryption mode (`GCM`, `CCM`, and `OCB` are +When using an authenticated encryption mode (`GCM`, `CCM`, `OCB`, and +`chacha20-poly1305` are currently supported), the `decipher.setAAD()` method sets the value used for the _additional authenticated data_ (AAD) input parameter. @@ -899,7 +902,8 @@ changes: * `encoding` {string} String encoding to use when `buffer` is a string. * Returns: {Decipher} for method chaining. -When using an authenticated encryption mode (`GCM`, `CCM`, and `OCB` are +When using an authenticated encryption mode (`GCM`, `CCM`, `OCB`, and +`chacha20-poly1305` are currently supported), the `decipher.setAuthTag()` method is used to pass in the received _authentication tag_. If no tag is provided, or if the cipher text has been tampered with, [`decipher.final()`][] will throw, indicating that the @@ -908,7 +912,8 @@ is invalid according to [NIST SP 800-38D][] or does not match the value of the `authTagLength` option, `decipher.setAuthTag()` will throw an error. The `decipher.setAuthTag()` method must be called before [`decipher.update()`][] -for `CCM` mode or before [`decipher.final()`][] for `GCM` and `OCB` modes. +for `CCM` mode or before [`decipher.final()`][] for `GCM` and `OCB` modes and +`chacha20-poly1305`. `decipher.setAuthTag()` can only be called once. When passing a string as the authentication tag, please consider @@ -2967,7 +2972,8 @@ Creates and returns a `Cipher` object that uses the given `algorithm` and `password`. The `options` argument controls stream behavior and is optional except when a -cipher in CCM or OCB mode is used (e.g. `'aes-128-ccm'`). In that case, the +cipher in CCM or OCB mode (e.g. `'aes-128-ccm'`) or `chacha20-poly1305` is used. +In that case, the `authTagLength` option is required and specifies the length of the authentication tag in bytes, see [CCM mode][]. In GCM mode, the `authTagLength` option is not required but can be used to set the length of the authentication @@ -3038,7 +3044,8 @@ Creates and returns a `Cipher` object, with the given `algorithm`, `key` and initialization vector (`iv`). The `options` argument controls stream behavior and is optional except when a -cipher in CCM or OCB mode is used (e.g. `'aes-128-ccm'`). In that case, the +cipher in CCM or OCB mode (e.g. `'aes-128-ccm'`) or `chacha20-poly1305` is used. +In that case, the `authTagLength` option is required and specifies the length of the authentication tag in bytes, see [CCM mode][]. In GCM mode, the `authTagLength` option is not required but can be used to set the length of the authentication @@ -3086,7 +3093,8 @@ Creates and returns a `Decipher` object that uses the given `algorithm` and `password` (key). The `options` argument controls stream behavior and is optional except when a -cipher in CCM or OCB mode is used (e.g. `'aes-128-ccm'`). In that case, the +cipher in CCM or OCB mode (e.g. `'aes-128-ccm'`) or `chacha20-poly1305` is used. +In that case, the `authTagLength` option is required and specifies the length of the authentication tag in bytes, see [CCM mode][]. @@ -3139,7 +3147,8 @@ Creates and returns a `Decipher` object that uses the given `algorithm`, `key` and initialization vector (`iv`). The `options` argument controls stream behavior and is optional except when a -cipher in CCM or OCB mode is used (e.g. `'aes-128-ccm'`). In that case, the +cipher in CCM or OCB mode (e.g. `'aes-128-ccm'`) or `chacha20-poly1305` is used. +In that case, the `authTagLength` option is required and specifies the length of the authentication tag in bytes, see [CCM mode][]. In GCM mode, the `authTagLength` option is not required but can be used to restrict accepted authentication tags |