CryptAcquireContextW 関数 (wincrypt.h)

この関数は、まず、dwProvType で説明されている特性を持つ CSP を検索し、pszProvider パラメーターを しようとします。 CSP が見つかった場合、関数は、pszContainer パラメーターで指定された名前と一致する CSP 内のキー コンテナーの検索を試みます。 コンテキスト と、証明書の 公開キー に関連付けられている 秘密キー のキー コンテナーを取得するには、CryptAcquireCertificatePrivateKeyを使用します。

dwFlagsの適切な設定により、この関数はキー コンテナーを作成および破棄することもでき、秘密キーへのアクセスが必要ない場合は、一時キー コンテナーを使用して CSP へのアクセスを提供することもできます。

構文

BOOL CryptAcquireContextW(
  [out] HCRYPTPROV *phProv,
  [in]  LPCWSTR    szContainer,
  [in]  LPCWSTR    szProvider,
  [in]  DWORD      dwProvType,
  [in]  DWORD      dwFlags
);

パラメーター

[out] phProv

CSP のハンドルへのポインター。 CSP の使用が完了したら、CryptReleaseContext 関数を呼び出してハンドルを解放します。

[in] szContainer

キー コンテナー名。 これは、CSP に対するキー コンテナーを識別する null で終わる文字列です。 この名前は、キーの格納に使用されるメソッドとは無関係です。 一部の CSP は、キー コンテナーを内部 (ハードウェア) に格納し、一部はシステム レジストリを使用し、他の CSP はファイル システムを使用します。 ほとんどの場合、dwFlags が CRYPT_VERIFYCONTEXT に設定されている場合、pszContainer NULLを に設定する必要があります。 ただし、スマート カード CSP などのハードウェア ベースの CSP の場合は、指定されたコンテナー内の公開されている情報にアクセスできます。

pszContainer パラメーターの使用方法の詳細については、「解説」を参照してください。

[in] szProvider

使用する CSP の名前を含む null で終わる文字列。

このパラメーターが NULL場合は、ユーザーの既定のプロバイダーが使用されます。 詳細については、「暗号化サービス プロバイダー コンテキストの」を参照してください。 使用可能な暗号化プロバイダーの一覧については、「暗号化プロバイダー名の」を参照してください。

アプリケーションは、CryptGetProvParam 関数を使用して、dwParam パラメーターのPP_NAME CSP 値を読み取ることで、使用中の CSP の名前を取得できます。

既定の CSP は、オペレーティング システムのリリース間で変更される可能性があります。 異なるオペレーティング システム プラットフォームでの相互運用性を確保するには、既定の CSP を使用するのではなく、このパラメーターを使用して CSP を明示的に設定する必要があります。

[in] dwProvType

取得するプロバイダーの種類を指定します。 定義済みのプロバイダーの種類については、暗号化プロバイダーの種類で説明します。

[in] dwFlags

次のフラグの 1 つ以上。 ほとんどのアプリケーションでは、デジタル署名を作成したりメッセージを復号化したりする必要がない限り、CRYPT_VERIFYCONTEXT フラグを設定する必要があります。

戻り値

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

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

NTE で開始されるエラー コードは、使用されている特定の CSP によって生成されます。 Winerror.h で定義されている可能性のあるエラー コードの一部を次に示します。

備考

pszContainer パラメーターは、キーを保持するために使用されるコンテナーの名前を指定します。 各コンテナーには、1 つのキーを含めることができます。 キーの作成時に既存のコンテナーの名前を指定すると、新しいキーによって前のコンテナーが上書きされます。

CSP 名とキー コンテナー名の組み合わせによって、システム上の 1 つのキーが一意に識別されます。 あるアプリケーションがキー コンテナーを使用しているときにキー コンテナーを変更しようとすると、予期しない動作が発生する可能性があります。

pszContainer パラメーターを NULL設定すると、既定のキー コンテナー名が使用されます。 この方法で Microsoft ソフトウェア CSP が呼び出されると、CryptAcquireContext 関数が呼び出されるたびに新しいコンテナーが作成されます。 ただし、この点では、CSP の動作が異なる場合があります。 特に、CSP には、CSP にアクセスするすべてのアプリケーションによって共有される 1 つの既定のコンテナーがある場合があります。 そのため、アプリケーションでは、秘密キーを格納するために既定のキー コンテナーを使用しないでください。 代わりに、dwFlags パラメーターに CRYPT_VERIFYCONTEXT フラグを渡してキー ストレージを禁止するか、別のアプリケーションで使用される可能性が低いアプリケーション固有のコンテナーを使用します。

アプリケーションは、CryptGetProvParam 関数を使用してPP_CONTAINER値を読み取ることで、使用中のキー コンテナーの名前を取得できます。

パフォーマンス上の理由から、pszContainer パラメーターを NULL に設定し、dwFlags パラメーターを永続化キーを必要としないすべての状況で CRYPT_VERIFYCONTEXT することをお勧めします。 特に、次のシナリオでは、pszContainer パラメーターを 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");
}

必要条件

関連項目

CryptGenKey

CryptGetProvParam

CryptReleaseContext

サービス プロバイダー関数の

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