DieimportKey() Methode derSubtleCrypto Schnittstelle importiert einen Schlüssel: das heißt, sie nimmt als Eingabe einen Schlüssel in einem externen, portablen Format und gibt Ihnen einCryptoKey Objekt, das Sie in derWeb Crypto API verwenden können.

Die Funktion akzeptiert mehrere Importformate: sieheUnterstützte Formate für Details.

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

EinArrayBuffer, einTypedArray,einDataView oder einJSONWebKey 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ürRSASSA-PKCS1-v1_5,RSA-PSS,oderRSA-OAEP:übergeben Sie einRsaHashedImportParams Objekt.
• FürECDSA oderECDH:übergeben Sie einEcKeyImportParams Objekt.
• FürHMAC:übergeben Sie einHmacImportParams Objekt.
• FürAES-CTR,AES-CBC,AES-GCM, undAES-KW:übergeben Sie den String, der den Algorithmus identifiziert, oder ein Objekt der Form{ name: ALGORITHM }, wobeiALGORITHM der Name des Algorithmus ist.
• FürPBKDF2: übergeben Sie den StringPBKDF2 oder ein Objekt der Form{ name: "PBKDF2" }.
• FürHKDF: übergeben Sie den StringHKDF oder ein Objekt der Form{ name: "HKDF" }.
• FürEd25519: übergeben Sie den StringEd25519 oder ein Objekt der Form{ name: "Ed25519" }.
• FürX25519: übergeben Sie den StringX25519 oder ein Objekt der Form{ name: "X25519" }.

extractable

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

keyUsages

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

• encrypt: Der Schlüssel kann verwendet werden, um Nachrichten zuverschlüsseln.
• decrypt: Der Schlüssel kann verwendet werden, um Nachrichten zuentschlüsseln.
• sign: Der Schlüssel kann verwendet werden, um Nachrichten zusignieren.
• verify: Der Schlüssel kann verwendet werden, um Signaturen zuverifizieren.
• deriveKey: Der Schlüssel kann zumAbleiten eines neuen Schlüssels verwendet werden.
• deriveBits: Der Schlüssel kann zumAbleiten von Bits verwendet werden.
• wrapKey: Der Schlüssel kann verwendet werden, um einen Schlüssel zuverpacken.
• unwrapKey: Der Schlüssel kann verwendet werden, um einen Schlüssel zuentpacken.

Rückgabewert

EinPromise, der mit dem importierten Schlüssel alsCryptoKey Objekt erfüllt wird.

Ausnahmen

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

SyntaxErrorDOMException

Wird ausgelöst, wennkeyUsages leer ist, aber der nicht verpackte Schlüssel vom Typsecret oderprivate ist.

TypeError

Wird ausgelöst, wenn versucht wird, ein ungültiges Format zu verwenden oder wenn diekeyData 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 einArrayBuffer bereitgestellt, der die rohen Bytes des Schlüssels enthält.

Beachten Sie, dass beim Import von elliptischen Kurven-Public-Schlüsseln die Datenkomprimierte 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 inRFC 5208 definiert, unter Verwendung derASN.1 Notation:

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

DieimportKey() Methode erwartet, dieses Objekt als einArrayBuffer zu erhalten, das dieDER-kodierte Form desPrivateKeyInfo 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 imPEM-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 diebase64-kodierten Binärdaten.Ein PEM-kodiertesPrivateKeyInfo sieht so aus:

-----BEGIN PRIVATE KEY-----MIG2AgEAMBAGByqGSM49AgEGBSuBBAAiBIGeMIGbAgEBBDAU9BD0jxDfF5OV380z9VIEUN2W5kJDZ3hbuaDenCxLiAMsoquKTfFaou71eLdN0TShZANiAARMUhCee/cpxmjGc1roj0D0k6VlUqtA+JVCWigXcIAukOeTHCngZDKCrD4PkXDBvbciJdZKvO+lml2FIkoovZh/8yeTKmjUMb804g6OmjUc9vVojCRV0YdaSmYkkJMJbLg=-----END PRIVATE KEY-----

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

• Dekodieren Sie den Teil zwischen Header und Footer mit Hilfe vonWindow.atob().
• Konvertieren Sie die resultierende Zeichenfolge in einenArrayBuffer.

Siehe den AbschnittBeispiele 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 inRFC 5280, Abschnitt 4.1 unter Verwendung derASN.1 Notation:

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

WiePKCS #8 erwartet dieimportKey() Methode, dieses Objekt als einArrayBuffer zu erhalten, das dieDER-kodierte Form desSubjectPublicKeyInfo enthält.

Auch hier werden Sie dieses Objekt höchstwahrscheinlich imPEM-Format antreffen.Ein PEM-kodiertesSubjectPublicKeyInfo sieht so aus:

-----BEGIN PUBLIC KEY-----MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA3j+HgSHUnc7F6XzvEbD0r3M5JNy+/kabiJVu8IU1ERAl3Osi38VgiMzjDBDOrFxVzNNzl+SXAHwXIV5BHiXLCQ6qhwYsDgH6OqgKIwiALra/wNH4UHxj1Or/iyAkjHRR/kGhUtjyVCjzvaQaDpJW2G+syd1ui0B6kJov2CRUWiPwpff8hBfVWv8q9Yc2yD5hCnykVL0iAiyn+SDAk/rv8dC5eIlzCI4efUCbyG4c9O88Qz7bS14DxSfaPTy8P/TWoihVVjLaDF743LgM/JLqCDPUBUA3HLsZUhKm3BbSkd7Q9Ngkjv3+yByo4/fL+fkYRa8j9Ypa2N0Iw53LFb3BgQIDAQAB-----END PUBLIC KEY-----

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

• Dekodieren Sie den Teil zwischen Header und Footer mit Hilfe vonWindow.atob().
• Konvertieren Sie die resultierende Zeichenfolge in einenArrayBuffer.

Siehe den AbschnittBeispiele 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 inRFC 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 einemArrayBuffer, 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 Promisethat 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 ArrayBufferfrom 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 Promisethat 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-kodiertenSubjectPublicKeyInfo 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-Stringfunction 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 Promisethat 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.