1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: update function description for decipher.setAAD

Browse Source 
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: https://github.com/nodejs/node/pull/33095
Reviewed-By: Ujjwal Sharma <ryzokuken@disroot.org>
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
This commit is contained in:
Jonathan Buhacoff 2020-04-27 08:30:42 -07:00 committed by Anna Henningsen
parent b51d1cfbf2
commit d093e788d1
No known key found for this signature in database
GPG Key ID: A94130F0BFC8EBE9
1 changed files with 7 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
doc/api/crypto.md
View File

@ -493,7 +493,7 @@ _additional authenticated data_ (AAD) input parameter.
The `options` argument is optional for `GCM`. When using `CCM`, the The `options` argument is optional for `GCM`. When using `CCM`, the
`plaintextLength` option must be specified and its value must match the length `plaintextLength` option must be specified and its value must match the length
of the plaintext in bytes. See [CCM mode][]. of the ciphertext in bytes. See [CCM mode][].
The `decipher.setAAD()` method must be called before [`decipher.update()`][]. The `decipher.setAAD()` method must be called before [`decipher.update()`][].
@ -3104,7 +3104,12 @@ mode must adhere to certain restrictions when using the cipher API:
mode might fail as CCM cannot handle more than one chunk of data per instance. mode might fail as CCM cannot handle more than one chunk of data per instance.
* When passing additional authenticated data (AAD), the length of the actual * When passing additional authenticated data (AAD), the length of the actual
message in bytes must be passed to `setAAD()` via the `plaintextLength` message in bytes must be passed to `setAAD()` via the `plaintextLength`
option. This is not necessary if no AAD is used. option.
Many crypto libraries include the authentication tag in the ciphertext,
which means that they produce ciphertexts of the length
`plaintextLength + authTagLength`. Node.js does not include the authentication
tag, so the ciphertext length is always `plaintextLength`.
This is not necessary if no AAD is used.
* As CCM processes the whole message at once, `update()` can only be called * As CCM processes the whole message at once, `update()` can only be called
once. once.
* Even though calling `update()` is sufficient to encrypt/decrypt the message, * Even though calling `update()` is sufficient to encrypt/decrypt the message,