DWORD CPCAPI CPCGenKey( HCRYPTMODULE hCSP, HCRYPTPROV hProv, ALG_ID AlgId, DWORD dwFlags, HCRYPTKEY * phKey );
Значение AlgId | Описание |
---|---|
CALG_G28147 | Ключ шифрования и/или имитозащиты данных по ГОСТ 28147-89. Впоследствии этот ключ можно пометить как ключ для импорта/экспорта с помощью функции CPCSetKeyParam(). |
CALG_TLS1_MASTER | Специальный ключ для реализации протокола TLS. |
AlgId | Описание |
---|---|
CALG_UECSYMMETRIC_EPHEM | Эфемерный симметричный ключ. Предназначен для управления ключами в системе Универсальная электронная карта. |
CALG_DH_EL_EPHEM | Эфемерная ключевая пара на базе ГОСТ Р 34.10-2001. Предназначена для обмена сессионными ключами. |
CALG_DH_GR3410_12_256_EPHEM | Эфемерная ключевая пара на базе ГОСТ Р 34.10-2012 с длиной ключа 256 бит. Предназначена для обмена сессионными ключами. |
CALG_DH_GR3410_12_512_EPHEM | Эфемерная ключевая пара на базе ГОСТ Р 34.10-2012 с длиной ключа 512 бит. Предназначена для обмена сессионными ключами. |
AlgId | Описание |
---|---|
AT_KEYEXCHANGE | Производится ключевая пара, сохраняемая в ключевом контейнере. Предназначена для обмена сессионными ключами и ЭП. В качестве алгоритма ключевой пары выбирается алгоритм по умолчанию для hProv, параметр PP_DHOID функции CPGetProvParam(). |
CALG_DH_EL_SF | Производится ключевая пара согласно ГОСТ Р 34.10-2001. Предназначена для обмена сессионными ключами и ЭП, в ключевой контейнер не заносится. |
CALG_DH_GR3410_12_256_SF | Производится ключевая пара согласно ГОСТ Р 34.10-2012 с длиной ключа 256 бит. Предназначена для обмена сессионными ключами и ЭП, в ключевой контейнер не заносится. |
CALG_DH_GR3410_12_512_SF | Производится ключевая пара согласно ГОСТ Р 34.10-2012 с длиной ключа 512 бит. Предназначена для обмена сессионными ключами и ЭП, в ключевой контейнер не заносится. |
AT_SIGNATURE | Производится ключевая пара, сохраняемая в ключевом контейнере. Предназначена для ЭП. В качестве алгоритма ключевой пары выбирается алгоритм по умолчанию для hProv, параметр PP_SIGNATUREOID функции CPGetProvParam(). |
CALG_GR3410EL | Производится ключевая пара согласно ГОСТ Р 34.10-2001, в ключевой контейнер не заносится. |
CALG_GR3410_12_256 | Производится ключевая пара согласно ГОСТ Р 34.10-2012 с длиной ключа подписи 256 бит, в ключевой контейнер не заносится. |
CALG_GR3410_12_512 | Производится ключевая пара согласно ГОСТ Р 34.10-2012 с длиной ключа подписи 512 бит, в ключевой контейнер не заносится. |
AT_UECSYMMETRICKEY | Производится симметричный пользовательский ключ. Предназначен для использования как мастерключ в системе производства ключей карт. Заносится в ключевой контейнер. |
CALG_UECSYMMETRIC | Производится симметричный ключ. Если генерация ключа производится в именованном контексте, где нет ключа AT_UECSYMMETRICKEY, создаваемый ключ заносится в ключевой контейнер. Предназначен для использования как мастер-ключ в системе производства ключей карт. В ключевой контейнер заносится, если соответствующий AT_UECSYMMETRICKEY в ключевом контейнере отсутствует. |
Значение dwFlags | Описание |
---|---|
CRYPT_EXPORTABLE | Если этот флаг установлен, то произведённый ключ может быть передан из криптопровайдера в ключевой блоб через функцию CPCExportKey(). Если этот флаг не установлен, ключ не будет экспортируемым и будет доступен только в пределах текущей сессии приложению, которое создало этот ключ. Действие этого флага не распространяются на открытые ключи ключевых пар. Экспорт закрытых ключей ключевых пар 2001 года возможен только на эфемерных ключах и ключах с алгоритмом CALG_PRO_EXPORT и CALG_PRO12_EXPORT. Экспорт закрытых ключей ключевых пар 2012 года возможен только на эфемерных ключах и ключах с алгоритмом CALG_PRO12_EXPORT. |
CRYPT_ARCHIVABLE | Если этот флаг установлен, то произведённый ключ может быть передан из криптопровайдера в ключевой блоб через функцию CPCExportKey() только в в том контексте провайдера (сессии), в котором он был создан, и только до вызова функции CPCDestroyKey() на дескриптор ключа. Данный флаг не может быть установлен одновременно с флагом CRYPT_EXPORTABLE. При экспорте ключа с этим флагом, создаётся CRYPT_PRIVATEKEYBLOB со сброшенным флагом pkaExportable. Экспорт закрытых ключей ключевых пар 2001 года возможен только на эфемерных ключах и ключах с алгоритмом CALG_PRO_EXPORT и CALG_PRO12_EXPORT. Экспорт закрытых ключей ключевых пар 2012 года возможен только на эфемерных ключах и ключах с алгоритмом CALG_PRO12_EXPORT. |
CRYPT_USER_PROTECTED | Если этот флаг установлен, то при любом запросе на доступ к носителю закрытого ключа пользователя выводится окно диалога, запрашивающего право доступа к ключу. |
CRYPT_PREGEN | Если этот флаг установлен, то генерируется "пустая" ключевая пара обмена. Параметры этой ключевой пары должны быть установлены с использованием функции CPCSetKeyParam(). |
CP_CRYPT_DH_ALLOWED | Если этот флаг установлен, то закрытый ключ произведенной ключевой пары может быть использован для согласования сессионного ключа с помощью алгоритма Диффи-Хеллмана (VKO). Если данный флаг не указан, то для ключевых пар электронной подписи 2012 года согласование будет запрещено. Для ключевых пар обмена разрешено всегда. |
Коды возврата | Описание |
---|---|
ERROR_INVALID_PARAMETER | Один из параметров содержит некорректное значение. Чаще всего это некорректный указатель. |
NTE_BAD_ALGID | Параметр AlgId определяет алгоритм, не поддерживаемый криптопровайдером. Эта ошибка возвращается также в случае попытки генерации пользовательских ключей AT_KEYEXCHANGE и AT_SIGNATURE криптопровайдером, сертифицированным по уровню KC2 и выше, при отсутствии физического ДСЧ в составе СКЗИ. |
NTE_BAD_FLAGS | Величина dwFlags имеет ошибочное значение. |
NTE_NO_MEMORY | Криптопровайдер во время операции исчерпал память. |
NTE_FAIL | Ошибка при считывании данных из системного реестра. см. Дополнительные параметры и определения . |
SCARD_W_CANCELLED_BY_USER | Пользователь прервал операцию нажатием клавиши Cancel |
SCARD_W_WRONG_CHV | Пользователь ввёл неправильный пароль или пароль, установленный функцией SetProvParam(), неправильный |
SCARD_E_INVALID_CHV | Пользователь ввёл пароль с нарушением формата или пароль, установленный функцией SetProvParam(), имеет неправильный формат. Например, пароль имеет недопустимую длину или содержит недопустимые символы. |
SCARD_W_CHV_BLOCKED | Ввод Pin-кода был заблокирован смарт-картой, т.к. исчерпалось количество попыток разрешенное картой для ввода. |
NTE_TOKEN_KEYSET_STORAGE_FULL | Недостаточно места на носителе для сохранения информации. |
NTE_SILENT_CONTEXT | Операция не может быть выполнена без пользовательского интерфейса. |
SCARD_W_REMOVED_CARD | Носитель контейнера был удален из считывателя. |
NTE_EXISTS | Попытка создания ключа в контейнере, где ключ уже существует. |
Если при запросе функции CPCAcquireContext() был создан ключевой контейнер с признаком CRYPT_VERIFYCONTEXT, прикладные программы не могут создавать долговременные ключевые пары. В этом случае функция CPCGenKey() возвращает код ошибки NTE_PERM. Когда ключи порождаются для симметричного шифрования, по умолчанию ключ будет установлен в шифратор в режиме гаммирования с обратной связью (CFB) со случайным начальным вектором. Эти параметры могут быть получены с использованием функции CPCSetKeyParam() и частично изменены функцией CPCSetKeyParam()
Функция CPCGenKey() получает ключ с программного ДСЧ криптопровайдера. Для инициализации программного ДСЧ с физического ДСЧ, следует использовать функцию CPCSetProvParam() с флагом PP_USE_HARDWARE_RNG. В варианте исполнения КС2 без такой инициализации генерация ключей невозможна.
Ключи AT_UECSYMMETRICKEY, CALG_UECSYMMETRIC, CALG_UECSYMMETRIC_EPHEM имеют ограниченный функционал, предназначены для использования в ключевых системах Универсальных Электронных Карт. Данные ключи не рекомендуется использоваться в иных системах.
Заметим, что, в соответствии с общепринятой мировой практикой, в качестве длины ключа при создании указывается именно длина открытого ключа, а не присутствующая в идентификаторах алгоритмов и oid'ах длина модуля, по которому производятся операции. В отличие от, например, алгоритма RSA (в реализациях которого открытая экспонента, как правило, фиксирована, а открытый ключ представляет собой модуль n), длина открытого ключа в стандартах подписи, основанных на операциях в группе точек эллиптической кривой (ECDSA, ГОСТ Р 34.10-2001, ГОСТ Р 34.10-2012), в два раза превосходит длину модуля.
При генерации ключа подписи/обмена выбор соответствующего алгоритма производится в зависимости от типа используемого провайдера. Провайдер типа PROV_GOST_2001_DH создает ключи в соответствии с алгоритмом ГОСТ Р 34.10-2001, используется функция хэширования в соответствии с ГОСТ Р 34.11-94. Провайдер типа PROV_GOST_2012_256 создает ключи длины 256 бит в соответствии с алгоритмом ГОСТ Р 34.10-2012, в качестве алгоритма хэширования использует алгоритм ГОСТ Р 34.11-2012 (256 бит). Провайдер типа PROV_GOST_2012_512 создает ключи длины 512 бит в соответствии с алгоритмом ГОСТ Р 34.10-2012, в качестве алгоритма хэширования использует алгоритм ГОСТ Р 34.11-2012 (512 бит).
При генерации сессионного ключа CALG_G28147 параметр KP_CIPHEROID полученного ключа по умолчанию принимает установленное для провайдера значение PP_CIPHEROID, либо, после загрузки ключей из контейнера с помощью CPCGetUserKey(), oid параметров шифрования, установленный в этом контейнере.
Для создания эфемеральных ключей необходимого типа с определёнными параметрами алгоритма Диффи-Хеллмана необходимо: сгенерировать "пустую" ключевую пару командой CPCGenKey(hCSP, hProv, algId, CRYPT_PREGEN, &hKey); затем установить тип параметров алгоритмов Диффи-Хеллмана командой CPCSetKeyParam(hCSP, hProv, hKey, KP_DHOID, pbOIDdata, 0); после чего непосредственно выработать значение ключа с помощью команды CPCSetKeyParam(hCSP, hProv, hKey, KP_X, NULL, 0);
Полученный дескриптор ключа должен в обязательном порядке быть удалён с помощью вызова функции CPCDestroyKey() до вызова функции CPCReleaseContext() для рабочего дескриптора криптопровайдера.
Ядро 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