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

js
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" }.
key

Ein CryptoKey Objekt, das den zu verwendenden Schlüssel für das Signieren enthält. Wenn algorithm ein öffentliches Schlüsselkryptosystem identifiziert, ist dies der private Schlüssel.

data

Ein ArrayBuffer, ein TypedArray oder ein DataView 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() oder importKey() übergeben.
  • Für ECDSA ist die Wahl des Digest-Algorithmus im algorithm Parameter enthalten, der in die sign() 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.

js
/*
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.

js
/*
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.

js
/*
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.

js
/*
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.

html
<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.

js
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.

js
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