Функция CryptSetKeyParam (wincrypt.h)
Базовый поставщик шифрования Майкрософт не разрешает задавать значения для ключей обмена ключами или ключей подписи; однако пользовательские поставщики могут определять значения, которые можно задать для его ключей.
Синтаксис
BOOL CryptSetKeyParam(
[in] HCRYPTKEY hKey,
[in] DWORD dwParam,
[in] const BYTE *pbData,
[in] DWORD dwFlags
);
Параметры
[in] hKey
Дескриптор ключа, для которого необходимо задать значения.
[in] dwParam
Следующие таблицы содержат предопределенные значения, которые можно использовать.
Для всех типов ключей этот параметр может содержать одно из следующих значений.
| Значение | Значение |
|---|---|
|
pbData указывает на соответствующий ALG_ID. Это используется при обмене ключами сеанса с microsoft Base Digital Signature Standard (DSS), Diffie-Hellman поставщиком шифрования или совместимыми CSP. После согласования ключа с функцией CryptImportKey ключ сеанса включается для использования, задав тип алгоритма. |
|
pbData — это адрес буфера, содержащего сертификат X.509, закодированный с помощью Distinguished Encoding Rules (DER). Открытый ключ в сертификате должен соответствовать соответствующей подписи или ключу обмена. |
|
pbData указывает на значение DWORD , указывающее ноль или более флагов разрешений. Описание этих флагов см. в разделе CryptGetKeyParam. |
|
pbData указывает на массив BYTE , указывающий новое значение соли , которое будет сделано частью ключа сеанса. Размер значения соли зависит от используемого CSP. Прежде чем задать это значение, определите размер значения соли, вызвав функцию CryptGetKeyParam . Значения salt используются, чтобы сделать ключи сеанса более уникальными, что усложняет атаки по словарю. Значение соли по умолчанию равно нулю для базового поставщика шифрования Майкрософт. |
|
pbData указывает на CRYPT_INTEGER_BLOB структуру, содержащую соль. Дополнительные сведения см. в разделе Указание значения соли. |
Если ключ стандарта цифровой подписи (DSS) указан параметром hKey , для значения dwParam также можно задать одно из следующих значений.
| Значение | Значение |
|---|---|
|
pbData указывает на генератор G из BLOB-объекта ключа DSS. Данные имеют форму структуры CRYPT_INTEGER_BLOB , где элемент pbData — это значение, а член cbData — это длина значения. Ожидается, что значение не содержит сведений о заголовке и имеет конечную форму. |
|
pbData указывает на основной модуль P большого двоичного объекта ключа DSS. Данные в виде структуры CRYPT_INTEGER_BLOB . Элемент pbData — это значение, а член cbData — это длина значения. Ожидается, что значение не содержит сведений о заголовке и имеет конечную форму. |
|
pbData указывает на основной Q большого двоичного объекта ключа DSS. Данные имеют форму структуры CRYPT_INTEGER_BLOB , где элемент pbData — это значение, а член cbData — это длина значения. Ожидается, что значение не содержит сведений о заголовке и имеет конечную форму. |
|
После установки значений P, Q и G функцию CryptSetKeyParam можно выполнить вызов, указывающий значение KP_X для dwParam и NULL для параметра pbData. Это приводит к созданию значений X и Y. |
Если ключ алгоритма Диффи-Хелмана или алгоритма цифровой подписи (DSA) указан с помощью hKey, для значения dwParam также можно задать одно из следующих значений.
| Значение | Значение |
|---|---|
|
Задает сведения для импортированного ключа Diffie-Hellman . Параметр pbData — это адрес структуры CMS_DH_KEY_INFO , содержащей задающиеся ключевые сведения. |
|
Задает открытые параметры (P, Q, G и т. д.) ключа DSS или Diffie-Hellman. Дескриптор ключа для этого ключа должен находиться в состоянии PREGEN, созданном с помощью флага CRYPT_PREGEN. Параметр pbData должен быть указателем на структуру DATA_BLOB , где данные в этой структуре являются DHPUBKEY_VER3 или DSSPUBKEY_VER3 BLOB. Функция копирует открытые параметры из этой структуры CRYPT_INTEGER_BLOB в дескриптор ключа. После выполнения этого вызова значение параметра KP_X следует использовать с CryptSetKeyParam для создания фактического закрытого ключа. Параметр KP_PUB_PARAMS используется как один вызов, а не несколько вызовов со значениями параметров KP_P, KP_Q и KP_G. |
Если ключ сеансаблочного шифра указан параметром hKey, для значения dwParam также можно задать одно из следующих значений.
| Значение | Значение |
|---|---|
|
Этот тип значения можно использовать только с ключами RC2 и добавлен из-за реализации функции CryptSetKeyParam в поставщике расширенного шифрования Майкрософт до Windows 2000. В предыдущей реализации ключи RC2 в расширенном поставщике имели длину 128 бит, но эффективная длина ключа, используемая для расширения ключей в таблицу ключей, составляла всего 40 бит. Это уменьшило прочность алгоритма до 40 бит. Для обеспечения обратной совместимости предыдущая реализация останется прежней. Однако эффективная длина ключа может быть больше 40 бит с помощью KP_EFFECTIVE_KEYLEN в вызове CryptSetKeyParam . Эффективная длина ключа передается в параметре pbData в качестве указателя на значение DWORD с эффективным значением длины ключа. Минимальная эффективная длина ключа в базовом поставщике шифрования Майкрософт составляет один, а максимальная — 40. В поставщике расширенного шифрования Майкрософт минимальное значение равно 1, а максимальное — 1024. Длина ключа должна быть задана перед шифрованием или расшифровкой с помощью ключа. |
|
Задает максимально допустимую версию TLS. Это свойство применяется только к ключам SSL и TLS. Параметр pbData — это адрес переменной DWORD , содержащей самый высокий поддерживаемый номер версии TLS. |
|
pbData указывает на массив BYTE , указывающий вектор инициализации. Этот массив должен содержать элементы BlockLength/8. Например, если длина блока составляет 64 бита, вектор инициализации состоит из 8 байт.
Вектор инициализации по умолчанию равен нулю для базового поставщика шифрования Майкрософт. |
|
Задайте значение ключа для стандартного ключа шифрования данных (DES). Параметр pbData — это адрес буфера, содержащего ключ. Длина этого буфера должна совпадать с длиной ключа. Это свойство применяется только к ключам DES. |
|
Установите режим заполнения. Параметр pbData является указателем на значение DWORD , которое получает числовой идентификатор, идентифицирующий метод заполнения , используемый шифром. Это может быть одно из следующих значений.
|
|
pbData указывает на значение DWORD , указывающее используемый режим шифра . Список определенных режимов шифра см. в разделе CryptGetKeyParam. Режим шифра по умолчанию CRYPT_MODE_CBC для базового поставщика шифрования Майкрософт. |
|
pbData указывает на значение DWORD , указывающее количество битов, обработанных в цикле при использовании режима шифрования обратной связи на выходе (OFB) или cipher Feedback (CFB). Число битов, обрабатываемых в цикле, по умолчанию равно 8 для базового поставщика служб шифрования Майкрософт. |
Если ключ RSA указан в параметре hKey , значение параметра dwParam может быть следующим.
| Значение | Значение |
|---|---|
|
Задайте параметры Оптимальное заполнение асимметричного шифрования (OAEP) (PKCS #1 версии 2) для ключа. Параметр pbData — это адрес структуры CRYPT_DATA_BLOB , содержащей метку OAEP. Это свойство применяется только к ключам RSA. |
Обратите внимание, что следующие значения не используются:
- KP_ADMIN_PIN
- KP_CMS_KEY_INFO
- KP_INFO
- KP_KEYEXCHANGE_PIN
- KP_PRECOMP_MD5
- KP_PRECOMP_SHA
- KP_PREHASH
- KP_PUB_EX_LEN
- KP_PUB_EX_VAL
- KP_RA
- KP_RB
- KP_ROUNDS
- KP_RP
- KP_SIGNATURE_PIN
- KP_Y
[in] pbData
Указатель на буфер, инициализированный со значением, которое необходимо задать перед вызовом CryptSetKeyParam. Форма этих данных зависит от значения dwParam.
[in] dwFlags
Используется только при KP_ALGID dwParam . Параметр dwFlags используется для передачи значений флагов для включенного ключа. Параметр dwFlags может содержать такие значения, как размер ключа и другие значения флагов, допустимые при создании ключа того же типа с помощью CryptGenKey. Сведения о допустимых значениях флагов см. в разделе CryptGenKey.
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение не равно нулю (TRUE).
Если функция завершается ошибкой, возвращаемое значение равно нулю (FALSE). Для получения дополнительных сведений об ошибке вызовите Метод GetLastError.
Коды ошибок, предваряемые "NTE", создаются конкретным поставщиком служб конфигурации. Ниже приведены некоторые возможные коды ошибок.
| Код возврата | Описание |
|---|---|
|
Контекст CSP в настоящее время используется другим процессом. |
|
Один из параметров указывает недопустимый дескриптор. |
|
Один из параметров содержит недопустимое значение. Чаще всего это недопустимый указатель. |
|
Параметр dwFlags не равен нулю, или буфер pbData содержит недопустимое значение. |
|
Параметр dwParam указывает неизвестный параметр. |
|
Не удается найти контекст CSP, указанный при создании ключа hKey . |
|
Сбой функции каким-то непредвиденным образом. |
|
Некоторые CSP имеют жестко заданные значения P, Q и G. В этом случае эта ошибка возникает при использовании KP_P, KP_Q и KP_G для значения dwParam . |
Комментарии
Если параметры KP_Q, KP_P или KP_X заданы для ключа PREGEN Diffie-Hellman или DSS, длина ключа должна быть совместима с длиной ключа , заданной с помощью верхних 16 бит параметра dwFlags при создании ключа с помощью CryptGenKey. Если длина ключа не задана в CryptGenKey, используется длина ключа по умолчанию. Это приведет к ошибке, если для задания P, Q или X используется длина ключа, не являющегося по умолчанию.
Примеры
Пример использования этой функции см. в разделе Пример программы C: дублирование ключа сеанса. Дополнительные сведения о коде, в котором используется эта функция, см. в разделе Пример программы C: настройка и получение параметров ключа сеанса .
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows XP [только классические приложения] |
| Минимальная версия сервера | Windows Server 2003 [только классические приложения] |
| Целевая платформа | Windows |
| Header | wincrypt.h |
| Библиотека | Advapi32.lib |
| DLL | Advapi32.dll |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по