SubtleCrypto: encrypt() Methode

Syntax

encrypt(algorithm, key, data)

Parameter

algorithm

Ein Objekt, das den zu verwendenden Algorithmus und gegebenenfalls zusätzliche Parameter angibt:

• Um RSA-OAEP zu verwenden, übergeben Sie ein RsaOaepParams-Objekt.
• Um AES-CTR zu verwenden, übergeben Sie ein AesCtrParams-Objekt.
• Um AES-CBC zu verwenden, übergeben Sie ein AesCbcParams-Objekt.
• Um AES-GCM zu verwenden, übergeben Sie ein AesGcmParams-Objekt.

key

Ein CryptoKey, der den Schlüssel enthält, der für die Verschlüsselung verwendet werden soll.

data

Ein ArrayBuffer, ein TypedArray oder ein DataView, das die zu verschlüsselnden Daten enthält (auch bekannt als Klartext).

Rückgabewert

Ein Promise, das mit einem ArrayBuffer erfüllt wird, der den "Chiffretext" enthält.

Ausnahmen

Das Promise wird abgelehnt, wenn die folgenden Ausnahmen auftreten:

InvalidAccessError DOMException

Wird ausgelöst, wenn die angeforderte Operation für den bereitgestellten Schlüssel nicht gültig ist (z.B. ungültiger Verschlüsselungsalgorithmus oder ungültiger Schlüssel für den angegebenen Verschlüsselungsalgorithmus).

OperationError DOMException

Wird ausgelöst, wenn die Operation aus einem operationsspezifischen Grund fehlgeschlagen ist (z.B. Algorithmusparameter mit ungültigen Größen oder AES-GCM-Klartext, der länger als 2³⁹−256 Bytes ist).

Unterstützte Algorithmen

Die Web Crypto API stellt vier Algorithmen bereit, die die encrypt() und decrypt() Operationen unterstützen.

Einer dieser Algorithmen – RSA-OAEP – ist ein Public-Key-Kryptosystem.

Die anderen drei Verschlüsselungsalgorithmen hier sind alle symmetrische Algorithmen, und sie basieren alle auf demselben zugrunde liegenden Chiffre, AES (Advanced Encryption Standard). Der Unterschied zwischen ihnen ist der Modus. Die Web Crypto API unterstützt drei verschiedene AES-Modi:

• CTR (Counter Mode)
• CBC (Cipher Block Chaining)
• GCM (Galois/Counter Mode)

Es wird dringend empfohlen, authentifizierte Verschlüsselung zu verwenden, die überprüft, dass der Chiffretext nicht von einem Angreifer verändert wurde. Authentifizierung hilft, sich gegen Chosen-Ciphertext-Angriffe zu schützen, bei denen ein Angreifer das System bitten kann, beliebige Nachrichten zu entschlüsseln, und das Ergebnis verwenden kann, um Informationen über den geheimen Schlüssel abzuleiten. Während es möglich ist, Authentifizierung zu den CTR- und CBC-Modi hinzuzufügen, bieten sie diese nicht standardmäßig an, und bei der manuellen Implementierung kann man leicht kleine, aber schwerwiegende Fehler machen. GCM bietet eine eingebaute Authentifizierung, und aus diesem Grund wird es oft gegenüber den anderen beiden AES-Modi empfohlen.

RSA-OAEP

Das RSA-OAEP-Public-Key-Verschlüsselungssystem ist in RFC 3447 spezifiziert.

AES-CTR

Dies stellt AES im Counter Mode dar, wie in NIST SP800-38A spezifiziert.

AES ist ein Blockchiffre, was bedeutet, dass er die Nachricht in Blöcke aufteilt und sie blockweise verschlüsselt. Im CTR-Modus wird jedes Mal, wenn ein Nachrichtenblock verschlüsselt wird, ein zusätzlicher Datenblock hinzugefügt. Dieser zusätzliche Block wird als der "Counter Block" bezeichnet.

Ein gegebener Counter Block Wert darf niemals mehr als einmal mit demselben Schlüssel verwendet werden:

• Bei einer Nachricht von n Blöcken Länge muss für jeden Block ein anderer Counter Block verwendet werden.
• Wenn derselbe Schlüssel verwendet wird, um mehr als eine Nachricht zu verschlüsseln, muss ein anderer Counter Block für alle Blöcke über alle Nachrichten hinweg verwendet werden.

In der Regel wird dies erreicht, indem der anfängliche Counter Block Wert in zwei verkettete Teile aufgeteilt wird:

• Ein Nonce (d.h. eine Zahl, die nur einmal verwendet werden darf). Der Nonce-Teil des Blocks bleibt für jeden Block der Nachricht gleich. Jedes Mal, wenn eine neue Nachricht verschlüsselt werden soll, wird ein neuer Nonce gewählt. Nonces müssen nicht geheim sein, dürfen aber nicht mit demselben Schlüssel wiederverwendet werden.
• Ein Zähler. Dieser Teil des Blocks wird jedes Mal inkrementiert, wenn ein Block verschlüsselt wird.

Im Wesentlichen: Der Nonce sollte sicherstellen, dass Counter Blocks nicht von einer Nachricht zur nächsten wiederverwendet werden, während der Zähler sicherstellen sollte, dass Counter Blocks nicht innerhalb einer einzelnen Nachricht wiederverwendet werden.

AES-CBC

Dies stellt AES im Cipher Block Chaining Mode dar, wie in NIST SP800-38A spezifiziert.

AES-GCM

Dies stellt AES im Galois/Counter Mode dar, wie in NIST SP800-38D spezifiziert.

Ein wesentlicher Unterschied zwischen diesem Modus und den anderen ist, dass GCM ein "authentifizierter" Modus ist, was bedeutet, dass er überprüft, dass der Chiffretext nicht von einem Angreifer verändert wurde.

Beispiele

RSA-OAEP

Dieser Code ruft den Inhalt eines Textfelds ab, kodiert ihn zur Verschlüsselung und verschlüsselt ihn mit RSA-OAEP. Siehe den vollständigen Code auf GitHub.

function getMessageEncoding() {
  const messageBox = document.querySelector(".rsa-oaep #message");
  let message = messageBox.value;
  let enc = new TextEncoder();
  return enc.encode(message);
}

function encryptMessage(publicKey) {
  let encoded = getMessageEncoding();
  return window.crypto.subtle.encrypt(
    {
      name: "RSA-OAEP",
    },
    publicKey,
    encoded,
  );
}

AES-CTR

Dieser Code ruft den Inhalt eines Textfelds ab, kodiert ihn zur Verschlüsselung und verschlüsselt ihn im CTR-Modus mit AES. Siehe den vollständigen Code auf GitHub.

function getMessageEncoding() {
  const messageBox = document.querySelector(".aes-ctr #message");
  let message = messageBox.value;
  let enc = new TextEncoder();
  return enc.encode(message);
}

function encryptMessage(key) {
  let encoded = getMessageEncoding();
  // counter will be needed for decryption
  counter = window.crypto.getRandomValues(new Uint8Array(16));
  return window.crypto.subtle.encrypt(
    {
      name: "AES-CTR",
      counter,
      length: 64,
    },
    key,
    encoded,
  );
}

let iv = window.crypto.getRandomValues(new Uint8Array(16));
let key = window.crypto.getRandomValues(new Uint8Array(16));
let data = new Uint8Array(12345);
// crypto functions are wrapped in promises so we have to use await and make sure the function that
// contains this code is an async function
// encrypt function wants a cryptokey object
const keyEncoded = await window.crypto.subtle.importKey(
  "raw",
  key.buffer,
  "AES-CTR",
  false,
  ["encrypt", "decrypt"],
);
const encryptedContent = await window.crypto.subtle.encrypt(
  {
    name: "AES-CTR",
    counter: iv,
    length: 128,
  },
  keyEncoded,
  data,
);

// Uint8Array
console.log(encryptedContent);

AES-CBC

Dieser Code ruft den Inhalt eines Textfelds ab, kodiert ihn zur Verschlüsselung und verschlüsselt ihn im CBC-Modus mit AES. Siehe den vollständigen Code auf GitHub.

function getMessageEncoding() {
  const messageBox = document.querySelector(".aes-cbc #message");
  let message = messageBox.value;
  let enc = new TextEncoder();
  return enc.encode(message);
}

function encryptMessage(key) {
  let encoded = getMessageEncoding();
  // iv will be needed for decryption
  iv = window.crypto.getRandomValues(new Uint8Array(16));
  return window.crypto.subtle.encrypt({ name: "AES-CBC", iv }, key, encoded);
}

AES-GCM

Dieser Code ruft den Inhalt eines Textfelds ab, kodiert ihn zur Verschlüsselung und verschlüsselt ihn im GCM-Modus mit AES. Siehe den vollständigen Code auf GitHub.

function getMessageEncoding() {
  const messageBox = document.querySelector(".aes-gcm #message");
  const message = messageBox.value;
  const enc = new TextEncoder();
  return enc.encode(message);
}

function encryptMessage(key) {
  const encoded = getMessageEncoding();
  // iv will be needed for decryption
  const iv = window.crypto.getRandomValues(new Uint8Array(12));
  return window.crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, encoded);
}

Spezifikationen

Browser-Kompatibilität

Siehe auch

• SubtleCrypto.decrypt().
• RFC 3447 spezifiziert RSAOAEP.
• NIST SP800-38A spezifiziert den CTR-Modus.
• NIST SP800-38A spezifiziert den CBC-Modus.
• NIST SP800-38D spezifiziert den GCM-Modus.