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