Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc/crypto: include options and correct return type for setAAD() #21420

Closed
wants to merge 4 commits into from
Closed

doc/crypto: include options and correct return type for setAAD() #21420

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1ca372f
Ensure most Decipher methods return Decipher; not Cipher
ZaneHannanAU Jun 20, 2018
9de6ebf
Remove unadded AADOptions type
ZaneHannanAU Jun 20, 2018
94cb48f
Add `plaintextLength` to `setAAD` options
ZaneHannanAU Jun 24, 2018
f8a6090
Fix misspelling, wordlinting mistake.
ZaneHannanAU Jun 24, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 9 additions & 4 deletions doc/api/crypto.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -398,7 +398,7 @@ Once the `decipher.final()` method has been called, the `Decipher` object can
no longer be used to decrypt data. Attempts to call `decipher.final()` more
than once will result in an error being thrown.

### decipher.setAAD(buffer)
### decipher.setAAD(buffer[, options])
<!-- YAML
added: v1.0.0
changes:
Expand All @@ -407,12 +407,17 @@ changes:
description: This method now returns a reference to `decipher`.
-->
- `buffer` {Buffer | TypedArray | DataView}
- Returns: {Cipher} for method chaining.
- `options` {Object}
Copy link
Contributor

@vsemozhetbyt vsemozhetbyt Jun 20, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems plaintextLength should be documented here as well, as a property of options, in a nested level.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah; I had originally planned on writing an AADOptions block but it was so short I didn't feel the need to.

Also I added CipherGCMOptions and CipherCCMOptions in @types/node; though not sure how I should go about that in @nodejs/node.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you check other documentations, you'll see how options are handled there. Normally it just get's a short description what it stands for right after the type.

- Returns: {Decipher} for method chaining.

When using an authenticated encryption mode (only `GCM` and `CCM` are currently
supported), the `decipher.setAAD()` method sets the value used for the
_additional authenticated data_ (AAD) input parameter.

The `options` argument is optional for `GCM`. When using `CCM`, the
`plaintextLength` option must be specified and its value must match the length
of the plaintext in bytes. See [CCM mode][].

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

### decipher.setAuthTag(buffer)
Expand All @@ -427,7 +432,7 @@ changes:
description: This method now returns a reference to `decipher`.
-->
- `buffer` {Buffer | TypedArray | DataView}
- Returns: {Cipher} for method chaining.
- Returns: {Decipher} for method chaining.

When using an authenticated encryption mode (only `GCM` and `CCM` are currently
supported), the `decipher.setAuthTag()` method is used to pass in the
Expand All @@ -453,7 +458,7 @@ The `decipher.setAuthTag()` method must be called before
added: v0.7.1
-->
- `autoPadding` {boolean} **Default:** `true`
- Returns: {Cipher} for method chaining.
- Returns: {Decipher} for method chaining.

When data has been encrypted without standard block padding, calling
`decipher.setAutoPadding(false)` will disable automatic padding to prevent
Expand Down