在此页

• 句法
• Supported algorithms
• 范例
• 规范
• 浏览器兼容性
• 另请参阅
• 相关话题

安全上下文
此特征只可用于 安全上下文 (HTTPS)，在某些或所有 支持浏览器 .

wrapKey() 方法在 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.

就像 SubtleCrypto.exportKey() , you specify an export format for the key. To export a key, it must have CryptoKey.extractable 设为 true .

But because wrapKey() also encrypts the key to be imported, you also need to pass in the key that must be used to encrypt it. This is sometimes called the "wrapping key".

逆 wrapKey() is SubtleCrypto.unwrapKey() : while wrapKey is composed of export + encrypt, unwrapKey is composed of import + decrypt.

句法

const result = crypto.subtle.wrapKey(
    format,
    key,
    wrappingKey,
    wrapAlgo
);
					

参数

• format is 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 格式。
  • pkcs8 : PKCS #8 格式。
  • spki : SubjectPublicKeyInfo 格式。
  • jwk : JSON Web Key 格式。
• key 是 CryptoKey to wrap.
• wrappingkey 是 CryptoKey used to encrypt the exported key. The key must have the wrapKey usage set.
• wrapAlgo is an object specifying the algorithm to be used to encrypt the exported key, and any required extra parameters:
  • 要使用 RSA-OAEP , pass an RsaOaepParams 对象。
  • 要使用 AES-CTR , pass an AesCtrParams 对象。
  • 要使用 AES-CBC , pass an AesCbcParams 对象。
  • 要使用 AES-GCM , pass an AesGcmParams 对象。
  • 要使用 AES-KW , pass the string "AES-KW" , or an object of the form { "name": "AES-KW } .

返回值

• result 是 Promise that fulfills with an ArrayBuffer containing the encrypted exported key.

异常

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

InvalidAccessError

Raised when the wrapping key is not a key for the requested wrap algorithm.

NotSupported

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

所有 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 .

范例

注意 : You can try the working examples out on GitHub.

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;
/*
Get some key material to use as input to the deriveKey method.
The key material is a password supplied by the user.
*/
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"]
  );
}
/*
Given some key material and some random salt
derive an AES-KW key using PBKDF2.
*/
function getKey(keyMaterial, salt) {
  return window.crypto.subtle.deriveKey(
    {
      "name": "PBKDF2",
      salt: salt,
      "iterations": 100000,
      "hash": "SHA-256"
    },
    keyMaterial,
    { "name": "AES-KW", "length": 256},
    true,
    [ "wrapKey", "unwrapKey" ]
  );
}
/*
Wrap the given key.
*/
async function wrapCryptoKey(keyToWrap) {
  // get the key encryption key
  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"
  );
}
/*
Generate an encrypt/decrypt secret key,
then wrap it.
*/
window.crypto.subtle.generateKey(
  {
    name: "AES-GCM",
    length: 256,
  },
  true,
  ["encrypt", "decrypt"]
)
.then((secretKey) => {
  return 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;
/*
Get some key material to use as input to the deriveKey method.
The key material is a password supplied by the user.
*/
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"]
  );
}
/*
Given some key material and some random salt
derive an AES-GCM key using PBKDF2.
*/
function getKey(keyMaterial, salt) {
  return window.crypto.subtle.deriveKey(
    {
      "name": "PBKDF2",
      salt: salt,
      "iterations": 100000,
      "hash": "SHA-256"
    },
    keyMaterial,
    { "name": "AES-GCM", "length": 256},
    true,
    [ "wrapKey", "unwrapKey" ]
  );
}
/*
Wrap the given key.
*/
async function wrapCryptoKey(keyToWrap) {
  // get the key encryption key
  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: iv
    }
  );
}
/*
Generate a sign/verify key pair,
then wrap the private key.
*/
window.crypto.subtle.generateKey(
  {
    name: "RSA-PSS",
    // Consider using a 4096-bit key for systems that require long-term security
    modulusLength: 2048,
    publicExponent: new Uint8Array([1, 0, 1]),
    hash: "SHA-256",
  },
  true,
  ["sign", "verify"]
)
.then((keyPair) => {
  return 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;
/*
Get some key material to use as input to the deriveKey method.
The key material is a password supplied by the user.
*/
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"]
  );
}
/*
Given some key material and some random salt
derive an AES-CBC key using PBKDF2.
*/
function getKey(keyMaterial, salt) {
  return window.crypto.subtle.deriveKey(
    {
      "name": "PBKDF2",
      salt: salt,
      "iterations": 100000,
      "hash": "SHA-256"
    },
    keyMaterial,
    { "name": "AES-CBC", "length": 256},
    true,
    [ "wrapKey", "unwrapKey" ]
  );
}
/*
Wrap the given key.
*/
async function wrapCryptoKey(keyToWrap) {
  // get the key encryption key
  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: iv
    }
  );
}
/*
Generate an encrypt/decrypt key pair,
then wrap it.
*/
window.crypto.subtle.generateKey(
  {
    name: "RSA-OAEP",
    // Consider using a 4096-bit key for systems that require long-term security
    modulusLength: 2048,
    publicExponent: new Uint8Array([1, 0, 1]),
    hash: "SHA-256",
  },
  true,
  ["encrypt", "decrypt"]
)
.then((keyPair) => {
  return wrapCryptoKey(keyPair.publicKey);
})
.then((wrappedKey) => {
  console.log(wrappedKey);
});
					

JSON Web Key import

This code 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;
/*
Get some key material to use as input to the deriveKey method.
The key material is a password supplied by the user.
*/
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"]
  );
}
/*
Given some key material and some random salt
derive an AES-GCM key using PBKDF2.
*/
function getKey(keyMaterial, salt) {
  return window.crypto.subtle.deriveKey(
    {
      "name": "PBKDF2",
      salt: salt,
      "iterations": 100000,
      "hash": "SHA-256"
    },
    keyMaterial,
    { "name": "AES-GCM", "length": 256},
    true,
    [ "wrapKey", "unwrapKey" ]
  );
}
/*
Wrap the given key.
*/
async function wrapCryptoKey(keyToWrap) {
  // get the key encryption key
  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: iv
    }
  );
}
/*
Generate a sign/verify key pair,
then wrap the private key
*/
window.crypto.subtle.generateKey(
  {
    name: "ECDSA",
    namedCurve: "P-384"
  },
  true,
  ["sign", "verify"]
)
.then((keyPair) => {
  return wrapCryptoKey(keyPair.privateKey);
})
.then((wrappedKey) => {
  console.log(wrappedKey);
});
					

规范

规范	状态	注释
Web Cryptography API The definition of 'SubtleCrypto.wrapKey()' in that specification.	推荐	初始定义。

浏览器兼容性

The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request. 更新 GitHub 上的兼容性数据

	桌面						移动
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
wrapKey	Chrome 37	Edge 部分支持 12 部分支持 12 Not supported: AES-CTR.	Firefox 34 34 不支持 32 — 34 Disabled Disabled ). To change preferences in Firefox, visit	IE 部分支持 11 部分支持 11 返回 KeyOperation 而不是 Promise	Opera 24	Safari 7	WebView Android 37	Chrome Android 37	Firefox Android 34 34 不支持 32 — 34 Disabled Disabled ). To change preferences in Firefox, visit	Opera Android 24	Safari iOS 7	Samsung Internet Android 6.0

图例

完整支持

完整支持

部分支持

部分支持

见实现注意事项。

用户必须明确启用此特征。

用户必须明确启用此特征。

另请参阅

• SubtleCrypto.exportKey()
• PKCS #8 format .
• SubjectPublicKeyInfo format .
• JSON Web Key format .
• AES-KW specification .

元数据

• 最后修改： Mar 23, 2020

相关话题

1. Web 加密 API
2. SubtleCrypto
3. 方法

   1. decrypt()
   2. deriveBits()
   3. deriveKey()
   4. digest()
   5. encrypt()
   6. exportKey()
   7. generateKey()
   8. importKey()
   9. sign()
   10. unwrapKey()
   11. verify()
   12. wrapKey()
4. Related pages for Web Crypto API

   1. Crypto
   2. CryptoKey
   3. CryptoKeyPair
   4. RandomSource
   5. Window.crypto