CryptGenKey 関数 (wincrypt.h)

[アーティクル]
08/27/2023

大事な この 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値は、ビットごとの OR 演算を使用して定義済みの値を他の dwFlags と組み合わせて使用されます。 0x08000000の上位 16 ビットは0x0800、つまり 10 進数の 2,048 です。 RSA1024BIT_KEY値を使用して、1024 ビット RSA キーを指定できます。

エクスポート制御の制限が変更されたため、既定の CSP と既定のキーの長さは、オペレーティングシステムのバージョン間で変更される可能性があります。暗号化と暗号化解除の両方で同じ CSP を使用し、 dwFlags パラメーターを使用してキーの長さを明示的に設定して、異なるオペレーティングシステムプラットフォームでの相互運用性を確保することが重要です。

特に、既定の RSA 完全暗号化サービスプロバイダーは、Microsoft RSA Strong Cryptographic Provider です。既定の DSS 署名 Diffie-Hellman 暗号化サービスプロバイダーは、Microsoft Enhanced DSS Diffie-Hellman Cryptographic Provider です。これらの各 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 関数を使用します。このフラグが設定されていない場合、キーには 0 の salt 値が指定されます。 0 以外の salt 値を持つキーをエクスポートする場合 ( CryptExportKey を使用)、 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 に設定し、0 を返します。 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 および 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 (デスクトップアプリのみ)
対象プラットフォーム	Windows
ヘッダー	wincrypt.h
Library	Advapi32.lib
[DLL]	Advapi32.dll