CryptGenKey 関数 (wincrypt.h)

重要 この 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

関連項目

CryptAcquireContext

CryptDestroyKey

CryptExportKey

CryptGetKeyParam

CryptImportKey

CryptSetKeyParam

キー生成と Exchange 関数の

暗号化サービス プロバイダーの に関するスレッドの問題を する