Note
一部の情報は、市販される前に大幅に変更される可能性があるプレリリース製品に関連しています。 Microsoft は、ここで提供される情報に関して明示的または黙示的な保証を行いません。 このトピックで説明する機能は、Windows Insider Previewのプレリリース バージョンで使用できます。
The NCryptDecapsulate function performs the Decapsulation operation of a Key Encapsulation Mechanism (KEM). KEM 暗号テキストを受け取り、指定された秘密キーで暗号化を解除し、共有秘密キーを返します。
暗号テキストが正しく書式設定されていても、カプセル化解除キーと一致しない場合、この API は成功しますが、ランダムな共有秘密キーが生成されます。
Syntax
SECURITY_STATUS NCryptDecapsulate (
[in] NCRYPT_KEY_HANDLE hKey,
[in] PCBYTE pbCipherText,
[in] ULONG cbCipherText,
[out] PBYTE pbSecretKey,
[in] ULONG cbSecretKey,
[out] ULONG *pcbSecretKey,
[in] ULONG dwFlags
);
Parameters
hKey[in]
カプセル化解除操作に使用するキーのハンドル。
pbCipherText[in]
KEM 暗号テキストを含むバッファーへのポインター。 The NCryptEncapsulate 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 |
|---|---|
ERROR_SUCCESS |
関数が成功しました。 |
NTE_BAD_FLAGS |
The dwFlags parameter contains a value that is not valid. |
NTE_INVALID_PARAMETER |
One or more required parameters (hKey, pcbSecretKey, pcbCipherText) is NULL, or one of the parameters has an invalid value. |
NTE_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 NCryptDecapsulate with a NULLpbSecretKey. The required size will be returned in pcbSecretKey. このクエリは効率的であり、カプセル化解除を実行せずにサイズを返します。
Equivalently, use NCryptGetProperty to query the NCRYPT_KEM_SHARED_SECRET_LENGTH_PROPERTY 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 agreed secret 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 self-test detect hardware error).
Requirements
| Requirement | Value |
|---|---|
| サポートされる最小クライアント | Windows Insider (ビルド 27843): ML-KEM のサポートが開始されます。 [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows Insider (ビルド 27843): ML-KEM のサポートが開始されます。 [デスクトップ アプリのみ] |
| Library | Ncrypt.lib |
| DLL | Ncrypt.dll |