Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Note
Certaines informations concernent un produit de préversion qui peut être sensiblement modifié avant sa publication commerciale. Microsoft n’offre aucune garantie, expresse ou implicite, en ce qui concerne les informations fournies ici. La fonctionnalité décrite dans cette rubrique est disponible dans les versions préliminaires du Windows Insider Preview.
The BCryptDecapsulate function performs the Decapsulation operation of a Key Encapsulation Mechanism (KEM). Il prend un texte chiffré KEM et il déchiffre avec la clé privée fournie, en retournant la clé secrète partagée.
Si le texte chiffré est correctement mis en forme mais ne correspond pas à la clé decapsulation, cette API réussit, mais une clé secrète partagée aléatoire est générée.
Syntax
NTSTATUS BCryptDecapsulate(
_In_ BCRYPT_KEY_HANDLE hKey,
_In_reads_bytes_(cbCipherText)
PUCHAR pbCipherText,
_In_ ULONG cbCipherText,
_Out_writes_bytes_to_opt_(cbSecretKey, *pcbSecretKey)
PUCHAR pbSecretKey,
_In_ ULONG cbSecretKey,
_Out_ ULONG *pcbSecretKey,
_In_ ULONG dwFlags
);
Parameters
hKey[in]
Handle de la clé à utiliser pour décapsuler le texte chiffré KEM. Il doit s’agir de la clé privée (decapsulation) qui correspond à la clé publique (encapsulation) utilisée pour produire le texte chiffré KEM. The key handle is obtained from one of the keypair creation functions, such as BCryptGenerateKeyPair or BCryptImportKeyPair.
pbCipherText[in]
Pointeur vers une mémoire tampon qui contient le texte chiffré KEM. The BCryptEncapsulate function may be used to create a KEM ciphertext.
cbCipherText[in]
The size, in bytes, of the pbCipherText buffer.
pbSecretKey[out]
Pointeur vers une mémoire tampon qui reçoit la clé secrète partagée. See remarks for more information.
cbSecretKey[in]
The size, in bytes, of the pbSecretKey buffer.
pcbSecretKey[out]
A pointer to a ULONG variable that the receives the number of bytes written to pbSecretKey buffer.
If pbSecretKey is NULL, this receives the size, in bytes, required for the shared secret key.
See remarks for more information.
dwFlags[in]
Réservée, doit être zéro.
Return value
Retourne un code d’état qui indique la réussite ou l’échec de la fonction.
Les codes de retour possibles incluent, mais ne sont pas limités à, les éléments suivants.
| Return Code | Description |
|---|---|
STATUS_SUCCESS |
La fonction a réussi. |
STATUS_INVALID_PARAMETER |
One or more required parameters (hKey, pcbSecretKey, pbCipherText) is NULL, or one of the parameters has an invalid value. |
STATUS_INVALID_BUFFER_SIZE |
A buffer size (cbSecretKey, cbCipherText) does not match the expected size for the KEM parameters associated with the decapsulation key. |
STATUS_BUFFER_TOO_SMALL |
An output buffer size (cbSecretKey) is too small for the result decapsulation operation for the KEM parameters associated with the decapsulation key. pcbSecretKey receives the number of bytes required for pbSecretKey. |
Remarks
To query the required size of the pbSecretKey buffer needed for the KEM shared secret key, call BCryptDecapsulate with a NULLpbSecretKey. The required size will be returned in pcbSecretKey. Cette requête est efficace et retourne la taille sans effectuer la décapsulation.
Equivalently, use BCryptGetProperty to query the BCRYPT_KEM_SHARED_SECRET_LENGTH property of the algorithm or key handle.
Pour les algorithmes KEM actuellement pris en charge (ML-KEM), la longueur du secret partagé est une taille constante pour un algorithme donné.
Additional remarks
Given an invalid, but correctly-sized, ciphertext, the ML-KEM decapsulation operation will implicitly reject the ciphertext by returning success in equal time to a valid decapsulation operation, with pseudo-random shared secret key output. Cela force les protocoles de niveau supérieur à échouer ultérieurement lorsque les clés symétriques des homologues ne correspondent pas. So, decapsulate will only ever fail if there are programming errors (i.e. incorrect size, use of uninitialized hKey), or something fundamentally goes wrong with the environment (i.e. internal memory allocation fails, or and internal consistency test detects hardware error).
Requirements
| Requirement | Value |
|---|---|
| Client minimum requis | Windows Insiders (build 27843) : La prise en charge de ML-KEM commence. [Applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Insiders (build 27843) : La prise en charge de ML-KEM commence. [Applications de bureau uniquement] |
| Library | Bcrypt.lib |
| DLL | Bcrypt.dll |