SubtleCrypto: importKey() Methode

Syntax

importKey(format, keyData, algorithm, extractable, keyUsages)

Parameter

format

Ein String, der das Datenformat des zu importierenden Schlüssels beschreibt. Er kann eines der folgenden sein:

• raw: Rohformat.
• pkcs8: PKCS #8 Format.
• spki: SubjectPublicKeyInfo Format.
• jwk: JSON Web Key Format.

keyData

Ein ArrayBuffer, ein TypedArray, ein DataView oder ein JSONWebKey Objekt, das den Schlüssel im gegebenen Format enthält.

algorithm

Ein Objekt, das den zu importierenden Schlüsseltyp definiert und zusätzliche algorithmenspezifische Parameter bereitstellt.

• Für RSASSA-PKCS1-v1_5, RSA-PSS, oder RSA-OAEP: übergeben Sie ein RsaHashedImportParams Objekt.
• Für ECDSA oder ECDH: übergeben Sie ein EcKeyImportParams Objekt.
• Für HMAC: übergeben Sie ein HmacImportParams Objekt.
• Für AES-CTR, AES-CBC, AES-GCM, und AES-KW: übergeben Sie den String, der den Algorithmus identifiziert, oder ein Objekt der Form { name: ALGORITHM }, wobei ALGORITHM der Name des Algorithmus ist.
• Für PBKDF2: übergeben Sie den String PBKDF2 oder ein Objekt der Form { name: "PBKDF2" }.
• Für HKDF: übergeben Sie den String HKDF oder ein Objekt der Form { name: "HKDF" }.
• Für Ed25519: übergeben Sie den String Ed25519 oder ein Objekt der Form { name: "Ed25519" }.
• Für X25519: übergeben Sie den String X25519 oder ein Objekt der Form { name: "X25519" }.

extractable

Ein boolescher Wert, der anzeigt, ob es möglich sein wird, den Schlüssel mit SubtleCrypto.exportKey() oder SubtleCrypto.wrapKey() zu exportieren.

keyUsages

Ein Array, das angibt, was mit dem Schlüssel gemacht werden kann. Mögliche Array-Werte sind:

• encrypt: Der Schlüssel kann verwendet werden, um Nachrichten zu verschlüsseln.
• decrypt: Der Schlüssel kann verwendet werden, um Nachrichten zu entschlüsseln.
• sign: Der Schlüssel kann verwendet werden, um Nachrichten zu signieren.
• verify: Der Schlüssel kann verwendet werden, um Signaturen zu verifizieren.
• deriveKey: Der Schlüssel kann zum Ableiten eines neuen Schlüssels verwendet werden.
• deriveBits: Der Schlüssel kann zum Ableiten von Bits verwendet werden.
• wrapKey: Der Schlüssel kann verwendet werden, um einen Schlüssel zu verpacken.
• unwrapKey: Der Schlüssel kann verwendet werden, um einen Schlüssel zu entpacken.

Rückgabewert

Ein Promise, der mit dem importierten Schlüssel als CryptoKey Objekt erfüllt wird.

Ausnahmen

Das Promise wird abgelehnt, wenn eine der folgenden Ausnahmen auftritt:

SyntaxError DOMException

Wird ausgelöst, wenn keyUsages leer ist, aber der nicht verpackte Schlüssel vom Typ secret oder private ist.

TypeError

Wird ausgelöst, wenn versucht wird, ein ungültiges Format zu verwenden oder wenn die keyData für dieses Format nicht geeignet sind.

Unterstützte Formate

Diese API unterstützt vier verschiedene Schlüsselimport/-exportformate: Raw, PKCS #8, SubjectPublicKeyInfo und JSON Web Key.

Raw

Sie können dieses Format verwenden, um AES- oder HMAC-Geheimschlüssel oder elliptische Kurven-Public-Schlüssel (ECDSA oder ECDH) zu importieren oder zu exportieren.

In diesem Format wird der Schlüssel als ein ArrayBuffer bereitgestellt, der die rohen Bytes des Schlüssels enthält.

Beachten Sie, dass beim Import von elliptischen Kurven-Public-Schlüsseln die Daten komprimierte elliptische Kurvenpunkte enthalten können.

PKCS #8

Sie können dieses Format verwenden, um RSA- oder elliptische Kurven-Private-Schlüssel zu importieren oder zu exportieren.

Das PKCS #8 Format ist in RFC 5208 definiert, unter Verwendung der ASN.1 Notation:

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

Die importKey() Methode erwartet, dieses Objekt als ein ArrayBuffer zu erhalten, das die DER-kodierte Form des PrivateKeyInfo enthält. DER ist ein Satz von Regeln zur Kodierung von ASN.1-Strukturen in eine binäre Form.

Sie werden dieses Objekt höchstwahrscheinlich im PEM-Format antreffen. Das PEM-Format ist eine Methode zur Kodierung binärer Daten in ASCII. Es besteht aus einem Header und einem Footer und enthält dazwischen die base64-kodierten Binärdaten. Ein PEM-kodiertes PrivateKeyInfo sieht so aus:

-----BEGIN PRIVATE KEY-----
MIG2AgEAMBAGByqGSM49AgEGBSuBBAAiBIGeMIGbAgEBBDAU9BD0jxDfF5OV380z
9VIEUN2W5kJDZ3hbuaDenCxLiAMsoquKTfFaou71eLdN0TShZANiAARMUhCee/cp
xmjGc1roj0D0k6VlUqtA+JVCWigXcIAukOeTHCngZDKCrD4PkXDBvbciJdZKvO+l
ml2FIkoovZh/8yeTKmjUMb804g6OmjUc9vVojCRV0YdaSmYkkJMJbLg=
-----END PRIVATE KEY-----

Um dies in ein Format zu bringen, das Sie importKey() übergeben können, müssen Sie zwei Dinge tun:

• Dekodieren Sie den Teil zwischen Header und Footer mit Hilfe von Window.atob().
• Konvertieren Sie die resultierende Zeichenfolge in einen ArrayBuffer.

Siehe den Abschnitt Beispiele für konkretere Anleitungen.

SubjectPublicKeyInfo

Sie können dieses Format verwenden, um RSA- oder elliptische Kurven-Public-Schlüssel zu importieren oder zu exportieren.

SubjectPublicKey ist definiert in RFC 5280, Abschnitt 4.1 unter Verwendung der ASN.1 Notation:

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

Wie PKCS #8 erwartet die importKey() Methode, dieses Objekt als ein ArrayBuffer zu erhalten, das die DER-kodierte Form des SubjectPublicKeyInfo enthält.

Auch hier werden Sie dieses Objekt höchstwahrscheinlich im PEM-Format antreffen. Ein PEM-kodiertes SubjectPublicKeyInfo sieht so aus:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA3j+HgSHUnc7F6XzvEbD0
r3M5JNy+/kabiJVu8IU1ERAl3Osi38VgiMzjDBDOrFxVzNNzl+SXAHwXIV5BHiXL
CQ6qhwYsDgH6OqgKIwiALra/wNH4UHxj1Or/iyAkjHRR/kGhUtjyVCjzvaQaDpJW
2G+syd1ui0B6kJov2CRUWiPwpff8hBfVWv8q9Yc2yD5hCnykVL0iAiyn+SDAk/rv
8dC5eIlzCI4efUCbyG4c9O88Qz7bS14DxSfaPTy8P/TWoihVVjLaDF743LgM/JLq
CDPUBUA3HLsZUhKm3BbSkd7Q9Ngkjv3+yByo4/fL+fkYRa8j9Ypa2N0Iw53LFb3B
gQIDAQAB
-----END PUBLIC KEY-----

Wie bei PKCS #8 müssen Sie, um dies in ein Format zu bringen, das Sie importKey() übergeben können, zwei Dinge tun:

• Dekodieren Sie den Teil zwischen Header und Footer mit Hilfe von Window.atob().
• Konvertieren Sie die resultierende Zeichenfolge in einen ArrayBuffer.

Siehe den Abschnitt Beispiele für konkretere Anleitungen.

JSON Web Key

Sie können das JSON Web Key Format verwenden, um RSA- oder elliptische Kurven-Public- oder Private-Schlüssel sowie AES- und HMAC-Geheimschlüssel zu importieren oder zu exportieren.

Das JSON Web Key Format ist in RFC 7517 definiert. Es beschreibt eine Methode, um öffentliche, private und geheime Schlüssel als JSON-Objekte darzustellen.

Ein JSON Web Key sieht in etwa so aus (dies ist ein EC-Privatschlüssel):

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

Beispiele

Raw Import

Dieses Beispiel importiert einen AES-Schlüssel aus einem ArrayBuffer, der die zu verwendenden Roh-Bytes enthält. Sehen Sie den vollständigen Code auf 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

Dieses Beispiel importiert einen RSA-Private-Signing-Schlüssel aus einem PEM-kodierten PKCS #8 Objekt. Sehen Sie den vollständigen Code auf 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 - 1,
  );
  // 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",
      hash: "SHA-256",
    },
    true,
    ["sign"],
  );
}

SubjectPublicKeyInfo Import

Dieses Beispiel importiert einen RSA-Public-Encryption-Schlüssel aus einem PEM-kodierten SubjectPublicKeyInfo Objekt. Sehen Sie den vollständigen Code auf 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 - 1,
  );
  // 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

Dieser Code importiert einen ECDSA-Privatsignaturschlüssel auf der Grundlage eines JSON Web Key Objekts, das ihn darstellt. Sehen Sie den vollständigen Code auf 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 JSON Web Key format EC private key, to use for ECDSA signing.
Takes an object representing the JSON Web 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"],
  );
}

Spezifikationen

Browser-Kompatibilität

Siehe auch

• SubtleCrypto.exportKey()
• PKCS #8 Format.
• SubjectPublicKeyInfo Format.
• JSON Web Key Format.