Commit d4e8714
doc: update function description for decipher.setAAD
According to the
[NodeJS CCM example](https://nodejs.org/docs/latest-v14.x/api/crypto.html#crypto_ccm_mode],
when decrypting the `plaintextLength` parameter actually refers to the
ciphertext length, not the plaintext length:
```
decipher.setAAD(aad, {
plaintextLength: ciphertext.length
});
```
The same can be seen in the
[OpenSSL docs](https://wiki.openssl.org/index.php/EVP_Authenticated_Encryption_and_Decryption)
where a call to `EVP_DecryptUpdate` passes the ciphertext length:
```
/* Provide the total ciphertext length */
if(1 != EVP_DecryptUpdate(ctx, NULL, &len, NULL, ciphertext_len))
handleErrors();
```
This parameter probably should have been called `inputLength` or
`bufferLength` instead of `plaintextLength`, so that it makes sense
both when encrypting and decrypting, but at least we can correct the
sentence in the documentation for now to refer to the correct value.
PR-URL: #33095
Reviewed-By: Ujjwal Sharma <ryzokuken@disroot.org>
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>1 parent e2484b2 commit d4e8714
1 file changed
Lines changed: 7 additions & 2 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -493,7 +493,7 @@ _additional authenticated data_ (AAD) input parameter. | |||
| 493 | 493 | ||
| 494 | 494 | The `options` argument is optional for `GCM`. When using `CCM`, the | |
| 495 | 495 | `plaintextLength` option must be specified and its value must match the length | |
| 496 | - of the plaintext in bytes. See [CCM mode][]. | ||
| 496 | + of the ciphertext in bytes. See [CCM mode][]. | ||
| 497 | 497 | ||
| 498 | 498 | The `decipher.setAAD()` method must be called before [`decipher.update()`][]. | |
| 499 | 499 | ||
@@ -3104,7 +3104,12 @@ mode must adhere to certain restrictions when using the cipher API: | |||
| 3104 | 3104 | mode might fail as CCM cannot handle more than one chunk of data per instance. | |
| 3105 | 3105 | * When passing additional authenticated data (AAD), the length of the actual | |
| 3106 | 3106 | message in bytes must be passed to `setAAD()` via the `plaintextLength` | |
| 3107 | - option. This is not necessary if no AAD is used. | ||
| 3107 | + option. | ||
| 3108 | + Many crypto libraries include the authentication tag in the ciphertext, | ||
| 3109 | + which means that they produce ciphertexts of the length | ||
| 3110 | + `plaintextLength + authTagLength`. Node.js does not include the authentication | ||
| 3111 | + tag, so the ciphertext length is always `plaintextLength`. | ||
| 3112 | + This is not necessary if no AAD is used. | ||
| 3108 | 3113 | * As CCM processes the whole message at once, `update()` can only be called | |
| 3109 | 3114 | once. | |
| 3110 | 3115 | * Even though calling `update()` is sufficient to encrypt/decrypt the message, | |
0 commit comments