CryptDeriveKey 関数 (wincrypt.h)

  • [アーティクル]
重要 この API は非推奨です。 新規および既存のソフトウェアでは、Cryptography Next Generation API の使用を開始する必要があります。 Microsoft は、今後のリリースでこの API を削除する可能性があります。
 
CryptDeriveKey 関数は、基本データ値から派生 暗号化 セッション キーを生成します。 この関数は、同じ 暗号化サービス プロバイダー (CSP) とアルゴリズムを使用する場合、同じ基本データから生成されたキーが同じであることを保証します。 基本データには、パスワードまたはその他のユーザー データを指定できます。

この関数は、CryptGenKeyと同じですが、生成された セッション キー はランダムではなく、基本データから派生します。 CryptDeriveKey は、セッション キーの生成にのみ使用できます。 公開キーと秘密キーのペアを生成することはできません。

セッション キーへのハンドルは、phKey パラメーターで返されます。 このハンドルは、キー ハンドルを必要とする任意の CryptoAPI 関数で使用できます。

構文

BOOL CryptDeriveKey(
  [in]      HCRYPTPROV hProv,
  [in]      ALG_ID     Algid,
  [in]      HCRYPTHASH hBaseData,
  [in]      DWORD      dwFlags,
  [in, out] HCRYPTKEY  *phKey
);

パラメーター

[in] hProv

HCRYPTPROV、CryptAcquireContextの呼び出しによって作成された CSP のハンドルです。

[in] Algid

キーを生成する 対称暗号化 アルゴリズムを識別する ALG_ID 構造体。 使用可能なアルゴリズムは、CSP ごとに異なる可能性が最も高くなります。 キー スペックのAT_KEYEXCHANGEとAT_SIGNATUREに対してさまざまなプロバイダーによって使用されるアルゴリズム識別子の詳細については、ALG_IDを参照してください。

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

[in] hBaseData

正確な基本データをフィードした ハッシュ オブジェクト へのハンドル。

このハンドルを取得するには、アプリケーションで最初に CryptCreateHash ハッシュ オブジェクトを作成してから、CryptHashDataを持つハッシュ オブジェクトに基本データを追加する必要があります。 このプロセスの詳細については、ハッシュとデジタル署名のに関するページを参照してください。

[in] dwFlags

生成されるキーの種類を指定します。

セッション キーのサイズは、キーの生成時に設定できます。 キー サイズは、キーの剰余の長さをビット単位で表し、このパラメーターの上位 16 ビットで設定されます。 したがって、128 ビット RC4 セッション キーを生成する場合、0x00800000値は、ビットごとのまたは 演算で定義済みの値、他の dwFlags と組み合わされます。 エクスポート制御の制限の変更により、既定の CSP と既定の キーの長 は、オペレーティング システムのリリース間で変更される可能性があります。 暗号化と暗号化解除の両方で同じ CSP を使用し、dwFlags パラメーターを使用してキーの長さを明示的に設定して、異なるオペレーティング システム プラットフォームでの相互運用性を確保することが重要です。

このパラメーターの下位 16 ビットは 0 にすることも、ビットごとのOR 演算子を使用して次のフラグを組み合わせて指定することもできます。

価値 意味
CRYPT_CREATE_SALT
 通常、セッション キーが ハッシュ 値から作成された場合、残りのビットが多数存在します。 たとえば、ハッシュ値が 128 ビットで、セッション キーが 40 ビットの場合、88 ビットが残ります。

このフラグが設定されている場合、キーには、未使用のハッシュ値ビットに基づいて salt 値が割り当てられます。 dwParam パラメーターを KP_SALT に設定した CryptGetKeyParam 関数を使用して、この salt 値 を取得できます。

このフラグが設定されていない場合、キーには 0 の salt 値が指定されます。

(CryptExportKeyを使用して) 0 以外の salt 値を持つキーをエクスポートする場合は、salt 値も取得し、キー BLOBと共に保持する必要があります。
CRYPT_EXPORTABLE
 このフラグが設定されている場合、セッション キーは、CryptExportKey 関数を使用して CSP からキー BLOB に転送できます。 通常、キーはエクスポート可能である必要があるため、このフラグは通常設定する必要があります。

このフラグが設定されていない場合、セッション キーはエクスポートできません。 つまり、キーは現在のセッション内でのみ使用でき、キーを作成したアプリケーションのみがキーを使用できます。

このフラグは、公開キーと秘密キーのペアには適用されません。
CRYPT_NO_SALT
 このフラグは、40 ビット 対称キーに salt 値が割り当てられていないことを指定します。 詳細については、「Salt Value Functionality」を参照してください。
CRYPT_UPDATE_KEY
 一部の CSP は、複数のハッシュ値から派生したセッション キーを使用します。 この場合、CryptDeriveKey を複数回呼び出す必要があります。

このフラグが設定されている場合、新しいセッション キーは生成されません。 代わりに、phKey で指定 キーが変更されます。 このフラグの正確な動作は、生成されるキーの種類と、使用されている特定の CSP によって異なります。

Microsoft 暗号化サービス プロバイダーは、このフラグを無視します。
CRYPT_SERVER
1024 (0x400)
 このフラグは、Schannel プロバイダーでのみ使用されます。 このフラグが設定されている場合、生成されるキーはサーバー書き込みキーです。それ以外の場合は、クライアント書き込みキーです。

[in, out] phKey

HCRYPTKEY 変数へのポインター。新しく生成されたキーのハンドルのアドレスを受け取ります。 キーの使用が完了したら、CryptDestroyKey 関数を呼び出してハンドルを解放します。

戻り値

関数が成功した場合、関数は 0 以外 (TRUE) を返します。

関数が失敗した場合は、0 (FALSE) を返します。 拡張エラー情報については、GetLastError呼び出します。

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

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

備考

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

CryptDeriveKey 関数は、ハッシュを完了します。 CryptDeriveKey が呼び出された後、ハッシュにデータを追加することはできません。 CryptHashData または CryptHashSessionKey 追加の呼び出し 失敗します。 アプリケーションがハッシュで完了したら、CryptDestroyHash 呼び出してハッシュ オブジェクトを破棄する必要があります。

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

  • CSP がサポートするアルゴリズムを列挙し、各アルゴリズムの最大キー長と最小キー長を取得するには、PP_ENUMALGS_EXを使用して CryptGetProvParam 呼び出します。
  • 適切なキー長を選択するには、最小長と最大長を使用します。 パフォーマンスの問題につながる可能性があるため、最大長を選択することは必ずしもお勧めできません。
  • 目的のキー長を選択したら、dwFlags パラメーターの上位 16 ビットを使用して、キーの長さを指定します。
n 必要な派生キーの長さ (バイト単位) にします。 派生キーは、CryptDeriveKeyによってハッシュ計算が完了した後の、ハッシュ値の最初の n バイトです。 ハッシュが SHA-2 ファミリのメンバーではなく、必要なキーが 3DES または AES の場合、キーは次のように派生します。
  1. 定数を 64 回繰り返して 64 バイトのバッファー 0x36 形成します。 k hBaseDataの入力パラメーターで表されるハッシュ値 長くします。 バッファーの最初の k バイトを、バッファーの最初の k バイトの XOR 演算の結果に、hBaseData入力パラメーターで表されるハッシュ値に設定します。
  2. 定数を 64 回繰り返して 64 バイトのバッファー 0x5C 形成します。 バッファーの最初の k バイトを、バッファーの最初の k バイトの XOR 演算の結果に、hBaseData入力パラメーターで表されるハッシュ値に設定します。
  3. hBaseData パラメーターで表されるハッシュ値の計算に使用したのと同じハッシュ アルゴリズムを使用して、手順 1 の結果をハッシュします。
  4. hBaseData パラメーターで表されるハッシュ値の計算に使用したのと同じハッシュ アルゴリズムを使用して、手順 2 の結果をハッシュします。
  5. 手順 3 の結果と手順 4 の結果を連結します。
  6. 手順 5 の結果の最初の n バイトを派生キーとして使用します。
既定の RSA 完全暗号化サービス プロバイダーは、Microsoft RSA 強力な暗号化プロバイダーです。 暗号化サービス プロバイダー Diffie-Hellman 既定の DSS 署名は、Microsoft Enhanced DSS Diffie-Hellman 暗号化プロバイダーです。 これらの各 CSP には、RC2 と RC4 の既定の 128 ビット対称キー長があります。

次の表に、アルゴリズムとプロバイダーごとのセッション キーの最小、既定値、および最大キーの長さを示します。

供給者 アルゴリズム 最小キーの長さ 既定のキーの長さ キーの最大長
MS Base RC4 と RC2 40 40 56
MS Base DES 56 56 56
MS Enhanced RC4 と RC2 40 128 128
MS Enhanced DES 56 56 56
MS Enhanced 3DES 112 112 112 112
MS Enhanced 3DES 168 168 168
MS Strong RC4 と RC2 40 128 128
MS Strong DES 56 56 56
MS Strong 3DES 112 112 112 112
MS Strong 3DES 168 168 168
DSS/DH ベース RC4 と RC2 40 40 56
DSS/DH ベース Cylink MEK 40 40 40
DSS/DH ベース DES 56 56 56
DSS/DH Enh RC4 と RC2 40 128 128
DSS/DH Enh Cylink MEK 40 40 40
DSS/DH Enh DES 56 56 56
DSS/DH Enh 3DES 112 112 112 112
DSS/DH Enh 3DES 168 168 168
 

例

この関数を使用する例については、「例 C プログラム: パスワードからセッション キーを派生する」を参照してください。

必要条件

要件 価値
サポートされる最小クライアント Windows XP [デスクトップ アプリのみ]
サポートされる最小サーバー Windows Server 2003 [デスクトップ アプリのみ]
ターゲット プラットフォーム の ウィンドウズ
ヘッダー wincrypt.h
ライブラリ Advapi32.lib
DLL Advapi32.dll

関連項目

CryptAcquireContext

CryptCreateHash

CryptDestroyHash

CryptDestroyKey

CryptExportKey

CryptGenKey

CryptGetKeyParam

CryptHashData

CryptHashSessionKey

CryptSetKeyParam

キー生成と Exchange 関数の