Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Note
Algumas informações referem-se a um produto de pré-lançamento que pode ser substancialmente modificado antes de ser lançado comercialmente. A Microsoft não oferece garantias, expressas ou implícitas, em relação às informações fornecidas aqui. O recurso descrito neste tópico está disponível em versões de pré-lançamento do Windows Insider Preview.
The BCryptDecapsulate function performs the Decapsulation operation of a Key Encapsulation Mechanism (KEM). Ele usa um texto criptografado KEM e descriptografa com a chave privada fornecida, retornando a chave secreta compartilhada.
Se o texto codificado estiver formatado corretamente, mas não corresponder à chave de descapsulação, essa API terá êxito, mas uma chave secreta compartilhada aleatória será gerada.
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]
O identificador da chave a ser usada para descapsular o texto codificado KEM. Essa deve ser a chave privada (decapsulação) que corresponde à chave pública (encapsulamento) usada para produzir o texto criptografado KEM. The key handle is obtained from one of the keypair creation functions, such as BCryptGenerateKeyPair or BCryptImportKeyPair.
pbCipherText[in]
Um ponteiro para um buffer que contém o texto criptografado KEM. The BCryptEncapsulate function may be used to create a KEM ciphertext.
cbCipherText[in]
The size, in bytes, of the pbCipherText buffer.
pbSecretKey[out]
Um ponteiro para um buffer que recebe a chave secreta compartilhada. 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]
Reservado; deve ser zero
Return value
Retorna um código de status que indica o êxito ou a falha da função.
Os códigos de retorno possíveis incluem, mas não se limitam a, o seguinte.
| Return Code | Description |
|---|---|
STATUS_SUCCESS |
A função foi bem-sucedida. |
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. Essa consulta é eficiente e retorna o tamanho sem executar a decapsulação.
Equivalently, use BCryptGetProperty to query the BCRYPT_KEM_SHARED_SECRET_LENGTH property of the algorithm or key handle.
Para algoritmos KEM com suporte no momento (ML-KEM), o comprimento do segredo compartilhado é um tamanho constante para um determinado algoritmo.
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. Isso força os protocolos de nível superior a falharem mais tarde quando as chaves simétricas dos pares não corresponderem. 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 |
|---|---|
| Cliente mínimo suportado | Windows Insiders (build 27843): O suporte para ML-KEM começa. [Somente aplicativos da área de trabalho] |
| Servidor mínimo compatível | Windows Insiders (build 27843): O suporte para ML-KEM começa. [Somente aplicativos da área de trabalho] |
| Library | Bcrypt.lib |
| DLL | Bcrypt.dll |