注
一部の情報は、市販される前に大幅に変更される可能性があるプレリリース製品に関連しています。 Microsoft は、ここで提供される情報に関して明示的または黙示的な保証を行いません。 このトピックで説明する機能は、Windows Insider Previewのプレリリース バージョンで使用できます。
BCryptDecapsulate 関数は、キー カプセル化メカニズム (KEM) のカプセル化解除操作を実行します。 KEM 暗号テキストを受け取り、指定された秘密キーで暗号化を解除し、共有秘密キーを返します。
暗号テキストが正しく書式設定されていても、カプセル化解除キーと一致しない場合、この API は成功しますが、ランダムな共有秘密キーが生成されます。
構文
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
);
パラメーター
hKey[in]
KEM 暗号テキストのカプセル化解除に使用するキーのハンドル。 これは、KEM 暗号テキストの生成に使用される公開 (カプセル化) キーに対応する秘密 (カプセル化解除) キーである必要があります。 キー ハンドルは、 BCryptGenerateKeyPair や BCryptImportKeyPair などのいずれかのキー ペア作成関数から取得されます。
pbCipherText[in]
KEM 暗号テキストを含むバッファーへのポインター。 BCryptEncapsulate 関数を使用して、KEM 暗号テキストを作成できます。
cbCipherText[in]
pbCipherText バッファーのサイズ (バイト単位)。
pbSecretKey[out]
共有秘密鍵を受け取るバッファーへのポインター。 詳細については 、「解説」 を参照してください。
cbSecretKey[in]
pbSecretKey バッファーのサイズ (バイト単位)。
pcbSecretKey[out]
pbSecretKey バッファーに書き込まれたバイト数を受け取る ULONG 変数へのポインター。
pbSecretKey がNULLされている場合、共有秘密鍵に必要なサイズ (バイト単位) を受け取ります。
詳細については 、「解説」 を参照してください。
dwFlags[in]
予約済み、0 でなければなりません。
戻り値
関数の成功または失敗を示す状態コードを返します。
可能な戻りコードには、以下が含まれますが、これらに限定されません。
| リターン コード | 説明 |
|---|---|
STATUS_SUCCESS |
関数が成功しました。 |
STATUS_INVALID_PARAMETER |
1 つ以上の必須パラメーター (hKey、 pcbSecretKey、 pbCipherText) が NULLされているか、いずれかのパラメーターの値が無効です。 |
STATUS_INVALID_BUFFER_SIZE |
バッファー サイズ (cbSecretKey、 cbCipherText) が、カプセル化解除キーに関連付けられている KEM パラメーターの予想サイズと一致しません。 |
STATUS_BUFFER_TOO_SMALL |
出力バッファー サイズ (cbSecretKey) は、カプセル化解除キーに関連付けられている KEM パラメーターの結果のカプセル化解除操作には小さすぎます。 pcbSecretKey は 、pbSecretKey に必要なバイト数を受け取ります。 |
注釈
KEM 共有秘密鍵に必要な pbSecretKey バッファーの必要なサイズを照会するには、NULLpbSecretKey を使用して BCryptDecapsulate を呼び出します。 必要なサイズは pcbSecretKey で返されます。 このクエリは効率的であり、カプセル化解除を実行せずにサイズを返します。
同様に、 BCryptGetProperty を使用して、アルゴリズムまたはキー ハンドルの BCRYPT_KEM_SHARED_SECRET_LENGTH プロパティに対してクエリを実行します。
現在サポートされている KEM アルゴリズム (ML-KEM) の場合、共有シークレットの長さは特定のアルゴリズムの定数サイズです。
付言
無効だが、正しいサイズの暗号テキストが指定された場合、ML-KEM のカプセル化解除操作では、擬似ランダム共有秘密鍵の出力を使用して、有効なカプセル化解除操作に等しい時間で成功を返すことによって、暗号テキストが 暗黙的に拒否 されます。 これにより、ピアの対称キーが一致しない場合、上位レベルのプロトコルは後で失敗します。 そのため、カプセル化解除は、プログラミング エラー (つまり、サイズが正しくない、初期化されていない hKey の使用) がある場合、または環境に根本的に問題がある (つまり、内部メモリの割り当てが失敗するか、内部整合性テストでハードウェア エラーが検出された) 場合にのみ失敗します。
要求事項
| 要件 | 価値 |
|---|---|
| サポートされる最小クライアント | Windows Insiders プレビュー [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows Insiders プレビュー [デスクトップ アプリのみ] |
| 図書館 | Bcrypt.lib |
| DLL | Bcrypt.dll |