SubtleCrypto.unwrapKey

The SubtleCrypto.unwrapKey() method returns a Promise of a CryptoKey corresponding to the wrapped key given in parameter.

Syntax

var result = crypto.unwrapKey(format, wrappedKey, unwrappingKey, unwrapAlgo, unwrappedKeyAlgo, extractable, keyUsages);

Parameters

• format is an enumerated value describing the data format of the key to unwrapped. It can be one of the following:
  • "raw", the key as an array of bytes, usually a secret key.
  • "pkcs8" a private key, in the IETF Public Key-Cryptographic Standard Encryption #8.
  • "spki", usually a public key, in the Simple public key infrastructure standard
  • "jwk", the key in the JSON Web Key format.
• wrappedKey is a ArrayBuffer or a ... containing the wrapped key in the given format.
• unwrappingKey is the CryptoKey to use to unwrap.
• unwrapAlgo is the DOMString} representing the algorithm used to perform the unwrapping. It is one of the following: AES-CBC, AES-CTR, AES-GCM, RSA-OAEP, and AES-KW.
• unwrappedKeyAlgois the DOMString} representing the algorithm of the wrapped key.
• extractable is a Boolean indicating if the key can be extracted from the CryptoKey object at a later stage.
• keyUsages is an Array indicating what can be done with the unwrapped key. Possible values of the array are:
  • "encrypt", allowing the key to be used for encrypting messages.
  • "decrypt", allowing the key to be used for decrypting messages.
  • "sign", allowing the key to be used for signing messages.
  • "verify", allowing the key to be used for verifying the signature of messages.
  • "deriveKey", allowing the key to be used as a base key when deriving a new key.
  • "deriveBits", allowing the key to be used as a base key when deriving bits of data for use in cryptographic primitives.
  • "wrapKey", allowing the key to wrap a symmetric key for usage (transfer, storage) in unsecure environments.
  • "unwrapKey", allowing the key to unwrap a symmetric key for usage (transfer, storage) in unsecure environments.

Return value

• result is a Promise that returns the unwrapped key as a CryptoKey

Exceptions

The promise is rejected when one of the following exceptions is encountered:

• InvalidAccessError when the unwrapping key is not a key for the requested unwrap algorithm or if the CryptoKey.usages value of that key doesn't contain "unwrap".
• NotSupported when trying to use an algorithm that is either unknown or isn't suitable for encryption or wrapping.
• SyntaxError when keyUsages is empty but the unwrapped key is of type "secret" or "private".
• TypeError when trying to use an invalid format.

Specifications

Specification	Status	Comment
Web Cryptography API The definition of 'SubtleCrypto.unwrapKey()' in that specification.	Candidate Recommendation	Initial definition.

Browser compatibility

See also

• Crypto and Crypto.subtle.
• SubtleCrypto, the interface it belongs to.