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

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

Синтаксис

BOOL CryptGetKeyParam(
  [in]      HCRYPTKEY hKey,
  [in]      DWORD     dwParam,
  [out]     BYTE      *pbData,
  [in, out] DWORD     *pdwDataLen,
  [in]      DWORD     dwFlags
);

Параметры

[in] hKey

Дескриптор запрашиваемого ключа.

[in] dwParam

Указывает тип выполняемого запроса.

Для всех типов ключей этот параметр может содержать одно из следующих значений.

Значение Значение
KP_ALGID
 Получение алгоритма ключа. Параметр pbData является указателем на значение ALG_ID , которое получает идентификатор алгоритма, указанного при создании ключа.

Если для параметра Algid функции CryptGenKey указано AT_KEYEXCHANGE или AT_SIGNATURE, идентификаторы алгоритма, используемые для создания ключа, зависят от используемого поставщика. Дополнительные сведения см. в разделе ALG_ID.
KP_BLOCKLEN
 Если ключ сеанса указан параметром hKey , получите длину блока шифра ключа. Параметр pbData является указателем на значение DWORD , которое получает длину блока в битах. Для потоковых шифров это значение всегда равно нулю.

Если пара открытого и закрытого ключей указана с помощью hKey, получите степень детализации шифрования пары ключей. Параметр pbData является указателем на значение DWORD , которое получает степень детализации шифрования в битах. Например, базовый поставщик шифрования Майкрософт создает 512-разрядные пары ключей RSA, поэтому для этих ключей возвращается значение 512. Если алгоритм открытого ключа не поддерживает шифрование, полученное значение не определено.
KP_CERTIFICATE
 pbData — это адрес буфера, получающего сертификат X.509, закодированный с помощью Distinguished Encoding Rules (DER). Открытый ключ в сертификате должен соответствовать соответствующей подписи или ключу обмена.
KP_GET_USE_COUNT
 Это значение не используется.
KP_KEYLEN
 Получение фактической длины ключа. Параметр pbData является указателем на значение DWORD , которое получает длину ключа в битах. KP_KEYLEN можно использовать для получения длины ключа любого типа. Поставщики служб шифрования (CSP) Майкрософт возвращают длину ключа в 64 бита для CALG_DES, 128 бит для CALG_3DES_112 и 192 бита для CALG_3DES. Эти длины отличаются от длины, возвращаемой при перечислении алгоритмов со значением dwParam функции CryptGetProvParam , равным PP_ENUMALGS. Длина, возвращаемая этим вызовом, представляет собой фактический размер ключа, включая биты четности, включенные в ключ.

Поставщики служб конфигурации Майкрософт, поддерживающие CALG_CYLINK_MEK ALG_ID возвращают 64 бита для этого алгоритма. CALG_CYLINK_MEK является 40-разрядным ключом, но имеет четность и нулевые биты ключа, чтобы сделать ключ длиной 64 бита.
KP_SALT
 Получение значения соли ключа. Параметр pbData является указателем на массив BYTE , который получает значение соли в форме с малым эндианом . Размер значения соли зависит от используемого CSP и алгоритма. Значения salt не применяются к парам открытых и закрытых ключей.
KP_PERMISSIONS
 Получите разрешения ключа. Параметр pbData является указателем на значение DWORD , которое получает флаги разрешений для ключа.

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

CRYPT_ARCHIVE
Разрешить экспорт в течение времени существования дескриптора ключа. Это разрешение можно задать, только если оно уже задано в поле внутренних разрешений ключа. Попытки очистить это разрешение игнорируются.
CRYPT_DECRYPT
Разрешить расшифровку.
CRYPT_ENCRYPT
Разрешить шифрование.
CRYPT_EXPORT
Разрешите экспорт ключа.
CRYPT_EXPORT_KEY
Разрешите использование ключа для экспорта ключей.
CRYPT_IMPORT_KEY
Разрешите использование ключа для импорта ключей.
CRYPT_MAC
Разрешить использование кодов проверки подлинности сообщений (MACs) с ключом.
CRYPT_READ
Разрешить чтение значений.
CRYPT_WRITE
Разрешить задание значений.
 

Если ключ стандарта цифровой подписи (DSS) указан параметром hKey , для значения dwParam также можно задать одно из следующих значений.

Значение Значение
KP_P
 Получение простого номера модуля P ключа DSS. Параметр pbData является указателем на буфер, который получает значение в виде байтового значения. Параметр pdwDataLen содержит размер буфера в байтах.
KP_Q
 Получение простого номера модуля Q ключа DSS. Параметр pbData является указателем на буфер, который получает значение в виде байтового значения. Параметр pdwDataLen содержит размер буфера в байтах.
KP_G
 Получите генератор G ключа DSS. Параметр pbData является указателем на буфер, который получает значение в виде байтового значения. Параметр pdwDataLen содержит размер буфера в байтах.
 

Если ключ сеансаблочного шифра указан параметром hKey, для значения dwParam также можно задать одно из следующих значений.

Значение Значение
KP_EFFECTIVE_KEYLEN
 Получение эффективной длины ключа RC2. Параметр pbData является указателем на значение DWORD , которое получает действующую длину ключа.
KP_IV
 Получение вектора инициализации ключа. Параметр pbData является указателем на массив BYTE , получающий вектор инициализации. Размер этого массива равен размеру блока в байтах. Например, если длина блока составляет 64 бита, вектор инициализации состоит из 8 байт.
KP_PADDING
 Получение режима заполнения. Параметр pbData является указателем на значение DWORD , которое получает числовой идентификатор, идентифицирующий метод заполнения , используемый шифром. Это может быть одно из следующих значений.
PKCS5_PADDING
Задает метод заполнения PKCS 5 (sec 6.2).
RANDOM_PADDING
Заполнение использует случайные числа. Этот метод заполнения не поддерживается поставщиками служб конфигурации, предоставленными Корпорацией Майкрософт.
ZERO_PADDING
Заполнение использует нули. Этот метод заполнения не поддерживается поставщиками служб конфигурации, предоставленными Корпорацией Майкрософт.
KP_MODE
 Получение режима шифра. Параметр pbData является указателем на значение DWORD , которое получает идентификатор режима шифра. Дополнительные сведения о режимах шифра см. в разделе Шифрование и расшифровка данных.

В настоящее время определены следующие идентификаторы режима шифра.

CRYPT_MODE_CBC
Режим шифра — это цепочка блоков шифров.
CRYPT_MODE_CFB
Режим шифра — это обратная связь с шифром (CFB). Поставщики служб конфигурации Майкрософт в настоящее время поддерживают только 8-разрядную обратную связь в режиме обратной связи с шифром.
CRYPT_MODE_ECB
Режимом шифра является электронный кодовой сборник.
CRYPT_MODE_OFB
Режимом шифра является выходная обратная связь (OFB). Поставщики служб конфигурации Майкрософт в настоящее время не поддерживают режим обратной связи на выходе.
CRYPT_MODE_CTS
Режим шифра — это режим кражи зашифрованного текста .
KP_MODE_BITS
 Получение количества битов для обратной отправки. Параметр pbData — это указатель на значение DWORD , которое получает количество битов, обрабатываемых за цикл при использовании режимов шифра OFB или CFB.
 

Если ключ алгоритма Диффи-Хелмана или алгоритма цифровой подписи (DSA) указан с помощью hKey, то для значения dwParam можно также задать следующее значение.

Значение Значение
KP_VERIFY_PARAMS
 Проверяет параметры алгоритма Diffie-Hellman или ключа DSA. Параметр pbData не используется, и значение, на которое указывает pdwDataLen , получает ноль.

Эта функция возвращает ненулевое значение, если параметры ключа допустимы, или ноль в противном случае.
KP_KEYVAL
 Это значение не используется.

Windows Vista, Windows Server 2003 и Windows XP: Получите значение соглашения секрета из импортированного ключа алгоритма Диффи-Хелмана типа CALG_AGREEDKEY_ANY. Параметр pbData — это адрес буфера, который получает значение соглашения секрета в формате с минимальным байтом. Длина этого буфера должна совпадать с длиной ключа. Параметру dwFlags необходимо задать значение 0xF42A19B6. Это свойство может получить только поток, работающий под локальной системной учетной записью. Это свойство доступно для использования в перечисленных выше операционных системах. В последующих версиях он может быть изменен или недоступен.
 

Если сертификат указан с помощью hKey, то для значения dwParam можно также задать следующее значение.

Значение Значение
KP_CERTIFICATE
 Буфер, содержащий сертификат X.509 в кодировке DER. Параметр pbData не используется, и значение, на которое указывает pdwDataLen , получает ноль.

Эта функция возвращает ненулевое значение, если параметры ключа допустимы, или ноль в противном случае.

[out] pbData

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

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

[in, out] pdwDataLen

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

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

[in] dwFlags

Этот параметр зарезервирован для использования в будущем и должен иметь нулевое значение.

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

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

Если функция завершается сбоем, она возвращает ноль. Для получения дополнительных сведений об ошибке вызовите Метод GetLastError.

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

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

Требования

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

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

CryptSetKeyParam

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