Skip to content

Commit 0c9b826

Browse files
jbuhacoffcodebytere
authored andcommittedJun 9, 2020
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 4749156 commit 0c9b826

File tree

1 file changed

+7
-2
lines changed

1 file changed

+7
-2
lines changed
 

‎doc/api/crypto.md

+7-2
Original file line numberDiff line numberDiff line change
@@ -493,7 +493,7 @@ _additional authenticated data_ (AAD) input parameter.
493493

494494
The `options` argument is optional for `GCM`. When using `CCM`, the
495495
`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][].
497497

498498
The `decipher.setAAD()` method must be called before [`decipher.update()`][].
499499

@@ -3088,7 +3088,12 @@ mode must adhere to certain restrictions when using the cipher API:
30883088
mode might fail as CCM cannot handle more than one chunk of data per instance.
30893089
* When passing additional authenticated data (AAD), the length of the actual
30903090
message in bytes must be passed to `setAAD()` via the `plaintextLength`
3091-
option. This is not necessary if no AAD is used.
3091+
option.
3092+
Many crypto libraries include the authentication tag in the ciphertext,
3093+
which means that they produce ciphertexts of the length
3094+
`plaintextLength + authTagLength`. Node.js does not include the authentication
3095+
tag, so the ciphertext length is always `plaintextLength`.
3096+
This is not necessary if no AAD is used.
30923097
* As CCM processes the whole message at once, `update()` can only be called
30933098
once.
30943099
* Even though calling `update()` is sufficient to encrypt/decrypt the message,

0 commit comments

Comments
 (0)
Please sign in to comment.