Функция CPCGenKey() генерирует случайные криптографические ключи или ключевую пару (закрытый/открытый ключи).

DWORD CPCAPI CPCGenKey(
  HCRYPTMODULE hCSP,
  HCRYPTPROV hProv,
  ALG_ID AlgId,
  DWORD dwFlags,
  HCRYPTKEY * phKey
);

Аргументы

hCSP

[in] Указатель на таблицу функций криптопровайдера. Получается при помощи функции CPCCreateProvider()

hProv

[in] Дескриптор криптопровайдера. Получается при помощи функции CPCAcquireContext().

AlgId

[in] Идентификатор алгоритма шифрования или ЭЦП, для которого производится ключ. Могут быть произведены ключи следующих классов:

• временные симметричные ключи (сессионные ключи);
• временные (эфемерные) ключевые пары алгоритмов Диффи-Хеллмана;
• долговременные ключевые пары, сохраняемые в ключевом контейнере.

Возможные сессионые ключи:

Значение AlgId	Описание
CALG_G28147	Ключ шифрования и/или имтозащиты данных по ГОСТ 28147-89. Впоследствии этот ключ можно пометить как ключ для импорта/экспорта с помощью функции CPCSetKeyParam().
CALG_TLS1_MASTER	Специальный ключ для реализации протокола TLS.

Возможные эфемерные ключи Диффи-Хеллмана:

AlgId	Описание
CALG_UECSYMMETRIC_EPHEM	Эфемерный симметричный ключ. Предназначен для управления ключами в системе Универсальная электронная карта.
CALG_DH_EL_EPHEM	Эфемерная ключевая пара на базе ГОСТ Р 34.10-2001. Предназначена для обмена сессионными ключами.

Возможные долговременные ключевые пары:

AlgId	Описание
AT_KEYEXCHANGE	Производится ключевая пара, сохраняемая в ключевом контейнере. Предназначена для обмена сессионными ключами и ЭЦП. В качестве алгоритма ключевой пары выбирается алгоритм по умолчанию для hProv, параметр PP_DHOID CPCGetProvParam().
CALG_DH_EL_SF	Производится ключевая пара согласно ГОСТ Р 34.10-2001. Предназначена для обмена сессионными ключами и ЭЦП, в ключевой контейнер не заносится.
AT_SIGNATURE	Производится ключевая пара, сохраняемая в ключевом контейнере. Предназначена для ЭЦП. В качестве алгоритма ключевой пары выбирается алгоритм по умолчанию для hProv, параметр PP_SIGNATUREOID функции CPCGetProvParam().
CALG_GR3410EL	Производится ключевая пара согласно ГОСТ Р 34.10-2001. Предназначена для ЭЦП. Используется в криптопровайдере "КриптоПро ГОСТ Р 34.10-2001 CSP" и эквивалентна AT_SIGNATURE, но в ключевой контейнер не заносится.
AT_UECSYMMETRICKEY	Производится симметричный поьзовательский ключ. Предназначен для использования как мастерключ в системе производства ключей карт. Заносится в ключевой контейнер.
CALG_UECSYMMETRIC	Производится симметричный ключ. Если генерация ключа производится в именованном контексте, где нет ключа AT_UECSYMMETRICKEY, создаваемый ключ заносится в ключевой контейнер. Предназначен для использования как мастер-ключ в системе производства ключей карт. В ключевой контейнер заносится, если соответствующий AT_UECSYMMETRICKEY в ключевом контейнере отсутствует.

dwFlags

[in] Флаги определяют признаки производимого ключа. Размеры ключей подписи и ключей обмена могут быть установлены при выработке ключа. Размер ключа устанавливается в старших 16 битах параметра dwFlags, эти 16 бит представляют размер модуля в битах. Размер модуля ключа равен 512 (для ГОСТ Р 34.10-2001). В настоящее время определенны следующие флаги:

Значение dwFlags	Описание
CRYPT_EXPORTABLE	Если этот флаг установлен, то произведённый ключ может быть передан из криптопровайдера в ключевой блоб через функцию CPCExportKey(). Если этот флаг не установлен, ключ не будет экспортируемым и будет доступен только в пределах текущей сессии приложению, которое создало этот ключ. Действие этого флага не распространяются на открытые ключи ключевых пар. Экспорт закрытых ключей ключевых пар возможен только на эфемерных ключах и ключах с алгоритмом CALG_PRO_EXPORT.
CRYPT_ARCHIVABLE	Если этот флаг установлен, то произведённый ключ может быть передан из криптопровайдера в ключевой блоб через функцию CPCExportKey() только в в том контексте провайдера (сессии), в котором он был создан, и только до вызова функции CPCDestroyKey() на дескриптор ключа. Данный флаг не может быть установлен одновременно с флагом CRYPT_EXPORTABLE. При экспорте ключа с этим флагом, создаётся CRYPT_PRIVATEKEYBLOB со сброшенным флагом pkaExportable. Экспорт закрытых ключей ключевых пар возможен только на эфемерных ключах и ключах с алгоритмом CALG_PRO_EXPORT.
CRYPT_USER_PROTECTED	Если этот флаг установлен, то при любом запросе на доступ к носителю закрытого ключа пользователя выводится окно диалога, запрашивающего право доступа к ключу.
CRYPT_PREGEN	Если этот флаг установлен, то генерируется "пустая" ключевая пара обмена. Параметры этой ключевой пары должны быть установлены с использованием функции CPCSetKeyParam().

phKey

[out] Адрес, по которому функция копирует дескриптор сформированного ключа (ключевой пары открытый/закрытый ключи).

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

При успешном завершении функция возвращает 0 (S_OK), в противном случае возвращается соответствующий код ошибки (см. таблицу).

Примечания

Если при запросе функции CPCAcquireContext() был создан ключевой контейнер с признаком CRYPT_VERIFYCONTEXT, прикладные программы не могут создавать долговременные ключевые пары. В этом случае функция CPCGenKey() возвращает код ошибки NTE_PERM. Когда ключи порождаются для симметричного шифрования, по умолчанию ключ будет установлен в шифратор в режиме гаммирования с обратной связью (CFB) со случайным начальным вектором. Эти параметры могут быть получены с использованием функции CPCSetKeyParam() и частично изменены функцией CPCSetKeyParam()

Функция CPCGenKey() получает ключ с программного ДСЧ криптопровайдера. Для инициализации программного ДСЧ с физического ДСЧ, следует использовать функцию CPCSetProvParam() с флагом PP_USE_HARDWARE_RNG. В варианте исполнения КС2 без такой инициализации генерация ключей невозможна.

Ключи AT_UECSYMMETRICKEY, CALG_UECSYMMETRIC, CALG_UECSYMMETRIC_EPHEM имеют ограниченный функционал, предназначены для использования в ключевых системах Универсальных Электронных Карт. Данные ключи не рекомендуется использоваться в иных системах.

Требования:

Ядро FreeBSD: 7/8/9 или выше
Ядро Linux: ядро 2.4.x/2.6.x/3.0.х/3.2.х или выше
Ядро Solaris: 10/11 или выше.
Ядро Windows 2000 или выше: Необходимо Windows 2000 SP4 или старше.
Ядро ОС: При использовании в ядре ОС CPCGenKey допустимо вызывать только для производства ключей сессии и эфемеральных ключей.

См. также

CPCDestroyKey() ,CPCExportKey() ,CPCImportKey() ,CPCGetKeyParam() ,CPCSetKeyParam() ,CPCReleaseContext() ,CPGenKey в MS CSP ,CryptGenKey в MS CryptoAPI 2.0