Skip to content

doc,crypto: add description to the KEM and supports() methods #59644

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

Merged
merged 1 commit into from
Sep 7, 2025
+29 −2
Merged

doc,crypto: add description to the KEM and supports() methods #59644

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
31 changes: 29 additions & 2 deletions doc/api/webcrypto.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -790,9 +790,9 @@ added: REPLACEME

<!--lint disable maximum-line-length remark-lint-->

* `operation` {string} "encrypt", "decrypt", "sign", "verify", "digest", "generateKey", "deriveKey", "deriveBits", "importKey", "exportKey", "getPublicKey", "wrapKey", or "unwrapKey"
* `operation` {string} "encrypt", "decrypt", "sign", "verify", "digest", "generateKey", "deriveKey", "deriveBits", "importKey", "exportKey", "getPublicKey", "wrapKey", "unwrapKey", "encapsulateBits", "encapsulateKey", "decapsulateBits", or "decapsulateKey"
* `algorithm` {string|Algorithm}
* `lengthOrAdditionalAlgorithm` {null|number|string|Algorithm|undefined} Depending on the operation this is either ignored, the value of the length argument when operation is "deriveBits", the algorithm of key to be derived when operation is "deriveKey", the algorithm of key to be exported before wrapping when operation is "wrapKey", or the algorithm of key to be imported after unwrapping when operation is "unwrapKey". **Default:** `null` when operation is "deriveBits", `undefined` otherwise.
* `lengthOrAdditionalAlgorithm` {null|number|string|Algorithm|undefined} Depending on the operation this is either ignored, the value of the length argument when operation is "deriveBits", the algorithm of key to be derived when operation is "deriveKey", the algorithm of key to be exported before wrapping when operation is "wrapKey", the algorithm of key to be imported after unwrapping when operation is "unwrapKey", or the algorithm of key to be imported after en/decapsulating a key when operation is "encapsulateKey" or "decapsulateKey". **Default:** `null` when operation is "deriveBits", `undefined` otherwise.
* Returns: {boolean} Indicating whether the implementation supports the given operation

<!--lint enable maximum-line-length remark-lint-->
Expand All @@ -801,6 +801,8 @@ Allows feature detection in Web Crypto API,
which can be used to detect whether a given algorithm identifier
(including its parameters) is supported for the given operation.

See [Checking for runtime algorithm support][] for an example use of this method.

### `subtle.decapsulateBits(decapsulationAlgorithm, decapsulationKey, ciphertext)`

<!-- YAML
Expand All @@ -814,6 +816,10 @@ added: REPLACEME
* `ciphertext` {ArrayBuffer|TypedArray|DataView|Buffer}
* Returns: {Promise} Fulfills with {ArrayBuffer} upon success.

A message recipient uses their asymmetric private key to decrypt an
"encapsulated key" (ciphertext), thereby recovering a temporary symmetric
key (represented as {ArrayBuffer}) which is then used to decrypt a message.

The algorithms currently supported include:

* `'ML-KEM-512'`[^modern-algos]
Expand All @@ -836,6 +842,10 @@ added: REPLACEME
* `usages` {string\[]} See [Key usages][].
* Returns: {Promise} Fulfills with {CryptoKey} upon success.

A message recipient uses their asymmetric private key to decrypt an
"encapsulated key" (ciphertext), thereby recovering a temporary symmetric
key (represented as {CryptoKey}) which is then used to decrypt a message.

The algorithms currently supported include:

* `'ML-KEM-512'`[^modern-algos]
Expand Down Expand Up @@ -1021,6 +1031,9 @@ added: REPLACEME
* `encapsulationKey` {CryptoKey}
* Returns: {Promise} Fulfills with {EncapsulatedBits} upon success.

Uses a message recipient's asymmetric public key to encrypt a temporary symmetric key.
This encrypted key is the "encapsulated key" represented as {EncapsulatedBits}.

The algorithms currently supported include:

* `'ML-KEM-512'`[^modern-algos]
Expand All @@ -1042,6 +1055,9 @@ added: REPLACEME
* `usages` {string\[]} See [Key usages][].
* Returns: {Promise} Fulfills with {EncapsulatedKey} upon success.

Uses a message recipient's asymmetric public key to encrypt a temporary symmetric key.
This encrypted key is the "encapsulated key" represented as {EncapsulatedKey}.

The algorithms currently supported include:

* `'ML-KEM-512'`[^modern-algos]
Expand Down Expand Up @@ -2023,6 +2039,11 @@ which is equivalent to not providing context at all.
added: REPLACEME
-->

A temporary symmetric secret key (represented as {ArrayBuffer}) for message encryption
and the ciphertext (that can be transmitted to the message recipient along with the
message) encrypted by this shared key. The recipient uses their private key to determine
what the shared key is which then allows them to decrypt the message.

#### `encapsulatedBits.ciphertext`

<!-- YAML
Expand All @@ -2045,6 +2066,11 @@ added: REPLACEME
added: REPLACEME
-->

A temporary symmetric secret key (represented as {CryptoKey}) for message encryption
and the ciphertext (that can be transmitted to the message recipient along with the
message) encrypted by this shared key. The recipient uses their private key to determine
what the shared key is which then allows them to decrypt the message.

#### `encapsulatedKey.ciphertext`

<!-- YAML
Expand Down Expand Up @@ -2538,6 +2564,7 @@ The length (in bytes) of the random salt to use.

[^openssl35]: Requires OpenSSL >= 3.5

[Checking for runtime algorithm support]: #checking-for-runtime-algorithm-support
[JSON Web Key]: https://tools.ietf.org/html/rfc7517
[Key usages]: #cryptokeyusages
[Modern Algorithms in the Web Cryptography API]: #modern-algorithms-in-the-web-cryptography-api
Expand Down
Loading