SubtleCrypto: sign() 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: Dieses Feature ist verfügbar in Web Workers.
Die sign()
Methode der SubtleCrypto
Schnittstelle erzeugt eine digitale Signatur.
Sie nimmt als Argumente einen Schlüssel zum Signieren, einige algorithmenspezifische Parameter und die zu signierenden Daten. Sie gibt ein Promise
zurück, das mit der Signatur erfüllt wird.
Sie können die entsprechende SubtleCrypto.verify()
Methode verwenden, um die Signatur zu überprüfen.
Syntax
sign(algorithm, key, data)
Parameter
algorithm
-
Ein String oder Objekt, das den zu verwendenden Signaturalgorithmus und seine Parameter spezifiziert:
- Um RSASSA-PKCS1-v1_5 zu verwenden, übergeben Sie den String
RSASSA-PKCS1-v1_5
oder ein Objekt der Form{ name: "RSASSA-PKCS1-v1_5" }
. - Um RSA-PSS zu verwenden, übergeben Sie ein
RsaPssParams
Objekt. - Um ECDSA zu verwenden, übergeben Sie ein
EcdsaParams
Objekt. - Um HMAC zu verwenden, übergeben Sie den String
HMAC
oder ein Objekt der Form{ name: "HMAC" }
. - Um Ed25519 zu verwenden, übergeben Sie den String
Ed25519
oder ein Objekt der Form{ name: "Ed25519" }
.
- Um RSASSA-PKCS1-v1_5 zu verwenden, übergeben Sie den String
key
-
Ein
CryptoKey
Objekt, das den zu verwendenden Schlüssel für das Signieren enthält. Wennalgorithm
ein öffentliches Schlüsselkryptosystem identifiziert, ist dies der private Schlüssel. data
-
Ein
ArrayBuffer
, einTypedArray
oder einDataView
Objekt, das die zu signierenden Daten enthält.
Rückgabewert
Ein Promise
, das mit einem ArrayBuffer
erfüllt wird, welcher die Signatur enthält.
Ausnahmen
Das Promise
wird abgelehnt, wenn die folgende Ausnahme auftritt:
InvalidAccessError
DOMException
-
Wird ausgelöst, wenn der Signaturschlüssel kein Schlüssel für den angeforderten Signaturalgorithmus ist oder wenn versucht wird, einen Algorithmus zu verwenden, der entweder unbekannt ist oder nicht zum Signieren geeignet ist.
Unterstützte Algorithmen
Die Web Crypto API stellt die folgenden Algorithmen bereit, die für das Signieren und die Signaturverifizierung verwendet werden können.
RSASSA-PKCS1-v1_5, RSA-PSS, ECDSA und Ed25519 sind öffentliche Schlüsselkryptosysteme, die den privaten Schlüssel für das Signieren und den öffentlichen Schlüssel für die Verifizierung verwenden. Diese Systeme verwenden alle einen Digest-Algorithmus, um die Nachricht vor dem Signieren in eine kurze feste Größe zu hashen.
- Für RSASSA-PKCS1-v1_5 und RSA-PSS wird die Auswahl des Digest-Algorithmus in die Funktionen
generateKey()
oderimportKey()
übergeben. - Für ECDSA ist die Wahl des Digest-Algorithmus im
algorithm
Parameter enthalten, der in diesign()
Funktion übergeben wird. - Für Ed25519 ist der Digest-Algorithmus immer SHA-512.
Der HMAC-Algorithmus unterscheidet sich von den anderen darin, dass er kein öffentliches Schlüsselkryptosystem ist: er verwendet denselben Algorithmus und Schlüssel sowohl für die Signierung als auch für die Verifizierung. Das bedeutet, dass der Verifizierungsschlüssel geheim gehalten werden muss, was wiederum bedeutet, dass dieser Algorithmus für viele Signaturszenarien nicht geeignet ist. Er kann jedoch eine gute Wahl sein, wenn der Signierer und der Verifizierer dieselbe Entität sind.
RSASSA-PKCS1-v1_5
Der RSASSA-PKCS1-v1_5 Algorithmus wird in RFC 3447 spezifiziert.
RSA-PSS
Der RSA-PSS Algorithmus wird in RFC 3447 spezifiziert.
Er unterscheidet sich von RSASSA-PKCS1-v1_5 darin, dass er ein zufälliges Salt in den Signiervorgang einbezieht, sodass dieselbe Nachricht mit demselben Schlüssel nicht jedes Mal zur selben Signatur führt. Eine zusätzliche Eigenschaft, die die Salt-Länge definiert, wird in die sign()
und verify()
Funktionen übergeben, wenn sie aufgerufen werden.
ECDSA
ECDSA (Elliptic Curve Digital Signature Algorithm) ist eine Variante des Digital Signature Algorithmus, spezifiziert in FIPS-186, der die elliptische Kurven-Kryptographie (RFC 6090) verwendet.
Signaturen werden als die s1
und s2
Werte codiert, wie in RFC 6090 spezifiziert (auch bekannt als r
und s
in RFC 4754), jeweils in Big-Endian-Byte-Arrays, mit ihrer Länge der Bitgröße der Kurve, aufgerundet auf eine ganze Anzahl von Bytes.
Diese Werte werden in dieser Reihenfolge zusammengefügt.
Diese Codierung wurde auch durch den IEEE 1363-2000 Standard vorgeschlagen und wird manchmal das IEEE P1363 Format genannt. Sie unterscheidet sich von der X.509 Signaturstruktur, die das Standardformat ist, das von einigen Tools und Bibliotheken wie OpenSSL produziert wird.
Ed25519
Ed25519 ist ein digitales Signaturalgorithmus, das auf der Curve25519 elliptischen Kurve basiert, die Teil der Edwards-Curve Digital Signature Algorithm (EdDSA) Familie von Algorithmen ist, definiert in RFC 8032.
HMAC
Der HMAC Algorithmus berechnet und verifiziert hashbasierte Nachrichten-Authentifizierungscodes gemäß dem FIPS 198-1 Standard (PDF).
Der zu verwendende Digest-Algorithmus wird im HmacKeyGenParams
Objekt spezifiziert, das Sie in generateKey()
übergeben, oder im
HmacImportParams
Objekt, das Sie in importKey()
übergeben.
Der HMAC-Algorithmus verwendet denselben Algorithmus und Schlüssel sowohl für das Signieren als auch für die Verifizierung: Das bedeutet, dass der Verifizierungsschlüssel geheim gehalten werden muss, was wiederum bedeutet, dass dieser Algorithmus für viele Signaturszenarien nicht geeignet ist. Er kann jedoch eine gute Wahl sein, wenn der Signierer und der Verifizierer dieselbe Entität sind.
Beispiele
Hinweis: Sie können die funktionierenden Beispiele auf GitHub ausprobieren.
RSASSA-PKCS1-v1_5
Dieser Code holt den Inhalt eines Textfeldes, kodiert ihn zum Signieren und signiert ihn mit einem privaten Schlüssel. Siehe den vollständigen Quellcode auf GitHub.
/*
Fetch the contents of the "message" textbox, and encode it
in a form we can use for the sign operation.
*/
function getMessageEncoding() {
const messageBox = document.querySelector(".rsassa-pkcs1 #message");
let message = messageBox.value;
let enc = new TextEncoder();
return enc.encode(message);
}
let encoded = getMessageEncoding();
let signature = await window.crypto.subtle.sign(
"RSASSA-PKCS1-v1_5",
privateKey,
encoded,
);
RSA-PSS
Dieser Code holt den Inhalt eines Textfeldes, kodiert ihn zum Signieren und signiert ihn mit einem privaten Schlüssel. Siehe den vollständigen Quellcode auf GitHub.
/*
Fetch the contents of the "message" textbox, and encode it
in a form we can use for the sign operation.
*/
function getMessageEncoding() {
const messageBox = document.querySelector(".rsa-pss #message");
let message = messageBox.value;
let enc = new TextEncoder();
return enc.encode(message);
}
let encoded = getMessageEncoding();
let signature = await window.crypto.subtle.sign(
{
name: "RSA-PSS",
saltLength: 32,
},
privateKey,
encoded,
);
ECDSA
Dieser Code holt den Inhalt eines Textfeldes, kodiert ihn zum Signieren und signiert ihn mit einem privaten Schlüssel. Siehe den vollständigen Quellcode auf GitHub.
/*
Fetch the contents of the "message" textbox, and encode it
in a form we can use for the sign operation.
*/
function getMessageEncoding() {
const messageBox = document.querySelector(".ecdsa #message");
let message = messageBox.value;
let enc = new TextEncoder();
return enc.encode(message);
}
let encoded = getMessageEncoding();
let signature = await window.crypto.subtle.sign(
{
name: "ECDSA",
hash: { name: "SHA-384" },
},
privateKey,
encoded,
);
HMAC
Dieser Code holt den Inhalt eines Textfeldes, kodiert ihn zum Signieren und signiert ihn mit einem geheimen Schlüssel. Siehe den vollständigen Quellcode auf GitHub.
/*
Fetch the contents of the "message" textbox, and encode it
in a form we can use for the sign operation.
*/
function getMessageEncoding() {
const messageBox = document.querySelector(".hmac #message");
let message = messageBox.value;
let enc = new TextEncoder();
return enc.encode(message);
}
let encoded = getMessageEncoding();
let signature = await window.crypto.subtle.sign("HMAC", key, encoded);
Ed25519 (Schlüsselerzeugung, Signierung und Verifizierung)
Dieser Code erzeugt ein Ed25519-Signaturschlüsselpaar, verwendet den privaten Schlüssel zum Signieren der (kodierten) Inhalte eines Textes <input>
, und überprüft dann die Signatur mit dem öffentlichen Schlüssel.
Es ist abgeleitet von diesem Quellcode auf GitHub., den Sie hier live ausführen können.
HTML
Das HTML definiert ein <input>
Element, das den zu signierenden Text enthält, und einen Button, der die Operation zum Erstellen von Schlüsseln startet, den Text signiert und dann die Signatur verifiziert.
<label for="message">Enter a message to sign:</label>
<input
type="text"
id="message"
name="message"
size="25"
value="The lion roars near dawn" />
<input id="sign-button" type="button" value="Run" />
JavaScript
Das JavaScript erhält zuerst die #sign-button
und #message
<input>
Elemente, dann wird ein Listener für das click
Ereignis auf den Button hinzugefügt.
Der Ereignishandler löscht das Log und führt die anderen Operationen mit dem Inhalt des <input>
Elements aus.
const button = document.querySelector("#sign-button");
const input = document.querySelector("#message");
button.addEventListener("click", () => {
// Clear log
logElement.innerText = "";
logElement.scrollTop = logElement.scrollHeight;
// Run test
test(input.value);
});
Zuerst erzeugt es Schlüssel mit dem Ed25519 Algorithmus, dann kodiert es Text und signiert diesen Text mit dem privaten Schlüssel.
Abschließend ruft es SubtleCrypto.verify()
mit dem öffentlichen Schlüssel auf, um die Signatur zu überprüfen.
async function test(data) {
log(`Message: ${data}`);
try {
// Generate keys
const { publicKey, privateKey } = await crypto.subtle.generateKey(
{
name: "Ed25519",
},
true,
["sign", "verify"],
);
log(`publicKey: ${publicKey}, type: ${publicKey.type}`);
log(`privateKey: ${privateKey}, type: ${privateKey.type}`);
// Encode data prior to signing
const encoder = new TextEncoder();
encodedData = encoder.encode(data);
// Log the first part of the encoded data
const shorterEncodedBuffer = new Uint8Array(encodedData.buffer, 0, 14);
log(
`encodedData: ${shorterEncodedBuffer}...[${encodedData.byteLength} bytes total]`,
);
//log(`encodedData: ${encodedData}`);
// Sign the data using the private key.
const signature = await crypto.subtle.sign(
{
name: "Ed25519",
},
privateKey,
encodedData,
);
// Log the first part of the signature data
const signatureBuffer = new Uint8Array(signature, 0, 14);
log(
`signature: ${signatureBuffer}...[${signature.byteLength} bytes total]`,
);
// Verify the signature using the public key
const verifyResult = await crypto.subtle.verify(
{
name: "Ed25519",
},
publicKey,
signature,
encodedData,
);
// Log result - true if the text was signed with the corresponding public key.
log(`signature verified?: ${verifyResult}`);
} catch (error) {
log(error);
}
}
Ergebnis
Spezifikationen
Specification |
---|
Web Cryptography API # SubtleCrypto-method-sign |
Browser-Kompatibilität
BCD tables only load in the browser
Siehe auch
SubtleCrypto.verify()
.- RFC 3447 spezifiziert RSASSA-PKCS1-v1_5.
- RFC 3447 spezifiziert RSA-PSS.
- FIPS-186 spezifiziert ECDSA.
- FIPS 198-1 spezifiziert HMAC.