Note
일부 정보는 상용 출시되기 전에 실질적으로 수정될 수 있는 시험판 제품과 관련이 있습니다. Microsoft는 여기에 제공된 정보에 대해 어떠한 명시적이거나 묵시적인 보증도 하지 않습니다. 이 항목에 설명된 기능은 Windows Insider Preview시험판 버전에서 사용할 수 있습니다.
The BCryptDecapsulate function performs the Decapsulation operation of a Key Encapsulation Mechanism (KEM). KEM 암호 텍스트를 사용하고 제공된 프라이빗 키로 암호를 해독하고 공유 비밀 키를 반환합니다.
암호 텍스트의 형식이 올바르게 지정되었지만 캡슐화 키와 일치하지 않는 경우 이 API는 성공하지만 임의 공유 비밀 키가 생성됩니다.
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]
KEM 암호 텍스트를 캡슐화하는 데 사용할 키의 핸들입니다. KEM 암호 텍스트를 생성하는 데 사용되는 공용(캡슐화) 키에 해당하는 프라이빗(캡슐화) 키여야 합니다. The key handle is obtained from one of the keypair creation functions, such as BCryptGenerateKeyPair or BCryptImportKeyPair.
pbCipherText[in]
KEM 암호 텍스트가 포함된 버퍼에 대한 포인터입니다. The BCryptEncapsulate function may be used to create a KEM ciphertext.
cbCipherText[in]
The size, in bytes, of the pbCipherText buffer.
pbSecretKey[out]
공유 비밀 키를 받는 버퍼에 대한 포인터입니다. 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]
예약됨, 0이어야 합니다.
Return value
함수의 성공 또는 실패를 나타내는 상태 코드를 반환합니다.
가능한 반환 코드는 다음을 포함하지만 제한되지는 않습니다.
| Return Code | Description |
|---|---|
STATUS_SUCCESS |
함수가 성공했습니다. |
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. 이 쿼리는 효율적이며 캡슐화를 수행하지 않고 크기를 반환합니다.
Equivalently, use BCryptGetProperty to query the BCRYPT_KEM_SHARED_SECRET_LENGTH property of the algorithm or key handle.
현재 지원되는 KEM 알고리즘(ML-KEM)의 경우 공유 비밀 길이는 지정된 알고리즘의 상수 크기입니다.
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. 이렇게 하면 피어의 대칭 키가 일치하지 않을 때 상위 수준 프로토콜이 나중에 실패합니다. 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 |
|---|---|
| 지원되는 최소 클라이언트 | Windows 참가자(빌드 27843): ML-KEM 대한 지원이 시작됩니다. [데스크톱 앱만 해당] |
| 지원되는 최소 서버 | Windows 참가자(빌드 27843): ML-KEM 대한 지원이 시작됩니다. [데스크톱 앱만 해당] |
| Library | Bcrypt.lib |
| DLL | Bcrypt.dll |