CryptGenKey 関数 (wincrypt.h)
呼び出し元のアプリケーションは、この関数を呼び出すときにアルゴリズムを指定する必要があります。 このアルゴリズムの種類はキーにバンドルされたままであるため、実際の暗号化操作が実行されるときに、後でアルゴリズムを指定する必要はありません。
構文
BOOL CryptGenKey(
[in] HCRYPTPROV hProv,
[in] ALG_ID Algid,
[in] DWORD dwFlags,
[out] HCRYPTKEY *phKey
);
パラメーター
[in] hProv
CryptAcquireContextの呼び出しによって作成された 暗号化サービス プロバイダー (CSP) へのハンドル。
[in] Algid
キーを生成するアルゴリズムを識別する ALG_ID 値。 このパラメーターの値は、使用される CSP によって異なります。
Microsoft 基本暗号化プロバイダーで使用する
Microsoft Strong Cryptographic Provider または Microsoft Enhanced Cryptographic Provider で使用する
Diffie-Hellman CSP の場合は、次のいずれかの値を使用します。
| 価値 | 意味 |
|---|---|
|
"エフェメラル" Diffie-Hellman キーを指定します。 |
|
"ストアアンドフォワード" Diffie-Hellman キーを指定します。 |
この関数は、
| 価値 | 意味 |
|---|---|
|
キー交換 |
|
デジタル署名 |
[in] dwFlags
生成されるキーの種類を指定します。 セッション キー、RSA 署名キー、および RSA キー 交換キー のサイズは、キーの生成時に設定できます。 キー サイズは、キーの剰余の長さをビット単位で表し、このパラメーターの上位 16 ビットで設定されます。 したがって、2,048 ビット RSA 署名キーを生成する場合、0x08000000値は、ビットごとの
エクスポート制御の制限の変更により、既定の CSP と既定の キーの長 は、オペレーティング システムのバージョン間で変更される可能性があります。 暗号化と暗号化解除の両方で同じ CSP を使用し、dwFlags パラメーターを使用してキーの長さを明示的に設定して、異なるオペレーティング システム プラットフォームでの相互運用性を確保することが重要です。
特に、既定の RSA 完全暗号化サービス プロバイダーは、Microsoft RSA 強力な暗号化プロバイダーです。 暗号化サービス プロバイダー Diffie-Hellman 既定の DSS 署名は、Microsoft Enhanced DSS Diffie-Hellman 暗号化プロバイダーです。 これらの各 CSP には、RC2 と RC4 の既定の 128 ビット対称キー長と、公開キー アルゴリズムの 1,024 ビットの既定のキー長があります。
上位 16 ビットが 0 の場合、既定のキー サイズが生成されます。 最大値より大きいキーまたは最小値より小さいキーが指定されている場合、呼び出しはERROR_INVALID_PARAMETERコードで失敗します。
次の表に、Windows XP 以降の署名と交換キーの最小、既定値、および最大長を示します。
| キーの種類とプロバイダー | 最小長 | 既定の長さ | 最大長 |
|---|---|---|---|
|
RSA ベース プロバイダー Signature と ExchangeKeys |
384 | 512 | 16,384 |
|
RSA の強力なプロバイダーと強化されたプロバイダー 署名キーと Exchange キー |
384 | 1,024 | 16,384 |
|
DSS ベース プロバイダー 署名キー |
512 | 1,024 | 1,024 |
|
DSS ベース プロバイダー Exchange キー |
該当なし | 該当なし | 該当なし |
|
DSS/DH ベース プロバイダー 署名キー |
512 | 1,024 | 1,024 |
|
DSS/DH ベース プロバイダー Exchange キー |
512 | 512 | 1,024 |
|
DSS/DH 拡張プロバイダー 署名キー |
512 | 1,024 | 1,024 |
|
DSS/DH 拡張プロバイダー Exchange キー |
512 | 1,024 | 4,096 |
セッション キーの長さについては、CryptDeriveKeyを参照してください。
Microsoft プロバイダーを使用して生成されるキーの詳細については、「Microsoft Cryptographic Service Providers」を参照してください。
このパラメーターの下位 16 ビットは、0 または次の値の 1 つ以上の組み合わせにすることができます。
| 価値 | 意味 |
|---|---|
|
このフラグが設定されている場合、CryptDestroyKey |
|
このフラグは使用されません。 |
|
このフラグが設定されている場合、キーにはランダムな salt 値 自動的に割り当てられます。
dwParam パラメーターを KP_SALT に設定した CryptGetKeyParam 関数を使用して、この salt 値を取得できます。
このフラグが設定されていない場合、キーには 0 の salt 値が指定されます。 (CryptExportKeyを使用して) 0 以外のソルト値を持つキーをエクスポートする場合は、の salt 値 も取得し、キー BLOBと共に保持する必要があります。 |
|
このフラグは使用されません。 |
|
このフラグが設定されている場合、CryptExportKey 関数を使用して、キーを CSP からキー BLOB に転送できます。 通常、セッション キーはエクスポート可能である必要があるため、このフラグは通常、作成時に設定する必要があります。
このフラグが設定されていない場合、キーはエクスポートできません。 セッション キーの場合、これは、キーが現在のセッション内でのみ使用でき、キーを作成したアプリケーションのみが使用できることを意味します。 公開キーと秘密キーのペアが場合、これは秘密キーを転送またはバックアップできないことを意味します。 このフラグは、セッション キーと 秘密キー BLOBにのみ適用されます。 常にエクスポート可能な公開キーには適用されません。 |
|
このフラグは、強力なキー保護を指定します。 このフラグを設定すると、ユーザーはキーの作成時にキーのパスワードを入力するように求められます。 ユーザーは、このキーが使用されるたびにパスワードの入力を求められます。
このフラグは、Microsoft によって提供される CSP によってのみ使用されます。 サード パーティ CSP は、強力なキー保護のために独自の動作を定義します。 このフラグを指定すると、システム レジストリで強力なキー保護が指定されている場合、CRYPT_USER_PROTECTED フラグを使用してこの関数を呼び出す場合と同じ結果になります。 このフラグを指定し、hProv パラメーターのプロバイダー ハンドルが CRYPT_VERIFYCONTEXT または CRYPT_SILENT フラグを使用して作成された場合、この関数は最後のエラーを NTE_SILENT_CONTEXT に設定し、ゼロを返します。 Windows Server 2003 および Windows XP: このフラグはサポートされていません。 |
|
このフラグは使用されません。 |
|
このフラグは使用されません。 |
|
このフラグは、40 ビット |
|
このフラグは使用されません。 |
|
このフラグは、初期 Diffie-Hellman または DSS キー生成を指定します。 このフラグは、Diffie-Hellman CSP と DSS CSP でのみ役立ちます。 使用すると、dwFlags パラメーターの上位 16 ビットでキー長が指定されていない限り、既定のキー長が使用されます。 CryptSetKeyParamを使用して PREGEN Diffie-Hellman または DSS キーにキーの長さを含むパラメーターを設定する場合、キーの長さはここで設定したキーの長さと互換性がある必要があります。 |
|
このフラグは使用されません。 |
|
このフラグは使用されません。 |
|
このフラグは使用されません。 |
|
このフラグを設定すると、特定のアクションがこのキーを使用しようとしたときに、ダイアログ ボックスまたは別のメソッドを通じてユーザーに通知されます。 正確な動作は、使用されている CSP によって指定されます。 プロバイダー コンテキストが CRYPT_SILENT フラグを設定して開かれた場合、このフラグを使用するとエラーが発生し、最後のエラーがNTE_SILENT_CONTEXTに設定されます。 |
|
このフラグは使用されません。 |
[out] phKey
関数が新しく生成されたキーのハンドルをコピーするアドレス。 キーの使用が完了したら、CryptDestroyKey 関数を呼び出して、キーへのハンドルを削除します。
戻り値
成功した場合は 0 以外、それ以外の場合は 0 を返します。
拡張エラー情報については、GetLastError
"NTE" で開始されるエラー コードは、使用されている特定の CSP によって生成されます。 考えられるエラー コードを次の表に示します。
| リターン コード | 形容 |
|---|---|
|
パラメーターの 1 つは無効なハンドルを指定します。 |
|
パラメーターの 1 つに無効な値が含まれています。 これは、多くの場合、無効なポインターです。 |
|
Algid パラメーターは、この CSP がサポートしていないアルゴリズムを指定します。 |
|
dwFlags パラメーターに無効な値が含まれています。 |
|
hProv パラメーターに有効なコンテキスト ハンドルが含まれていません。 |
|
予期しない方法で関数が失敗しました。 |
|
コンテキストがサイレントとして取得されたため、プロバイダーはアクションを実行できませんでした。 |
備考
- CSP がサポートするアルゴリズムを列挙し、各アルゴリズムの最大キー長と最小キー長を取得します。 これを行うには、PP_ENUMALGS_EX CryptGetProvParam を呼び出します。
- 適切なキー長を選択するには、最小長と最大長を使用します。 パフォーマンスの問題につながる可能性があるため、最大長を選択することは必ずしもお勧めできません。
- 目的のキー長を選択したら、dwFlags パラメーターの上位 16 ビットを使用して、キーの長さを指定します。
例
次の例は、ランダム なセッション キーの作成を示しています。 この例の完全なコンテキストを含む例については、「サンプル C プログラム: ファイルの暗号化」を参照してください。 この関数を使用する別の例については、「サンプル C プログラム: ファイルの復号化」を参照してください。
//-------------------------------------------------------------------
// Declare the handle to the key.
HCRYPTKEY hKey;
//-------------------------------------------------------------------
// This example assumes that a cryptographic context
// has been acquired, and that it is stored in hCryptProv.
//---------------------------------------------------------------
// Create a random session key.
if(CryptGenKey(
hCryptProv,
ENCRYPT_ALGORITHM,
KEYLENGTH | CRYPT_EXPORTABLE,
&hKey))
{
printf("A session key has been created.\n");
}
else
{
printf("Error during CryptGenKey.\n");
exit(1);
}
//-------------------------------------------------------------------
// The key created can be exported into a key BLOB that can be
// written to a file.
// ...
// When you have finished using the key, free the resource.
if (!CryptDestroyKey(hKey))
{
printf("Error during CryptDestroyKey.\n");
exit(1);
}
必要条件
| 要件 | 価値 |
|---|---|
| サポートされる最小クライアント | Windows XP [デスクトップ アプリのみ] |
| サポートされる最小サーバー | Windows Server 2003 [デスクトップ アプリのみ] |
| ターゲット プラットフォーム の |
ウィンドウズ |
| ヘッダー | wincrypt.h |
| ライブラリ | Advapi32.lib |
| DLL | Advapi32.dll |
関連項目
暗号化サービス プロバイダーの に関するスレッドの問題を