Функция CryptAcquireCertificatePrivateKey (wincrypt.h)

Статья
08/27/2023

Функция 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

Набор флагов, которые изменяют поведение этой функции. Это может быть ноль или сочетание одного или нескольких из следующих значений.

Значение	Значение
CRYPT_ACQUIRE_CACHE_FLAG	Если дескриптор уже получен и кэширован, возвращается тот же дескриптор. В противном случае новый дескриптор получается и кэшируется с помощью свойства CERT_KEY_CONTEXT_PROP_ID сертификата. Если этот флаг установлен, параметр pfCallerFreeProvOrNCryptKey получает значение FALSE , и вызывающее приложение не должно освобождать дескриптор. Дескриптор освобождается при освобождении контекста сертификата; Однако необходимо сохранить контекст сертификата, на который ссылается параметр pCert , пока используется ключ. В противном случае операции, использующие этот ключ, завершатся ошибкой.
CRYPT_ACQUIRE_COMPARE_KEY_FLAG	Открытый ключ в сертификате сравнивается с открытым ключом, возвращенным поставщиком служб шифрования (CSP). Если ключи не совпадают, операция приобретения завершается сбоем и для последнего кода ошибки устанавливается значение NTE_BAD_PUBLIC_KEY. Если возвращается кэшированный дескриптор, сравнение не выполняется.
CRYPT_ACQUIRE_NO_HEALING	Эта функция не будет пытаться повторно создать свойство CERT_KEY_PROV_INFO_PROP_ID в контексте сертификата, если это свойство не удается получить.
CRYPT_ACQUIRE_SILENT_FLAG	Поставщик служб CSP не должен отображать пользовательский интерфейс для этого контекста. Если поставщик служб CSP должен отображать пользовательский интерфейс для работы, вызов завершается сбоем, а код ошибки NTE_SILENT_CONTEXT устанавливается как последняя ошибка.
CRYPT_ACQUIRE_USE_PROV_INFO_FLAG	Использует свойство CERT_KEY_PROV_INFO_PROP_ID сертификата, чтобы определить, следует ли выполнять кэширование. Дополнительные сведения о свойстве CERT_KEY_PROV_INFO_PROP_ID см. в разделе CertSetCertificateContextProperty. Эта функция будет использовать кэширование, только если во время предыдущего вызова элемент dwFlagsструктуры CRYPT_KEY_PROV_INFO содержит CERT_SET_KEY_CONTEXT_PROP.
CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG	Любой пользовательский интерфейс, необходимый 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: Эти флаги не поддерживаются.

Значение	Значение
CRYPT_ACQUIRE_ALLOW_NCRYPT_KEY_FLAG	Эта функция попытается получить ключ с помощью CryptoAPI. В случае сбоя эта функция попытается получить ключ с помощью API шифрования следующего поколения (CNG). Переменная pdwKeySpec получает флаг CERT_NCRYPT_KEY_SPEC , если для получения ключа используется CNG.
CRYPT_ACQUIRE_ONLY_NCRYPT_KEY_FLAG	Эта функция будет пытаться получить ключ только с помощью CNG и не будет использовать CryptoAPI для получения ключа. Переменная pdwKeySpec получает флаг CERT_NCRYPT_KEY_SPEC , если для получения ключа используется CNG.
CRYPT_ACQUIRE_PREFER_NCRYPT_KEY_FLAG	Эта функция попытается получить ключ с помощью CNG. В случае сбоя эта функция попытается получить ключ с помощью CryptoAPI. Переменная pdwKeySpec получает флаг CERT_NCRYPT_KEY_SPEC , если для получения ключа используется CNG. Примечание CryptoAPI не поддерживает асимметричные алгоритмы CNG Diffie-Hellman или DSA. CryptoAPI поддерживает только открытые ключи Diffie-Hellman и DSA через устаревшие CSP. Если этот флаг установлен для сертификата, содержащего открытый ключ Diffie-Hellman или DSA, эта функция неявно изменит этот флаг на CRYPT_ACQUIRE_ALLOW_NCRYPT_KEY_FLAG , чтобы сначала попытаться использовать CryptoAPI для получения ключа.

[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 , которая получает дополнительные сведения о ключе. Это может быть одно из следующих значений.

Значение	Значение
AT_KEYEXCHANGE	Пара ключей — это пара обмена ключами.
AT_SIGNATURE	Пара ключей является парой подписей.
CERT_NCRYPT_KEY_SPEC	Ключ является ключом CNG. Windows Server 2003 и Windows XP: Это значение не поддерживается.

[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.

Если эта переменная получает значение FALSE, вызывающее приложение не должно освобождать дескриптор, возвращенный в переменной phCryptProvOrNCryptKey . Дескриптор будет освобожден при последнем свободном действии контекста сертификата.

Если эта переменная получает значение TRUE, вызывающий объект отвечает за освобождение дескриптора, возвращаемого в переменной phCryptProvOrNCryptKey . Если переменная pdwKeySpec получает значение CERT_NCRYPT_KEY_SPEC , дескриптор должен быть освобожден путем его передачи в функцию NCryptFreeObject ; В противном случае дескриптор освобождается путем его передачи в функцию CryptReleaseContext .

Возвращаемое значение

Если функция выполнена успешно, возвращается ненулевое значение (TRUE).

Если функция завершается сбоем, возвращаемое значение равно нулю (FALSE). Чтобы получить дополнительные сведения об ошибке, вызовите Метод GetLastError. Ниже приведен один из возможных кодов ошибки.

Код возврата	Описание
NTE_BAD_PUBLIC_KEY	Открытый ключ в сертификате не совпадает с открытым ключом, возвращенным поставщиком служб конфигурации. Этот код ошибки возвращается, если задано CRYPT_ACQUIRE_COMPARE_KEY_FLAG и открытый ключ в сертификате не соответствует открытому ключу, возвращенном поставщиком шифрования.
NTE_SILENT_CONTEXT	Параметр dwFlags содержал флаг CRYPT_ACQUIRE_SILENT_FLAG , и поставщикУ служб CSP не удалось продолжить операцию без отображения пользовательского интерфейса.

Код возврата

Описание

NTE_BAD_PUBLIC_KEY

Открытый ключ в сертификате не совпадает с открытым ключом, возвращенным поставщиком служб конфигурации. Этот код ошибки возвращается, если задано CRYPT_ACQUIRE_COMPARE_KEY_FLAG и открытый ключ в сертификате не соответствует открытому ключу, возвращенном поставщиком шифрования.

NTE_SILENT_CONTEXT

Параметр 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

См. также раздел

CRYPT_KEY_PROV_INFO

CertSetCertificateContextProperty

CryptReleaseContext

Функции создания ключей и обмена

Поделиться через