SubtleCrypto: wrapKey() method
The wrapKey()
method of the SubtleCrypto
interface "wraps" a key. This means that it exports the key in an external, portable format, then encrypts the exported key. Wrapping a key helps protect it in untrusted environments, such as inside an otherwise unprotected data store or in transmission over an unprotected network.
As with SubtleCrypto.exportKey()
, you specify an export format for the key. To export a key, it must have CryptoKey.extractable
set to true
.
But because wrapKey()
also encrypts the key to be exported, you also need to pass in the key that must be used to encrypt it. This is sometimes called the "wrapping key".
The inverse of wrapKey()
is SubtleCrypto.unwrapKey()
: while wrapKey
is composed of export + encrypt, unwrapKey
is composed of import + decrypt.
Syntax
wrapKey(format, key, wrappingKey, wrapAlgo)
Parameters
format
-
A string describing the data format in which the key will be exported before it is encrypted. It can be one of the following:
raw
-
Raw format.
pkcs8
-
PKCS #8 format.
spki
-
SubjectPublicKeyInfo format.
jwk
-
JSON Web Key format.
key
-
The CryptoKey
to wrap.
wrappingkey
-
The CryptoKey
used to encrypt the exported key. The key must have the wrapKey
usage set.
wrapAlgo
-
An object specifying the algorithm to be used to encrypt the exported key, and any required extra parameters:
Return value
A Promise
that fulfills with an ArrayBuffer
containing the encrypted exported key.
Exceptions
The promise is rejected when one of the following exceptions is encountered:
-
InvalidAccessError
DOMException
-
Raised when the wrapping key is not a key for the requested wrap algorithm.
-
NotSupported
DOMException
-
Raised when trying to use an algorithm that is either unknown or isn't suitable for encryption or wrapping.
TypeError
-
Raised when trying to use an invalid format.
Supported algorithms
All algorithms that are usable for encryption are also usable for key wrapping, as long as the key has the "wrapKey" usage set. For key wrapping you have the additional option of AES-KW.
AES-KW
AES-KW is a way to use the AES cipher for key wrapping.
One advantage of using AES-KW over another AES mode such as AES-GCM is that AES-KW does not require an initialization vector. To use AES-KW, the input must be a multiple of 64 bits.
AES-KW is specified in RFC 3394.
Examples
Raw wrap
This example wraps an AES key. It uses "raw" as the export format and AES-KW, with a password-derived key, to encrypt it. See the complete code on GitHub.
let salt;
function getKeyMaterial() {
const password = window.prompt("Enter your password");
const enc = new TextEncoder();
return window.crypto.subtle.importKey(
"raw",
enc.encode(password),
{ name: "PBKDF2" },
false,
["deriveBits", "deriveKey"],
);
}
function getKey(keyMaterial, salt) {
return window.crypto.subtle.deriveKey(
{
name: "PBKDF2",
salt,
iterations: 100000,
hash: "SHA-256",
},
keyMaterial,
{ name: "AES-KW", length: 256 },
true,
["wrapKey", "unwrapKey"],
);
}
async function wrapCryptoKey(keyToWrap) {
const keyMaterial = await getKeyMaterial();
salt = window.crypto.getRandomValues(new Uint8Array(16));
const wrappingKey = await getKey(keyMaterial, salt);
return window.crypto.subtle.wrapKey("raw", keyToWrap, wrappingKey, "AES-KW");
}
window.crypto.subtle
.generateKey(
{
name: "AES-GCM",
length: 256,
},
true,
["encrypt", "decrypt"],
)
.then((secretKey) => wrapCryptoKey(secretKey))
.then((wrappedKey) => console.log(wrappedKey));
PKCS #8 wrap
This example wraps an RSA private signing key. It uses "pkcs8" as the export format and AES-GCM, with a password-derived key, to encrypt it. See the complete code on GitHub.
let salt;
let iv;
function getKeyMaterial() {
const password = window.prompt("Enter your password");
const enc = new TextEncoder();
return window.crypto.subtle.importKey(
"raw",
enc.encode(password),
{ name: "PBKDF2" },
false,
["deriveBits", "deriveKey"],
);
}
function getKey(keyMaterial, salt) {
return window.crypto.subtle.deriveKey(
{
name: "PBKDF2",
salt,
iterations: 100000,
hash: "SHA-256",
},
keyMaterial,
{ name: "AES-GCM", length: 256 },
true,
["wrapKey", "unwrapKey"],
);
}
async function wrapCryptoKey(keyToWrap) {
const keyMaterial = await getKeyMaterial();
salt = window.crypto.getRandomValues(new Uint8Array(16));
const wrappingKey = await getKey(keyMaterial, salt);
iv = window.crypto.getRandomValues(new Uint8Array(12));
return window.crypto.subtle.wrapKey("pkcs8", keyToWrap, wrappingKey, {
name: "AES-GCM",
iv,
});
}
window.crypto.subtle
.generateKey(
{
name: "RSA-PSS",
modulusLength: 2048,
publicExponent: new Uint8Array([1, 0, 1]),
hash: "SHA-256",
},
true,
["sign", "verify"],
)
.then((keyPair) => wrapCryptoKey(keyPair.privateKey))
.then((wrappedKey) => {
console.log(wrappedKey);
});
SubjectPublicKeyInfo wrap
This example wraps an RSA public encryption key. It uses "spki" as the export format and AES-CBC, with a password-derived key, to encrypt it. See the complete code on GitHub.
let salt;
let iv;
function getKeyMaterial() {
const password = window.prompt("Enter your password");
const enc = new TextEncoder();
return window.crypto.subtle.importKey(
"raw",
enc.encode(password),
{ name: "PBKDF2" },
false,
["deriveBits", "deriveKey"],
);
}
function getKey(keyMaterial, salt) {
return window.crypto.subtle.deriveKey(
{
name: "PBKDF2",
salt,
iterations: 100000,
hash: "SHA-256",
},
keyMaterial,
{ name: "AES-CBC", length: 256 },
true,
["wrapKey", "unwrapKey"],
);
}
async function wrapCryptoKey(keyToWrap) {
const keyMaterial = await getKeyMaterial();
salt = window.crypto.getRandomValues(new Uint8Array(16));
const wrappingKey = await getKey(keyMaterial, salt);
iv = window.crypto.getRandomValues(new Uint8Array(16));
return window.crypto.subtle.wrapKey("spki", keyToWrap, wrappingKey, {
name: "AES-CBC",
iv,
});
}
window.crypto.subtle
.generateKey(
{
name: "RSA-OAEP",
modulusLength: 2048,
publicExponent: new Uint8Array([1, 0, 1]),
hash: "SHA-256",
},
true,
["encrypt", "decrypt"],
)
.then((keyPair) => wrapCryptoKey(keyPair.publicKey))
.then((wrappedKey) => console.log(wrappedKey));
JSON Web Key wrap
This example wraps an ECDSA private signing key. It uses "jwk" as the export format and AES-GCM, with a password-derived key, to encrypt it. See the complete code on GitHub.
let salt;
let iv;
function getKeyMaterial() {
const password = window.prompt("Enter your password");
const enc = new TextEncoder();
return window.crypto.subtle.importKey(
"raw",
enc.encode(password),
{ name: "PBKDF2" },
false,
["deriveBits", "deriveKey"],
);
}
function getKey(keyMaterial, salt) {
return window.crypto.subtle.deriveKey(
{
name: "PBKDF2",
salt,
iterations: 100000,
hash: "SHA-256",
},
keyMaterial,
{ name: "AES-GCM", length: 256 },
true,
["wrapKey", "unwrapKey"],
);
}
async function wrapCryptoKey(keyToWrap) {
const keyMaterial = await getKeyMaterial();
salt = window.crypto.getRandomValues(new Uint8Array(16));
const wrappingKey = await getKey(keyMaterial, salt);
iv = window.crypto.getRandomValues(new Uint8Array(12));
return window.crypto.subtle.wrapKey("jwk", keyToWrap, wrappingKey, {
name: "AES-GCM",
iv,
});
}
window.crypto.subtle
.generateKey(
{
name: "ECDSA",
namedCurve: "P-384",
},
true,
["sign", "verify"],
)
.then((keyPair) => wrapCryptoKey(keyPair.privateKey))
.then((wrappedKey) => console.log(wrappedKey));
Specifications
Browser compatibility
|
Desktop |
Mobile |
|
Chrome |
Edge |
Firefox |
Internet Explorer |
Opera |
Safari |
WebView Android |
Chrome Android |
Firefox for Android |
Opera Android |
Safari on IOS |
Samsung Internet |
wrapKey |
37 |
7912–79Not supported: AES-CTR.
|
34 |
11Returns KeyOperation instead of Promise |
24 |
7 |
37 |
37 |
34 |
24 |
7 |
3.0 |
See also