CryptAcquireCertificatePrivateKey 関数 (wincrypt.h)
CryptAcquireCertificatePrivateKey 関数は、証明書の秘密キーを取得します。 この関数は、ユーザーの証明書を使用できるが、ユーザーのキー コンテナーのハンドルを使用できない場合に、ユーザーの 秘密 キーへのアクセスを取得するために使用されます。 この関数は、秘密キーの所有者のみが使用でき、他のユーザーは使用できません。
CSP ハンドルと、ユーザーの秘密キーを含むキー コンテナーを使用できる場合は、代わりに CryptGetUserKey 関数を使用する必要があります。
構文
BOOL CryptAcquireCertificatePrivateKey(
[in] PCCERT_CONTEXT pCert,
[in] DWORD dwFlags,
[in, optional] void *pvParameters,
[out] HCRYPTPROV_OR_NCRYPT_KEY_HANDLE *phCryptProvOrNCryptKey,
[out] DWORD *pdwKeySpec,
[out] BOOL *pfCallerFreeProvOrNCryptKey
);
パラメーター
[in] pCert
秘密キーを取得する証明書コンテキストを含むCERT_CONTEXT構造体のアドレス。
[in] dwFlags
この関数の動作を変更するフラグのセット。 これは、0 または次の値の 1 つ以上の組み合わせにすることができます。
| 値 | 説明 |
|---|---|
|
ハンドルが既に取得され、キャッシュされている場合は、その同じハンドルが返されます。 それ以外の場合は、証明書の CERT_KEY_CONTEXT_PROP_ID プロパティを使用して、新しいハンドルが取得され、キャッシュされます。
このフラグを設定すると、 pfCallerFreeProvOrNCryptKey パラメーターは FALSE を 受け取り、呼び出し元のアプリケーションがハンドルを解放することはできません。 証明書コンテキストが解放されると、ハンドルが解放されます。ただし、キーが使用されている限り、 pCert パラメーターによって参照される証明書コンテキストを保持する必要があります。そうしないと、キーに依存する操作は失敗します。 |
|
証明書の 公開キー は、 暗号化サービス プロバイダー (CSP) によって返される公開キーと比較されます。 キーが一致しない場合、取得操作は失敗し、最後のエラー コードは NTE_BAD_PUBLIC_KEY に設定されます。 キャッシュされたハンドルが返された場合、比較は行われません。 |
|
このプロパティを取得できない場合、この関数は証明書コンテキストで CERT_KEY_PROV_INFO_PROP_ID プロパティの再作成を試みません。 |
|
CSP では、このコンテキストのユーザー インターフェイス (UI) を表示しないでください。 CSP が操作するために UI を表示する必要がある場合、呼び出しは失敗し、 NTE_SILENT_CONTEXT エラー コードが最後のエラーとして設定されます。 |
|
証明書の CERT_KEY_PROV_INFO_PROP_ID プロパティを使用して、キャッシュを実行する必要があるかどうかを判断します。 CERT_KEY_PROV_INFO_PROP_ID プロパティの詳細については、「CertSetCertificateContextProperty」を参照してください。
この関数は、前回の呼び出し中に、CRYPT_KEY_PROV_INFO構造体の dwFlags メンバーが CERT_SET_KEY_CONTEXT_PROP 含まれている場合にのみキャッシュ を使用します。 |
|
CSP または KSP で必要な UI は、pvParameters パラメーターで指定された HWND の子になります。 CSP キーの場合、このフラグを使用すると、この HWND を使用PP_CLIENT_HWNDフラグを持つ CryptSetProvParam 関数が HCRYPTPROV の NULL で呼び出されます。 KSP キーの場合、このフラグを使用すると、NCRYPT_WINDOW_HANDLE_PROPERTY フラグを持つ NCryptSetProperty 関数が HWND を使用して呼び出されます。
このフラグは 、CRYPT_ACQUIRE_SILENT_FLAGでは使用しないでください。 |
次のフラグは、キーを取得するために使用されるテクノロジを決定します。 これらのフラグが存在しない場合、この関数は CryptoAPI を使用してキーの取得のみを試みます。
Windows Server 2003 および Windows XP: これらのフラグはサポートされていません。
[in, optional] pvParameters
CRYPT_ACQUIRE_WINDOW_HANDLE_FLAGが設定されている場合、これは HWND のアドレスです。 CRYPT_ACQUIRE_WINDOW_HANDLE_FLAGが設定されていない場合、このパラメーターは NULL である必要があります。
Windows Server 2008 R2、Windows 7、Windows Server 2008、Windows Vista、Windows Server 2003、Windows XP: このパラメーターは pvReserved という名前で、将来使用するために予約されており、 NULL である必要があります。
[out] phCryptProvOrNCryptKey
CryptoAPI プロバイダーまたは CNG キーのハンドルを受け取る HCRYPTPROV_OR_NCRYPT_KEY_HANDLE変数の アドレス。 pdwKeySpec 変数が CERT_NCRYPT_KEY_SPEC フラグを受け取る場合、これは NCRYPT_KEY_HANDLE 型の CNG キー ハンドルです。それ以外の場合、これは HCRYPTPROV 型の CryptoAPI プロバイダー ハンドルです。
このハンドルを解放するタイミングと方法の詳細については、 pfCallerFreeProvOrNCryptKey パラメーターの説明を参照してください。
[out] pdwKeySpec
キーに関する追加情報を受け取る DWORD 変数のアドレス。 次のいずれかの値を指定できます。
| 値 | 説明 |
|---|---|
|
キー ペアはキー交換ペアです。 |
|
キーペアは署名ペアです。 |
|
キーは CNG キーです。
Windows Server 2003 および Windows XP: この値はサポートされていません。 |
[out] pfCallerFreeProvOrNCryptKey
呼び出し元が phCryptProvOrNCryptKey 変数で返されるハンドルを解放する必要があるかどうかを示す値を受け取る BOOL 変数のアドレス。 次のいずれかが当てはまる場合、FALSE を 受け取ります。
- 公開キーの取得または比較が失敗します。
- dwFlags パラメーターには、CRYPT_ACQUIRE_CACHE_FLAG フラグが含まれています。
- dwFlags パラメーターにはCRYPT_ACQUIRE_USE_PROV_INFO_FLAG フラグが含まれており、証明書コンテキスト プロパティは CRYPT_KEY_PROV_INFO 構造体でCERT_KEY_PROV_INFO_PROP_IDに設定され、CRYPT_KEY_PROV_INFO構造体の dwFlags メンバーは CERT_SET_KEY_CONTEXT_PROP_ID に設定されます。
この変数が TRUE を受け取った場合、呼び出し元は phCryptProvOrNCryptKey 変数で返されるハンドルを解放します。 pdwKeySpec 変数がCERT_NCRYPT_KEY_SPEC値を受け取る場合は、ハンドルを NCryptFreeObject 関数に渡して解放する必要があります。それ以外の場合、ハンドルは CryptReleaseContext 関数に渡すことによって解放されます。
戻り値
関数が成功した場合、戻り値は 0 以外 (TRUE) になります。
関数が失敗した場合、戻り値は 0 (FALSE) になります。 拡張エラー情報については、 GetLastError を呼び出します。 考えられるエラー コードの 1 つは次のとおりです。
| リターン コード | 説明 |
|---|---|
|
証明書の公開キーが、CSP によって返される公開キーと一致しません。 このエラー コードは、CRYPT_ACQUIRE_COMPARE_KEY_FLAGが設定されていて、証明書の公開キーが暗号化プロバイダーから返された公開キーと一致しない場合に返されます。 |
|
dwFlags パラメーターには CRYPT_ACQUIRE_SILENT_FLAG フラグが含まれており、CSP はユーザー インターフェイスを表示せずに操作を続行できませんでした。 |
解説
CRYPT_ACQUIRE_WINDOW_HANDLE_FLAGが設定されている場合、呼び出し元は HWND が有効であることを確認する必要があります。 HWND が無効になった場合、CSP の場合、呼び出し元は、HCRYPTPROV の場合は NULL、HCRYPTPROV の場合は NULL でフラグ PP_CLIENT_HWNDを使用して CryptSetProvParam を呼び出す必要があります。 KSP の場合、呼び出し元は ncrypt キーのNCRYPT_WINDOW_HANDLE_PROPERTYを NULL に設定する必要があります。 KSP CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG フラグが設定されている場合、ストレージ プロバイダーとキーにNCRYPT_WINDOW_HANDLE_PROPERTYが設定されます。 両方の呼び出しが失敗した場合、関数は失敗します。 1 つだけ失敗した場合、関数は成功します。 HWND を NULL に設定すると、HCRYPTPROV キーまたは ncrypt キーから HWND が実質的に削除されることに注意してください。
例
この関数を使用する例については、「 C プログラムの例: 署名されたメッセージと暗号化されたメッセージの送受信」を参照してください。
要件
| サポートされている最小のクライアント | Windows XP [デスクトップ アプリ | UWP アプリ] |
| サポートされている最小のサーバー | Windows Server 2003 [デスクトップ アプリのみ | UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | wincrypt.h |
| Library | Crypt32.lib |
| [DLL] | Crypt32.dll |