BackPup/node
1
0 Fork 0
mirror of https://github.com/nodejs/node.git synced 2026-10-14 10:26:26 -04:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
PR-URL: https://github.com/nodejs/node/pull/59644
Reviewed-By: James M Snell <jasnell@gmail.com>
This commit is contained in:
Filip Skokan authored and GitHub committed 2025-09-07 13:17:50 +00:00
1 parent a3cd430ef8
commit 4d5792a66c
1 file changed
+29 -2
Download Patch File Download Diff File Expand all files Collapse all files
doc/api/webcrypto.md
+29 -2
View File
@@ -801,9 +801,9 @@ added: v24.7.0
<!--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-->
@@ -812,6 +812,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
@@ -825,6 +827,10 @@ added: v24.7.0
* `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]
@@ -847,6 +853,10 @@ added: v24.7.0
* `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]
@@ -1032,6 +1042,9 @@ added: v24.7.0
* `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]
@@ -1053,6 +1066,9 @@ added: v24.7.0
* `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]
@@ -2033,6 +2049,11 @@ added: v15.0.0
added: v24.7.0
-->
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
@@ -2055,6 +2076,11 @@ added: v24.7.0
added: v24.7.0
-->
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
@@ -2657,6 +2683,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