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

PR-URL: #59644
Reviewed-By: James M Snell <[email protected]>

Author: panva

doc/api/webcrypto.md

@@ -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