SubtleCrypto: encrypt() Methode
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.
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 encrypt()
Methode der SubtleCrypto
Schnittstelle verschlüsselt Daten.
Sie nimmt als Argumente einen Schlüssel zur Verschlüsselung, einige algorithmusspezifische Parameter und die zu verschlüsselnden Daten (auch als "Klartext" bekannt).
Sie gibt ein Promise
zurück, das mit den verschlüsselten Daten (auch als "Ciphertext" bekannt) erfüllt wird.
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, geben Sie ein
RsaOaepParams
Objekt an. - Um AES-CTR zu verwenden, geben Sie ein
AesCtrParams
Objekt an. - Um AES-CBC zu verwenden, geben Sie ein
AesCbcParams
Objekt an. - Um AES-GCM zu verwenden, geben Sie ein
AesGcmParams
Objekt an.
- Um RSA-OAEP zu verwenden, geben Sie ein
key
-
Ein
CryptoKey
, der den Schlüssel zur Verwendung für die Verschlüsselung enthält. data
-
Ein
ArrayBuffer
, einTypedArray
oder eineDataView
, 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 "Ciphertext" 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 fehlschlägt (z.B. Algorithmusparameter mit ungültigen Größen oder AES-GCM-Klartext, der länger als 239−256 Byte ist).
Unterstützte Algorithmen
Die Web Crypto API bietet vier Algorithmen, die die encrypt()
und decrypt()
Operationen unterstützen.
Einer dieser Algorithmen — RSA-OAEP — ist ein Public-Key-Kryptosystem.
Die anderen drei hier aufgeführten Verschlüsselungsalgorithmen sind alle symmetrische Algorithmen und basieren alle auf dem gleichen 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 Ciphertext nicht von einem Angreifer verändert wurde. Authentifizierung hilft, sich gegen gewählte-Ciphertext-Angriffe zu schützen, in 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 CTR- und CBC-Modi hinzuzufügen, bieten sie diese standardmäßig nicht an, und bei manueller Implementierung können leicht kleine, aber schwerwiegende Fehler gemacht werden. GCM bietet 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-Modus dar, wie in NIST SP800-38A spezifiziert.
AES ist ein Blockchiffre, was bedeutet, dass es die Nachricht in Blöcke aufteilt und diese blockweise verschlüsselt. Im CTR-Modus wird jedes Mal, wenn ein Block der Nachricht verschlüsselt wird, ein zusätzlicher Datenblock hinzugemischt. Dieser zusätzliche Block wird "Counter-Block" genannt.
Ein gegebener Counter-Block-Wert darf mit demselben Schlüssel niemals mehr als einmal verwendet werden:
- Gegeben ist eine n Blöcke lange Nachricht, 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 für alle Blöcke über alle Nachrichten hinweg ein anderer Counter-Block verwendet werden.
Typischerweise wird dies erreicht, indem der anfängliche Counter-Block-Wert in zwei verkettete Teile aufgeteilt wird:
- Ein Nonce (das heißt, eine Zahl, die nur einmal verwendet werden darf). Der Nonce-Teil des Blocks bleibt für jeden Block in 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, aber sie dürfen nicht mit demselben Schlüssel erneut verwendet werden.
- Ein Zähler. Dieser Teil des Blocks wird jedes Mal erhöht, wenn ein Block verschlüsselt wird.
Im Wesentlichen: Der Nonce sollte sicherstellen, dass Counter-Blöcke von einer Nachricht zur nächsten nicht wiederverwendet werden, während der Zähler sicherstellen sollte, dass Counter-Blöcke innerhalb einer einzelnen Nachricht nicht wiederverwendet werden.
Hinweis: Weitere Informationen finden Sie in Anhang B des NIST SP800-38A Standards.
AES-CBC
Dies stellt AES im Cipher Block Chaining-Modus dar, wie in NIST SP800-38A spezifiziert.
AES-GCM
Dies stellt AES im Galois/Counter-Modus dar, wie in NIST SP800-38D spezifiziert.
Ein wesentlicher Unterschied zwischen diesem Modus und den anderen besteht darin, dass GCM ein "authentifizierter" Modus ist, was bedeutet, dass er überprüft, dass der Ciphertext nicht von einem Angreifer verändert wurde.
Beispiele
Hinweis: Sie können die funktionierenden Beispiele auf GitHub ausprobieren.
RSA-OAEP
Dieser Code holt den Inhalt eines Textfelds, kodiert es zur Verschlüsselung und verschlüsselt es mit RSA-OAEP. Sehen Sie 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 holt den Inhalt eines Textfelds, kodiert es zur Verschlüsselung, und verschlüsselt es mit AES im CTR-Modus. Sehen Sie 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 key_encoded = await window.crypto.subtle.importKey(
"raw",
key.buffer,
"AES-CTR",
false,
["encrypt", "decrypt"],
);
const encrypted_content = await window.crypto.subtle.encrypt(
{
name: "AES-CTR",
counter: iv,
length: 128,
},
key_encoded,
data,
);
// Uint8Array
console.log(encrypted_content);
AES-CBC
Dieser Code holt den Inhalt eines Textfelds, kodiert es zur Verschlüsselung, und verschlüsselt es mit AES im CBC-Modus. Sehen Sie 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 holt den Inhalt eines Textfelds, kodiert es zur Verschlüsselung, und verschlüsselt es mit AES im GCM-Modus. Sehen Sie 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
Specification |
---|
Web Cryptography Level 2 # SubtleCrypto-method-encrypt |
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.