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

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

 

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

Синтаксис

BOOL CryptSetProvParam(
  [in] HCRYPTPROV hProv,
  [in] DWORD      dwParam,
  [in] const BYTE *pbData,
  [in] DWORD      dwFlags
);

Параметры

[in] hProv

Дескриптор CSP, для которого задаются значения. Этот дескриптор должен быть уже создан с помощью функции CryptAcquireContext .

[in] dwParam

Задает заданный параметр. Это может быть одно из следующих значений.

Значение	Значение
PP_CLIENT_HWND 1 (0x1)	Задайте дескриптор окна, который поставщик использует в качестве родительского элемента для всех создаваемых диалоговых окон. pbData содержит указатель на HWND , содержащий дескриптор родительского окна. Этот параметр необходимо задать перед вызовом CryptAcquireContext , так как многие поставщики служб конфигурации будут отображать пользовательский интерфейс при вызове CryptAcquireContext . Вы можете передать значение NULL для параметра hProv , чтобы задать этот дескриптор окна для всех криптографических контекстов, полученных впоследствии в рамках этого процесса.
PP_DELETEKEY 24 (0x18)	Удалите эфемерный ключ, связанный с контекстом хэша, шифрования или проверки. Это освободит память и очистит параметры реестра, связанные с разделом.
PP_KEYEXCHANGE_ALG	Эта константа не используется.
PP_KEYEXCHANGE_PIN 32 (0x20)	Указывает, что ПИН-код обмена ключами содержится в pbData. ПИН-код представлен в виде строки ASCII, завершаемой null.
PP_KEYEXCHANGE_KEYSIZE	Эта константа не используется.
PP_KEYSET_SEC_DESCR 8 (0x8)	Задает дескриптор безопасности для контейнера хранилища ключей. Параметр pbData — это адрес структуры SECURITY_DESCRIPTOR , содержащей новый дескриптор безопасности для контейнера хранилища ключей.
PP_PIN_PROMPT_STRING 44 (0x2C)	Задает альтернативную строку запроса, отображаемую пользователю при запросе ПИН-кода пользователя. Параметр pbData является указателем на строку Юникода, завершаемую null.
PP_ROOT_CERTSTORE 46 (0x2E)	Задает корневое хранилище сертификатов для смарт-карта. Поставщик скопирует корневые сертификаты из этого хранилища в смарт-карта. Параметр pbData — это переменная HCERTSTORE , содержащая дескриптор нового хранилища сертификатов. Поставщик копирует сертификаты из хранилища во время этого вызова, поэтому после вызова этой функции это хранилище можно закрыть. Windows XP и Windows Server 2003: Этот параметр не поддерживается.
PP_SIGNATURE_ALG	Эта константа не используется.
PP_SIGNATURE_PIN 33 (0x21)	Указывает ПИН-код подписи. Параметр pbData представляет собой строку ASCII, завершающуюся null, которая представляет ПИН-код.
PP_SIGNATURE_KEYSIZE	Эта константа не используется.
PP_UI_PROMPT 21 (0x15)	Для поставщика смарт-карта задает строку поиска, отображаемую пользователю в виде запроса на вставку смарт-карта. Эта строка передается как член lpstrSearchDescструктуры OPENCARDNAME_EX , которая передается в функцию SCardUIDlgSelectCard . Эта строка используется для времени существования вызывающего процесса. Параметр pbData является указателем на строку Юникода, завершаемую null.
PP_USE_HARDWARE_RNG 38 (0x26)	Указывает, что поставщик служб CSP должен использовать исключительно аппаратный генератор случайных чисел (RNG). При установке PP_USE_HARDWARE_RNG случайные значения берутся исключительно из аппаратного RNG и не используются другие источники. Если аппаратный RNG поддерживается поставщиком служб CSP и может использоваться исключительно, функция выполняется успешно и возвращает значение TRUE; В противном случае функция завершается сбоем и возвращает значение FALSE. Параметр pbData должен иметь значение NULL , а dwFlags — ноль при использовании этого значения. В настоящее время ни один из CSP Майкрософт не поддерживает использование аппаратного RNG.
PP_USER_CERTSTORE 42 (0x2A)	Указывает хранилище сертификатов пользователя для смарт-карта. Это хранилище сертификатов содержит все пользовательские сертификаты, хранящиеся в смарт-карта. Сертификаты в этом хранилище кодируются с помощью кодировки PKCS_7_ASN_ENCODING или X509_ASN_ENCODING и должны содержать свойство CERT_KEY_PROV_INFO_PROP_ID . Параметр pbData — это переменная HCERTSTORE , которая получает дескриптор хранилища сертификатов в памяти. Если этот дескриптор больше не требуется, вызывающий объект должен закрыть его с помощью функции CertCloseStore . Windows Server 2003 и Windows XP: Этот параметр не поддерживается.
PP_SECURE_KEYEXCHANGE_PIN 47 (0x2F)	Указывает, что ПИН-код зашифрованного обмена ключами содержится в pbData. Параметр pbData содержит DATA_BLOB.
PP_SECURE_SIGNATURE_PIN 48 (0x30)	Указывает, что зашифрованный ПИН-код подписи содержится в pbData. Параметр pbData содержит DATA_BLOB.
PP_SMARTCARD_READER 43 (0x2B)	Указывает имя средства чтения смарт-карта. Параметр pbData — это адрес массива символов ANSI, который содержит строку ANSI, завершающуюся null, которая содержит имя смарт-карта средства чтения. Windows Server 2003 и Windows XP: Этот параметр не поддерживается.
PP_SMARTCARD_GUID 45 (0x2D)	Указывает идентификатор смарт-карта. Параметр pbData — это адрес структуры GUID, содержащей идентификатор смарт-карта. Windows Server 2003 и Windows XP: Этот параметр не поддерживается.

[in] pbData

Указатель на буфер данных, содержащий значение, которое будет задано в качестве параметра поставщика. Форма этих данных зависит от значения dwParam . Если dwParam содержит PP_USE_HARDWARE_RNG, этот параметр должен иметь значение NULL.

[in] dwFlags

Если dwParam содержит PP_KEYSET_SEC_DESCR, dwFlags содержит SECURITY_INFORMATION применимые битовые флаги, как определено в пакете SDK для платформы. Безопасность контейнера ключей обрабатывается с помощью SetFileSecurity и GetFileSecurity.

Эти битовые флаги можно объединить с помощью побитовой операции ИЛИ . Дополнительные сведения см. в разделе CryptGetProvParam.

Если параметру dwParamприсвоено значение PP_USE_HARDWARE_RNG или PP_DELETEKEY, параметру dwFlags необходимо задать нулевое значение.

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

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

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

Коды ошибок, предваряемые "NTE", создаются конкретным поставщиком служб CSP. Коды ошибок включают следующие.

Код возврата	Описание
ERROR_BUSY	Контекст CSP в настоящее время используется другим процессом.
ERROR_INVALID_HANDLE	Один из параметров указывает недопустимый дескриптор.
ERROR_INVALID_PARAMETER	Один из параметров содержит недопустимое значение. Чаще всего это недопустимый указатель.
NTE_BAD_FLAGS	Параметр dwFlags не является нулевым или буфер pbData содержит недопустимое значение.
NTE_BAD_TYPE	Параметр dwParam указывает неизвестный параметр.
NTE_BAD_UID	Не удается найти контекст CSP, указанный при создании ключа hKey .
NTE_FAIL	Сбой функции каким-то неожиданным образом.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	wincrypt.h
Библиотека	Advapi32.lib
DLL	Advapi32.dll

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

CryptAcquireContext

CryptGetProvParam

CryptSetKeyParam

Функции поставщика услуг