Функция 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, которое получает идентификатор алгоритма, указанного при создании ключа.

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

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

Поставщики СЛУЖБ Майкрософт, поддерживающие CALG_CYLINK_MEKALG_ID возвращают 64 бита для этого алгоритма. CALG_CYLINK_MEK является 40-разрядным ключом, но имеет четность и ноль битов ключей, чтобы сделать длину ключа 64 битами.
KP_SALT
 Получите значение соли ключа. Параметр pbData — это указатель на массив BYTE, который получает значение соли в малоконечной форме. Размер значения соли зависит от используемого CSP и алгоритма. Значения соли не применяются к парам открытых и закрытых ключей .
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 (с 6.2).
RANDOM_PADDING
При заполнении используются случайные числа. Этот метод заполнения не поддерживается предоставленными корпорацией Майкрософт поставщиком поставщиков служб.
ZERO_PADDING
Заполнение использует нули. Этот метод заполнения не поддерживается предоставленными корпорацией Майкрософт поставщиком поставщиков служб.
KP_MODE
 Получение режима шифра . Параметр pbData — это указатель на значение DWORD, которое получает идентификатор режима шифра. Дополнительные сведения о режимах шифров см. в шифрования и расшифровки.

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

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

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

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

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

Windows Vista, Windows Server 2003 и Windows XP: получить значение секретного соглашения из импортированного алгоритма Diffie-Hellman ключа типа 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, создаются конкретным используемым поставщиком служб CSP. Ниже приведены некоторые возможные коды ошибок.

Возвращаемый код Описание
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 [только классические приложения]
целевая платформа Виндоус
заголовка wincrypt.h
библиотеки Advapi32.lib
DLL Advapi32.dll

См. также

CryptSetKeyParam

функции создания ключей и функций Exchange