Betriebsarten und Aufrufbindung

graph TD
    CALL["Aufruf einer Methode, etwa CreateSelfSigned"]
    FW[".NET-Methode, unverändert"]
    EXT["Erweiterung der Bibliothek"]
    DEF["PostQuantumConfig.DefaultMode"]
    C["Classic: Ergebnis der .NET-Methode"]
    H["Hybrid: klassisch plus ML-DSA"]
    P["PostQuantum: nur ML-DSA oder ML-KEM"]
    CALL -- "ohne Argument CryptoMode" --> FW
    CALL -- "mit Argument CryptoMode" --> EXT
    EXT -- "Wert null" --> DEF
    EXT --> C
    EXT --> H
    EXT --> P
    DEF --> C
    DEF --> H
    DEF --> P

Bild: Ob ein Aufruf in die Bibliothek führt, entscheidet allein der Compiler anhand des Arguments CryptoMode. Erst innerhalb der Bibliothek wählt der Wert des Arguments die Betriebsart.

Die Bibliothek kennt drei Betriebsarten. Welche ein Aufruf verwendet, steht an der Aufrufstelle; eine globale Umschaltung, die bestehenden Code still verändert, gibt es nicht.

• Drei Betriebsarten in der Aufzählung CryptoMode: Classic, Hybrid und PostQuantum.
• Bindung durch den Compiler: Ein Aufruf ohne CryptoMode erreicht immer die Methode von .NET.
• Voreinstellung für den Wert null: PostQuantumConfig.DefaultMode legt fest, was ein Aufruf mit mode: null erzeugt.
• Kein stiller Rückfall: Eine angeforderte PQ-Betriebsart liefert PQ oder scheitert.
• PostQuantum nur nach Freischaltung: Die Voreinstellung nach BSI TR-02102-1 lässt PQ-Verfahren allein erst zu, wenn die Anwendung es erlaubt.

Hybrid ist die Betriebsart für den Übergang: Gegenstellen ohne PQ-Kenntnis arbeiten unverändert weiter, und der PQ-Anteil schützt, sobald die klassischen Verfahren gebrochen werden können. BSI TR-02102-1 empfiehlt PQ-Verfahren nur in dieser Kombination mit einem klassischen Verfahren.

PostQuantum setzt voraus, dass alle Beteiligten ML-DSA oder ML-KEM verarbeiten. Weil die Richtlinie ein PQ-Verfahren allein nicht empfiehlt, wirft jede Operation in dieser Betriebsart eine CryptographicException, bis die Anwendung PostQuantumExemptions.PurePostQuantum in PostQuantumConfig.Exemptions setzt. Das gilt auch für das Prüfen. Einzelheiten: Richtlinie für Post-Quanten-Verfahren.

Jede Erweiterung trägt denselben Namen und dieselben Parameter wie die Methode von .NET und hängt einen optionalen Parameter CryptoMode? mode an. Der C#-Compiler zieht eine Instanzmethode stets einer Erweiterungsmethode vor, wenn beide passen. Daraus folgt:

// Bindet an CertificateRequest.CreateSelfSigned von .NET.
using var classic = request.CreateSelfSigned(notBefore, notAfter);
 
// Bindet an die Erweiterung der Bibliothek.
using var hybrid = request.CreateSelfSigned(notBefore, notAfter, CryptoMode.Hybrid);

Ein Aufruf ohne Argument verhält sich deshalb in allem wie bisher, auch in seinen Fehlern. Ein Beispiel: Für eine Anforderung mit ML-DSA-Schlüssel wirft CreateSelfSigned ohne Argument die InvalidOperationException von .NET, weil .NET diesen Schlüssel nicht kennt. Erst der Aufruf mit CryptoMode.PostQuantum stellt das Zertifikat aus.

Übergeben Sie mode: null, wendet die Erweiterung PostQuantumConfig.DefaultMode an. Die Voreinstellung ist Classic. PostQuantumConfig.EnablePostQuantum(mode) lädt OpenSSL und setzt DefaultMode erst dann auf mode, wenn das gelungen ist. So lässt sich die Betriebsart an einer Stelle der Anwendung festlegen, während jede Aufrufstelle durch das Argument sichtbar macht, dass sie die Bibliothek verwendet:

PostQuantumConfig.EnablePostQuantum(CryptoMode.Hybrid);
 
// DefaultMode ist jetzt Hybrid; der Aufruf erzeugt ein hybrides Zertifikat.
using var certificate = request.CreateSelfSigned(notBefore, notAfter, mode: null);

Fordert ein Aufruf Hybrid oder PostQuantum an und kann die Bibliothek den PQ-Anteil nicht erzeugen, scheitert der Aufruf mit einer CryptographicException. Das gilt, wenn OpenSSL fehlt oder das Verfahren nicht anbietet, wenn ein benötigter ML-DSA-Schlüssel nicht im Prozess vorhanden ist und wenn der Schlüssel nicht zur Betriebsart passt. Ein Ergebnis, das nur den klassischen Anteil trägt, liefert ein solcher Aufruf nie.

EnablePostQuantum folgt derselben Regel: Scheitert das Laden von OpenSSL oder bietet es ML-DSA-65 oder ML-KEM-768 nicht an, wirft die Methode, und DefaultMode behält seinen bisherigen Wert. EnablePostQuantum(CryptoMode.PostQuantum) wirft ohne die Freischaltung PurePostQuantum, bevor es OpenSSL lädt.

• Ohne Argument kein PQ. DefaultMode wirkt nur auf Aufrufe, die das Argument CryptoMode tragen. Bestehender Code ohne dieses Argument gewinnt durch EnablePostQuantum keinen PQ-Anteil.
• null nur mit Namen übergeben. Ein null an der Stelle des Arguments kann an eine andere Überladung von .NET binden; request.CreateSigningRequest(null) etwa ruft die Überladung von .NET mit einem X509SignatureGenerator auf. Schreiben Sie deshalb mode: null.
• Betriebsart und Schlüssel müssen passen. PostQuantum braucht einen ML-DSA- oder ML-KEM-Schlüssel, Hybrid einen RSA- oder ECDSA-Schlüssel; den ML-DSA-Schlüssel daneben erzeugt die Bibliothek oder übernimmt ihn vom Aufrufer.
• Prozessweite Voreinstellung. DefaultMode und OpenSslPath gelten für den ganzen Prozess. Setzen Sie beide einmal beim Start der Anwendung, bevor die erste kryptografische Operation läuft.

• WKL.System.Security.Cryptography – Überblick
• Richtlinie für Post-Quanten-Verfahren
• So binden Sie OpenSSL ein
• Formate der Post-Quanten-Anteile
• Die erste hybride Zertifikatskette