SubtleCrypto: generateKey() Methode

Syntax

generateKey(algorithm, extractable, keyUsages)

Parameter

algorithm

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

• Für RSASSA-PKCS1-v1_5, RSA-PSS, oder RSA-OAEP: geben Sie ein RsaHashedKeyGenParams Objekt an.
• Für ECDSA oder ECDH: geben Sie ein EcKeyGenParams Objekt an.
• Für HMAC: geben Sie ein HmacKeyGenParams Objekt an.
• Für AES-CTR, AES-CBC, AES-GCM, oder AES-KW: geben Sie ein AesKeyGenParams Objekt an.
• 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. Beachten Sie, dass beim Erzeugen asymmetrischer Schlüsselpaare (wie RSA oder ECDSA) der extractable Parameter bestimmt, ob der private Schlüssel exportiert werden kann; der öffentliche Schlüssel ist immer exportierbar.

keyUsages

Ein Array von Strings, das angibt, 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 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 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 ungültig für den Algorithmustyp ist.

SyntaxError DOMException

Wird ausgelöst, wenn das Ergebnis ein CryptoKeyPair ist und sein privateKey.usages Attribut leer oder ungültig für den Algorithmustyp ist.

Beispiele

RSA Schlüsselpaargenerierung

Dieser Code generiert ein RSA-OAEP-Verschlüsselungsschlüsselpaar. Sehen Sie 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üsselpaargenerierung

Dieser Code generiert ein ECDSA-Signaturschlüsselpaar. Sehen Sie 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 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 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-Signaturschlüsselpaar. Es ist abgeleitet von 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 zur Protokollierung 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.

JavaScript holt zuerst die Elemente #sign-button und #message <input> und fügt dann einen Listener für das click-Ereignis auf der Schaltfläche hinzu. Der Ereignis-Handler löscht das Protokoll und führt die anderen Operationen aus, indem der Inhalt des <input>-Elements übergeben wird.

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 über die erstellten Schlüssel werden unten protokolliert (oder ein Fehlermeldungs-String, wenn der Browser die Erstellung des Schlüssels nicht erlaubt).

X25519 Schlüsselerzeugung

Dieser Code generiert ein X25519-Öffentlich- und Privatschlüsselpaar, das in SubtleCrypto.deriveKey() zur Erstellung eines gemeinsamen Schlüssels oder in SubtleCrypto.deriveBits() zur Erstellung 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 zur Protokollierung 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.

JavaScript holt zuerst die Elemente #run-button und #log <input> und fügt dann einen Listener für das click-Ereignis auf der Schaltfläche hinzu. Der Ereignis-Handler 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 über die erstellten Schlüssel werden unten protokolliert (oder ein Fehlermeldungs-String, wenn der Browser die Erstellung des Schlüssels nicht erlaubt).

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Empfehlungen zur Länge kryptografischer Schlüssel.
• NIST Übergang zur Verwendung kryptographischer Algorithmen und Schlüssellängen.