doc,crypto: add description to the KEM and supports() methods · nodejs/node@f5b6829
@@ -800,9 +800,9 @@ added: v24.7.0
800800801801<!--lint disable maximum-line-length remark-lint-->
802802803-* `operation` {string} "encrypt", "decrypt", "sign", "verify", "digest", "generateKey", "deriveKey", "deriveBits", "importKey", "exportKey", "getPublicKey", "wrapKey", or "unwrapKey"
803+* `operation` {string} "encrypt", "decrypt", "sign", "verify", "digest", "generateKey", "deriveKey", "deriveBits", "importKey", "exportKey", "getPublicKey", "wrapKey", "unwrapKey", "encapsulateBits", "encapsulateKey", "decapsulateBits", or "decapsulateKey"
804804* `algorithm` {string|Algorithm}
805-* `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.
805+* `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.
806806* Returns: {boolean} Indicating whether the implementation supports the given operation
807807808808<!--lint enable maximum-line-length remark-lint-->
@@ -811,6 +811,8 @@ Allows feature detection in Web Crypto API,
811811which can be used to detect whether a given algorithm identifier
812812(including its parameters) is supported for the given operation.
813813814+See [Checking for runtime algorithm support][] for an example use of this method.
815+814816### `subtle.decapsulateBits(decapsulationAlgorithm, decapsulationKey, ciphertext)`
815817816818<!-- YAML
@@ -824,6 +826,10 @@ added: v24.7.0
824826* `ciphertext` {ArrayBuffer|TypedArray|DataView|Buffer}
825827* Returns: {Promise} Fulfills with {ArrayBuffer} upon success.
826828829+A message recipient uses their asymmetric private key to decrypt an
830+"encapsulated key" (ciphertext), thereby recovering a temporary symmetric
831+key (represented as {ArrayBuffer}) which is then used to decrypt a message.
832+827833The algorithms currently supported include:
828834829835* `'ML-KEM-512'`[^modern-algos]
@@ -846,6 +852,10 @@ added: v24.7.0
846852* `usages` {string\[]} See [Key usages][].
847853* Returns: {Promise} Fulfills with {CryptoKey} upon success.
848854855+A message recipient uses their asymmetric private key to decrypt an
856+"encapsulated key" (ciphertext), thereby recovering a temporary symmetric
857+key (represented as {CryptoKey}) which is then used to decrypt a message.
858+849859The algorithms currently supported include:
850860851861* `'ML-KEM-512'`[^modern-algos]
@@ -1031,6 +1041,9 @@ added: v24.7.0
10311041* `encapsulationKey` {CryptoKey}
10321042* Returns: {Promise} Fulfills with {EncapsulatedBits} upon success.
103310431044+Uses a message recipient's asymmetric public key to encrypt a temporary symmetric key.
1045+This encrypted key is the "encapsulated key" represented as {EncapsulatedBits}.
1046+10341047The algorithms currently supported include:
1035104810361049* `'ML-KEM-512'`[^modern-algos]
@@ -1052,6 +1065,9 @@ added: v24.7.0
10521065* `usages` {string\[]} See [Key usages][].
10531066* Returns: {Promise} Fulfills with {EncapsulatedKey} upon success.
105410671068+Uses a message recipient's asymmetric public key to encrypt a temporary symmetric key.
1069+This encrypted key is the "encapsulated key" represented as {EncapsulatedKey}.
1070+10551071The algorithms currently supported include:
1056107210571073* `'ML-KEM-512'`[^modern-algos]
@@ -2032,6 +2048,11 @@ added: v15.0.0
20322048added: v24.7.0
20332049-->
203420502051+A temporary symmetric secret key (represented as {ArrayBuffer}) for message encryption
2052+and the ciphertext (that can be transmitted to the message recipient along with the
2053+message) encrypted by this shared key. The recipient uses their private key to determine
2054+what the shared key is which then allows them to decrypt the message.
2055+20352056#### `encapsulatedBits.ciphertext`
2036205720372058<!-- YAML
@@ -2054,6 +2075,11 @@ added: v24.7.0
20542075added: v24.7.0
20552076-->
205620772078+A temporary symmetric secret key (represented as {CryptoKey}) for message encryption
2079+and the ciphertext (that can be transmitted to the message recipient along with the
2080+message) encrypted by this shared key. The recipient uses their private key to determine
2081+what the shared key is which then allows them to decrypt the message.
2082+20572083#### `encapsulatedKey.ciphertext`
2058208420592085<!-- YAML
@@ -2656,6 +2682,7 @@ The length (in bytes) of the random salt to use.
2656268226572683[^openssl35]: Requires OpenSSL >= 3.5
265826842685+[Checking for runtime algorithm support]: #checking-for-runtime-algorithm-support
26592686[JSON Web Key]: https://tools.ietf.org/html/rfc7517
26602687[Key usages]: #cryptokeyusages
26612688[Modern Algorithms in the Web Cryptography API]: #modern-algorithms-in-the-web-cryptography-api