CryptGenKey 関数 (wincrypt.h)

[アーティクル]
07/16/2024

重要この API は非推奨です。新規および既存のソフトウェアでは、Cryptography Next Generation API の使用を開始する必要があります。 Microsoft は、今後のリリースでこの API を削除する可能性があります。

CryptGenKey 関数は、ランダムな暗号化セッションキーまたは公開キーと秘密キーのペアを生成します。キーまたはキーペアのハンドルが phKey返されます。このハンドルは、キーハンドルを必要とする CryptoAPI 関数で必要に応じて使用できます。

呼び出し元のアプリケーションは、この関数を呼び出すときにアルゴリズムを指定する必要があります。このアルゴリズムの種類はキーにバンドルされたままであるため、実際の暗号化操作が実行されるときに、後でアルゴリズムを指定する必要はありません。

構文

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 基本暗号化プロバイダーで使用する ALG_ID 値については、「基本プロバイダーアルゴリズムの」を参照してください。

Microsoft Strong Cryptographic Provider または Microsoft Enhanced Cryptographic Provider で使用する ALG_ID 値については、「拡張プロバイダーアルゴリズムの」を参照してください。

Diffie-Hellman CSP の場合は、次のいずれかの値を使用します。

価値	意味
CALG_DH_EPHEM	"エフェメラル" Diffie-Hellman キーを指定します。
CALG_DH_SF	"ストアアンドフォワード" Diffie-Hellman キーを指定します。

この関数は、対称アルゴリズムのセッションキーを生成するだけでなく、公開キーと秘密キーのペアを生成することもできます。各 CryptoAPI クライアントは、通常、2 つの公開キーと秘密キーのペアを持っています。これらのキーペアのいずれかを生成するには、Algid パラメーターを次のいずれかの値に設定します。

価値	意味
AT_KEYEXCHANGE	キー交換
AT_SIGNATURE	デジタル署名

注キーの仕様AT_KEYEXCHANGEとAT_SIGNATUREが指定されている場合、キーの生成に使用されるアルゴリズム識別子は、使用されるプロバイダーによって異なります。その結果、これらのキー仕様では、CryptGetKeyParam (KP_ALGID パラメーターが指定されている場合) から返される値は、使用されるプロバイダーによって異なります。キースペックのAT_KEYEXCHANGEとAT_SIGNATUREに対して異なるプロバイダーによって使用されるアルゴリズム識別子を特定するには、ALG_IDを参照してください。

[in] dwFlags

生成されるキーの種類を指定します。セッションキー、RSA 署名キー、および RSA キー交換キーのサイズは、キーの生成時に設定できます。キーサイズは、キーの剰余の長さをビット単位で表し、このパラメーターの上位 16 ビットで設定されます。したがって、2,048 ビット RSA 署名キーを生成する場合、0x08000000値は、ビットごとのまたは演算で定義済みの値他の dwFlags と組み合わされます。 0x08000000の上位 16 ビットは0x0800、つまり 10 進数の 2,048 です。 RSA1024BIT_KEY 値を使用して、1024 ビット RSA キーを指定できます。

エクスポート制御の制限の変更により、既定の 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 つ以上の組み合わせにすることができます。

価値	意味
CRYPT_ARCHIVABLE	このフラグが設定されている場合、CryptDestroyKey呼び出しによってハンドルが閉じられるまで、キーをエクスポートできます。これにより、アーカイブまたはキーの回復のために、新しく生成されたキーを作成時にエクスポートできます。ハンドルを閉じると、キーはエクスポートできなくなります。
CRYPT_CREATE_IV	このフラグは使用されません。
CRYPT_CREATE_SALT	このフラグが設定されている場合、キーにはランダムな salt 値自動的に割り当てられます。 dwParam パラメーターを KP_SALT に設定した CryptGetKeyParam 関数を使用して、この salt 値を取得できます。このフラグが設定されていない場合、キーには 0 の salt 値が指定されます。 (CryptExportKeyを使用して) 0 以外のソルト値を持つキーをエクスポートする場合は、の salt 値も取得し、キー BLOBと共に保持する必要があります。
CRYPT_DATA_KEY	このフラグは使用されません。
CRYPT_EXPORTABLE	このフラグが設定されている場合、CryptExportKey 関数を使用して、キーを CSP からキー BLOB に転送できます。通常、セッションキーはエクスポート可能である必要があるため、このフラグは通常、作成時に設定する必要があります。このフラグが設定されていない場合、キーはエクスポートできません。セッションキーの場合、これは、キーが現在のセッション内でのみ使用でき、キーを作成したアプリケーションのみが使用できることを意味します。公開キーと秘密キーのペアが場合、これは秘密キーを転送またはバックアップできないことを意味します。このフラグは、セッションキーと秘密キー BLOBにのみ適用されます。常にエクスポート可能な公開キーには適用されません。
CRYPT_FORCE_KEY_PROTECTION_HIGH	このフラグは、強力なキー保護を指定します。このフラグを設定すると、ユーザーはキーの作成時にキーのパスワードを入力するように求められます。ユーザーは、このキーが使用されるたびにパスワードの入力を求められます。このフラグは、Microsoft によって提供される CSP によってのみ使用されます。サードパーティ CSP は、強力なキー保護のために独自の動作を定義します。このフラグを指定すると、システムレジストリで強力なキー保護が指定されている場合、CRYPT_USER_PROTECTED フラグを使用してこの関数を呼び出す場合と同じ結果になります。このフラグを指定し、hProv パラメーターのプロバイダーハンドルが CRYPT_VERIFYCONTEXT または CRYPT_SILENT フラグを使用して作成された場合、この関数は最後のエラーを NTE_SILENT_CONTEXT に設定し、ゼロを返します。 Windows Server 2003 および Windows XP: このフラグはサポートされていません。
CRYPT_KEK	このフラグは使用されません。
CRYPT_INITIATOR	このフラグは使用されません。
CRYPT_NO_SALT	このフラグは、40 ビット対称キーに割り当てられる salt 値がないことを指定します。詳細については、「Salt Value Functionality」を参照してください。
CRYPT_ONLINE	このフラグは使用されません。
CRYPT_PREGEN	このフラグは、初期 Diffie-Hellman または DSS キー生成を指定します。このフラグは、Diffie-Hellman CSP と DSS CSP でのみ役立ちます。使用すると、dwFlags パラメーターの上位 16 ビットでキー長が指定されていない限り、既定のキー長が使用されます。 CryptSetKeyParamを使用して PREGEN Diffie-Hellman または DSS キーにキーの長さを含むパラメーターを設定する場合、キーの長さはここで設定したキーの長さと互換性がある必要があります。
CRYPT_RECIPIENT	このフラグは使用されません。
CRYPT_SF	このフラグは使用されません。
CRYPT_SGCKEY	このフラグは使用されません。
CRYPT_USER_PROTECTED	このフラグを設定すると、特定のアクションがこのキーを使用しようとしたときに、ダイアログボックスまたは別のメソッドを通じてユーザーに通知されます。正確な動作は、使用されている CSP によって指定されます。プロバイダーコンテキストが CRYPT_SILENT フラグを設定して開かれた場合、このフラグを使用するとエラーが発生し、最後のエラーがNTE_SILENT_CONTEXTに設定されます。
CRYPT_VOLATILE	このフラグは使用されません。

[out] phKey

関数が新しく生成されたキーのハンドルをコピーするアドレス。キーの使用が完了したら、CryptDestroyKey 関数を呼び出して、キーへのハンドルを削除します。

戻り値

成功した場合は 0 以外、それ以外の場合は 0 を返します。

拡張エラー情報については、GetLastError呼び出します。

"NTE" で開始されるエラーコードは、使用されている特定の CSP によって生成されます。考えられるエラーコードを次の表に示します。

リターンコード	形容
ERROR_INVALID_HANDLE	パラメーターの 1 つは無効なハンドルを指定します。
ERROR_INVALID_PARAMETER	パラメーターの 1 つに無効な値が含まれています。これは、多くの場合、無効なポインターです。
NTE_BAD_ALGID	Algid パラメーターは、この CSP がサポートしていないアルゴリズムを指定します。
NTE_BAD_FLAGS	dwFlags パラメーターに無効な値が含まれています。
NTE_BAD_UID	hProv パラメーターに有効なコンテキストハンドルが含まれていません。
NTE_FAIL	予期しない方法で関数が失敗しました。
NTE_SILENT_CONTEXT	コンテキストがサイレントとして取得されたため、プロバイダーはアクションを実行できませんでした。

備考

対称ブロック暗号に対してキーが生成された場合、キーは既定で、初期化ベクトルが 0 の暗号ブロックチェーン (CBC) モード設定されます。この暗号モードは、データを一括暗号化するための適切な既定の方法を提供します。これらのパラメーターを変更するには、CryptSetKeyParam 関数を使用します。

適切なキー長を選択するには、次の方法をお勧めします。

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

次の方法で共有

CryptGenKey 関数 (wincrypt.h)

構文

パラメーター

戻り値

備考

例

必要条件

関連項目

フィードバック

フィードバック

その他のリソース