SubtleCrypto: generateKey()-Methode

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

Sicherer Kontext: Diese Funktion ist nur in sicheren Kontexten (HTTPS) in einigen oder allen unterstützenden Browsern verfügbar.

Hinweis: Diese Funktion ist in Web Workers verfügbar.

Die generateKey()-Methode der SubtleCrypto-Schnittstelle wird verwendet, um einen neuen Schlüssel (für symmetrische Algorithmen) oder ein Schlüsselpaar (für Public-Key-Algorithmen) zu generieren.

Syntax

generateKey(algorithm, extractable, keyUsages)

Parameter

algorithm

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

Für RSASSA-PKCS1-v1_5, RSA-PSS, oder RSA-OAEP: übergeben Sie ein RsaHashedKeyGenParams-Objekt.
Für ECDSA oder ECDH: übergeben Sie ein EcKeyGenParams-Objekt.
Für HMAC: übergeben Sie ein HmacKeyGenParams-Objekt.
Für AES-CTR, AES-CBC, AES-GCM, oder AES-KW: übergeben Sie ein AesKeyGenParams-Objekt.
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 angibt, ob es möglich sein wird, den Schlüssel mit SubtleCrypto.exportKey() oder SubtleCrypto.wrapKey() zu exportieren.

keyUsages

Ein Array von Zeichenfolgen, die angeben, was mit dem neu generierten Schlüssel gemacht werden kann. Mögliche Werte für Array-Elemente 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 überprüfen.
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 verpacken.
unwrapKey: Der Schlüssel kann verwendet werden, um einen Schlüssel zu entpacken.

Rückgabewert

Ein Promise, das mit einem CryptoKey (für symmetrische Algorithmen) oder einem CryptoKeyPair (für Public-Key-Algorithmen) erfüllt wird.

Ausnahmen

Das Promise wird abgelehnt, wenn die folgende Ausnahme auftritt:

SyntaxError DOMException: Wird ausgelöst, wenn das Ergebnis ein CryptoKey vom Typ secret oder private ist, aber keyUsages leer oder für den Algorithmustyp ungültig ist.
SyntaxError DOMException: Wird ausgelöst, wenn das Ergebnis ein CryptoKeyPair ist und sein privateKey.usages-Attribut leer oder für den Algorithmustyp ungültig ist.

Beispiele

Hinweis: Sie können die funktionierenden Beispiele auf GitHub ausprobieren.

RSA-Schlüsselpaar-Generierung

Dieser Code generiert ein RSA-OAEP Verschlüsselungs-Schlüsselpaar. Sehen Sie sich den vollständigen Code auf GitHub an.

let keyPair = await window.crypto.subtle.generateKey(
  {
    name: "RSA-OAEP",
    modulusLength: 4096,
    publicExponent: new Uint8Array([1, 0, 1]),
    hash: "SHA-256",
  },
  true,
  ["encrypt", "decrypt"],
);

Elliptische-Kurve-Schlüsselpaar-Generierung

Dieser Code generiert ein ECDSA-Signaturschlüsselpaar. Sehen Sie sich den vollständigen Code auf GitHub an.

let keyPair = await window.crypto.subtle.generateKey(
  {
    name: "ECDSA",
    namedCurve: "P-384",
  },
  true,
  ["sign", "verify"],
);

HMAC-Schlüsselerzeugung

Dieser Code generiert einen HMAC-Signaturschlüssel. Sehen Sie sich den vollständigen Code auf GitHub an.

let key = await window.crypto.subtle.generateKey(
  {
    name: "HMAC",
    hash: { name: "SHA-512" },
  },
  true,
  ["sign", "verify"],
);

AES-Schlüsselerzeugung

Dieser Code generiert einen AES-GCM Verschlüsselungsschlüssel. Sehen Sie sich den vollständigen Code auf GitHub an.

let key = await window.crypto.subtle.generateKey(
  {
    name: "AES-GCM",
    length: 256,
  },
  true,
  ["encrypt", "decrypt"],
);

Ed25519-Schlüsselerzeugung

Dieser Code generiert ein Ed25519 Signatur-Schlüsselpaar. Er stammt aus diesem Quellcode auf GitHub, den Sie hier live ausführen können.

<input id="run-button" type="button" value="Run" />
<pre id="log">Click "Run" button</pre>

#log {
  height: 170px;
  white-space: pre-wrap; /* wrap pre blocks */
  overflow-wrap: break-word; /* break on words */
  overflow-y: auto;
  padding: 0.5rem;
  border: 1px solid black;
}

const logElement = document.querySelector("#log");
function log(text) {
  logElement.innerText = `${logElement.innerText}${text}\n`;
  logElement.scrollTop = logElement.scrollHeight;
}

JavaScript

Der Code zur Erzeugung eines Schlüsselpaares mit dem Ed25519-Algorithmus und zum Protokollieren der Informationen in jedem Schlüssel wird unten gezeigt. Beachten Sie, dass der Code in einem try..catch-Block ausgeführt wird, da nicht alle Browser diesen Algorithmus unterstützen.

Das JavaScript holt zuerst die #sign-button und #message <input> Elemente und fügt dann einen Listener für das click Ereignis auf dem Button hinzu. Der Ereignishandler löscht das Protokoll und führt die anderen Operationen aus, indem er den Inhalt des <input> Elements übergibt.

const button = document.querySelector("#run-button");
const input = document.querySelector("#log");

button.addEventListener("click", () => {
  // Clear log
  logElement.innerText = "";
  logElement.scrollTop = logElement.scrollHeight;
  // Run test
  test();
});

async function test() {
  try {
    // Create a key pair and use destructuring assignment to assign to variables
    const { publicKey, privateKey } = await crypto.subtle.generateKey(
      {
        name: "Ed25519",
      },
      true,
      ["sign", "verify"],
    );

    // Log the properties of the keys
    log(`publicKey: ${publicKey}`);
    log(` type: ${publicKey.type}`);
    log(` extractable: ${publicKey.extractable}`);
    log(` algorithm: ${JSON.stringify(publicKey.algorithm)}`);
    log(` usages: ${publicKey.usages}`);
    log(`privateKey: ${privateKey}`);
    log(` type: ${privateKey.type}`);
    log(` extractable: ${privateKey.extractable}`);
    log(` algorithm: ${JSON.stringify(privateKey.algorithm)}`);
    log(` usages: ${privateKey.usages}`);
  } catch (error) {
    log(error);
  }
}

Ergebnis

Die Informationen zu den erstellten Schlüsseln werden unten protokolliert (oder eine Fehlermeldung, wenn der Browser das Erstellen des Schlüssels nicht zulässt).

X25519-Schlüsselerzeugung

Dieser Code generiert ein X25519-Öffentliches und Privates Schlüsselpaar, das in SubtleCrypto.deriveKey() zum Erstellen eines gemeinsamen Schlüssels oder in SubtleCrypto.deriveBits() zum Erstellen eines gemeinsamen Geheimnisses verwendet werden kann.

<input id="run-button" type="button" value="Run" />
<pre id="log">Click "Run" button</pre>

#log {
  height: 170px;
  white-space: pre-wrap; /* wrap pre blocks */
  overflow-wrap: break-word; /* break on words */
  overflow-y: auto;
  padding: 0.5rem;
  border: 1px solid black;
}

const logElement = document.querySelector("#log");
function log(text) {
  logElement.innerText = `${logElement.innerText}${text}\n`;
  logElement.scrollTop = logElement.scrollHeight;
}

JavaScript

Der Code zur Erzeugung eines Schlüsselpaares mit dem X25519-Algorithmus und zum Protokollieren der Informationen in jedem Schlüssel wird unten gezeigt. Beachten Sie, dass der Code in einem try..catch-Block ausgeführt wird, da nicht alle Browser diesen Algorithmus unterstützen.

Das JavaScript holt zuerst die #run-button und #log <input> Elemente und fügt dann einen Listener für das click Ereignis auf dem Button hinzu. Der Ereignishandler löscht das Protokoll, generiert ein X25519-Schlüsselpaar und protokolliert einige seiner Eigenschaften.

const button = document.querySelector("#run-button");
const input = document.querySelector("#log");

button.addEventListener("click", () => {
  // Clear log
  logElement.innerText = "";
  logElement.scrollTop = logElement.scrollHeight;
  // Run test
  test();
});

async function test() {
  try {
    // Create a key pair and use destructuring assignment to assign to variables
    const { publicKey, privateKey } = await crypto.subtle.generateKey(
      {
        name: "X25519",
      },
      true,
      ["deriveKey", "deriveBits"],
    );

    // Log the properties of the keys
    log(`publicKey: ${publicKey}`);
    log(` type: ${publicKey.type}`);
    log(` extractable: ${publicKey.extractable}`);
    log(` algorithm: ${JSON.stringify(publicKey.algorithm)}`);
    log(` usages: ${publicKey.usages}`);
    log(`privateKey: ${privateKey}`);
    log(` type: ${privateKey.type}`);
    log(` extractable: ${privateKey.extractable}`);
    log(` algorithm: ${JSON.stringify(privateKey.algorithm)}`);
    log(` usages: ${privateKey.usages}`);
  } catch (error) {
    log(error);
  }
}

Ergebnis

Die Informationen zu den erstellten Schlüsseln werden unten protokolliert (oder eine Fehlermeldung, wenn der Browser das Erstellen des Schlüssels nicht zulässt).

Spezifikationen

Specification
Web Cryptography API # SubtleCrypto-method-generateKey

Browser-Kompatibilität

BCD tables only load in the browser