CryptSetKeyParam 関数 (wincrypt.h)
Microsoft Base Cryptographic Provider は、キー交換キーまたは署名キーの値の設定を許可していません。ただし、カスタム プロバイダーでは、キーに設定できる値を定義できます。
構文
BOOL CryptSetKeyParam(
[in] HCRYPTKEY hKey,
[in] DWORD dwParam,
[in] const BYTE *pbData,
[in] DWORD dwFlags
);
パラメーター
[in] hKey
値を設定するキーへのハンドル。
[in] dwParam
次の表には、使用できる定義済みの値が含まれています。
すべてのキーの種類に対して、このパラメーターには次のいずれかの値を含めることができます。
| 値 | 意味 |
|---|---|
|
pbData は 適切な ALG_IDを指します。 これは、Microsoft Base Digital Signature Standard (DSS)、Diffie-Hellman 暗号化プロバイダー、または互換性のある CSP とセッション キーを交換するときに使用されます。 キーが CryptImportKey 関数と合意されると、セッション キーはアルゴリズムの種類を設定して使用できるようになります。 |
|
pbData は、Distinguished Encoding Rules (DER) を使用してエンコードされた X.509 証明書を含むバッファーのアドレスです。 証明書の公開キーは、対応する署名または交換キーと一致する必要があります。 |
|
pbData は、0 個以上のアクセス許可フラグを指定する DWORD 値を指します。 これらのフラグの詳細については、「 CryptGetKeyParam」を参照してください。 |
|
pbData は、セッション キーの一部となる新しい salt 値を指定する BYTE 配列を指します。 salt 値のサイズは、使用されている CSP によって異なります。 この値を設定する前に、 CryptGetKeyParam 関数を呼び出して salt 値のサイズを決定します。 Salt 値は、セッション キーをより一意にするために使用され、ディクショナリ攻撃がより困難になります。 Microsoft Base Cryptographic Provider の既定では、salt 値は 0 です。 |
|
pbData は、塩を含む CRYPT_INTEGER_BLOB 構造体を指します。 詳細については、「 Salt Value の指定」を参照してください。 |
デジタル 署名標準 (DSS) キーが hKey パラメーターで指定されている場合は、 dwParam 値を次のいずれかの値に設定することもできます。
| 値 | 意味 |
|---|---|
|
pbData は、DSS キー BLOB からジェネレーター G を指します。 データは CRYPT_INTEGER_BLOB 構造体の形式で、 ここで pbData メンバーは値、 cbData メンバーは値の長さです。 この値は、ヘッダー情報がなく、 リトル エンディアン 形式で想定されています。 |
|
pbData は、DSS キー BLOB の素数 P を指します。 データは、 CRYPT_INTEGER_BLOB 構造の形式です。 pbData メンバーは値、cbData メンバーは値の長さです。 この値は、ヘッダー情報がなく、 リトル エンディアン 形式で想定されています。 |
|
pbData は、DSS キー BLOB の素数 Q を指します。 データは、pbData メンバーが値であるCRYPT_INTEGER_BLOB構造体の形式で、cbData メンバーは値の長さです。 この値は、ヘッダー情報がなく、 リトル エンディアン 形式で想定されています。 |
|
P、Q、G の値を設定した後、dwParam のKP_X値と pbData パラメーターの NULL を指定する呼び出しを CryptSetKeyParam 関数に対して行うことができます。 これにより、X と Y の値が生成されます。 |
Diffie-Hellman アルゴリズムまたはデジタル署名アルゴリズム (DSA) キーが hKey で指定されている場合は、dwParam 値を次のいずれかの値に設定することもできます。
| 値 | 意味 |
|---|---|
|
インポートされた Diffie-Hellman キーの情報を設定します。 pbData パラメーターは、設定するキー情報を含むCMS_DH_KEY_INFO構造体のアドレスです。 |
|
DSS キーまたは Diffie-Hellman キーのパブリック パラメーター (P、Q、G など) を設定します。 このキーのキー ハンドルは、CRYPT_PREGEN フラグで生成された PREGEN 状態である必要があります。 pbData パラメーターは、この構造体内のデータがDHPUBKEY_VER3またはDSSPUBKEY_VER3 BLOB であるDATA_BLOB構造体へのポインターである必要があります。 関数は、この CRYPT_INTEGER_BLOB 構造体からキー ハンドルにパブリック パラメーターをコピーします。 この呼び出しが行われた後、KP_X パラメーター値を CryptSetKeyParam と共に使用して、実際の秘密キーを作成する必要があります。 KP_PUB_PARAMS パラメーターは、パラメーター値がKP_P、KP_Q、KP_Gを持つ複数の呼び出しではなく、1 つの呼び出しとして使用されます。 |
ブロック 暗号セッション キー が hKey パラメーターで指定されている場合は、 dwParam 値を次のいずれかの値に設定することもできます。
| 値 | 意味 |
|---|---|
|
この値型は RC2 キーでのみ使用でき、Windows 2000 より前の Microsoft Enhanced Cryptographic Provider で CryptSetKeyParam 関数が実装されているため、追加されています。 前の実装では、拡張プロバイダーの RC2 キーは 128 ビットの強度でしたが、キーをキー テーブルに拡張するために使用される有効なキーの長さは 40 ビットのみでした。 これにより、アルゴリズムの強度が 40 ビットに低下しました。 下位互換性を維持するために、前の実装はそのまま残ります。 ただし、 CryptSetKeyParam 呼び出しで KP_EFFECTIVE_KEYLENを使用することで、有効なキー長を 40 ビットを超える値に設定できます。 有効なキー長は、有効なキー長の値を持つ DWORD 値へのポインターとして pbData パラメーターに渡されます。 Microsoft Base Cryptographic Provider の有効キーの最小長は 1 で、最大は 40 です。 Microsoft 拡張暗号化プロバイダーでは、最小値は 1 で、最大値は 1,024 です。 キーを使用して暗号化または暗号化解除する前に、キーの長さを設定する必要があります。 |
|
許可されるトランスポート 層セキュリティ (TLS) の最も高いバージョンを設定します。 このプロパティは、SSL キーと TLS キーにのみ適用されます。 pbData パラメーターは、サポートされている TLS バージョン番号が最も大きい DWORD 変数のアドレスです。 |
|
pbData は 、初期化ベクトルを指定する BYTE 配列を指します。 この配列には BlockLength/8 要素が含まれている必要があります。 たとえば、ブロック長が 64 ビットの場合、初期化ベクトルは 8 バイトで構成されます。
Microsoft Base Cryptographic Provider の既定では、初期化ベクトルは 0 に設定されます。 |
|
Data Encryption Standard (DES) キーのキー値を設定します。 pbData パラメーターは、キーを含むバッファーのアドレスです。 このバッファーは、キーと同じ長さである必要があります。 このプロパティは DES キーにのみ適用されます。 |
|
埋め込みモードを設定します。 pbData パラメーターは、暗号で使用される埋め込みメソッドを識別する数値識別子を受け取る DWORD 値へのポインターです。 これには、次のいずれかの値を指定できます。 |
|
pbData は、使用する暗号モードを指定する DWORD 値を指します。 定義された暗号モードの一覧については、「 CryptGetKeyParam」を参照してください。 暗号化モードは、Microsoft 基本暗号化プロバイダーの既定でCRYPT_MODE_CBCに設定されています。 |
|
pbData は DWORD 値を指し、 出力フィードバック (OFB) または 暗号フィードバック (CFB) 暗号モードを使用した場合に 1 サイクルに処理されるビット数を示します。 Microsoft Base Cryptographic Provider の場合、サイクルごとに処理されるビット数は既定で 8 に設定されています。 |
hKey パラメーターに RSA キーが指定されている場合、dwParam パラメーターの値は次の値になります。
| 値 | 意味 |
|---|---|
|
キーの最適非対称暗号化パディング (OAEP) (PKCS #1 バージョン 2) パラメーターを設定します。 pbData パラメーターは、OAEP ラベルを含むCRYPT_DATA_BLOB構造体のアドレスです。 このプロパティは RSA キーにのみ適用されます。 |
次の値は使用されないことに注意してください。
- KP_ADMIN_PIN
- KP_CMS_KEY_INFO
- KP_INFO
- KP_KEYEXCHANGE_PIN
- KP_PRECOMP_MD5
- KP_PRECOMP_SHA
- KP_PREHASH
- KP_PUB_EX_LEN
- KP_PUB_EX_VAL
- KP_RA
- KP_RB
- KP_ROUNDS
- KP_RP
- KP_SIGNATURE_PIN
- KP_Y
[in] pbData
CryptSetKeyParam を呼び出す前に設定する値で初期化されたバッファーへのポインター。 このデータの形式は、 dwParam の値によって異なります。
[in] dwFlags
dwParam がKP_ALGIDされている場合にのみ使用されます。 dwFlags パラメーターは、有効なキーのフラグ値を渡すために使用されます。 dwFlags パラメーターは、CryptGenKey を使用して同じ種類のキーを生成するときに許可されるキー サイズやその他のフラグ値などの値を保持できます。 許容されるフラグ値の詳細については、「 CryptGenKey」を参照してください。
戻り値
関数が成功した場合、戻り値は 0 以外 (TRUE) になります。
関数が失敗した場合、戻り値は 0 (FALSE) になります。 拡張エラー情報については、 GetLastError を呼び出します。
"NTE" の前にあるエラー コードは、使用されている特定の CSP によって生成されます。 考えられるエラー コードの一部を次に示します。
| リターン コード | 説明 |
|---|---|
|
現在、CSP コンテキストは別の プロセスで使用されています。 |
|
パラメーターの 1 つは、無効なハンドルを指定します。 |
|
パラメーターの 1 つに無効な値が含まれています。 これは、ほとんどの場合、無効なポインターです。 |
|
dwFlags パラメーターが 0 以外であるか、pbData バッファーに無効な値が含まれています。 |
|
dwParam パラメーターは、不明なパラメーターを指定します。 |
|
hKey キーの作成時に指定された CSP コンテキストが見つかりません。 |
|
関数が予期しない方法で失敗しました。 |
|
一部の CSP には、P、Q、G の値がハードコーディングされています。 この場合、 dwParam の値に対して KP_P、KP_Q、KP_Gを使用すると、このエラーが発生します。 |
注釈
KP_Q、KP_P、またはKP_Xパラメーターが PREGEN Diffie-Hellman または DSS キーに設定されている場合、キーの長さは、CryptGenKey を使用してキーが作成されたときに dwFlags パラメーターの上位 16 ビットを使用して設定されたキー長と互換性がある必要があります。 CryptGenKey にキー長が設定されていない場合は、既定のキー長が使用されました。 既定以外のキー長を使用して P、Q、または X を設定すると、エラーが発生します。
例
この関数を使用する例については、「 C プログラムの例: セッション キーの複製」を参照してください。 この関数を使用するその他のコードについては、「 サンプル C プログラム: セッション キー パラメーターの設定と取得 」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows XP (デスクトップ アプリのみ) |
| サポートされている最小のサーバー | Windows Server 2003 (デスクトップ アプリのみ) |
| 対象プラットフォーム | Windows |
| ヘッダー | wincrypt.h |
| Library | Advapi32.lib |
| [DLL] | Advapi32.dll |
こちらもご覧ください
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示