CryptAcquireContextA 関数 (wincrypt.h)
この関数は、まず dwProvType パラメーターと szProvider パラメーターで説明されている特性を持つ CSP の検索を試みます。 CSP が見つかった場合、関数は szContainer パラメーターで指定された名前と一致するキー コンテナーを CSP 内で検索しようとします。 証明書の公開キーに関連付けられている秘密キーのコンテキストとキー コンテナーを取得するには、CryptAcquireCertificatePrivateKey を使用します。
dwFlags の適切な設定により、この関数はキー コンテナーを作成および破棄することもでき、秘密キーへのアクセスが必要ない場合は、一時キー コンテナーを使用して CSP へのアクセスを提供することもできます。
構文
BOOL CryptAcquireContextA(
[out] HCRYPTPROV *phProv,
[in] LPCSTR szContainer,
[in] LPCSTR szProvider,
[in] DWORD dwProvType,
[in] DWORD dwFlags
);
パラメーター
[out] phProv
CSP のハンドルへのポインター。 CSP の使用が完了したら、 CryptReleaseContext 関数を呼び出してハンドルを解放します。
[in] szContainer
キー コンテナー名。 これは、CSP に対するキー コンテナーを識別する null で終わる文字列です。 この名前は、キーの格納に使用されるメソッドとは無関係です。 一部の CSP は、キー コンテナーを内部的に (ハードウェアに) 格納し、一部はシステム レジストリを使用し、他の CSP はファイル システムを使用します。 ほとんどの場合、 dwFlags が CRYPT_VERIFYCONTEXT に設定されている場合、 szContainer を NULL に設定する必要があります。 ただし、スマート カード CSP などのハードウェアベースの CSP の場合は、指定されたコンテナーで公開されている情報にアクセスできます。
szContainer パラメーターの使用方法の詳細については、「解説」を参照してください。
[in] szProvider
使用する CSP の名前を含む null で終わる文字列。
このパラメーターが NULL の場合は、ユーザーの既定のプロバイダーが使用されます。 詳細については、「 暗号化サービス プロバイダーコンテキスト」を参照してください。 使用可能な暗号化プロバイダーの一覧については、「 暗号化プロバイダー名」を参照してください。
アプリケーションは、 CryptGetProvParam 関数を使用して dwParam パラメーターのPP_NAME CSP 値を読み取ることによって、使用中の CSP の名前を取得できます。
既定の CSP は、オペレーティング システムのリリース間で変更できます。 異なるオペレーティング システム プラットフォームでの相互運用性を確保するには、既定の CSP を使用するのではなく、このパラメーターを使用して CSP を明示的に設定する必要があります。
[in] dwProvType
取得するプロバイダーの種類を指定します。 定義されたプロバイダーの種類については、「 暗号化プロバイダーの種類」を参照してください。
[in] dwFlags
フラグ値。 通常、このパラメーターは 0 に設定されますが、一部のアプリケーションでは次のフラグの 1 つ以上が設定されます。
| 値 | 意味 |
|---|---|
|
このオプションは、エフェメラル キーを使用しているアプリケーション、またはハッシュ、暗号化、デジタル署名検証のみを実行するアプリケーションなど、永続化された秘密キーへのアクセスを必要としないアプリケーションを対象としています。 秘密キーにアクセスする必要があるのは、署名を作成したりメッセージを復号化したりするアプリケーションだけです。 ほとんどの場合、このフラグを設定する必要があります。
ファイルベースの CSP の場合、このフラグが設定されている場合、 szContainer パラメーターを NULL に設定する必要があります。 アプリケーションは、公開キーと秘密キーのペアの永続化された秘密キーにアクセスできません。 このフラグを設定すると、一時的な 公開キーと秘密キーのペア を作成できますが、永続化されません。 スマート カード CSP などのハードウェア ベースの CSP の場合、 szContainer パラメーターが NULL または空白の場合、このフラグはキーへのアクセスが必要なく、ユーザーに UI を表示する必要がないことを意味します。 このフォームは、CSP に接続してその機能に対してクエリを実行するために使用されますが、実際にはキーを使用しません。 szContainer パラメーターが NULL ではなく、空白でない場合、このフラグは、指定されたコンテナー内で公開されている情報にのみアクセスする必要があることを意味します。 CSP は PIN を要求しないでください。 個人情報 ( CryptSignHash 関数など) にアクセスしようとすると失敗します。 CryptAcquireContext が呼び出されると、多くの CSP は、キー コンテナー内の秘密キーへのアクセスを許可する前に、所有ユーザーからの入力を必要とします。 たとえば、秘密キーを暗号化して、使用する前にユーザーのパスワードを要求できます。 ただし、 CRYPT_VERIFYCONTEXT フラグを指定した場合、秘密キーへのアクセスは必要なく、ユーザー インターフェイスをバイパスできます。 |
|
szContainer で指定された名前の新しいキー コンテナーを作成します。 szContainer が NULL の場合、既定の名前のキー コンテナーが作成されます。 |
|
既定では、キーとキー コンテナーはユーザー キーとして格納されます。 基本プロバイダーの場合、これはユーザー キー コンテナーがユーザーのプロファイルに格納されることを意味します。 管理者によってこのフラグなしで作成されたキー コンテナーには、キー コンテナーを作成しているユーザーと管理特権を持つユーザーのみがアクセスできます。
Windows XP: 管理者によってこのフラグなしで作成されたキー コンテナーには、キー コンテナーとローカル システム アカウントを作成しているユーザーのみがアクセスできます。 管理者ではないユーザーがこのフラグなしで作成したキー コンテナーには、キー コンテナーとローカル システム アカウントを作成しているユーザーのみがアクセスできます。 CRYPT_MACHINE_KEYSET フラグを他のすべてのフラグと組み合わせて、対象のキー コンテナーがコンピューター キー コンテナーであり、CSP がそれをそのように扱うことを示すことができます。 ベース プロバイダーの場合、キーはキー コンテナーを作成したコンピューターにローカルに格納されることを意味します。 キー コンテナーをコンピューター コンテナーにする場合は、コンピューター コンテナーを参照する CryptAcquireContext のすべての呼び出しで、CRYPT_MACHINE_KEYSET フラグを使用する必要があります。 管理者によってCRYPT_MACHINE_KEYSETで作成されたキー コンテナーには、CryptSetProvParam を使用してコンテナーへのアクセス権が付与されていない限り、その作成者と管理者特権を持つユーザーのみがアクセスできます。 Windows XP: 管理者によってCRYPT_MACHINE_KEYSETで作成されたキー コンテナーには、 CryptSetProvParam を使用してコンテナーへのアクセス権が付与されていない限り、その作成者とローカル システム アカウントのみがアクセスできます。 管理者ではないユーザーがCRYPT_MACHINE_KEYSETで作成したキー コンテナーは、 CryptSetProvParam を使用してコンテナーへのアクセス権が付与されていない限り、その作成者とローカル システム アカウントによってのみアクセスできます。 CRYPT_MACHINE_KEYSET フラグは、対話形式でログオンしなかったサービスまたはユーザー アカウントからユーザーがアクセスしている場合に便利です。 キー コンテナーが作成されると、ほとんどの CSP は 公開キーと秘密キーのペアを自動的に作成しません。 これらのキーは、 CryptGenKey 関数を使用して別の手順として作成する必要があります。 |
|
szContainer で指定されたキー コンテナーを削除します。 szContainer が NULL の場合、既定の名前のキー コンテナーが削除されます。 キー コンテナー内のすべての キー ペア も破棄されます。
このフラグが設定されている場合、 phProv で返される値は未定義であるため、 後で CryptReleaseContext 関数を呼び出す必要はありません。 |
|
アプリケーションは、このコンテキストのユーザー インターフェイス (UI) を CSP に表示しないことを要求 します。 CSP が操作する UI を表示する必要がある場合、呼び出しは失敗し、NTE_SILENT_CONTEXTエラー コードが最後のエラーとして設定されます。 さらに、CRYPT_SILENT フラグを使用して取得されたコンテキストを持つ CRYPT_USER_PROTECTED フラグを持つ CryptGenKey への呼び出しが行われた場合、呼び出しは失敗し、CSP はNTE_SILENT_CONTEXTを設定します。
CRYPT_SILENTは、CSP で UI を表示できないアプリケーションで使用することを目的としています。 |
|
ハッシュと対称キー操作に使用できるスマート カード CSP のコンテキストを取得しますが、PIN を使用したスマート カードへの認証を必要とする操作には使用できません。 この種類のコンテキストは、 CryptSetProvParam を使用して PIN を設定するなど、空のスマート カードに対する操作を実行するために最もよく使用されます。 このフラグは、スマート カード CSP でのみ使用できます。
Windows Server 2003 および Windows XP: このフラグはサポートされていません。 |
戻り値
関数が成功した場合、関数は 0 以外 (TRUE) を返します。
関数が失敗した場合は、0 (FALSE) を返します。 拡張エラー情報については、 GetLastError を呼び出します。
NTE の前に表示されるエラー コードは、使用されている特定の CSP によって生成されます。 Winerror.h で定義されている可能性のあるエラー コードの一部を次に示します。
| リターン コード/値 | Description |
|---|---|
|
一部の CSP は、CRYPT_DELETEKEYSET フラグ値が設定され、別のスレッドまたは プロセス がこの キー コンテナーを使用している場合に、このエラーを設定します。 |
|
ユーザーのプロファイルが読み込まれず、見つかりません。 これは、アプリケーションがユーザー (たとえば、IUSR_ComputerName アカウント) を偽装した場合に発生します。 |
|
パラメーターの 1 つに無効な値が含まれています。 これはほとんどの場合、無効なポインターです。 |
|
操作中にオペレーティング システムのメモリが不足しました。 |
|
dwFlags パラメーターの値が無効です。 |
|
秘密キーが暗号化されてから、ユーザー パスワードが変更されました。 |
|
キー コンテナーを開けませんでした。 このエラーの一般的な原因は、キー コンテナーが存在しないことです。 キー コンテナーを作成するには、CRYPT_NEWKEYSET フラグを使用して CryptAcquireContext を呼び出します。 このエラー コードは、既存のキー コンテナーへのアクセスが拒否されたことを示す場合もあります。 コンテナーへのアクセス権は、キー セット作成者が CryptSetProvParam を使用して付与できます。 |
|
szContainer または szProvider パラメーターが無効な値に設定されています。 |
|
dwProvType パラメーターの値が範囲外です。 すべてのプロバイダーの種類は、1 ~ 999 の範囲である必要があります。 |
|
プロバイダー DLL 署名を検証できませんでした。 DLL またはデジタル署名のいずれかが改ざんされています。 |
|
dwFlags パラメーターはCRYPT_NEWKEYSETされていますが、キー コンテナーは既に存在します。 |
|
szContainer キー コンテナーが見つかりましたが、破損しています。 |
|
要求されたプロバイダーが存在しません。 |
|
操作中に CSP のメモリが不足しました。 |
|
プロバイダー DLL ファイルが存在しないか、現在のパスにありません。 |
|
dwProvType で指定されたプロバイダーの種類が壊れています。 このエラーは、ユーザーの既定の CSP の一覧またはコンピューターの既定の CSP の一覧のいずれかに関連する場合があります。 |
|
dwProvType で指定されたプロバイダーの種類が、見つかったプロバイダーの種類と一致しません。 このエラーは、 szProvider で実際の CSP 名が指定されている場合にのみ発生します。 |
|
dwProvType で指定されたプロバイダーの種類のエントリは存在しません。 |
|
プロバイダー DLL ファイルを読み込めなかったか、初期化に失敗しました。 |
|
署名を確認する前に、DLL ファイル イメージの読み込み中にエラーが発生しました。 |
注釈
szContainer パラメーターは、キーを保持するために使用されるコンテナーの名前を指定します。 各コンテナーには、1 つのキーを含めることができます。 キーの作成時に既存のコンテナーの名前を指定すると、新しいキーによって前のコンテナーが上書きされます。
CSP 名とキー コンテナー名の組み合わせによって、システム上の 1 つのキーが一意に識別されます。 あるアプリケーションがキー コンテナーを使用しているときにキー コンテナーを変更しようとすると、予期しない動作が発生する可能性があります。
szContainer パラメーターを NULL に設定すると、既定のキー コンテナー名が使用されます。 この方法で Microsoft ソフトウェア CSP が呼び出されると、 CryptAcquireContext 関数が呼び出されるたびに新しいコンテナーが作成されます。 ただし、この点では、CSP の動作が異なる場合があります。 特に、CSP には、CSP にアクセスするすべてのアプリケーションで共有される 1 つの既定のコンテナーが含まれる場合があります。 したがって、アプリケーションでは、秘密キーを格納するために既定のキー コンテナーを使用することはできません。 代わりに、dwFlags パラメーターに CRYPT_VERIFYCONTEXT フラグを渡してキーストレージを禁止するか、別のアプリケーションで使用される可能性が低いアプリケーション固有のコンテナーを使用します。
アプリケーションは、 CryptGetProvParam 関数を使用してPP_CONTAINER値を読み取ることで、使用中のキー コンテナーの名前を取得できます。
パフォーマンス上の理由から、永続化されたキーを必要としないすべての状況で、 szContainer パラメーターを NULL に設定し、 dwFlags パラメーターを CRYPT_VERIFYCONTEXT に設定することをお勧めします。 特に、次のシナリオでは、 szContainer パラメーターを NULL に設定し、 dwFlags パラメーターを CRYPT_VERIFYCONTEXT に設定することを検討してください。
- ハッシュを作成しています。
- データを暗号化または暗号化解除するための対称キーを生成しています。
- データを暗号化または暗号化解除するために、ハッシュから対称キーを派生しています。
- 署名を確認しています。 CryptImportKey または CryptImportPublicKeyInfo を使用して、PUBLICKEYBLOB または証明書から公開キーをインポートできます。 公開キーのみをインポートする場合は、 CRYPT_VERIFYCONTEXT フラグを使用してコンテキストを取得できます。
- 対称キーをエクスポートする予定ですが、暗号化コンテキストの有効期間内にはインポートしません。 過去 2 つのシナリオの公開キーのみをインポートする予定の場合は、 CRYPT_VERIFYCONTEXT フラグを使用してコンテキストを取得できます。
- 秘密キー操作を実行していますが、キー コンテナーに格納されている永続化された秘密キーを使用していません。
例
次の例は、暗号化コンテキストの取得と、キー コンテナー内の公開キーと秘密キーのペアへのアクセスを示しています。 要求されたキー コンテナーが存在しない場合は、作成されます。
この例の完全なコンテキストを含む例については、「 C プログラムの例: キー コンテナーの作成」と「キーの生成」を参照してください。 その他の例については、「 サンプル C プログラム: CryptAcquireContext の使用」を参照してください。
//-------------------------------------------------------------------
// Declare and initialize variables.
HCRYPTPROV hCryptProv = NULL; // handle for a cryptographic
// provider context
LPCSTR UserName = "MyKeyContainer"; // name of the key container
// to be used
//-------------------------------------------------------------------
// Attempt to acquire a context and a key
// container. The context will use the default CSP
// for the RSA_FULL provider type. DwFlags is set to zero
// to attempt to open an existing key container.
if(CryptAcquireContext(
&hCryptProv, // handle to the CSP
UserName, // container name
NULL, // use the default provider
PROV_RSA_FULL, // provider type
0)) // flag values
{
printf("A cryptographic context with the %s key container \n",
UserName);
printf("has been acquired.\n\n");
}
else
{
//-------------------------------------------------------------------
// An error occurred in acquiring the context. This could mean
// that the key container requested does not exist. In this case,
// the function can be called again to attempt to create a new key
// container. Error codes are defined in Winerror.h.
if (GetLastError() == NTE_BAD_KEYSET)
{
if(CryptAcquireContext(
&hCryptProv,
UserName,
NULL,
PROV_RSA_FULL,
CRYPT_NEWKEYSET))
{
printf("A new key container has been created.\n");
}
else
{
printf("Could not create a new key container.\n");
exit(1);
}
}
else
{
printf("A cryptographic service handle could not be "
"acquired.\n");
exit(1);
}
} // End of else.
//-------------------------------------------------------------------
// A cryptographic context and a key container are available. Perform
// any functions that require a cryptographic provider handle.
//-------------------------------------------------------------------
// When the handle is no longer needed, it must be released.
if (CryptReleaseContext(hCryptProv,0))
{
printf("The handle has been released.\n");
}
else
{
printf("The handle could not be released.\n");
}
注意
wincrypt.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして CryptAcquireContext を定義します。 エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows XP (デスクトップ アプリのみ) |
| サポートされている最小のサーバー | Windows Server 2003 (デスクトップ アプリのみ) |
| 対象プラットフォーム | Windows |
| ヘッダー | wincrypt.h |
| Library | Advapi32.lib |
| [DLL] | Advapi32.dll |