CryptGetProvParam function (wincrypt.h)

Статья
08/27/2023

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

Функция CryptGetProvParam извлекает параметры, управляющие операциями поставщика служб шифрования (CSP).

Синтаксис

BOOL CryptGetProvParam(
  [in]      HCRYPTPROV hProv,
  [in]      DWORD      dwParam,
  [out]     BYTE       *pbData,
  [in, out] DWORD      *pdwDataLen,
  [in]      DWORD      dwFlags
);

Параметры

[in] hProv

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

[in] dwParam

Характер запроса. Определены следующие запросы.

Значение	Значение
PP_ADMIN_PIN 31 (0x1F)	Возвращает личный идентификационный номер администратора (ПИН-код) в параметре pbData в виде LPSTR.
PP_APPLI_CERT 18 (0x12)	Эта константа не используется.
PP_CHANGE_PASSWORD 7 (0x7)	Эта константа не используется.
PP_CERTCHAIN 9 (0x9)	Возвращает цепочку сертификатов, связанную с дескриптором hProv . Возвращаемая цепочка сертификатов X509_ASN_ENCODING кодируется.
PP_CONTAINER 6 (0x6)	Имя текущего контейнера ключей в виде строки CHAR с пустым завершением. Эта строка в точности совпадает с той, которая передается в параметре pszContainer функции CryptAcquireContext для указания используемого контейнера ключей. Параметр pszContainer можно прочитать, чтобы определить имя контейнера ключей по умолчанию.
PP_CRYPT_COUNT_KEY_USE 41 (0x29)	Не реализовано поставщиками служб конфигурации Майкрософт. Это поведение может быть реализовано другими поставщиками служб конфигурации. Windows XP: Этот параметр не поддерживается.
PP_ENUMALGS 1 (0x1)	Структура PROV_ENUMALGS , содержащая сведения об одном алгоритме, поддерживаемом запрашиваемым поставщиком служб CSP. При первом чтении этого значения параметр dwFlags должен содержать флаг CRYPT_FIRST . Это приводит к тому, что эта функция извлекает первый элемент в перечислении. Последующие элементы можно получить, установив флаг CRYPT_NEXT в параметре dwFlags . Если эта функция завершается сбоем с кодом ошибки ERROR_NO_MORE_ITEMS , то достигается конец перечисления. Эта функция не является потокобезопасной, и все доступные алгоритмы могут не перечисляться, если эта функция используется в многопотоковом контексте.
PP_ENUMALGS_EX 22 (0x16)	Структура PROV_ENUMALGS_EX , содержащая сведения об одном алгоритме, поддерживаемом запрашиваемым поставщиком служб CSP. Возвращаемая структура содержит больше сведений об алгоритме, чем структура, возвращаемая для PP_ENUMALGS. При первом чтении этого значения параметр dwFlags должен содержать флаг CRYPT_FIRST . Это приводит к тому, что эта функция извлекает первый элемент в перечислении. Последующие элементы можно получить, установив флаг CRYPT_NEXT в параметре dwFlags . Если эта функция завершается сбоем с кодом ошибки ERROR_NO_MORE_ITEMS , то достигается конец перечисления. Эта функция не является потокобезопасной, и все доступные алгоритмы могут не перечисляться, если эта функция используется в многопотоковом контексте.
PP_ENUMCONTAINERS 2 (0x2)	Имя одного из контейнеров ключей, поддерживаемых CSP, в виде строки CHAR, завершаемой null. При первом чтении этого значения параметр dwFlags должен содержать флаг CRYPT_FIRST . Это приводит к тому, что эта функция извлекает первый элемент в перечислении. Последующие элементы можно получить, установив флаг CRYPT_NEXT в параметре dwFlags . Если эта функция завершается сбоем с кодом ошибки ERROR_NO_MORE_ITEMS , то достигается конец перечисления. Чтобы перечислить контейнеры ключей, связанные с компьютером, сначала вызовите CryptAcquireContext с помощью флага CRYPT_MACHINE_KEYSET , а затем используйте дескриптор, возвращенный из CryptAcquireContext в качестве параметра hProv в вызове CryptGetProvParam. Эта функция не является потокобезопасной, и все доступные алгоритмы могут не перечисляться, если эта функция используется в многопотоковом контексте.
PP_ENUMELECTROOTS 26 (0x1A)	Эта константа не используется.
PP_ENUMEX_SIGNING_PROT 40 (0x28)	Указывает, что текущий поставщик служб CSP поддерживает член dwProtocolsструктуры PROV_ENUMALGS_EX . Если эта функция выполняется успешно, поставщик служб CSP поддерживает член dwProtocolsструктуры PROV_ENUMALGS_EX . Если эта функция завершается сбоем с кодом ошибки NTE_BAD_TYPE , CSP не поддерживает член dwProtocols .
PP_ENUMMANDROOTS 25 (0x19)	Эта константа не используется.
PP_IMPTYPE 3 (0x3)	Значение DWORD , указывающее, как реализуется CSP. Таблицу возможных значений см. в разделе Примечания.
PP_KEY_TYPE_SUBTYPE 10 (0xA)	Этот запрос не используется.
PP_KEYEXCHANGE_PIN 32 (0x20)	Указывает, что ПИН-код обмена ключами содержится в pbData. ПИН-код представлен в виде строки ASCII, завершаемой null.
PP_KEYSET_SEC_DESCR 8 (0x8)	Извлекает дескриптор безопасности для контейнера хранилища ключей. Параметр pbData — это адрес структуры SECURITY_DESCRIPTOR , которая получает дескриптор безопасности для контейнера хранилища ключей. Дескриптор безопасности возвращается в само относительном формате.
PP_KEYSET_TYPE 27 (0x1B)	Определяет, является ли параметр hProv набором ключей компьютера. Параметр pbData должен быть DWORD; параметрУ DWORD будет присвоен флаг CRYPT_MACHINE_KEYSET, если этот флаг был передан в функцию CryptAcquireContext .
PP_KEYSPEC 39 (0x27)	Возвращает сведения о значениях описателя ключа, поддерживаемых CSP. Значения описателя ключа объединяются в логическом ИЛИ и возвращаются в параметре pbData вызова в виде DWORD. Например, базовый поставщик шифрования Майкрософт версии 1.0 возвращает значение DWORD AT_SIGNATURE \| AT_KEYEXCHANGE.
PP_KEYSTORAGE 17 (0x11)	Возвращает значение DWORD CRYPT_SEC_DESCR.
PP_KEYX_KEYSIZE_INC 35 (0x23)	Число битов для длины приращения AT_KEYEXCHANGE. Эти сведения используются со сведениями, возвращаемыми в PP_ENUMALGS_EX значении. С помощью сведений, возвращаемых при использовании PP_ENUMALGS_EX и PP_KEYX_KEYSIZE_INC, можно определить допустимую длину ключей для AT_KEYEXCHANGE. Затем эти длины ключей можно использовать с CryptGenKey. Например, если CSP перечисляет CALG_RSA_KEYX (AT_KEYEXCHANGE) с минимальной длиной ключа 512 бит и максимальной длиной 1024 бита и возвращает длину приращения в 64 бита, то допустимые длины ключей: 512, 576, 640,... 1024.
PP_NAME 4 (0x4)	Имя поставщика служб конфигурации в виде строки CHAR, завершаемой null. Эта строка идентична той, которая передается в параметре pszProvider функции CryptAcquireContext для указания того, что будет использоваться текущий CSP.
PP_PROVTYPE 16 (0x10)	Значение DWORD , указывающее тип поставщика поставщика CSP.
PP_ROOT_CERTSTORE 46 (0x2E)	Получает корневое хранилище сертификатов для смарт-карта. Это хранилище сертификатов содержит все корневые сертификаты, хранящиеся в смарт-карта. Параметр pbData — это адрес переменной HCERTSTORE , которая получает дескриптор хранилища сертификатов. Если этот дескриптор больше не нужен, вызывающий объект должен закрыть его с помощью функции CertCloseStore . Windows Server 2003 и Windows XP: Этот параметр не поддерживается.
PP_SESSION_KEYSIZE 20 (0x14)	Размер сеансового ключа в битах.
PP_SGC_INFO 37 (0x25)	Используется с шифрованием с серверным шлюзом.
PP_SIG_KEYSIZE_INC 34 (0x22)	Число битов для длины приращения AT_SIGNATURE. Эти сведения используются со сведениями, возвращаемыми в PP_ENUMALGS_EX значении. С помощью сведений, возвращаемых при использовании PP_ENUMALGS_EX и PP_SIG_KEYSIZE_INC, можно определить допустимую длину ключей для AT_SIGNATURE. Затем эти длины ключей можно использовать с CryptGenKey. Например, если CSP перечисляет CALG_RSA_SIGN (AT_SIGNATURE) с минимальной длиной ключа 512 бит и максимальным значением 1024 бита и возвращает длину приращения в 64 бита, то допустимыми длинами ключей являются 512, 576, 640,... 1024.
PP_SIGNATURE_PIN 33 (0x21)	Указывает, что ПИН-код сигнатуры ключа содержится в pbData. ПИН-код представляется в виде строки ASCII, заканчивающейся нулевым значением.
PP_SMARTCARD_GUID 45 (0x2D)	Получает идентификатор смарт-карта. Параметр pbData — это адрес структуры GUID, которая получает идентификатор смарт-карта. Windows Server 2003 и Windows XP: Этот параметр не поддерживается.
PP_SMARTCARD_READER 43 (0x2B)	Получает имя средства чтения смарт-карта. Параметр pbData — это адрес массива символов ANSI, который получает строку ANSI, завершающуюся null, которая содержит имя средства чтения смарт-карта. Размер этого буфера, содержащегося в переменной, на которую указывает параметр pdwDataLen , должен включать признак конца NULL . Windows Server 2003 и Windows XP: Этот параметр не поддерживается.
PP_SYM_KEYSIZE 19 (0x13)	Размер симметричного ключа.
PP_UI_PROMPT 21 (0x15)	Этот запрос не используется.
PP_UNIQUE_CONTAINER 36 (0x24)	Уникальное имя контейнера текущего контейнера ключей в виде строки CHAR, завершаемой null. Для многих поставщиков служб конфигурации это имя совпадает с именем, возвращаемым при использовании значения PP_CONTAINER. Функция CryptAcquireContext должна работать с этим именем контейнера.
PP_USE_HARDWARE_RNG 38 (0x26)	Указывает, поддерживается ли аппаратный генератор случайных чисел (RNG). Если указан PP_USE_HARDWARE_RNG , функция выполняется успешно и возвращает значение TRUE , если поддерживается аппаратный RNG. Функция завершается сбоем и возвращает значение FALSE , если аппаратный RNG не поддерживается. Если RNG поддерживается, PP_USE_HARDWARE_RNG можно задать в CryptSetProvParam , чтобы указать, что CSP должен использовать исключительно аппаратный RNG для этого контекста поставщика. При использовании PP_USE_HARDWARE_RNG параметр pbData должен иметь значение NULL , а dwFlags — ноль. Ни один из поставщиков служб конфигурации Майкрософт в настоящее время не поддерживает использование аппаратного 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_VERSION 5 (0x5)	Номер версии поставщика служб конфигурации. Наименьший значимый байт содержит дополнительный номер версии, а следующий наиболее значимый байт — основной номер версии. Версия 2.0 представлена как 0x00000200. Для обеспечения обратной совместимости с более ранними версиями базового поставщика шифрования Майкрософт и поставщика расширенного шифрования Майкрософт имена поставщиков сохраняют обозначение "версия 1.0" в более поздних версиях.

[out] pbData

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

Этот параметр может иметь значение NULL , чтобы задать размер этих сведений для целей выделения памяти. Дополнительные сведения см. в разделе Извлечение данных неизвестной длины.

[in, out] pdwDataLen

Указатель на значение DWORD , указывающее размер (в байтах) буфера, на который указывает параметр pbData . При возврате функции значение DWORD содержит количество байтов, хранящихся или хранимых в буфере.

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

Если PP_ENUMALGS или PP_ENUMALGS_EX задано, параметр pdwDataLen работает несколько иначе. Если pbData имеет значение NULL или значение, на которое указывает pdwDataLen , слишком мало, то значение, возвращаемое в этом параметре, представляет собой размер самого большого элемента в списке перечисления, а не размер считываемого в данный момент элемента.

Если задано PP_ENUMCONTAINERS, первый вызов функции возвращает максимальный размер контейнера ключей, разрешенный текущим поставщиком. Это отличается от других возможных вариантов поведения, таких как возврат длины самого длинного существующего контейнера или длины текущего контейнера. Последующие вызовы перечисления не изменяют параметр dwLen . Для каждого перечисляемого контейнера вызывающий объект может программно определить длину строки, завершаемой значением NULL, при необходимости. Если одно из значений перечисления считывается, а параметр pbData имеет значение NULL, для правильного извлечения сведений о размере необходимо указать флаг CRYPT_FIRST.

[in] dwFlags

Если параметр dwParamPP_KEYSET_SEC_DESCR, извлекается дескриптор безопасности в контейнере ключей , в котором хранятся ключи. В этом случае dwFlags используется для передачи SECURITY_INFORMATION битовых флагов, которые указывают запрошенные сведения о безопасности, как определено в пакете SDK для платформы. SECURITY_INFORMATION битовые флаги можно объединить с побитовой операцией ИЛИ .

Для использования с PP_KEYSET_SEC_DESCR определены следующие значения.

Значение	Значение
OWNER_SECURITY_INFORMATION	Идентификатор владельца объекта, на который ссылается ссылка.
GROUP_SECURITY_INFORMATION	Ссылка на первичный идентификатор группы объекта.
DACL_SECURITY_INFORMATION	На объект ссылается дискреционный список управления доступом.
SACL_SECURITY_INFORMATION	Системный список ACL объекта, на который ссылается объект .

Следующие значения определяются для использования с PP_ENUMALGS, PP_ENUMALGS_EX и PP_ENUMCONTAINERS.

Значение	Значение
CRYPT_FIRST 1 (0x1)	Получение первого элемента в перечислении. Это имеет тот же эффект, что и сброс перечислителя.
CRYPT_NEXT 2 (0x2)	Получение следующего элемента в перечислении. Если элементов для извлечения больше нет, эта функция завершится ошибкой и присвоит последней ошибке значение ERROR_NO_MORE_ITEMS.
CRYPT_SGC_ENUM 4 (0x4)	Получение сертификатов с поддержкой шифрования с серверным шлюзом (SGC). Сертификаты с поддержкой SGC больше не поддерживаются.
CRYPT_SGC	Этот флаг не используется.
CRYPT_FASTSGC	Этот флаг не используется.

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

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

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

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

Код возврата	Описание
ERROR_INVALID_HANDLE	Один из параметров указывает недопустимый дескриптор.
ERROR_INVALID_PARAMETER	Один из параметров содержит недопустимое значение. Чаще всего это недопустимый указатель.
ERROR_MORE_DATA	Если буфер, заданный параметром pbData , недостаточно велик для хранения возвращаемых данных, функция задает код ERROR_MORE_DATA и сохраняет требуемый размер буфера в байтах в переменной, на которую указывает pdwDataLen.
ERROR_NO_MORE_ITEMS	Достигнут конец списка перечисления. Допустимые данные не были помещены в буфер pbData . Этот код ошибки возвращается, только если значение dwParam равно PP_ENUMALGS или PP_ENUMCONTAINERS.
NTE_BAD_FLAGS	Параметр dwFlags указывает недопустимый флаг.
NTE_BAD_TYPE	Параметр dwParam указывает неизвестное число значений.
NTE_BAD_UID	Контекст CSP, заданный hProv, недопустим.

Значение	Значение
CRYPT_IMPL_HARDWARE 0x01	Реализация выполняется на оборудовании.
CRYPT_IMPL_SOFTWARE 0x02	Реализация осуществляется в программном обеспечении.
CRYPT_IMPL_MIXED 0x03	Реализация включает в себя как оборудование, так и программное обеспечение.
CRYPT_IMPL_UNKNOWN 0x04	Тип реализации неизвестен.
CRYPT_IMPL_REMOVABLE 0x08	Реализация находится на съемном носителе.

Параметр dwFlags используется для передачи SECURITY_INFORMATION битовых флагов, указывающих запрошенные сведения о безопасности. Указатель на дескриптор безопасности возвращается в параметре pbData , а длина дескриптора безопасности возвращается в параметре pdwDataLen . Безопасность контейнера ключей обрабатывается с помощью SetFileSecurity и GetFileSecurity.

Можно определить класс алгоритма, перечисляемого с параметром dwParam , PP_ENUMALGS или PP_ENUMALGS_EX. Это можно сделать, чтобы отобразить список поддерживаемых алгоритмов шифрования и игнорировать остальные. Макрос GET_ALG_CLASS(x) принимает идентификатор алгоритма в качестве аргумента и возвращает код, указывающий общий класс этого алгоритма. Возможные возвращаемые значения:

ALG_CLASS_DATA_ENCRYPT
ALG_CLASS_HASH
ALG_CLASS_KEY_EXCHANGE
ALG_CLASS_SIGNATURE

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

Имя	Идентификатор	Класс
"MD2"	CALG_MD2	ALG_CLASS_HASH
"MD5"	CALG_MD5	ALG_CLASS_HASH
"SHA"	CALG_SHA	ALG_CLASS_HASH
"MAC"	CALG_MAC	ALG_CLASS_HASH
"RSA_SIGN"	CALG_RSA_SIGN	ALG_CLASS_SIGNATURE
"RSA_KEYX"	CALG_RSA_KEYX	ALG_CLASS_KEY_EXCHANGE
"RC2"	CALG_RC2	ALG_CLASS_DATA_ENCRYPT
"RC4"	CALG_RC4	ALG_CLASS_DATA_ENCRYPT

Приложения не должны использовать алгоритм с идентификатором алгоритма, который не распознается. Использование неизвестного алгоритма шифрования может привести к непредсказуемым результатам.

Примеры

В следующем примере показано поиск имени CSP, связанного с дескриптором поставщика служб шифрования, и имени контейнера ключей, связанного с дескриптором. Полный контекст для этого примера см. в разделе Пример программы C: использование CryptAcquireContext.

Другой пример, в котором используется эта функция, см. в разделе Пример программы C: перечисление поставщиков И типов поставщиков CSP.

//-----------------------------------------------------------------
//  Declare and initialize variables.

HCRYPTPROV hCryptProv;
BYTE       pbData[1000];       // 1000 will hold the longest 
                               // key container name.
DWORD cbData;

//-------------------------------------------------------------------
// An HCRYPTPROV must be acquired before using code like that in 
// "Example C Program Using CryptAcquireContext."

//-------------------------------------------------------------------
// Read the name of the default CSP.

cbData = 1000;
if(CryptGetProvParam(
    hCryptProv, 
    PP_NAME, 
    pbData, 
    &cbData, 
    0))
{
    printf("CryptGetProvParam succeeded.\n");
    printf("Provider name: %s\n", pbData);
}
else
{
    printf("Error reading CSP name. \n");
    exit(1);
}
//--------------------------------------------------------------------
// Read the name of the default key container.

cbData = 1000;
if(CryptGetProvParam(
    hCryptProv, 
    PP_CONTAINER, 
    pbData, 
    &cbData, 
    0))
{
    printf("CryptGetProvParam succeeded. \n");
    printf("Key Container name: %s\n", pbData);
}
else
{
    printf("Error reading key container name. \n");
    exit(1);
}

Требования

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