КриптоПро CSP  

CPCGetKeyParam

Функция CPCGetKeyParam() возвращает параметры ключа.

DWORD CPCAPI CPCGetKeyParam(
  HCRYPTMODULE hCSP,
  HCRYPTPROV hProv,
  HCRYPTKEY hKey,
  DWORD dwParam,
  BYTE * pbData,
  DWORD * pdwDataLen,
  DWORD dwFlags
);

Аргументы

hCSP
[in] Указатель на таблицу функций криптопровайдера. Получается при помощи функции CPCCreateProvider()
hProv
[in] Дескриптор криптопровайдера. Получается при помощи функции CPCAcquireContext().
hKey
[in] Дескриптор ключа, параметры которого возвращаются.
dwParam
[in] Параметр, принимающий следующие возможные значения:
Значение dwParam Содержимое буфера pbData
KP_ALGID Идентификатор алгоритма (ALG_ID), соответствующий данному ключу.
KP_PERMISSIONS Флаги разрешения использования ключа. Возвращаются в виде переменной типа DWORD.
KP_IV Возвращает начальное значение вектора инициализации (IV или синхропосылки) алгоритма шифрования. Если ключ использовался в вызове CPCEncrypt() или CPCDecrypt() с параметром Final = FALSE, то значение данного параметра остается неизменным до вызова соответствующей функции с параметром Final = TRUE. По завершению работы функции начальное значение синхропосылки изменяется на случайное. До вызова CPCEncrypt() или CPCDecrypt() с параметром Final = FALSE значение параметра может быть изменено с помощью функции CPCSetKeyParam().
KP_IV_BLOB Возвращает начальное значение вектора инициализации (IV или синхропосылки) для алгоритма VKO GOST R 34.10-2012-256 и шифрования по ГОСТ Р 34.12-2015.
KP_CERTIFICATE Получение сертификата из контейнера (из носителя).
KP_MODE Режим алгоритма шифрования. Возвращается в виде переменной типа DWORD. Для ключей CALG_G28147 используются режимы шифрования:
  • CRYPT_MODE_ECB - блочный шифр простой замены ГОСТ 28147-89;
  • CRYPT_MODE_CNT - шифрование гаммированием ГОСТ 28147-89;
  • CRYPT_MODE_CFB - шифрование гаммированием с обратной связью ГОСТ 28147-89;
  • CRYPT_MODE_CBCRFC4357 - блочный шифр с обратной связью на базе ГОСТ 28147-89, согласно RFC 4357;
  • CRYPT_MODE_CBCSTRICT - блочный шифр с обратной связью на базе ГОСТ 28147-89, шифртекст блока всегда является IV для следующего. Рекомендуется для использования только для обеспечения совместимости с существующими продуктами.
Для ключей CALG_GR3412_2015_M, CALG_GR3412_2015_K используются следующие режимы шифрования, определенные в ГОСТ Р 34.13-2015:
  • CRYPT_MODE_ECB - шифрование в режиме простой замены;
  • CRYPT_MODE_CBC - шифрование в режиме простой замены с зацеплением;
  • CRYPT_MODE_OFB - шифрование гаммированием с обратной связью по выходу;
  • CRYPT_MODE_CFB - шифрование гаммированием с обратной связью по шифртексту;
  • CRYPT_MODE_CTR - шифрование гаммированием;
а также режим, определённый в рекомендациях по стандартизации Р 1323565.1.026-2019 "Режимы работы блочных шифров, реализующие аутентифицированное шифрование":
  • CRYPT_MODE_MGM - шифрование в AEAD-режиме Multilinear Galois Mode.
KP_PADDING Способ дополнения. Величина DWORD, содержащая метод дополнения, используемый шифром ключа, передаётся функции через буфер pbData. В настоящее время определены следующие способы дополнения:
  • PKCS5_PADDING - PKCS#5.(См ПРИМЕЧАНИЕ в данном разделе и ПРИМЕЧАНИЕ к CryptSetKeyParam в MS CryptoAPI 2.0 World Wide Web link )
  • ZERO_PADDING - дополнение нулевыми байтами,
  • RANDOM_PADDING - дополнение случайными байтами,
  • ISO10126_PADDING - дополнение в соответствии с ISO 10126,
  • ANSI_X923_PADDING - дополнение в соответствии с ANSI X.923.
При первоначальной выработке ключа по умолчанию устанавливается значение PKCS5_PADDING.
KP_AUTH_TAG Получение тэга аутентификации при шифровании в AEAD-режиме. Может быть использовано при шифровании потока данных после вызова CPCEncrypt() с финализацией (флагом Final = TRUE) или непосредственно после установки аутентифицируемых данных через CPCSetKeyParam() с параметром KP_AUTH_DATA.
KP_MODE_BITS

Глубина обратной связи. Возвращается в виде переменной типа DWORD. Для CALG_G28147 значение этой величины равно 64, что соответствует режиму гаммирования с обратной связью ГОСТ 28147-89.

Для ключей CALG_GR3412_2015_M и CALG_GR3412_2015_K определяет длину блока гаммы и по умолчанию равно 64 и 128 бит соответственно.

KP_MIXMODE Режим преобразования ключа. Возвращается в виде переменной типа DWORD. Используются режимы преобразования:
  • CRYPT_PROMIX_MODE - преобразование ключей CALG_G28147 после зашифрования каждых 1024 байт информации.
  • CRYPT_ACPKM_MODE - преобразование ключей CALG_GR3412_2015_M и CALG_GR3412_2015_K после зашифрования X байт, где X определяется для CALG_GR3412_2015_M и CALG_GR3412_2015_K как 128 и 256, соответственно, умноженное на длину блока гаммы в байтах.
  • CRYPT_SIMPLEMIX_MODE - без преобразования.
KP_MIX_BLOCK_SIZE Количество зашифрований блока данных, после которого производится смена ключа при работе в режиме CRYPT_PROMIX_MODE для алгоритмов CALG_GR3412_2015_M и CALG_GR3412_2015_K. По умолчанию имеет значения 128 и 256 соответственно.
KP_KEYLEN Длина ключа в битах. Возвращается в виде переменной типа DWORD. Для ключей шифрования в параметре pbData возвращается длина ключа, для ключевых пар возвращается длина открытого ключа.
KP_BLOCKLEN Длина блока шифрования, обрабатываемого криптопровайдером. Возвращается в виде переменной типа DWORD. В случае сессионного ключа если для ключа установлен режим блочного шифрованя (CRYPT_MODE_ЕСB, CRYPT_MODE_CBС), в параметре pbData устанавливается размер блока алгоритмов ГОСТ 28147-89 или ГОСТ Р 34.12-2015 в зависимости от типа ключа, если установлен режим поточного шифрования (CRYPT_MODE_CNT, CRYPT_MODE_CFB), в параметре pbData устанавливается значение оптимального с точки зрения скорости шифрования размера блока, принимаемого от приложения (в настоящее время 8Кбит). В случае ключевой пары в параметре pbData устанавливается число бит модуля q для ключей на базе эллиптической кривой (ГОСТ Р 34.10-2001 и ГОСТ Р 34.10-2012).
KP_CIPHEROID Идентификатор узла замены, устанавливаемого приложением. Строковая величина с признаком конца строки.
KP_DHOID Идентификатор алгоритма Диффи-Хеллмана. Строка, заканчивающаяся нулем.
KP_SIGNATUREOID Идентификатор алгоритма подписи. Строка, заканчивающаяся нулем.
KP_HASHOID Идентификатор функции хэширования, устанавливаемой приложением. Строка, заканчивающаяся нулем.
KP_DELTA Возвращает значение дельты после установки на пользовательский ключ значение синхропосылки. В pbData указавает на данные – 32 байта дельты. Специфика протокола ООО "КРИПТО-ПРО" взаимодействия с функциональным ключевым носителем.
KP_FP Возвращает первые 8 байт открытого ключа.
KP_NOTAFTER См. Сроки действия долговременных ключей в "КриптоПро CSP 5.0" .
KP_UEC_DERIVE_COUNTER Для ключа типа AT_UECSYMMETRICKEY возвращает значение счетчика ключей, полученных диверсификацией данного. Возвращается в виде переменной типа DWORD.
pbData
[out] Указатель на буфер данных параметра. Функция копирует соответствующие параметру данные в буфер. Формат этих данных зависит от значения dwParam. Если параметр - NULL, то данные не копируются. Требуемый размер буфера в байтах возвращается в pdwDataLen. Подробнее см. Возвращение данных неопределенной длины.
pdwDataLen
[in/out] Указатель на буфер, содержащий длину данных параметра. При вызове функции указанный параметр содержит число байтов в буфере pbData. После её выполнения параметр будет установлен числом байтов данных параметра, скопированных в буфер pbData. Если буфер, соответствующий pbData, недостаточно велик, чтобы в него копировать запрошенные данные, через функцию GetLastError() будет возвращен код ошибки ERROR_MORE_DATA. В этом случае требуемый размер буфера возвращается в pdwDataLen. Если эта функция завершается с кодом ошибки, отличным от ERROR_MORE_DATA, в этом параметре возвращается ноль.
dwFlags
[in] Значения флагов. Параметр зарезервирован для будущего использования и должен быть нулевым.

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

При успешном завершении функция возвращает 0 (S_OK), в противном случае возвращается соответствующий код ошибки (см. таблицу).
Коды возвратаОписание
ERROR_INVALID_PARAMETERОдин из параметров содержит некорректное значение. Чаще всего это некорректный указатель.
ERROR_MORE_DATAРазмер буфера pbData недостаточен для копирования затребованных данных.
NTE_BAD_FLAGSПараметр dwFlags имеет ненулевое значение.
NTE_BAD_TYPEПараметр dwParam передаёт неизвестное значение параметра.
NTE_BAD_KEYДескриптор ключа ошибочен.
NTE_PERMПопытка чтения ключевых параметров, когда право чтения криптопровайдером не представлено.
SCARD_E_NO_SUCH_CERTIFICATEПри попытке получения сертификата, когда сертификат отсутствует.
SCARD_E_NO_KEY_CONTAINERПопытка выполнения операции в контексте смарт-карты или токена, а не контейнера.
SCARD_W_SECURITY_VIOLATIONФукции безопасности токена или смарт-карты работают некорректно.
ERROR_PASSWORD_EXPIREDПароль данного носителя истек, необходимо его сменить.
SCARD_E_READ_ONLY_CARDСмарт-карта недоступна для использования из-за ограничений безопасности.

Примечания

Синхропосылка ключа для шифрования по алгоритмам ГОСТ 28147-89 и ГОСТ Р 34.12-2015 вырабатывается криптопровайдером автоматически с установкой типа ключа CALG_28147 и CALG_GR3412_2015_M/CALG_GR3412_2015_K (сессионный ключ) соответственно. Эту синхропосылку рекомендуется получить на передающем конце из ключа с помощью функции CPCGetKeyParam() для значения pvParam KP_IV для CALG_28147 и KP_IV_BLOB для CALG_GR3412_2015_M/CALG_GR3412_2015_K. На приёмном конце значение синхропосылки устанавливается на ключ функцией CPCSetKeyParam() при значении pvParam KP_IV для CALG_28147 и KP_IV_BLOB для CALG_GR3412_2015_M/CALG_GR3412_2015_K. Если требуется задание синхропосылки из приложения, то ее рекомендуется вырабатывать с помощью функции CPCGenRandom(). Использовать в системе другие алгоритмы образования синхропосылок можно только по согласованию с разработчиком криптопровайдера.

Требования:

Ядро AIX: 6/7.
Ядро FreeBSD: 11/12.
Ядро Linux: 2.6.x и выше.
Ядро Solaris: 10/11.
Ядро Windows: 7/8/8.1/10, Server 2008/2008R2/2012/2012R2/2016/2019.

См. также

CPCSetKeyParam() ,CPGetKeyParam в MS CSP World Wide Web link ,CryptGetKeyParam в MS CryptoAPI 2.0 World Wide Web link