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

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

[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値は、ビットごとの OR 演算を使用して定義済みの値を他の dwFlags と組み合わされます。 エクスポート制御の制限の変更により、オペレーティング システムのリリース間で既定の CSP と既定の キーの長さが 変更される可能性があります。 暗号化と暗号化解除の両方で同じ CSP を使用し、 dwFlags パラメーターを使用してキーの長さを明示的に設定して、異なるオペレーティング システム プラットフォームでの相互運用性を確保することが重要です。

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

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

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

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

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

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

このフラグは 、公開キーと秘密キーのペアには適用されません。
CRYPT_NO_SALT
 このフラグは、40 ビット対称キーに対してソルト値が割り当てられていないことを指定します。 詳細については、「 Salt Value の機能」を参照してください。
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 バイトを、入力パラメーター hBaseData で表されるハッシュ値を持つバッファーの最初の k バイトの XOR 操作の結果に設定します。
  2. 定数を 64 回繰り返して 64 バイト のバッファー 0x5C 形成します。 バッファーの最初の k バイトを、入力パラメーター hBaseData で表されるハッシュ値を持つバッファーの最初の k バイトの XOR 操作の結果に設定します。
  3. hBaseData パラメーターで表されるハッシュ値の計算に使用したのと同じハッシュ アルゴリズムを使用して、手順 1 の結果をハッシュします。
  4. hBaseData パラメーターで表されるハッシュ値の計算に使用したのと同じハッシュ アルゴリズムを使用して、手順 2 の結果をハッシュします。
  5. 手順 3 の結果と手順 4 の結果を連結します。
  6. 手順 5 の結果の最初の n バイトを派生キーとして使用します。
既定の RSA 完全暗号化サービス プロバイダーは、Microsoft RSA Strong Cryptographic Provider です。 既定の DSS Signature Diffie-Hellman Cryptographic Service Provider は、Microsoft Enhanced DSS Diffie-Hellman Cryptographic Provider です。 これらの CSP にはそれぞれ、 RC2 と RC4 の既定の 128 ビット対称キー長があります。

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

プロバイダー アルゴリズム キーの最小長 既定のキーの長さ キーの最大長
MS Base RC4 と RC2 40 40 56
MS Base DES 56 56 56
MS 拡張 RC4 と RC2 40 128 128
MS 拡張 DES 56 56 56
MS 拡張 3DES 112 112 112 112
MS 拡張 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 (デスクトップ アプリのみ)
対象プラットフォーム Windows
ヘッダー wincrypt.h
Library Advapi32.lib
[DLL] Advapi32.dll

こちらもご覧ください

CryptAcquireContext

CryptCreateHash

CryptDestroyHash

CryptDestroyKey

CryptExportKey

CryptGenKey

CryptGetKeyParam

CryptHashData

CryptHashSessionKey

CryptSetKeyParam

キー生成と Exchange 関数