SubtleCrypto.importKey()

在此页

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

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

importKey() 方法在 SubtleCrypto interface imports a key: that is, it takes as input a key in an external, portable format and gives you a CryptoKey object that you can use in the Web 加密 API .

The function accepts several import formats: see Supported formats 了解细节。

句法

const result = crypto.subtle.importKey(
    format,
    keyData,
    algorithm,
    extractable,
    usages
);

参数

format is a string describing the data format of the key to import. It can be one of the following:
- raw : Raw 格式。
- pkcs8 : PKCS #8 格式。
- spki : SubjectPublicKeyInfo 格式。
- jwk : JSON Web Key 格式。
keyData 是 ArrayBuffer ， TypedArray ， DataView ，或 JSONWebKey object containing the key in the given format.
algorithm is a dictionary object defining the type of key to import and providing extra algorithm-specific parameters.
- For RSASSA-PKCS1-v1_5 , RSA-PSS ，或 RSA-OAEP : Pass an RsaHashedImportParams 对象。
- For ECDSA or ECDH : Pass an EcKeyImportParams 对象。
- For HMAC : Pass an HmacImportParams 对象。
- For AES-CTR , AES-CBC , AES-GCM ，或 AES-KW : Pass the string identifying the algorithm or an object of the form { "name": ALGORITHM } ，其中 ALGORITHM is the name of the algorithm.
- For PBKDF2 : Pass the string PBKDF2 .
extractable 是 布尔 indicating whether it will be possible to export the key using SubtleCrypto.exportKey() or SubtleCrypto.wrapKey() .
keyUsages 是 数组 indicating what can be done with the key. Possible array values are:
- encrypt : The key may be used to encrypt messages.
- decrypt : The key may be used to decrypt messages.
- sign : The key may be used to sign messages.
- verify : The key may be used to verify signatures.
- deriveKey : The key may be used in deriving a new key .
- deriveBits : The key may be used in deriving bits .
- wrapKey : The key may be used to wrap a key .
- unwrapKey : The key may be used to unwrap a key .

返回值

result 是 Promise that fulfills with the imported key as a CryptoKey 对象。

异常

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

SyntaxError: Raised when keyUsages is empty but the unwrapped key is of type secret or private .
TypeError: Raised when trying to use an invalid format or if the keyData is not suited for that format.

Supported formats

This API supports four different key import/export formats: Raw, PKCS #8, SubjectPublicKeyInfo, and JSON Web Key.

Raw

You can use this format to import or export AES or HMAC secret keys, or Elliptic Curve public keys.

In this format the key is supplied as an ArrayBuffer containing the raw bytes for the key.

PKCS #8

You can use this format to import or export RSA or Elliptic Curve private keys.

The PKCS #8 format is defined in RFC 5208 ., using the ASN.1 notation :

PrivateKeyInfo ::= SEQUENCE {
    version                   Version,
    privateKeyAlgorithm       PrivateKeyAlgorithmIdentifier,
    privateKey                PrivateKey,
    attributes           [0]  IMPLICIT Attributes OPTIONAL }

importKey() method expects to receive this object as an ArrayBuffer containing the DER-encoded form of the PrivateKeyInfo . DER is a set of rules for encoding ASN.1 structures into a binary form.

You are most likely to encounter this object in PEM format . PEM format is a way to encode binary data in ASCII. It consists of a header and a footer, and in between, the base64-encoded binary data. A PEM-encoded PrivateKeyInfo 看起来像这样：

To get this into a format you can give to importKey() you need to do two things:

base64-decode the part between header and footer, using window.atob() .
convert the resulting string into an ArrayBuffer .

见范例 section for more concrete guidance.

SubjectPublicKeyInfo

You can use this format to import or export RSA or Elliptic Curve public keys.

SubjectPublicKey is defined in RFC 5280, Section 4.1 使用 ASN.1 notation:

SubjectPublicKeyInfo  ::=  SEQUENCE  {
    algorithm            AlgorithmIdentifier,
    subjectPublicKey     BIT STRING  }

就像 PKCS #8 ， importKey() method expects to receive this object as an ArrayBuffer containing the DER-encoded form of the SubjectPublicKeyInfo .

Again, you are most likely to encounter this object in PEM format . A PEM-encoded SubjectPublicKeyInfo 看起来像这样：

Just as with PKCS #8 , to get this into a format you can give to importKey() you need to do two things:

base64-decode the part between header and footer, using window.atob() .
convert the resulting string into an ArrayBuffer .

见范例 section for more concrete guidance.

JSON Web Key

You can use JSON Web Key format to import or export RSA or Elliptic Curve public or private keys, as well as AES and HMAC secret keys.

JSON Web Key format is defined in RFC 7517 . It describes a way to represent public, private, and secret keys as JSON objects.

A JSON Web Key looks something like this (this is an EC private key):

{
  "crv": "P-384",
  "d": "wouCtU7Nw4E8_7n5C1-xBjB4xqSb_liZhYMsy8MGgxUny6Q8NCoH9xSiviwLFfK_",
  "ext": true,
  "key_ops": ["sign"],
  "kty": "EC",
  "x": "SzrRXmyI8VWFJg1dPUNbFcc9jZvjZEfH7ulKI1UkXAltd7RGWrcfFxqyGPcwu6AQ",
  "y": "hHUag3OvDzEr0uUQND4PXHQTXP5IDGdYhJhL-WLKjnGjQAw0rNGy5V29-aV-yseW"
};

范例

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

Raw import

This example imports an AES key from an ArrayBuffer containing the bytes to use. See the complete code on GitHub.

const rawKey = window.crypto.getRandomValues(new Uint8Array(16));
/*
Import an AES secret key from an ArrayBuffer containing the raw bytes.
Takes an ArrayBuffer string containing the bytes, and returns a Promise
that will resolve to a CryptoKey representing the secret key.
*/
function importSecretKey(rawKey) {
  return window.crypto.subtle.importKey(
    "raw",
    rawKey,
    "AES-GCM",
    true,
    ["encrypt", "decrypt"]
  );
}

PKCS #8 import

This example imports an RSA private signing key from a PEM-encoded PKCS #8 object. See the complete code on GitHub.

/*
Convert a string into an ArrayBuffer
from https://developers.google.com/web/updates/2012/06/How-to-convert-ArrayBuffer-to-and-from-String
*/
function str2ab(str) {
  const buf = new ArrayBuffer(str.length);
  const bufView = new Uint8Array(buf);
  for (let i = 0, strLen = str.length; i < strLen; i++) {
    bufView[i] = str.charCodeAt(i);
  }
  return buf;
}
const pemEncodedKey = `-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDD0tPV/du2vftjvXj1t/gXTK39sNBVrOAEb/jKzXae+Xa0H+3LhZaQIQNMfACiBSgIfZUvEGb+7TqXWQpoLoFR/R7MvGWcSk98JyrVtveD8ZmZYyItSY7m2hcasqAFiKyOouV5vzyRe87/lEyzzBpF3bQQ4IDaQu+K9Hj5fKuU6rrOeOhsdnJc+VdDQLScHxvMoLZ9Vtt+oK9J4/tOLwr4CG8khDlBURcBY6gPcLo3dPU09SW+6ctX2cX4mkXx6O/0mmdTmacr/vu50KdRMleFeZYOWPAEhhMfywybTuzBiPVIZVP8WFCSKNMbfi1S9A9PdBqnebwwHhX3/hsEBt2BAgMBAAECggEABEI1P6nf6Zs7mJlyBDv+Pfl5rjL2cOqLy6TovvZVblMkCPpJyFuNIPDK2tK2i897ZaXfhPDBIKmllM2Hq6jZQKB110OAnTPDg0JxzMiIHPs32S1d/KilHjGff4Hjd4NXp1l1Dp8BUPOllorR2TYm2x6dcCGFw9lhTr8O03Qp4hjn84VjGIWADYCk83mgS4nRsnHkdiqYnWx1AjKlY51yEK6RcrDMi0Th2RXrrINoC35sVv+APt2rkoMGi52RwTEseA1KZGFrxjq61ReJif6p2VXEcvHeX6CWLx014LGk43z6Q28P6HgeEVEfIjyqCUea5Du/mYb/QsRSCosXLxBqwQKBgQD1+fdC9ZiMrVI+km7Nx2CKBn8rJrDmUh5SbXn2MYJdrUd8bYNnZkCgKMgxVXsvJrbmVOrby2txOiqudZkk5mD3E5O/QZWPWQLgRu8ueYNpobAX9NRgNfZ7rZD+81vh5MfZiXfuZOuzv29iZhU0oqyZ9y75eHkLdrerNkwYOe5aUQKBgQDLzapDi1NxkBgsj9iiO4KUa7jvD4JjRqFy4Zhj/jbQvlvM0F/uFp7sxVcHGx4r11C+6iCbhX4u+Zuu0HGjT4d+hNXmgGyxR8fIUVxOlOtDkVJa5sOBZK73/9/MBeKusdmJPRhalZQfMUJRWIoEVDMhfg3tW/rBj5RYAtP2dTVUMQKBgDs8yr52dRmT+BWXoFWwaWB0NhYHSFz/c8v4D4Ip5DJ5M5kUqquxJWksySGQa40sbqnD05fBQovPLU48hfgr/zghn9hUjBcsoZOvoZR4sRw0UztBvA+7jzOz1hKAOyWIulR6Vca0yUrNlJ6G5R56+sRNkiOETupi2dLCzcqb0PoxAoGAZyNHvTLvIZN4iGSrjz5qkM4LIwBIThFadxbv1fq6pt0O/BGf2o+cEdq0diYlGK64cEVwBwSBnSg4vzlBqRIAUejLjwEDAJyA4EE8Y5A9l04dzV7nJb5cRak6CrgXxay/mBJRFtaHxVlaZGxYPGSYE6UFS0+3EOmmevvDZQBf4qECgYEA0ZF6Vavz28+8wLO6SP3w8NmpHk7K9tGEvUfQ30SgDx4G7qPIgfPrbB4OP/E0qCfsIImi3sCPpjvUMQdVVZyPOIMuB+rV3ZOxkrzxEUOrpOpR48FZbL7RN90yRQsAsrp9e4iv8QwB3VxLe7X0TDqqnRyqrc/osGzuS2ZcHOKmCU8=
-----END PRIVATE KEY-----`;
/*
Import a PEM encoded RSA private key, to use for RSA-PSS signing.
Takes a string containing the PEM encoded key, and returns a Promise
that will resolve to a CryptoKey representing the private key.
*/
function importPrivateKey(pem) {
  // fetch the part of the PEM string between header and footer
  const pemHeader = "-----BEGIN PRIVATE KEY-----";
  const pemFooter = "-----END PRIVATE KEY-----";
  const pemContents = pem.substring(pemHeader.length, pem.length - pemFooter.length);
  // base64 decode the string to get the binary data
  const binaryDerString = window.atob(pemContents);
  // convert from a binary string to an ArrayBuffer
  const binaryDer = str2ab(binaryDerString);
  return window.crypto.subtle.importKey(
    "pkcs8",
    binaryDer,
    {
      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"]
  );
}

SubjectPublicKeyInfo import

This example imports an RSA public encryption key from a PEM-encoded SubjectPublicKeyInfo object. See the complete code on GitHub.

  // from https://developers.google.com/web/updates/2012/06/How-to-convert-ArrayBuffer-to-and-from-String
  function str2ab(str) {
    const buf = new ArrayBuffer(str.length);
    const bufView = new Uint8Array(buf);
    for (let i = 0, strLen = str.length; i < strLen; i++) {
      bufView[i] = str.charCodeAt(i);
    }
    return buf;
  }
  const pemEncodedKey = `-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAy3Xo3U13dc+xojwQYWoJLCbOQ5fOVY8LlnqcJm1W1BFtxIhOAJWohiHuIRMctv7dzx47TLlmARSKvTRjd0dF92jx/xY20Lz+DXp8YL5yUWAFgA3XkO3LSJgEOex10NB8jfkmgSb7QIudTVvbbUDfd5fwIBmCtaCwWx7NyeWWDb7A9cFxj7EjRdrDaK3ux/ToMLHFXVLqSL341TkCf4ZQoz96RFPUGPPLOfvN0x66CM1PQCkdhzjE6U5XGE964ZkkYUPPsy6Dcie4obhW4vDjgUmLzv0z7UD010RLIneUgDE2FqBfY/C+uWigNPBPkkQ+Bv/UigS6dHqTCVeD5wgyBQIDAQAB
-----END PUBLIC KEY-----`;
  function importRsaKey(pem) {
    // fetch the part of the PEM string between header and footer
    const pemHeader = "-----BEGIN PUBLIC KEY-----";
    const pemFooter = "-----END PUBLIC KEY-----";
    const pemContents = pem.substring(pemHeader.length, pem.length - pemFooter.length);
    // base64 decode the string to get the binary data
    const binaryDerString = window.atob(pemContents);
    // convert from a binary string to an ArrayBuffer
    const binaryDer = str2ab(binaryDerString);
    return window.crypto.subtle.importKey(
      "spki",
      binaryDer,
      {
        name: "RSA-OAEP",
        hash: "SHA-256"
      },
      true,
      ["encrypt"]
    );
  }

JSON Web Key import

This code imports an ECDSA private signing key, given a JSON Web Key object that represents it. See the complete code on GitHub.

const jwkEcKey = {
  "crv": "P-384",
  "d": "wouCtU7Nw4E8_7n5C1-xBjB4xqSb_liZhYMsy8MGgxUny6Q8NCoH9xSiviwLFfK_",
  "ext": true,
  "key_ops": ["sign"],
  "kty": "EC",
  "x": "SzrRXmyI8VWFJg1dPUNbFcc9jZvjZEfH7ulKI1UkXAltd7RGWrcfFxqyGPcwu6AQ",
  "y": "hHUag3OvDzEr0uUQND4PXHQTXP5IDGdYhJhL-WLKjnGjQAw0rNGy5V29-aV-yseW"
};
/*
Import a PEM encoded RSA private key, to use for RSA-PSS signing.
Takes a string containing the PEM encoded key, and returns a Promise
that will resolve to a CryptoKey representing the private key.
*/
function importPrivateKey(jwk) {
  return window.crypto.subtle.importKey(
    "jwk",
    jwk,
    {
      name: "ECDSA",
      namedCurve: "P-384"
    },
    true,
    ["sign"]
  );
}

规范

规范	状态	注释
Web Cryptography API The definition of 'SubtleCrypto.importKey()' 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
`importKey`	Chrome 37	Edge 部分支持 12 部分支持 12 Not supported: RSA-PSS, ECDSA, ECDH. Not supported: AES-CTR, HKDF, PBKDF2.	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

图例

完整支持
部分支持

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

另请参阅

元数据

最后修改： Mar 23, 2020

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

在此页

句法

参数

返回值

异常