SubtleCrypto: importKey() Methode

format

Ein String, der das Datenformat des zu importierenden Schlüssels beschreibt. Es 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 angegebenen Format enthält.

algorithm

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

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

extractable

Ein boolescher Wert, der angibt, 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 verwendet werden, um einen neuen Schlüssel abzuleiten.
• deriveBits: Der Schlüssel kann verwendet werden, um Bits abzuleiten.
• wrapKey: Der Schlüssel kann verwendet werden, um einen Schlüssel zu umhüllen.
• unwrapKey: Der Schlüssel kann verwendet werden, um einen Schlüssel zu enthüllen.

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

Das Versprechen wird abgelehnt, wenn einer der folgenden Ausnahmen auftritt:

SyntaxError DOMException

Ausgelöst, wenn keyUsages leer ist, aber der entschlüsselte Schlüssel von Typ secret oder private ist.

TypeError

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

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

Sie können dieses Format verwenden, um AES- oder HMAC-Geheimschlüssel oder elliptische Kurven öffentliche Schlüssel zu importieren oder zu exportieren.

In diesem Format wird der Schlüssel als ArrayBuffer bereitgestellt, der die rohen Bytes für den Schlüssel enthält.

Dieses Format kann verwendet werden, um RSA- oder elliptische Kurven-Privatschlü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, dass sie dieses Objekt als einen ArrayBuffer erhält, der die DER-codierte Form des PrivateKeyInfo enthält. DER ist eine Sammlung von Regeln zum Kodieren von ASN.1 Strukturen in eine binäre Form.

Sie werden dieses Objekt höchstwahrscheinlich im PEM-Format finden. Das PEM-Format ist eine Möglichkeit, Binärdaten in ASCII zu kodieren. Es besteht aus einem Header und einem Footer und dazwischen den base64-kodierten Binärdaten. Ein PEM-kodiertes PrivateKeyInfo sieht wie folgt 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() geben können, müssen Sie zwei Dinge tun:

• Den Teil zwischen Header und Footer base64-dekodieren, mit Window.atob().
• Den resultierenden String in einen ArrayBuffer konvertieren.

Siehe den Beispiele-Abschnitt für konkretere Anleitungen.

Dieses Format kann verwendet werden, um RSA- oder elliptische Kurven-öffentliche Schlüssel zu importieren oder zu exportieren.

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

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

Genau wie bei PKCS #8 erwartet die importKey()-Methode den Empfang dieses Objekts als einen ArrayBuffer mit der DER-codierten Form des SubjectPublicKeyInfo.

Auch hier werden Sie dieses Objekt höchstwahrscheinlich im PEM-Format finden. 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-----

Genauso wie bei PKCS #8, um dies in ein für importKey() geeignetes Format zu bringen, müssen Sie zwei Dinge tun:

• Den Teil zwischen Header und Footer base64-dekodieren, mit Window.atob().
• Den resultierenden String in einen ArrayBuffer konvertieren.

Siehe den Beispiele-Abschnitt für konkretere Anleitungen.

Sie können das JSON Web Key-Format verwenden, um RSA- oder elliptische Kurven-öffentliche oder privatschlü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 Möglichkeit, öffentliche, private und geheime Schlüssel als JSON-Objekte darzustellen.

Ein JSON Web Key sieht ungefähr so aus (dies ist ein 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"
};

Dieses Beispiel importiert einen AES-Schlüssel aus einem ArrayBuffer, der die Rohbytes enthält, die verwendet werden sollen. Sehen Sie sich den vollständigen Code auf GitHub an.

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",
  ]);
}

Dieses Beispiel importiert einen RSA-Privat-Signaturschlüssel aus einem PEM-kodierten PKCS #8 Objekt. Sehen Sie sich den vollständigen Code auf GitHub an.

/*
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"],
  );
}

Dieses Beispiel importiert einen RSA-Öffentlichkeitsverschlüsselungsschlüssel aus einem PEM-kodierten SubjectPublicKeyInfo-Objekt. Sehen Sie sich den vollständigen Code auf GitHub an.

// 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"],
  );
}

Dieser Code importiert einen ECDSA-Privat-Signaturschlüssel, der durch ein JSON Web Key-Objekt repräsentiert wird, das ihn darstellt. Sehen Sie sich den vollständigen Code auf GitHub an.

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"],
  );
}

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