Функция 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
Набор флагов, которые изменяют поведение этой функции. Это может быть ноль или сочетание одного или нескольких из следующих значений.
| Значение | Значение |
|---|---|
|
Если дескриптор уже получен и кэширован, возвращается тот же дескриптор. В противном случае новый дескриптор получается и кэшируется с помощью свойства CERT_KEY_CONTEXT_PROP_ID сертификата.
Если этот флаг установлен, параметр pfCallerFreeProvOrNCryptKey получает значение FALSE , и вызывающее приложение не должно освобождать дескриптор. Дескриптор освобождается при освобождении контекста сертификата; Однако необходимо сохранить контекст сертификата, на который ссылается параметр pCert , пока используется ключ. В противном случае операции, использующие этот ключ, завершатся ошибкой. |
|
Открытый ключ в сертификате сравнивается с открытым ключом, возвращенным поставщиком служб шифрования (CSP). Если ключи не совпадают, операция приобретения завершается сбоем и для последнего кода ошибки устанавливается значение NTE_BAD_PUBLIC_KEY. Если возвращается кэшированный дескриптор, сравнение не выполняется. |
|
Эта функция не будет пытаться повторно создать свойство CERT_KEY_PROV_INFO_PROP_ID в контексте сертификата, если это свойство не удается получить. |
|
Поставщик служб CSP не должен отображать пользовательский интерфейс для этого контекста. Если поставщик служб CSP должен отображать пользовательский интерфейс для работы, вызов завершается сбоем, а код ошибки NTE_SILENT_CONTEXT устанавливается как последняя ошибка. |
|
Использует свойство CERT_KEY_PROV_INFO_PROP_ID сертификата, чтобы определить, следует ли выполнять кэширование. Дополнительные сведения о свойстве CERT_KEY_PROV_INFO_PROP_ID см. в разделе CertSetCertificateContextProperty.
Эта функция будет использовать кэширование, только если во время предыдущего вызова элемент dwFlagsструктуры CRYPT_KEY_PROV_INFO содержит CERT_SET_KEY_CONTEXT_PROP. |
|
Любой пользовательский интерфейс, необходимый CSP или KSP, будет дочерним элементом HWND , который предоставляется в параметре pvParameters . Для ключа CSP использование этого флага приведет к вызову функции CryptSetProvParam с флагом PP_CLIENT_HWND с использованием этого HWND со значением NULL для HCRYPTPROV. Для ключа KSP использование этого флага приведет к вызову функции NCryptSetProperty с флагом NCRYPT_WINDOW_HANDLE_PROPERTY с помощью 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
Адрес переменной HCRYPTPROV_OR_NCRYPT_KEY_HANDLE , которая получает дескриптор поставщика CryptoAPI или ключ CNG. Если переменная pdwKeySpec получает флаг CERT_NCRYPT_KEY_SPEC , это дескриптор ключа CNG типа NCRYPT_KEY_HANDLE; В противном случае это дескриптор поставщика CryptoAPI типа HCRYPTPROV.
Дополнительные сведения о том, когда и как освободить этот дескриптор, см. в описании параметра pfCallerFreeProvOrNCryptKey .
[out] pdwKeySpec
Адрес переменной DWORD , которая получает дополнительные сведения о ключе. Это может быть одно из следующих значений.
[out] pfCallerFreeProvOrNCryptKey
Адрес переменной BOOL , получающей значение, указывающее, должен ли вызывающий объект освободить дескриптор, возвращенный в переменной phCryptProvOrNCryptKey . При этом возвращается значение FALSE , если выполняется одно из следующих значений:
- Не удается получить или сравнить открытый ключ.
- Параметр dwFlags содержит флаг CRYPT_ACQUIRE_CACHE_FLAG .
- Параметр dwFlags содержит флаг CRYPT_ACQUIRE_USE_PROV_INFO_FLAG , свойству контекста сертификата присваивается значение CERT_KEY_PROV_INFO_PROP_ID со структурой CRYPT_KEY_PROV_INFO , а члену dwFlags структуры CRYPT_KEY_PROV_INFO присвоено значение CERT_SET_KEY_CONTEXT_PROP_ID.
Если эта переменная получает значение TRUE, вызывающий объект отвечает за освобождение дескриптора, возвращаемого в переменной phCryptProvOrNCryptKey . Если переменная pdwKeySpec получает значение CERT_NCRYPT_KEY_SPEC , дескриптор должен быть освобожден путем его передачи в функцию NCryptFreeObject ; В противном случае дескриптор освобождается путем его передачи в функцию CryptReleaseContext .
Возвращаемое значение
Если функция выполнена успешно, возвращается ненулевое значение (TRUE).
Если функция завершается сбоем, возвращаемое значение равно нулю (FALSE). Чтобы получить дополнительные сведения об ошибке, вызовите Метод GetLastError. Ниже приведен один из возможных кодов ошибки.
| Код возврата | Описание |
|---|---|
|
Открытый ключ в сертификате не совпадает с открытым ключом, возвращенным поставщиком служб конфигурации. Этот код ошибки возвращается, если задано CRYPT_ACQUIRE_COMPARE_KEY_FLAG и открытый ключ в сертификате не соответствует открытому ключу, возвращенном поставщиком шифрования. |
|
Параметр dwFlags содержал флаг CRYPT_ACQUIRE_SILENT_FLAG , и поставщикУ служб CSP не удалось продолжить операцию без отображения пользовательского интерфейса. |
Комментарии
Если задано CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG , вызывающий объект должен убедиться, что HWND является допустимым. Если HWND больше недействителен, для CSP вызывающий объект должен вызвать CryptSetProvParam , используя флаг PP_CLIENT_HWND со значением NULL для HWND и NULL для HCRYPTPROV. Для KSP вызывающий объект должен задать для NCRYPT_WINDOW_HANDLE_PROPERTY ключа ncrypt значение NULL. Если для KSP установлен флаг CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG, NCRYPT_WINDOW_HANDLE_PROPERTY устанавливается для поставщика хранилища и ключа. Если оба вызова завершаются ошибкой, функция завершается ошибкой. Если только один из них завершается ошибкой, функция завершается успешно. Обратите внимание, что при установке HWND значения NULLHWND фактически удаляет HWND из ключа HCRYPTPROV или ncrypt.
Примеры
Пример использования этой функции см. в разделе Пример программы C. Отправка и получение подписанного и зашифрованного сообщения.
Требования
| Минимальная версия клиента | Windows XP [классические приложения | Приложения UWP] |
| Минимальная версия сервера | Windows Server 2003 [классические приложения | Приложения UWP] |
| Целевая платформа | Windows |
| Header | wincrypt.h |
| Библиотека | Crypt32.lib |
| DLL | Crypt32.dll |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по