unwrapKey

unwrapKey is a function in the Web Cryptography API that reconstructs a CryptoKey from wrapped key material. It is a method of the SubtleCrypto interface and is typically used in key provisioning or secure key storage workflows, where a key has been wrapped (encrypted) for safe transport or storage and must be later restored for use.

The function takes several parameters:

- format: a string describing the import format for the unwrapped key, such as "raw" for secret keys, "spki" for public keys, "pkcs8" for private keys, or "jwk" for JSON Web Key representations.

- wrappedKey: an ArrayBuffer or TypedArray containing the wrapped key data.

- unwrappingKey: a CryptoKey that will be used to unwrap the wrappedKey material. This is the key that performs the unwrapping operation.

- unwrapAlgorithm: an object describing the wrapping algorithm, for example { name: "AES-KW" } or { name: "RSA-OAEP" }. This must match the algorithm used to wrap the key.

- unwrappedKeyAlgorithm: an object describing the algorithm of the resulting key, such as { name: "AES-GCM", length: 256 } or a suitable RSA algorithm. The algorithm must be compatible with the unwrapped key material.

- extractable: a boolean indicating whether the resulting key may be exported again.

- keyUsages: an array of permitted operations for the unwrapped key, such as ["encrypt", "decrypt"] or ["sign", "verify"].

unwrapKey returns a Promise that resolves to the resulting CryptoKey, or rejects if the operation fails (due to mismatched algorithms, invalid key material, or security constraints).

Example usage involves wrapping a key with a wrapping key and later restoring it with unwrapKey to obtain a usable CryptoKey.