SubtleCrypto: Methode generateKey()

Baseline

Weitgehend verfügbar

Diese Funktion ist gut etabliert und funktioniert auf vielen Geräten und in vielen Browserversionen. Sie ist seit Januar 2020 browserübergreifend verfügbar.

* Einige Teile dieser Funktion werden möglicherweise unterschiedlich gut unterstützt.

Vollständige Kompatibilität anzeigen
Mehr erfahren

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 Methode generateKey() der Schnittstelle SubtleCrypto wird verwendet, um einen neuen Schlüssel (für symmetrische Algorithmen) oder ein Schlüsselpaar (für Public-Key-Algorithmen) zu erzeugen.

Syntax

generateKey(algorithm, extractable, keyUsages)

Parameter

algorithm

Ein Objekt, das den Typ des zu erzeugenden Schlüssels festlegt und zusätzliche algorithmusspezifische 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 die Zeichenfolge Ed25519 oder ein Objekt der Form { name: "Ed25519" }.
Für X25519: Übergeben Sie die Zeichenfolge X25519 oder ein Objekt der Form { name: "X25519" }.

extractable

Ein boolescher Wert, der angibt, ob der Schlüssel mit SubtleCrypto.exportKey() oder SubtleCrypto.wrapKey() exportiert werden kann. Beachten Sie, dass beim Erzeugen asymmetrischer Schlüsselpaare (wie RSA oder ECDSA) der Parameter extractable bestimmt, ob der private Schlüssel exportiert werden kann; der öffentliche Schlüssel ist immer exportierbar.

keyUsages

Ein Array von Zeichenfolgen, die angeben, wofür der neu erzeugte Schlüssel verwendet werden kann. Mögliche Werte für die Array-Elemente sind:

encrypt: Der Schlüssel kann zum Verschlüsseln von Nachrichten verwendet werden.
decrypt: Der Schlüssel kann zum Entschlüsseln von Nachrichten verwendet werden.
sign: Der Schlüssel kann zum Signieren von Nachrichten verwendet werden.
verify: Der Schlüssel kann zum Überprüfen von Signaturen verwendet werden.
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 zum Verpacken eines Schlüssels verwendet werden.
unwrapKey: Der Schlüssel kann zum Entpacken eines Schlüssels verwendet werden.

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 zurückgewiesen, wenn eine der folgenden Ausnahmen 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 dessen Attribut privateKey.usages leer oder für den Algorithmustyp ungültig ist.

Beispiele

Hinweis: Sie können die funktionsfähigen Beispiele auf GitHub ausprobieren.

Erzeugen eines RSA-Schlüsselpaars

Dieser Code erzeugt ein RSA-OAEP-Schlüsselpaar für die Verschlüsselung. 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"],
);

Erzeugen eines Schlüsselpaares mit elliptischen Kurven

Dieser Code erzeugt ein ECDSA-Schlüsselpaar zum Signieren. 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"],
);

Erzeugen eines HMAC-Schlüssels

Dieser Code erzeugt einen HMAC-Schlüssel zum Signieren. 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"],
);

Erzeugen eines AES-Schlüssels

Dieser Code erzeugt einen AES-GCM-Schlüssel für die Verschlüsselung. 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"],
);

Erzeugen eines Ed25519-Schlüssels

Dieser Code erzeugt ein Ed25519-Schlüsselpaar zum Signieren. Er basiert auf diesem Quellcode auf GitHub, den Sie hier direkt 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 folgende Code zeigt, wie ein Schlüsselpaar mit dem Algorithmus Ed25519 erzeugt und die Informationen zu jedem Schlüssel protokolliert werden. Beachten Sie, dass der Code in einem try..catch-Block ausgeführt wird, da nicht alle Browser diesen Algorithmus unterstützen.

Das JavaScript ruft zunächst die <input>-Elemente #sign-button und #message ab und fügt dann dem Button einen Listener für das click-Ereignis hinzu. Der Event-Handler leert das Protokoll und führt die weiteren Operationen mit dem Inhalt des <input>-Elements aus.

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 erzeugten Schlüsseln werden unten protokolliert (oder eine Fehlermeldung, wenn der Browser das Erzeugen des Schlüssels nicht zulässt).

Erzeugen eines X25519-Schlüssels

Dieser Code erzeugt ein öffentliches und ein privates X25519-Schlüsselpaar, das in SubtleCrypto.deriveKey() zum Erzeugen eines gemeinsamen Schlüssels oder in SubtleCrypto.deriveBits() zum Erzeugen 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 folgende Code zeigt, wie ein Schlüsselpaar mit dem Algorithmus X25519 erzeugt und die Informationen zu jedem Schlüssel protokolliert werden. Beachten Sie, dass der Code in einem try..catch-Block ausgeführt wird, da nicht alle Browser diesen Algorithmus unterstützen.

Das JavaScript ruft zunächst die <input>-Elemente #run-button und #log ab und fügt dann dem Button einen Listener für das click-Ereignis hinzu. Der Event-Handler leert das Protokoll, erzeugt 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 erzeugten Schlüsseln werden unten protokolliert (oder eine Fehlermeldung, wenn der Browser das Erzeugen des Schlüssels nicht zulässt).

Spezifikationen

Spezifikation
Web Cryptography Level 2 # SubtleCrypto-method-generateKey

Browser-Kompatibilität

Siehe auch

Help improve MDN

Erfahren Sie, wie Sie beitragen können Diese Seite wurde automatisch aus dem Englischen übersetzt.

Übersetzung auf GitHub anzeigen • Fehler mit dieser Übersetzung melden