Note
一部の情報は、市販される前に大幅に変更される可能性があるプレリリース製品に関連しています。 Microsoft は、ここで提供される情報に関して明示的または黙示的な保証を行いません。 このトピックで説明する機能は、Windows Insider Previewのプレリリース バージョンで使用できます。
The BCryptEncapsulate function performs the Encapsulation operation of a Key Encapsulation Mechanism (KEM). 共有秘密キーを生成し、指定された公開キーで暗号化して KEM 暗号テキストを生成し、共有秘密キーと KEM 暗号テキストの両方を返します。
Syntax
NTSTATUS BCryptEncapsulate(
_In_ BCRYPT_KEY_HANDLE hKey,
_Out_writes_bytes_to_opt_(cbSecretKey ,*pcbSecretKey)
PUCHAR pbSecretKey,
_In_ ULONG cbSecretKey,
_Out_ ULONG *pcbSecretKey,
_Out_writes_bytes_to_opt_(cbCipherText ,*pcbCipherText)
PUCHAR pbCipherText,
_In_ ULONG cbCipherText,
_Out_ ULONG *pcbCipherText,
_In_ ULONG dwFlags
);
Parameters
hKey[in]
カプセル化操作に使用するキーのハンドル。 This key must contain a public (encapsulation) key, and the handle would typically be obtained by using BCryptImportKeyPair with a public key BLOB for the KEM algorithm. KEM 秘密キー ハンドルはキー ペアを表しているため、カプセル化操作に秘密キー ハンドルを使用することもできます。
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.
pbCipherText[out]
KEM 暗号テキストを受け取るバッファーへのポインター。 See remarks for more information.
cbCipherText[in]
The size, in bytes, of the pbCipherText buffer.
pcbCipherText[out]
A pointer to a ULONG variable that the receives the number of bytes written to pbCipherText buffer.
If pbCipherText is NULL, this receives the size, in bytes, required for the KEM ciphertext.
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, pcbCipherText) 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 encapsulation key. *pcbSecretKey receives the number of bytes required for pbSecretKey, pcbCipherText receives the number of bytes required for pbCipherText. |
STATUS_BUFFER_TOO_SMALL |
An output buffer size (cbSecretKey, cbCipherText) is too small for the result encapsulation operation for the KEM parameters associated with the encapsulation key. pcbSecretKey receives the number of bytes required for pbSecretKey, pcbCipherText receives the number of bytes required for pbCipherText. |
Remarks
To query the required sizes of the pbSecretKey and pbCipherText buffers, callers may call BCryptEncapsulate with NULLpbSecretKey and pbCipherText. The required sizes will be returned in pcbSecretKey and pcbCipherText, respectively. このクエリは効率的であり、カプセル化を実行せずにサイズを返します。
Equivalently, use BCryptGetProperty to query the BCRYPT_KEM_SHARED_SECRET_LENGTH property of the algorithm or key handle, and the BCRYPT_KEM_CIPHERTEXT_LENGTH property of the key handle.
現在サポートされている KEM アルゴリズム (ML-KEM) の場合、共有シークレットの長さは特定のアルゴリズムの定数サイズであり、KEM 暗号テキストの長さは特定のパラメーター セットの定数サイズです。
Requirements
| Requirement | Value |
|---|---|
| サポートされる最小クライアント | Windows Insider (ビルド 27843): ML-KEM のサポートが開始されます。 [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows Insider (ビルド 27843): ML-KEM のサポートが開始されます。 [デスクトップ アプリのみ] |
| Library | Bcrypt.lib |
| DLL | Bcrypt.dll |