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 つ以上の組み合わせにすることができます。

次のフラグは、キーを取得するために使用されるテクノロジを決定します。 これらのフラグが存在しない場合、この関数は 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 変数のアドレス。 次のいずれかの値を指定できます。

[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 つは次のとおりです。

解説

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 プログラムの例: 署名されたメッセージと暗号化されたメッセージの送受信」を参照してください。

要件

関連項目

CRYPT_KEY_PROV_INFO

CertSetCertificateContextProperty

CryptReleaseContext

キー生成と Exchange 関数