Freigeben über

Verwenden von ML-KEM mit CNG

Hinweis

Einige Informationen beziehen sich auf ein Vorabversionsprodukt, das vor der kommerziellen Veröffentlichung erheblich geändert werden kann. Microsoft gibt keine Garantie, weder ausdrücklich noch impliziert, hinsichtlich der hier bereitgestellten Informationen. Das in diesem Thema beschriebene Feature ist in Vorabversionen der Windows Insider Previewverfügbar.

Dieser Artikel bietet einen Leitfaden zur Implementierung des End-to-End-Workflows für die Durchführung eines Schlüsselaustauschs mithilfe des Modul-Lattice-Based-Algorithmus für den Key-Kapselungsmechanismus (ML-KEM) mit der Microsoft CNG-API.

Beispiel für ML-KEM Key-Kapselungs- und Entkapselungscode mit BCrypt

ML-KEM ist ein Post-Quantum-Algorithmus, der für den Schlüsselaustausch verwendet wird und in FIPS 203 standardisiert wird. Der Schlüsselaustausch ist ein wichtiger Bestandteil von Sicherheitsprotokollen wie TLS, wobei ein Client und ein Server eine Verbindung aushandeln und Schlüsselmaterial zum Verschlüsseln und Entschlüsseln von Nachrichten erstellen und teilen, die über das Internet gesendet werden. In KEM werden die Schlüssel, die im Schlüsselpaargenerierungsprozess erzeugt werden, als Kapselschlüssel und Entkapselungsschlüssel bezeichnet. Der Kapselungsschlüssel ist öffentlich und kann von jedem verwendet werden, um einen Schlüsselkapselvorgang auszuführen, der einen geheimen Schlüssel (für die Partei, die diesen Vorgang ausführt) und einen Chiffretext erzeugt. Der Chiffretext wird als Eingabe für den Schlüsseldecapsulationsvorgang vom Besitzer des privaten Schlüssels bereitgestellt, um denselben freigegebenen geheimen Schlüssel wiederherzustellen, den die Kapselungspartei während des Schlüsselkapselungsprozesses erhalten hat. In diesem Beispiel wird veranschaulicht, wie ein hypothetischer TLS-Client und eine Serveranwendung die neuen ML-KEM-APIs in BCrypt nutzen würden, um einen Schlüsselaustausch durchzuführen.

Einrichtung und Schlüsselpaargenerierung

In den folgenden Schritten wird das Einrichten der ML-KEM Schlüsselpaargenerierung und Kapselung beschrieben:

  1. Verwenden Sie BCryptGenerateKeyPair mit BCRYPT_MLKEM_ALG_HANDLE , um ein neues Schlüsselpaar für die Schlüsselkapselung zu erstellen. Die Felder "Länge" und "Flags" sind beide 0, da die Schlüssellängen durch den ML-KEM Parametersatz definiert werden.

    // Generate the key pair for key exchange
unique_bcrypt_key hKeyPair;
THROW_IF_NTSTATUS_FAILED(
   BCryptGenerateKeyPair(
     BCRYPT_MLKEM_ALG_HANDLE,
     &hKeyPair,
     0, // dwLength
     0)); // dwFlags

  2. Rufen Sie BCryptSetProperty für das Schlüsselpaar auf, um BCRYPT_PARAMETER_SET_NAME auf BCRYPT_MLKEM_PARAMETER_SET_768 zu setzen, wobei das Parametersatz für den ML-KEM-Vorgang festgelegt wird. ML-KEM unterstützt auch die 512- und 1024-Parametersätze, die von NIST definiert werden.

    THROW_IF_NTSTATUS_FAILED(
   BCryptSetProperty(
       &hKeyPair,
       BCRYPT_PARAMETER_SET_NAME,
      (PUCHAR) BCRYPT_MLKEM_PARAMETER_SET_768,
       sizeof(BCRYPT_MLKEM_PARAMETER_SET_768),
       0)); // dwFlags

  3. Rufen Sie BCryptFinalizeKeyPair auf, um das Schlüsselpaar für die Verwendung in nachfolgenden Vorgängen vorzubereiten.

    THROW_IF_NTSTATUS_FAILED(
    BCryptFinalizeKeyPair(
        hKeyPair.get(),
        0)); // dwFlags

Öffentlicher Schlüsselexport und Exchange

  1. Rufen Sie BCryptExportKey mit einem NULL Ausgabepuffer auf, um die erforderliche Größe für den Export der BCRYPT_MLKEM_ENCAPSULATION_BLOB abzufragen.

    ULONG cbEncapsulationKeyBlob = 0;

THROW_IF_NTSTATUS_FAILED(
    BCryptExportKey(
        hKeyPair.get(),
        NULL,
        BCRYPT_MLKEM_ENCAPSULATION_BLOB,
        NULL, // pbOutput
        0, // cbOutput
        &cbEncapsulationKeyBlob,
        0)); // dwFlags

  2. Weisen Sie einen Puffer basierend auf der zuvor abgerufenen Größe zu, und exportieren Sie dann den Kapselungsschlüssel (public) mithilfe von BCryptExportKey. Dieses Blob wird an den Schlüsselaustauschpartner (z. B. den Server in einem Clientserverszenario) gesendet.

    vector<BYTE> encapsulationKeyBlob(cbEncapsulationKeyBlob);
THROW_IF_NTSTATUS_FAILED(
    BCryptExportKey(
        hKeyPair.get(),
        NULL,
        BCRYPT_MLKEM_ENCAPSULATION_BLOB,
        encapsulationKeyBlob.data(),
        static_cast<ULONG>(encapsulationKeyBlob.size()),
        &cbEncapsulationKeyBlob,
        0));

  3. Stellen Sie sicher, dass die BCRYPT_MLKEM_KEY_BLOB die richtige öffentliche Magie und 768 Parameter festgelegt hat.

    BCRYPT_MLKEM_KEY_BLOB* pEncapsulationKeyBlob = 
    reinterpret_cast<BCRYPT_MLKEM_KEY_BLOB *>(encapsulationKeyBlob.data());
ASSERT(pEncapsulationKeyBlob->dwMagic == BCRYPT_MLKEM_PUBLIC_MAGIC);
ASSERT(pEncapsulationKeyBlob->cbParameterSet == sizeof(BCRYPT_MLKEM_PARAMETER_SET_768));

if (wcscmp(BCRYPT_MLKEM_PARAMETER_SET_768, reinterpret_cast<WCHAR *>(pEncapsulationKeyBlob + 1)) != 0)
{
    return;
}

  4. Senden Sie den Kapselungsschlüssel an den Server in der Clientschlüsselaustauschnachricht.

    PBYTE pbEncapsulationKey = reinterpret_cast<PBYTE>(pEncapsulationKeyBlob) + sizeof(BCRYPT_MLKEM_KEY_BLOB) + sizeof(BCRYPT_MLKEM_PARAMETER_SET_768);
ULONG cbEncapsulationKey = pEncapsulationKeyBlob->cbKey;
SendToServer(pbEncapsulationKey, cbEncapsulationKey);

Kapselung und Entkapselung

Die folgenden Schritte beschreiben den Prozess der Kapselung und Entkapselung des gemeinsam genutzten geheimen Schlüssels:

  1. Der Server empfängt die Schlüsselaustauschnachricht des Clients und ruft die Bytes des Kapselungsschlüssels ab.

    // Server receives the client's key_exchange message and retrieves the
// encapsulation key bytes.
vector<BYTE> encapsulationKey = GetClientKeyExchange();
ULONG cbEncapsulationKey = static_cast<ULONG>(encapsulationKey.size());

  2. Der Server setzt den Schlüssel in eine BCRYPT_KEY_BLOB unter Verwendung des 768-Parametersatzes und der öffentlichen Magie und importiert den Kapselschlüssel.

    // Put the Key in a BCRYPT_KEY_BLOB and import it.
ULONG cbEncapsulationKeyBlob = sizeof(BCRYPT_MLKEM_KEY_BLOB) + sizeof(BCRYPT_MLKEM_PARAMETER_SET_768) + cbEncapsulationKey;
vector<BYTE> encapsulationKeyBlob(cbEncapsulationKeyBlob);
BCRYPT_MLKEM_KEY_BLOB* pEncapsulationKeyBlob = 
    reinterpret_cast<BCRYPT_MLKEM_KEY_BLOB *>(encapsulationKeyBlob.data());
pEncapsulationKeyBlob->dwMagic = BCRYPT_MLKEM_PUBLIC_MAGIC;
pEncapsulationKeyBlob->cbParameterSet = sizeof(BCRYPT_MLKEM_PARAMETER_SET_768);
pEncapsulationKeyBlob->cbKey = cbEncapsulationKey;

CopyMemory(
    reinterpret_cast<PBYTE>(pEncapsulationKeyBlob) + sizeof(BCRYPT_MLKEM_KEY_BLOB),
    BCRYPT_MLKEM_PARAMETER_SET_768,
    sizeof(BCRYPT_MLKEM_PARAMETER_SET_768));

CopyMemory(
    reinterpret_cast<PBYTE>(pEncapsulationKeyBlob) + sizeof(BCRYPT_MLKEM_KEY_BLOB) + sizeof(BCRYPT_MLKEM_PARAMETER_SET_768),
    encapsulationKey.data(),
    encapsulationKey.size());

unique_bcrypt_key hKeyPair;

// The server knows the ML-KEM parameter set from the client's
// key_exchange, which denotes the parameter set associated with the
// encapsulation key it sent. In this case, we know it's
// BCRYPT_MLKEM_PARAMETER_SET_768.
THROW_IF_NTSTATUS_FAILED(
    BCryptImportKeyPair(
        BCRYPT_MLKEM_ALG_HANDLE,
        NULL, // hImportKey
        BCRYPT_MLKEM_ENCAPSULATION_BLOB,
        &hKeyPair,
        encapsulationKeyBlob.data(),
        static_cast<ULONG>(encapsulationKeyBlob.size()),
        0)); // dwFlags

// Get the secret key length and ciphertext length. These values are static
// and can be cached for the algorithm handle.
ULONG cbSecretKey = 0;
ULONG cbProperty = sizeof(cbSecretKey);

  3. Der Server verwendet BCryptGetProperty , um die Länge des geheimen Schlüssels und die Länge des Chiffretexts abzurufen und die erforderlichen Puffer für beide zuzuweisen.

    THROW_IF_NTSTATUS_FAILED(
    BCryptGetProperty(
        &hKeyPair,
        BCRYPT_KEM_SHARED_SECRET_LENGTH,
        reinterpret_cast<PUCHAR>(&cbSecretKey),
        cbProperty,
        &cbProperty,
        0)); // dwFlags

ULONG cbCipherText = 0; 
cbProperty = sizeof(cbCipherText);

THROW_IF_NTSTATUS_FAILED(
    BCryptGetProperty(
        &hKeyPair,
        BCRYPT_KEM_CIPHERTEXT_LENGTH,
        reinterpret_cast<PUCHAR>(&cbCipherText),
        cbProperty,
        &cbProperty,
        0)); // dwFlags

// Then allocate the required buffers.
vector<BYTE> secretKey(cbSecretKey);
vector<BYTE> cipherText(cbCipherText);

  4. Der Server führt BCryptEncapsulate aus und sendet das Chiffrat an den Client in der Nachricht des Serverschlüsselaustauschs.

    // Perform the encapsulate operation.
THROW_IF_NTSTATUS_FAILED(
    BCryptEncapsulate(
        hKeyPair.get(),
        secretKey.data(),
        static_cast<ULONG>(secretKey.size()),
        &cbSecretKey,
        cipherText.data(),
        static_cast<ULONG>(cipherText.size()),
        &cbCipherText,
        0)); // dwFlags

// cipherText is sent to the client in the server's key_exchange message.
SendToClient(cipherText.data(), cipherText.size());

  5. Der Client verwendet den empfangenen Serverschlüsselaustausch, um einen Chiffretext zu generieren, der einen freigegebenen geheimen Schlüssel kapselt.

    // pbEncapsulationKey is sent on the wire in the client's key_exchange
// message.
// ...
// < It's now the server's turn. It will use the encapsulation key to
// generate the a CipherText encapsulating the shared secret key and send
// it as a response to the client's key_exchange message. Sample_Server()
// demonstrates how a hypothetical server may do this.>
// ...
// When the ServerKeyExchange message is received from the TLS server,
// get the ML-KEM CipherText from the ServerKeyExchange message.
vector<BYTE> cipherText = GetServerKeyExchange();

  6. Der Client ruft BCryptGetProperty auf, um die Länge des geheimen Schlüssels abzurufen und den entsprechenden Puffer zuzuweisen.

    // Get the secret key length. This value is static and can be cached for
// the algorithm handle.
ULONG cbSecretKey = 0;
ULONG cbProperty = sizeof(cbSecretKey);
THROW_IF_NTSTATUS_FAILED(
    BCryptGetProperty(
        &hKeyPair,
        BCRYPT_KEM_SHARED_SECRET_LENGTH,
        reinterpret_cast<PUCHAR>(&cbSecretKey),
        cbProperty,
        &cbProperty,
        0)); // dwFlags

  7. Der Client konstruiert den freigegebenen geheimen Schlüssel, indem er ein Schlüssel-BLOB erstellt und BCryptDecapsulate mit dem Chiffretext und der Länge des Geheimnisses aufruft.

    vector<BYTE> secretKey(cbSecretKey);

THROW_IF_NTSTATUS_FAILED(
    BCryptDecapsulate(
        hKeyPair.get(),
        cipherText.data(),
        static_cast<ULONG>(cipherText.size()),
        secretKey.data(),
        static_cast<ULONG>(secretKey.size()),
        &cbSecretKey,
        0)); // dwFlags

Ableiten von Sitzungsschlüsseln

Sowohl Client als auch Server verfügen jetzt über denselben freigegebenen geheimen Schlüssel, der an eine Schlüsselableitungsfunktion wie "DeriveSessionKeys " übergeben werden kann, um Sitzungsschlüssel für die sichere Kommunikation zu generieren.

    // secretKey contains the shared secret key which plugs into the TLS key
    // schedule.
    DeriveSessionKeys(secretKey);

Überprüfen des vollständigen Codebeispiels

Sie können das vollständige Codebeispiel unten überprüfen:

void Sample_Client()
{
    // Generate the key pair for key exchange
    unique_bcrypt_key hKeyPair;
    THROW_IF_NTSTATUS_FAILED(
        BCryptGenerateKeyPair(
            BCRYPT_MLKEM_ALG_HANDLE,
            &hKeyPair,
            0, // dwLength
            0)); // dwFlags

   THROW_IF_NTSTATUS_FAILED(
        BCryptSetProperty(
            &hKeyPair,
            BCRYPT_PARAMETER_SET_NAME,
            (PUCHAR) BCRYPT_MLKEM_PARAMETER_SET_768,
            sizeof(BCRYPT_MLKEM_PARAMETER_SET_768),
            0)); // dwFlags

    THROW_IF_NTSTATUS_FAILED(
        BCryptFinalizeKeyPair(
            hKeyPair.get(),
            0)); // dwFlags

    ULONG cbEncapsulationKeyBlob = 0;

    THROW_IF_NTSTATUS_FAILED(
        BCryptExportKey(
            hKeyPair.get(),
            NULL,
            BCRYPT_MLKEM_ENCAPSULATION_BLOB,
            NULL, // pbOutput
            0, // cbOutput
            &cbEncapsulationKeyBlob,
            0)); // dwFlags

    vector<BYTE> encapsulationKeyBlob(cbEncapsulationKeyBlob);
    THROW_IF_NTSTATUS_FAILED(
        BCryptExportKey(
            hKeyPair.get(),
            NULL,
            BCRYPT_MLKEM_ENCAPSULATION_BLOB,
            encapsulationKeyBlob.data(),
            static_cast<ULONG>(encapsulationKeyBlob.size()),
            &cbEncapsulationKeyBlob,
            0));

    BCRYPT_MLKEM_KEY_BLOB* pEncapsulationKeyBlob = 
        reinterpret_cast<BCRYPT_MLKEM_KEY_BLOB *>(encapsulationKeyBlob.data());
    ASSERT(pEncapsulationKeyBlob->dwMagic == BCRYPT_MLKEM_PUBLIC_MAGIC);
    ASSERT(pEncapsulationKeyBlob->cbParameterSet == sizeof(BCRYPT_MLKEM_PARAMETER_SET_768));

    if (wcscmp(BCRYPT_MLKEM_PARAMETER_SET_768, reinterpret_cast<WCHAR *>(pEncapsulationKeyBlob + 1)) != 0)
    {
        return;
    }

    PBYTE pbEncapsulationKey = reinterpret_cast<PBYTE>(pEncapsulationKeyBlob) + sizeof(BCRYPT_MLKEM_KEY_BLOB) + sizeof(BCRYPT_MLKEM_PARAMETER_SET_768);
    ULONG cbEncapsulationKey = pEncapsulationKeyBlob->cbKey;
    SendToServer(pbEncapsulationKey, cbEncapsulationKey);

    // pbEncapsulationKey is sent on the wire in the client's key_exchange
    // message.
    // ...
    // < It's now the server's turn. It will use the encapsulation key to
    // generate the a CipherText encapsulating the shared secret key and send
    // it as a response to the client's key_exchange message. Sample_Server()
    // demonstrates how a hypothetical server may do this.>
    // ...
    // When the ServerKeyExchange message is received from the TLS server,
    // get the ML-KEM CipherText from the ServerKeyExchange message.
    vector<BYTE> cipherText = GetServerKeyExchange(); 

    // Get the secret key length. This value is static and can be cached for
    // the algorithm handle.
    ULONG cbSecretKey = 0;
    ULONG cbProperty = sizeof(cbSecretKey);
    THROW_IF_NTSTATUS_FAILED(
        BCryptGetProperty(
            &hKeyPair,
            BCRYPT_KEM_SHARED_SECRET_LENGTH,
            reinterpret_cast<PUCHAR>(&cbSecretKey),
            cbProperty,
            &cbProperty,
            0)); // dwFlags

    vector<BYTE> secretKey(cbSecretKey);

    THROW_IF_NTSTATUS_FAILED(
        BCryptDecapsulate(
            hKeyPair.get(),
            cipherText.data(),
            static_cast<ULONG>(cipherText.size()),
            secretKey.data(),
            static_cast<ULONG>(secretKey.size()),
            &cbSecretKey,
            0)); // dwFlags

    // secretKey is the shared secret key which plugs into the TLS key
    // schedule.
   DeriveSessionKeys(secretKey);
}

void Sample_Server()
{
    // Server receives the client's key_exchange message and retrieves the
    // encapsulation key bytes.
    vector<BYTE> encapsulationKey = GetClientKeyExchange();
    ULONG cbEncapsulationKey = static_cast<ULONG>(encapsulationKey.size());

    // Put the Key in a BCRYPT_KEY_BLOB and import it.
    ULONG cbEncapsulationKeyBlob = sizeof(BCRYPT_MLKEM_KEY_BLOB) + sizeof(BCRYPT_MLKEM_PARAMETER_SET_768) + cbEncapsulationKey;
    vector<BYTE> encapsulationKeyBlob(cbEncapsulationKeyBlob);
    BCRYPT_MLKEM_KEY_BLOB* pEncapsulationKeyBlob = 
        reinterpret_cast<BCRYPT_MLKEM_KEY_BLOB *>(encapsulationKeyBlob.data());
    pEncapsulationKeyBlob->dwMagic = BCRYPT_MLKEM_PUBLIC_MAGIC;
    pEncapsulationKeyBlob->cbParameterSet = sizeof(BCRYPT_MLKEM_PARAMETER_SET_768);
    pEncapsulationKeyBlob->cbKey = cbEncapsulationKey;

    CopyMemory(
        reinterpret_cast<PBYTE>(pEncapsulationKeyBlob) + sizeof(BCRYPT_MLKEM_KEY_BLOB),
        BCRYPT_MLKEM_PARAMETER_SET_768,
        sizeof(BCRYPT_MLKEM_PARAMETER_SET_768));

    CopyMemory(
        reinterpret_cast<PBYTE>(pEncapsulationKeyBlob) + sizeof(BCRYPT_MLKEM_KEY_BLOB) + sizeof(BCRYPT_MLKEM_PARAMETER_SET_768),
        encapsulationKey.data(),
        encapsulationKey.size());

    unique_bcrypt_key hKeyPair;

    // The server knows the ML-KEM parameter set from the client's
    // key_exchange, which denotes the parameter set associated with the
    // encapsulation key it sent. In this case, we know it's
    // BCRYPT_MLKEM_PARAMETER_SET_768.
    THROW_IF_NTSTATUS_FAILED(
        BCryptImportKeyPair(
            BCRYPT_MLKEM_ALG_HANDLE,
            NULL, // hImportKey
            BCRYPT_MLKEM_ENCAPSULATION_BLOB,
            &hKeyPair,
            encapsulationKeyBlob.data(),
            static_cast<ULONG>(encapsulationKeyBlob.size()),
            0)); // dwFlags

    // Get the secret key length and ciphertext length. These values are static
    // and can be cached for the algorithm handle.
    ULONG cbSecretKey = 0;
    ULONG cbProperty = sizeof(cbSecretKey);

    THROW_IF_NTSTATUS_FAILED(
        BCryptGetProperty(
            &hKeyPair,
            BCRYPT_KEM_SHARED_SECRET_LENGTH,
            reinterpret_cast<PUCHAR>(&cbSecretKey),
            cbProperty,
            &cbProperty,
            0)); // dwFlags

    ULONG cbCipherText = 0; 
    cbProperty = sizeof(cbCipherText);

    THROW_IF_NTSTATUS_FAILED(
        BCryptGetProperty(
            &hKeyPair,
            BCRYPT_KEM_CIPHERTEXT_LENGTH,
            reinterpret_cast<PUCHAR>(&cbCipherText),
            cbProperty,
            &cbProperty,
            0)); // dwFlags

    // Then allocate the required buffers.
    vector<BYTE> secretKey(cbSecretKey);
    vector<BYTE> cipherText(cbCipherText);

    // Perform the encapsulate operation.
    THROW_IF_NTSTATUS_FAILED(
        BCryptEncapsulate(
            hKeyPair.get(),
            secretKey.data(),
            static_cast<ULONG>(secretKey.size()),
            &cbSecretKey,
            cipherText.data(),
            static_cast<ULONG>(cipherText.size()),
            &cbCipherText,
            0)); // dwFlags

    // cipherText is sent to the client in the server's key_exchange message.
    SendToClient(cipherText.data(), cipherText.size());

    // secretKey contains the shared secret key which plugs into the TLS key
    // schedule.
    DeriveSessionKeys(secretKey);
}

Verwandte Inhalte