Навигация

Функции управления ключами

C_GenerateKey

CK_RV C_GenerateKey(CK_SESSION_HANDLE hSession, CK_MECHANISM_PTR pMechanism, CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulCount, CK_OBJECT_HANDLE_PTR phKey)
Параметры:
  • hSession (in) – дескриптор сеанса.
  • pMechanism (in) – указатель на механизм.
  • pTemplate (in) – указатель на шаблон объекта ключа.
  • ulCount (in) – количество атрибутов в шаблоне.
  • phKey (in/out) – идентификатор создаваемого ключа.

Генерирует секретный ключ.

Особенности апплетов:

  • Криптотокен

    Поддерживаемые механизмы:

    • CKM_GOST28147_KEY_GEN (0x00001220) – механизм генерации ключей, соответствующий стандарту ГОСТ 28147–89.

  • Криптотокен 2 ЭП

    Предупреждение

    Согласно правилам пользования сертифицированного устройства JaCarta-2 ГОСТ данная операция должна выполняться с использованием ПО «АРМ администратора безопасности JaCarta-2 ГОСТ».
    Для облегчения процесса интеграции JaCarta-2 ГОСТ в прикладное ПО в ходе работ по разработке и тестированию допускается использовать облегчённую версию этого АРМа – «АРМ разработчика JaCarta-2 ГОСТ», входящего в состав комплекта разработчика JaCarta-2 SDK.

  • Laser

    Поддерживаемые механизмы:

    • CKM_DES2_KEY_GEN (0x00000130) – механизм генерации ключей DES двойной длины.
    • CKM_DES3_KEY_GEN (0x00000131) – механизм генерации ключей для алгоритма triple-DES.
    • CKM_TLS_PRE_MASTER_KEY_GEN (0x00000374) – механизм генерации 48-байтных секретных ключей, используемых при создании pre_master ключей для протокола TLS 1.0.
    • CKM_AES_KEY_GEN (0x00001080) – механизм генерации ключей для алгоритма AES.

Запускается в режимах

Результат:
  • CKR_ARGUMENTS_BAD – недопустимые аргументы.
  • CKR_ATTRIBUTE_READ_ONLY – невозможно установить значение атрибута, т.к. он поддерживает только чтение.
  • CKR_ATTRIBUTE_TYPE_INVALID – недопустимый тип атрибута.
  • CKR_ATTRIBUTE_VALUE_INVALID – недопустимое значение атрибута.
  • CKR_CRYPTOKI_NOT_INITIALIZED – функция не может быть выполнена, т.к. библиотека еще не была инициализирована (см. C_Initialize()).
  • CKR_DEVICE_ERROR – возникла проблема с токеном и/или слотом.
  • CKR_DEVICE_MEMORY – памяти токена недостаточно для данной операции.
  • CKR_DEVICE_REMOVED – токен был изъят из слота.
  • CKR_FUNCTION_CANCELED – функция была отменена в момент исполнения.
  • CKR_FUNCTION_FAILED – выполнение функции было прервано или она не может быть выполнена.
  • CKR_GENERAL_ERROR – общий сбой при работе с библиотекой.
  • CKR_HOST_MEMORY – компьютер, на котором запущена библиотека, не имеет достаточно памяти для выполнения функции.
  • CKR_MECHANISM_INVALID – недопустимый механизм.
  • CKR_MECHANISM_PARAM_INVALID – недопустимый параметр механизма.
  • CKR_OK – функция выполнена успешно.
  • CKR_OPERATION_ACTIVE – на устройстве уже есть активная операция, что не позволяет активизировать данную операцию.
  • CKR_PIN_EXPIRED – срок действия указанного PIN-кода истек.
  • CKR_SESSION_CLOSED – сеанс был закрыт в момент выполнения функции.
  • CKR_SESSION_HANDLE_INVALID – недопустимый дескриптор сеанса.
  • CKR_SESSION_READ_ONLY – сеанс открыт только на чтение.
  • CKR_TEMPLATE_INCOMPLETE – шаблон, указанный для создания объекта, неполон.
  • CKR_TEMPLATE_INCONSISTENT – шаблон, указанный для создания объекта, содержит конфликтующие атрибуты.
  • CKR_TOKEN_WRITE_PROTECTED – данный токен защищен от записи.
  • CKR_USER_NOT_LOGGED_IN – действие не может быть выполнено, т.к. пользователь не залогинен.

Совет

Полный список ошибок см. в приложении.

Пример использования

Пример генерации сессионного ключа на языке C:

static CK_BYTE id_Gost28147_89_CryptoPro_A_ParamSet[] = { 0x06, 0x07, 0x2A, 0x85, 0x03, 0x02, 0x02, 0x1F, 0x01 };

// результат выполнения функции
CK_RV rv = CKR_OK;

// дескриптор сессии
CK_SESSION_HANDLE pkcs11SessionHandle;

// механизм генерации ключей
CK_MECHANISM pkcs11GenKeyMechanism = {CKM_GOST28147_KEY_GEN, NULL, 0};

// шаблон ключа
CK_ATTRIBUTE pkcs11SessionKeyTemplate[] =
{
  {CKA_GOST28147_PARAMS, id_Gost28147_89_CryptoPro_A_ParamSet, sizeof(id_Gost28147_89_CryptoPro_A_ParamSet)}
};

// дескриптор сессионного ключа PKCS#11
CK_OBJECT_HANDLE pkcs11SessionKeyHandle;

// функция генерирует ключ, используя заданный шаблон
rv = C_GenerateKey(pkcs11SessionHandle,
                   &pkcs11GenKeyMechanism,
                   pkcs11SessionKeyTemplate,
                   sizeof(pkcs11SessionKeyTemplate)/sizeof(CK_ATTRIBUTE),
                   &pkcs11SessionKeyHandle);
if(rv != CKR_OK)
{
  PrintError("C_GenerateKey", rv);
  return;
}
Возможные значения атрибута CKA_GOST28147_PARAMS описаны в приложении.
Более полную информацию о работе с объектами смотри в приложении.

C_GenerateKeyPair

CK_RV C_GenerateKeyPair(CK_SESSION_HANDLE hSession, CK_MECHANISM_PTR pMechanism, CK_ATTRIBUTE_PTR pPublicKeyTemplate, CK_ULONG ulPublicKeyAttributeCount, CK_ATTRIBUTE_PTR pPrivateKeyTemplate, CK_ULONG ulPrivateKeyAttributeCount, CK_OBJECT_HANDLE_PTR phPublicKey, CK_OBJECT_HANDLE_PTR phPrivateKey)
Параметры:
  • hSession (in) – дескриптор сеанса.
  • pMechanism (in) – указатель на механизм.
  • pPublicKeyTemplate (in) – шаблон открытого ключа.
  • ulPublicKeyAttributeCount (in) – количество атрибутов в шаблоне открытого ключа.
  • pPrivateKeyTemplate (in) – шаблон закрытого ключа.
  • ulPrivateKeyAttributeCount (in) – количество атрибутов в шаблоне закрытого ключа.
  • phPublicKey (in/out) – указатель, получающий дескриптор созданного открытого ключа.
  • phPrivateKey (in/out) – указатель, получающий дескриптор созданного закрытого ключа.

Генерирует ключевую пару и возвращает идентификаторы закрытого и открытого ключей.

Поддерживаются следующие механизмы:

  • Криптотокен

    • CKM_GOSTR3410_KEY_PAIR_GEN (0x00001200) – механизм генерации ключевой пары в соответствии со стандартом ГОСТ Р 34.10–2001.

  • Криптотокен 2 ЭП

    • CKM_GOSTR3410_KEY_PAIR_GEN (0x00001200) – механизм генерации ключевой пары в соответствии со стандартом ГОСТ Р 34.10–2001.
    • CKM_GOSTR3410_256_KEY_PAIR_GEN (0x00001200 идентичен CKM_GOSTR3410_KEY_PAIR_GEN) – механизм генерации ключевой пары в соответствии со стандартом ГОСТ Р 34.10–2012 (длина ключа 256 бит).

    Для генерации ключевых пар конкретного стандарта, помимо указания механизма, необходимо передавать соответствующее значение в атрибут CKA_GOSTR3411_PARAMS шаблона открытого ключа.

    Стандарт ключевой пары Механизм Значение CKA_GOSTR3411_PARAMS
    ГОСТ Р 34.10–2001 CKM_GOSTR3410_KEY_PAIR_GEN id-GostR3411-94-CryptoProParamSet
    ГОСТ Р 34.10–2012 (длина ключа 256 бит) CKM_GOSTR3410_256_KEY_PAIR_GEN id-tc26-gost3411-12-256

    Совет

    Значения атрибута CKA_GOSTR3411_PARAMS см. в приложении.

  • Laser

    • CKM_RSA_PKCS_KEY_PAIR_GEN (0x00000000) – механизм генерации ключевой пары для алгоритма RSA.
    • CKM_ECDSA_KEY_PAIR_GEN (0x00001040) – механизм генерации ключевой пары для алгоритма ECDSA.
    • CKM_EC_KEY_PAIR_GEN (0x00001040) – механизм генерации ключевой пары для алгоритма EC.

Запускается в режимах

Результат:
  • CKR_ARGUMENTS_BAD – недопустимые аргументы.
  • CKR_ATTRIBUTE_READ_ONLY – невозможно установить значение атрибута, т.к. он поддерживает только чтение.
  • CKR_ATTRIBUTE_TYPE_INVALID – недопустимый тип атрибута.
  • CKR_ATTRIBUTE_VALUE_INVALID – недопустимое значение атрибута.
  • CKR_CRYPTOKI_NOT_INITIALIZED – функция не может быть выполнена, т.к. библиотека еще не была инициализирована (см. C_Initialize()).
  • CKR_DEVICE_ERROR – возникла проблема с токеном и/или слотом.
  • CKR_DEVICE_MEMORY – памяти токена недостаточно для данной операции.
  • CKR_DEVICE_REMOVED – токен был изъят из слота.
  • CKR_DOMAIN_PARAMS_INVALID – недопустимые или неподдерживаемые параметры домена.
  • CKR_FUNCTION_CANCELED – функция была отменена в момент исполнения.
  • CKR_FUNCTION_FAILED – выполнение функции было прервано или она не может быть выполнена.
  • CKR_GENERAL_ERROR – общий сбой при работе с библиотекой.
  • CKR_HOST_MEMORY – компьютер, на котором запущена библиотека, не имеет достаточно памяти для выполнения функции.
  • CKR_MECHANISM_INVALID – недопустимый механизм.
  • CKR_MECHANISM_PARAM_INVALID – недопустимый параметр механизма.
  • CKR_OK – функция выполнена успешно.
  • CKR_OPERATION_ACTIVE – на устройстве уже есть активная операция, что не позволяет активизировать данную операцию.
  • CKR_PIN_EXPIRED – срок действия указанного PIN-кода истек.
  • CKR_SESSION_CLOSED – сеанс был закрыт в момент выполнения функции.
  • CKR_SESSION_HANDLE_INVALID – недопустимый дескриптор сеанса.
  • CKR_SESSION_READ_ONLY – сеанс открыт только на чтение.
  • CKR_TEMPLATE_INCOMPLETE – шаблон, указанный для создания объекта, неполон.
  • CKR_TEMPLATE_INCONSISTENT – шаблон, указанный для создания объекта, содержит конфликтующие атрибуты.
  • CKR_TOKEN_WRITE_PROTECTED – данный токен защищен от записи.
  • CKR_USER_NOT_LOGGED_IN – действие не может быть выполнено, т.к. пользователь не залогинен.

Совет

Полный список ошибок см. в приложении.

Примеры Криптотокен

Пример генерации ключевой пары ГОСТ Р 34.10–2001 на языке C:

static CK_BYTE id_GostR3410_2001_CryptoPro_A_ParamSet[] = { 0x06, 0x07, 0x2A, 0x85, 0x03, 0x02, 0x02, 0x23, 0x01 };
static CK_BYTE id_GostR3411_94_CryptoProParamSet[] = { 0x06, 0x07, 0x2A, 0x85, 0x03, 0x02, 0x02, 0x1E, 0x01 };

CK_BBOOL bTrue = CK_TRUE;
CK_BBOOL bFalse = CK_FALSE;

// результат выполнения функции
CK_RV rv = CKR_OK;

// дескриптор сессии
CK_SESSION_HANDLE session;

// механизм генерации ключевой пары
CK_MECHANISM mechanism = {CKM_GOSTR3410_KEY_PAIR_GEN, NULL, 0};

// параметры шаблона закрытого ключа
CK_OBJECT_CLASS privKeyClass = CKO_PRIVATE_KEY;
CK_UTF8CHAR privKeyLabel[] = "Private Key GOST R 34.10-2001";
CK_KEY_TYPE privKeyType = CKK_GOSTR3410;

// шаблон закрытого ключа
CK_ATTRIBUTE privKeyTemplate[] =
{
  {CKA_CLASS, &privKeyClass, sizeof(privKeyClass)},                           // класс
  {CKA_KEY_TYPE, &privKeyType, sizeof(privKeyType)},                          // тип ключа
  {CKA_TOKEN, (CK_VOID_PTR) &bTrue, sizeof(bTrue)},                           // объект хранится в токене
  {CKA_LABEL, (CK_VOID_PTR) privKeyLabel, (CK_ULONG) strlen(privKeyLabel)},   // метка закрытого ключа
  {CKA_PRIVATE, &bTrue,  sizeof(bTrue) },                                     // не виден без ввода PIN-кода пользователя
};

// параметры шаблона открытого ключа
CK_OBJECT_CLASS pubKeyClass = CKO_PUBLIC_KEY;
CK_UTF8CHAR pubKeyLabel[] = "Public Key GOST R 34.10-2001";
CK_KEY_TYPE pubKeyType = CKK_GOSTR3410;

// шаблон открытого ключа
CK_ATTRIBUTE pubKeyTemplate[] =
{
  {CKA_CLASS, &privKeyClass, sizeof(privKeyClass)},                           // класс
  {CKA_KEY_TYPE, &privKeyType, sizeof(privKeyType)},                          // тип ключа
  {CKA_TOKEN, (CK_VOID_PTR) &bTrue, sizeof(bTrue)},                           // объект хранится в токене
  {CKA_LABEL, (CK_VOID_PTR) pubKeyLabel, (CK_ULONG) strlen(pubKeyLabel)},     // метка закрытого ключа
  {CKA_PRIVATE, &bFalse,  sizeof(bFalse) },                                   // виден без ввода PIN-кода пользователя

  {
    CKA_GOSTR3410_PARAMS,
    (CK_VOID_PTR) id_GostR3410_2001_CryptoPro_A_ParamSet,
    sizeof(id_GostR3410_2001_CryptoPro_A_ParamSet)
  },                                                                          // тип ключевой пары

  {
    CKA_GOSTR3411_PARAMS,
    (CK_VOID_PTR) id_GostR3411_94_CryptoProParamSet,
    sizeof(id_GostR3411_94_CryptoProParamSet)
  }                                                                            // стандарт алгоритма хэширования
};

// дескрипторы открытого и закрытого ключа ключевой пары PKCS#11
CK_OBJECT_HANDLE pubKeyHandle, privKeyHandle;

// функция генерирует ключевую пару
rv = C_GenerateKeyPair(session,
                       &mechanism,
                       pubKeyTemplate, sizeof(pubKeyTemplate)/sizeof(CK_ATTRIBUTE),
                       privKeyTemplate, sizeof(privKeyTemplate)/sizeof(CK_ATTRIBUTE),
                       &pubKeyHandle,
                       &privKeyHandle);
if(rv != CKR_OK)
{
  PrintError("C_GenerateKeyPair", rv);
  return;
}
Значения атрибута CKA_GOSTR3410_PARAMS описаны в приложении.
Значения атрибута CKA_GOSTR3411_PARAMS описаны в приложении.
Более полную информацию о работе с объектами смотри в приложении.

Примеры Криптотокен 2 ЭП

Пример генерации ключевой пары ГОСТ Р 34.10–2001 на языке C:

static CK_BYTE id_GostR3410_2001_CryptoPro_A_ParamSet[] = { 0x06, 0x07, 0x2A, 0x85, 0x03, 0x02, 0x02, 0x23, 0x01 };
static CK_BYTE id_GostR3411_94_CryptoProParamSet[] = { 0x06, 0x07, 0x2A, 0x85, 0x03, 0x02, 0x02, 0x1E, 0x01 };

CK_BBOOL bTrue = CK_TRUE;
CK_BBOOL bFalse = CK_FALSE;

// результат выполнения функции
CK_RV rv = CKR_OK;

// дескриптор сессии
CK_SESSION_HANDLE session;

// механизм генерации ключевой пары
CK_MECHANISM mechanism = {CKM_GOSTR3410_KEY_PAIR_GEN, NULL, 0};

// параметры шаблона закрытого ключа
CK_OBJECT_CLASS privKeyClass = CKO_PRIVATE_KEY;
CK_UTF8CHAR privKeyLabel[] = "Private Key GOST R 34.10-2001";
CK_KEY_TYPE privKeyType = CKK_GOSTR3410;

// шаблон закрытого ключа
CK_ATTRIBUTE privKeyTemplate[] =
{
  {CKA_CLASS, &privKeyClass, sizeof(privKeyClass)},                           // класс
  {CKA_KEY_TYPE, &privKeyType, sizeof(privKeyType)},                          // тип ключа
  {CKA_TOKEN, (CK_VOID_PTR) &bTrue, sizeof(bTrue)},                           // объект хранится в токене
  {CKA_LABEL, (CK_VOID_PTR) privKeyLabel, (CK_ULONG) strlen(privKeyLabel)},   // метка закрытого ключа
  {CKA_PRIVATE, &bTrue,  sizeof(bTrue) },                                     // не виден без ввода PIN-кода пользователя
};

// параметры шаблона открытого ключа
CK_OBJECT_CLASS pubKeyClass = CKO_PUBLIC_KEY;
CK_UTF8CHAR pubKeyLabel[] = "Public Key GOST R 34.10-2001";
CK_KEY_TYPE pubKeyType = CKK_GOSTR3410;

// шаблон открытого ключа
CK_ATTRIBUTE pubKeyTemplate[] =
{
  {CKA_CLASS, &privKeyClass, sizeof(privKeyClass)},                           // класс
  {CKA_KEY_TYPE, &privKeyType, sizeof(privKeyType)},                          // тип ключа
  {CKA_TOKEN, (CK_VOID_PTR) &bTrue, sizeof(bTrue)},                           // объект хранится в токене
  {CKA_LABEL, (CK_VOID_PTR) pubKeyLabel, (CK_ULONG) strlen(pubKeyLabel)},     // метка закрытого ключа
  {CKA_PRIVATE, &bFalse,  sizeof(bFalse) },                                   // виден без ввода PIN-кода пользователя

  {
    CKA_GOSTR3410_PARAMS,
    (CK_VOID_PTR) id_GostR3410_2001_CryptoPro_A_ParamSet,
    sizeof(id_GostR3410_2001_CryptoPro_A_ParamSet)
  },                                                                          // тип ключевой пары

  {
    CKA_GOSTR3411_PARAMS,
    (CK_VOID_PTR) id_GostR3411_94_CryptoProParamSet,
    sizeof(id_GostR3411_94_CryptoProParamSet)
  }                                                                           // стандарт алгоритма хэширования
};

// дескрипторы открытого и закрытого ключа ключевой пары PKCS#11
CK_OBJECT_HANDLE pubKeyHandle, privKeyHandle;

// функция генерирует ключевую пару
rv = C_GenerateKeyPair(session,
                       &mechanism,
                       pubKeyTemplate, sizeof(pubKeyTemplate)/sizeof(CK_ATTRIBUTE),
                       privKeyTemplate, sizeof(privKeyTemplate)/sizeof(CK_ATTRIBUTE),
                       &pubKeyHandle,
                       &privKeyHandle);
if(rv != CKR_OK)
{
  PrintError("C_GenerateKeyPair", rv);
  return;
}

Пример генерации ключевой пары ГОСТ Р 34.10–2012 (длина ключа 256 бит) на языке C:

static CK_BYTE id_GostR3410_2001_CryptoPro_A_ParamSet[] = { 0x06, 0x07, 0x2A, 0x85, 0x03, 0x02, 0x02, 0x23, 0x01 };
static CK_BYTE id_tc26_gost3411_12_256[] = { 0x06, 0x08, 0x2A, 0x85, 0x03, 0x07, 0x01, 0x01, 0x02, 0x02 };

CK_BBOOL bTrue = CK_TRUE;
CK_BBOOL bFalse = CK_FALSE;

// результат выполнения функции
CK_RV rv = CKR_OK;

// дескриптор сессии
CK_SESSION_HANDLE session;

// механизм генерации ключевой пары
CK_MECHANISM mechanism = {CKM_GOSTR3410_256_KEY_PAIR_GEN, NULL, 0};

// параметры шаблона закрытого ключа
CK_OBJECT_CLASS privKeyClass = CKO_PRIVATE_KEY;
CK_UTF8CHAR privKeyLabel[] = "Private Key GOST R 34.10-2001 256";
CK_KEY_TYPE privKeyType = CKK_GOSTR3410;

// шаблон закрытого ключа
CK_ATTRIBUTE privKeyTemplate[] =
{
  {CKA_CLASS, &privKeyClass, sizeof(privKeyClass)},                            // класс
  {CKA_KEY_TYPE, &privKeyType, sizeof(privKeyType)},                           // тип ключа
  {CKA_TOKEN, (CK_VOID_PTR) &bTrue, sizeof(bTrue)},                            // объект хранится в токене
  {CKA_LABEL, (CK_VOID_PTR) privKeyLabel, (CK_ULONG) strlen(privKeyLabel)},    // метка закрытого ключа
  {CKA_PRIVATE, &bTrue,  sizeof(bTrue) },                                      // не виден без ввода PIN-кода пользователя
};

// параметры шаблона открытого ключа
CK_OBJECT_CLASS pubKeyClass = CKO_PUBLIC_KEY;
CK_UTF8CHAR pubKeyLabel[] = "Public Key GOST R 34.10-2001 256";
CK_KEY_TYPE pubKeyType = CKK_GOSTR3410;

// шаблон открытого ключа
CK_ATTRIBUTE pubKeyTemplate[] =
{
  {CKA_CLASS, &privKeyClass, sizeof(privKeyClass)},                            // класс
  {CKA_KEY_TYPE, &privKeyType, sizeof(privKeyType)},                           // тип ключа
  {CKA_TOKEN, (CK_VOID_PTR) &bTrue, sizeof(bTrue)},                            // объект хранится в токене
  {CKA_LABEL, (CK_VOID_PTR) pubKeyLabel, (CK_ULONG) strlen(pubKeyLabel)},      // метка закрытого ключа
  {CKA_PRIVATE, &bFalse,  sizeof(bFalse) },                                    // виден без ввода PIN-кода пользователя

  {
    CKA_GOSTR3410_PARAMS,
    (CK_VOID_PTR) id_GostR3410_2001_CryptoPro_A_ParamSet,
    sizeof(id_GostR3410_2001_CryptoPro_A_ParamSet)
  },                                                                           // тип ключевой пары

  {
    CKA_GOSTR3411_PARAMS,
    (CK_VOID_PTR) id_tc26_gost3411_12_256,
    sizeof(id_tc26_gost3411_12_256)
  }                                                                            // стандарт алгоритма хэширования
};

// дескрипторы открытого и закрытого ключа ключевой пары PKCS#11
CK_OBJECT_HANDLE pubKeyHandle, privKeyHandle;

// функция генерирует ключевую пару
rv = C_GenerateKeyPair(session,
                       &mechanism,
                       pubKeyTemplate, sizeof(pubKeyTemplate)/sizeof(CK_ATTRIBUTE),
                       privKeyTemplate, sizeof(privKeyTemplate)/sizeof(CK_ATTRIBUTE),
                       &pubKeyHandle,
                       &privKeyHandle);
if(rv != CKR_OK)
{
  PrintError("C_GenerateKeyPair", rv);
  return;
}
Значения атрибута CKA_GOSTR3410_PARAMS описаны в приложении.
Значения атрибута CKA_GOSTR3411_PARAMS описаны в приложении.
Более полную информацию о работе с объектами смотри в приложении.

C_WrapKey

CK_RV C_WrapKey(CK_SESSION_HANDLE hSession, CK_MECHANISM_PTR pMechanism, CK_OBJECT_HANDLE hWrappingKey, CK_OBJECT_HANDLE hKey, CK_BYTE_PTR pWrappedKey, CK_ULONG_PTR pulWrappedKeyLen)
Параметры:
  • hSession (in) – дескриптор сеанса.
  • pMechanism (in) – указатель на механизм.
  • hWrappingKey (in) – указатель на ключ экспорта.
  • hKey (in) – указатель на исходный ключ.
  • pWrappedKey (in/out) – указатель на массив для экспортированного ключа.
  • pulWrappedKeyLen (in/out) – указатель на размер массива экспортированного ключа.

Производит экспорт симметричного сессионного ключа (сгенерированного программно) на симметричном ключе согласования.

Поддерживаются следующие механизмы:

  • Криптотокен

    • CKM_GOST28147_KEY_WRAP (0x00001224) – механизм для импорта и экспорта ключей, соответствующий стандарту ГОСТ 28147–89.

  • Криптотокен 2 ЭП

    • CKM_GOST28147_KEY_WRAP (0x00001224) – механизм для импорта и экспорта ключей, соответствующий стандарту ГОСТ 28147–89.

    • CKM_GOSTR3410_KEY_WRAP (0x00001203) – механизм для импорта и экспорта ключей, соответствующий стандарту ГОСТ Р 34.10–2001.

      Особенности механизма

      Используется аппаратный и программный экспорт ключа.

      Аппаратный экспорт ключа

      • При аппаратном экспорте функция позволяет генерировать и экспортировать сессионный ключ для преобразований по ГОСТ 28147–89 с параметрами id-tc26-gost-28147-param-Z.

      • Для апплета Криптотокен 2 ЭП вводится понятие «виртуального секретного ключа», под которым понимается ключ, который может присутствовать (но не обязательно) в оперативной памяти изделия.

        Вызову функции должно предшествовать получение дескриптора «виртуального секретного ключа», который потом передается в качестве параметра функции. Поиск объекта виртуального ключа осуществляется по шаблону, содержащему атрибуты CKA_CLASS = CKO_SECRET_KEY, CKA_ID = ”VSKO_ID”.

        После экспорта ключа атрибут CKA_KT2_KEY_ACTIVE принимает значение CK_TRUE.

      • Апплет версии 2.5.5 позволяет также экспортировать сгенерированный ранее секретный ключ. После завершения операции преобразования ключ удаляется из памяти изделия.

      Программный экспорт ключа

      • При программном экспорте функция работает согласно стандарту. Доступные атрибуты:
        • CKA_KT2_KEY_WRAP (CKA_VENDOR_DEFINED | 0x0024) – если атрибут имеет значение CK_TRUE, используется алгоритм шифрования ключа содержимого по RFC 4357 п.6.1/6.2; в противном случае используется RFC 4357 п.6.3/6.4.
        • CKA_KT2_AUTOGENERATE_KEY (CKA_VENDOR_DEFINED | 0x0026) – если атрибут имеет значение CK_TRUE, будет сгенерирован случайный секретный ключ. По умолчанию принимается значение CK_TRUE.

  • Laser

    • CKM_RSA_PKCS (0x00000001) – механизм для импорта и экспорта ключей с использованием ключевой пары и алгоритма RSA.
    • CKM_DES3_ECB (0x00000132) – механизм для импорта и экспорта ключей в режиме ECB с использованием алгоритма triple-DES.
    • CKM_DES3_CBC (0x00000133) – механизм для импорта и экспорта ключей в режиме CBC с использованием алгоритма triple-DES.
    • CKM_AES_ECB (0x00001081) – механизм для импорта и экспорта ключей в режиме ECB с использованием алгоритма AES.
    • CKM_AES_CBC (0x00001082) – механизм для импорта и экспорта ключей в режиме CBC с использованием алгоритма AES.

Запускается в режимах

Результат:
  • CKR_ARGUMENTS_BAD – недопустимые аргументы.
  • CKR_BUFFER_TOO_SMALL – вывод функции слишком велик для предоставленного буфера.
  • CKR_CRYPTOKI_NOT_INITIALIZED – функция не может быть выполнена, т.к. библиотека еще не была инициализирована (см. C_Initialize()).
  • CKR_DEVICE_ERROR – возникла проблема с токеном и/или слотом.
  • CKR_DEVICE_MEMORY – памяти токена недостаточно для данной операции.
  • CKR_DEVICE_REMOVED – токен был изъят из слота.
  • CKR_FUNCTION_CANCELED – функция была отменена в момент исполнения.
  • CKR_FUNCTION_FAILED – выполнение функции было прервано или она не может быть выполнена.
  • CKR_GENERAL_ERROR – общий сбой при работе с библиотекой.
  • CKR_HOST_MEMORY – компьютер, на котором запущена библиотека, не имеет достаточно памяти для выполнения функции.
  • CKR_KEY_HANDLE_INVALID – недопустимый дескриптор ключа.
  • CKR_KEY_NOT_WRAPPABLE – библиотека не может экспортировать данный ключ.
  • CKR_KEY_SIZE_RANGE – размер ключа лежит за пределами, поддерживаемыми библиотекой.
  • CKR_KEY_UNEXTRACTABLE – библиотека не может экспортировать данный ключ, так как атрибут CKA_EXTRACTABLE установлен в значение CK_FALSE.
  • CKR_MECHANISM_INVALID – недопустимый механизм.
  • CKR_MECHANISM_PARAM_INVALID – недопустимый параметр механизма.
  • CKR_OK – функция выполнена успешно.
  • CKR_OPERATION_ACTIVE – на устройстве уже есть активная операция, что не позволяет активизировать данную операцию.
  • CKR_PIN_EXPIRED – срок действия указанного PIN-кода истек.
  • CKR_SESSION_CLOSED – сеанс был закрыт в момент выполнения функции.
  • CKR_SESSION_HANDLE_INVALID – недопустимый дескриптор сеанса.
  • CKR_USER_NOT_LOGGED_IN – действие не может быть выполнено, т.к. пользователь не залогинен.
  • CKR_WRAPPING_KEY_HANDLE_INVALID – недопустимый указатель на ключ экспорта.

    Примечание

    Данный аргумент возвращается только функцией C_WrapKey.

  • CKR_WRAPPING_KEY_SIZE_RANGE – размер ключа экспорта лежит за пределами, поддерживаемыми библиотекой.

    Примечание

    Данный аргумент возвращается только функцией C_WrapKey.

  • CKR_WRAPPING_KEY_TYPE_INCONSISTENT – данный ключ экспорта невозможно использовать с указанным механизмом.

    Примечание

    Данный аргумент возвращается только функцией C_WrapKey.

Совет

Полный список ошибок см. в приложении.

Примеры Криптотокен 2 ЭП

Пример экспорта ключа с использованием CKM_GOSTR3410_KEY_WRAP и виртуального секретного ключа на языке C++:

// получаем дескриптор сессии
CK_SESSION_HANDLE hSession = … ;

// режим Пользователя
CK_UTF8CHAR pin[] = "1234567890";
C_Login(hSession, CKU_USER, pin, strlen(pin));


// получаем дескрипторы приватного ключа Отправителя и публичного ключа Получателя
CK_OBJECT_HANDLE hReceiverPublicKey = … ;
CK_OBJECT_HANDLE hSenderPrivateKey = … ;

CK_OBJECT_CLASS ckaClass = CKO_SECRET_KEY;
CK_BYTE ckaId[]          = "VSKO_ID"; // "VSKO_ID"

// атрибуты поиска виртуального ключа
CK_ATTRIBUTE searchAtt[] = {
  {CKA_CLASS, &ckaClass, sizeof(ckaClass)},
  {CKA_ID, ckaId, sizeof(ckaId) - 1}
};

CK_OBJECT_HANDLE hVirtualSecretKey = CK_INVALID_HANDLE; // дескриптор виртуального секретного ключа
CK_ULONG ulObjectsCount            = 5;

// поиск виртуального ключа
C_FindObjectsInit(hSession, searchAtt, 2);
C_FindObjects(hSession, &hVirtualSecretKey, 1, &ulObjectsCount);
C_FindObjectsFinal(hSession);

// параметры экспорта ключа
CK_GOSTR3410_KEY_WRAP_PARAMS wrapParams;
memset(&wrapParams, 0, sizeof(wrapParams));

wrapParams.hKey = hSenderPrivateKey;

CK_MECHANISM ckWrapMechanism;
ckWrapMechanism.mechanism      = CKM_GOSTR3410_KEY_WRAP;
ckWrapMechanism.pParameter     = &wrapParams;
ckWrapMechanism.ulParameterLen = sizeof(wrapParams);


// получаем требуемый размер для экспортированного представления
CK_ULONG wrappedKeySize = 0;
C_WrapKey(hSession, &ckWrapMechanism, hReceiverPublicKey, hVirtualSecretKey, NULL, &wrappedKeySize);

// генерируем и экспортируем ключ hVirtualSecretKey
std::vector<CK_BYTE> wrappedKey(wrappedKeySize);
C_WrapKey(hSession, &ckWrapMechanism, hReceiverPublicKey, hVirtualSecretKey, &wrappedKey[0], &wrappedKeySize);

C_UnwrapKey

CK_RV C_UnwrapKey(CK_SESSION_HANDLE hSession, CK_MECHANISM_PTR pMechanism, CK_OBJECT_HANDLE hUnwrappingKey, CK_BYTE_PTR pWrappedKey, CK_ULONG ulWrappedKeyLen, CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulAttributeCount, CK_OBJECT_HANDLE_PTR phKey)
Параметры:
  • hSession (in) – дескриптор сеанса.
  • pMechanism (in) – указатель на механизм.
  • hUnwrappingKey (in) – указатель на ключ импорта.
  • pWrappedKey (in) – указатель на массив, содержащий исходный зашифрованный ключ.
  • ulWrappedKeyLen (in) – размер массива для исходного ключа.
  • pTemplate (in) – указатель на шаблон сессионного ключа.
  • ulCount (in) – количество атрибутов в шаблоне.
  • phKey (out) – указатель на идентификатор импортированного сессионного ключа.

Производит импорт сессионного ключа на ключе согласования.

Поддерживаются следующие механизмы:

  • Криптотокен

    • CKM_GOST28147_KEY_WRAP (0x00001224) – механизм для импорта и экспорта ключей, соответствующий стандарту ГОСТ 28147–89.

  • Криптотокен 2 ЭП

    • CKM_GOST28147_KEY_WRAP (0x00001224) – механизм для импорта и экспорта ключей, соответствующий стандарту ГОСТ 28147–89.

    • CKM_GOSTR3410_KEY_WRAP (0x00001203) – механизм для импорта и экспорта ключей, соответствующий стандарту ГОСТ Р 34.10–2001.

      Особенности механизма

      Используется аппаратный и программный экспорт ключа.

      Аппаратный экспорт ключа

      • При аппаратном экспорте функция позволяет генерировать и экспортировать сессионный ключ для преобразований по ГОСТ 28147–89 с параметрами id-tc26-gost-28147-param-Z.
      • После импорта ключа атрибут CKA_KT2_KEY_ACTIVE принимает значение CK_TRUE.
      • После завершения операции преобразования ключ удаляется из памяти изделия, а атрибут CKA_KT2_KEY_ACTIVE принимает значение CK_FALSE.

      Программный экспорт ключа

      • При программном экспорте функция работает согласно стандарту. Доступные атрибуты:
        • CKA_KT2_KEY_WRAP (CKA_VENDOR_DEFINED | 0x0024) – если атрибут имеет значение CK_TRUE, используется алгоритм шифрования ключа содержимого по RFC 4357 п.6.1/6.2; в противном случае используется RFC 4357 п.6.3/6.4.

  • Laser

    • CKM_RSA_PKCS (0x00000001) – механизм для импорта и экспорта ключей с использованием ключевой пары и алгоритма RSA.
    • CKM_DES3_ECB (0x00000132) – механизм для импорта и экспорта ключей в режиме ECB с использованием алгоритма triple-DES.
    • CKM_DES3_CBC (0x00000133) – механизм для импорта и экспорта ключей в режиме CBC с использованием алгоритма triple-DES.
    • CKM_AES_ECB (0x00001081) – механизм для импорта и экспорта ключей в режиме ECB с использованием алгоритма AES.
    • CKM_AES_CBC (0x00001082) – механизм для импорта и экспорта ключей в режиме CBC с использованием алгоритма AES.

Запускается в режимах

Результат:
  • CKR_ARGUMENTS_BAD – недопустимые аргументы.
  • CKR_ATTRIBUTE_READ_ONLY – невозможно установить значение атрибута, т.к. он поддерживает только чтение.
  • CKR_ATTRIBUTE_TYPE_INVALID – недопустимый тип атрибута.
  • CKR_ATTRIBUTE_VALUE_INVALID – недопустимое значение атрибута.
  • CKR_BUFFER_TOO_SMALL – вывод функции слишком велик для предоставленного буфера.
  • CKR_CRYPTOKI_NOT_INITIALIZED – функция не может быть выполнена, т.к. библиотека еще не была инициализирована (см. C_Initialize()).
  • CKR_DEVICE_ERROR – возникла проблема с токеном и/или слотом.
  • CKR_DEVICE_MEMORY – памяти токена недостаточно для данной операции.
  • CKR_DEVICE_REMOVED – токен был изъят из слота.
  • CKR_DOMAIN_PARAMS_INVALID – недопустимые или неподдерживаемые параметры домена.
  • CKR_FUNCTION_CANCELED – функция была отменена в момент исполнения.
  • CKR_FUNCTION_FAILED – выполнение функции было прервано или она не может быть выполнена.
  • CKR_GENERAL_ERROR – общий сбой при работе с библиотекой.
  • CKR_HOST_MEMORY – компьютер, на котором запущена библиотека, не имеет достаточно памяти для выполнения функции.
  • CKR_MECHANISM_INVALID – недопустимый механизм.
  • CKR_MECHANISM_PARAM_INVALID – недопустимый параметр механизма.
  • CKR_OK – функция выполнена успешно.
  • CKR_OPERATION_ACTIVE – на устройстве уже есть активная операция, что не позволяет активизировать данную операцию.
  • CKR_PIN_EXPIRED – срок действия указанного PIN-кода истек.
  • CKR_SESSION_CLOSED – сеанс был закрыт в момент выполнения функции.
  • CKR_SESSION_HANDLE_INVALID – недопустимый дескриптор сеанса.
  • CKR_SESSION_READ_ONLY – сеанс открыт только на чтение.
  • CKR_TEMPLATE_INCOMPLETE – шаблон, указанный для создания объекта, неполон.
  • CKR_TEMPLATE_INCONSISTENT – шаблон, указанный для создания объекта, содержит конфликтующие атрибуты.
  • CKR_TOKEN_WRITE_PROTECTED – данный токен защищен от записи.
  • CKR_UNWRAPPING_KEY_HANDLE_INVALID – недопустимый указатель на ключ импорта.

    Примечание

    Данный аргумент возвращается только функцией C_UnwrapKey.

  • CKR_UNWRAPPING_KEY_SIZE_RANGE – размер ключа импорта лежит за пределами, поддерживаемыми библиотекой.

    Примечание

    Данный аргумент возвращается только функцией C_UnwrapKey.

  • CKR_UNWRAPPING_KEY_TYPE_INCONSISTENT – данный ключ импорта невозможно использовать с указанным механизмом.

    Примечание

    Данный аргумент возвращается только функцией C_UnwrapKey.

  • CKR_USER_NOT_LOGGED_IN – действие не может быть выполнено, т.к. пользователь не залогинен.
  • CKR_WRAPPED_KEY_INVALID – недопустимый исходный (экспортированный) ключ.

    Примечание

    Данный аргумент возвращается только функцией C_UnwrapKey.

  • CKR_WRAPPED_KEY_SIZE_RANGE – размер исходного (экспортированного) ключа лежит за пределами, поддерживаемыми библиотекой.

    Примечание

    Данный аргумент возвращается только функцией C_UnwrapKey.

Совет

Полный список ошибок см. в приложении.

Примеры Криптотокен 2 ЭП

Пример импорта ключа с использованием CKM_GOSTR3410_KEY_WRAP на языке C++:

// экспортное представление ключа
CK_BYTE wrappedKey[] = {0x30, 0x41, 0x30, 0x28, 0x04, 0x20, 0x65, 0xB2, 0xD5, 0x22, 0xD7, 0x74, 0xEF, 0x34, 0x39, 0xD2, 0xAC , 0x98, 0x65, 0x8B, 0xFA, 0xB5, 0x4A, 0xE7, 0xDE, 0xA2, 0x98, 0x25, 0x8E, 0xAA, 0xC6, 0x0D, 0x26, 0x17, 0x0C , 0x2C, 0xCB, 0x24, 0x04, 0x04, 0xA6, 0x2B, 0x37, 0xF0, 0xA0, 0x15, 0x06, 0x09, 0x2A, 0x85, 0x03, 0x07, 0x01 , 0x02, 0x05, 0x01, 0x01, 0x04, 0x08, 0x1F, 0x41, 0xBD, 0x67, 0x24, 0x48, 0xBF, 0x55};

CK_BYTE STR_CRYPTO_PRO_GOST28147_Z[] = {0x06, 0x09, 0x2A, 0x85, 0x03, 0x07, 0x01, 0x02, 0x05, 0x01, 0x01};
const CK_ULONG STR_CRYPTO_PRO_GOST28147_Z_SIZE = sizeof(STR_CRYPTO_PRO_GOST28147_Z);


CK_OBJECT_HANDLE receiverPrivateKey= … ; // дескриптор приватного ключа Получателя
CK_OBJECT_HANDLE senderPublicKey = … ; // дескриптор публичного ключа Отправителя

CK_BBOOL s_TrueValue = CK_TRUE;
CK_BBOOL s_FalseValue = CK_FALSE;

// шаблон секретного ключа
CK_OBJECT_CLASS objectClass      = CKO_SECRET_KEY;
CK_KEY_TYPE keyType              = CKK_GOST28147;
CK_ATTRIBUTE secretKeyTemplate[] = {
  {CKA_GOST28147_PARAMS, STR_CRYPTO_PRO_GOST28147_Z, STR_CRYPTO_PRO_GOST28147_Z_SIZE},
  {CKA_TOKEN, &s_TrueValue, sizeof(s_TrueValue)},
  {CKA_PRIVATE, &s_TrueValue, sizeof(s_TrueValue)},
  {CKA_CLASS, &objectClass, sizeof(objectClass)},
  {CKA_KEY_TYPE, &keyType, sizeof(keyType)},
  {CKA_DECRYPT, &s_TrueValue, sizeof(s_TrueValue)}
};

// параметры импорта ключа
CK_GOSTR3410_KEY_WRAP_PARAMS wrapParams;
memset(&wrapParams, 0, sizeof(wrapParams));

CK_MECHANISM mechanism;
mechanism.mechanism      = CKM_GOSTR3410_KEY_WRAP;
mechanism.pParameter     = &wrapParams;
mechanism.ulParameterLen = sizeof(wrapParams);

CK_OBJECT_HANDLE hCEK = CK_INVALID_HANDLE;

// импорт ключа в память изделия
wrapParams.hKey = hSenderPublicKey;

C_UnwrapKey(hSession, &mechanism, hReceiverPrivateKey, &wrappedKey[0], sizeof(wrappedKey), secretKeyTemplate, 6, &hCEK);

C_DeriveKey

CK_RV C_DeriveKey(CK_SESSION_HANDLE hSession, CK_MECHANISM_PTR pMechanism, CK_OBJECT_HANDLE hBaseKey, CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulAttributeCount, CK_OBJECT_HANDLE_PTR phKey)
Параметры:
  • hSession (in) – дескриптор сеанса.
  • pMechanism (in) – указатель на механизм.
  • hBaseKey (in) – дескриптор закрытого ключа отправителя или получателя.
  • pTemplate (in) – указатель на шаблон объекта ключа согласования.
  • ulAttributeCount (in) – количество атрибутов в шаблоне.
  • phKey (in/out) – ключ согласования/экспортированный сессионный ключ.

Вырабатывает ключ согласования или сессионный ключ (в зависимости от апплета, с которым происходит работа и используемого механизма).

Особенности апплетов:

  • Криптотокен

    Поддерживаемые механизмы:

    • CKM_GOSTR3410_DERIVE (0x00001204) – механизм для выработки ключа согласования, соответствующий стандарту ГОСТ Р 34.10–2001.
    • CKM_TLS_GOST_MASTER_KEY_DERIVE (NSSCK_VENDOR_PKSC11_RU_TEAM | 0x101) – механизм для выработки 48-байтного ключа из 32-байтного ключа, используемый при создании master_secret ключей для протокола TLS 1.0.
    • CKM_TLS_GOST_KEY_AND_MAC_DERIVE (NSSCK_VENDOR_PKSC11_RU_TEAM | 0x102) – механизм для выработки ключа согласования из master_secret и случайных данных.
    • CKM_TLS_GOST_PRF (NSSCK_VENDOR_PKSC11_RU_TEAM | 0x103) – механизм для генерации псевдослучайных данных произвольной длины защищенным образом, соответствующий стандарту ГОСТ.

  • Криптотокен 2 ЭП

    Для Криптотокен 2 ЭП версии 2.5.3 поддерживается выработка ключа согласования только с использованием дескриптора открытого ключа Отправителя.
    Для Криптотокен 2 ЭП версии 2.5.5 поддерживается выработка ключа согласования с использованием дескриптора и значения открытого ключа Отправителя.

    Для выработки ключа с использованием дескриптора может использоваться структура JC_KT2_GOSTR3410_DERIVE_PARAMS.

    Поддерживаемые механизмы:

    • CKM_GOSTR3410_DERIVE (0x00001204) – механизм для выработки ключа согласования, соответствующий стандарту ГОСТ Р 34.10–2001.
    • CKM_GOSTR3410_2012_DERIVE (CK_VENDOR_PKCS11_RU_TEAM_TC26 | 0x007) – механизм для выработки ключа согласования, соответствующий стандарту ГОСТ Р 34.10–2012.
    • CKM_GOSTR3410_12_DERIVE – псевдоним для CKM_GOSTR3410_2012_DERIVE.

  • Laser

    Поддерживаемые механизмы:

    • CKM_TLS_MASTER_KEY_DERIVE (0x00000375) – механизм для выработки 48-байтного ключа из другого 48-байтного ключа, используемый при создании master_secret ключей для протокола TLS 1.0.
    • CKM_TLS_KEY_AND_MAC_DERIVE (0x00000376) – механизм для выработки ключа согласования из master_secret и случайных данных.
    • CKM_TLS_MASTER_KEY_DERIVE_DH (0x00000377) – механизм для выработки 48-байтного ключа из другого ключа произвольного размера, используемый при создании master_secret ключей для протокола TLS 1.0.
    • CKM_TLS_PRF (0x00000378) – механизм для генерации псевдослучайных данных произвольной длины.
    • CKM_ECDH1_DERIVE (0x00001050) – механизм для генерации ключа согласования, основывающийся на эллиптических кривых и алгоритме Диффи-Хеллмана.

Запускается в режимах

Результат:
  • CKR_ARGUMENTS_BAD – недопустимые аргументы.
  • CKR_ATTRIBUTE_READ_ONLY – невозможно установить значение атрибута, т.к. он поддерживает только чтение.
  • CKR_ATTRIBUTE_TYPE_INVALID – недопустимый тип атрибута.
  • CKR_ATTRIBUTE_VALUE_INVALID – недопустимое значение атрибута.
  • CKR_CRYPTOKI_NOT_INITIALIZED – функция не может быть выполнена, т.к. библиотека еще не была инициализирована (см. C_Initialize()).
  • CKR_DEVICE_ERROR – возникла проблема с токеном и/или слотом.
  • CKR_DEVICE_MEMORY – памяти токена недостаточно для данной операции.
  • CKR_DEVICE_REMOVED – токен был изъят из слота.
  • CKR_DOMAIN_PARAMS_INVALID – недопустимые или неподдерживаемые параметры домена.
  • CKR_FUNCTION_CANCELED – функция была отменена в момент исполнения.
  • CKR_FUNCTION_FAILED – выполнение функции было прервано или она не может быть выполнена.
  • CKR_GENERAL_ERROR – общий сбой при работе с библиотекой.
  • CKR_HOST_MEMORY – компьютер, на котором запущена библиотека, не имеет достаточно памяти для выполнения функции.
  • CKR_KEY_HANDLE_INVALID – недопустимый дескриптор ключа.
  • CKR_KEY_SIZE_RANGE – размер ключа лежит за пределами, поддерживаемыми библиотекой.
  • CKR_KEY_TYPE_INCONSISTENT – данный ключ невозможно использовать с указанным механизмом.
  • CKR_MECHANISM_INVALID – недопустимый механизм.
  • CKR_MECHANISM_PARAM_INVALID – недопустимый параметр механизма.
  • CKR_OK – функция выполнена успешно.
  • CKR_OPERATION_ACTIVE – на устройстве уже есть активная операция, что не позволяет активизировать данную операцию.
  • CKR_PIN_EXPIRED – срок действия указанного PIN-кода истек.
  • CKR_SESSION_CLOSED – сеанс был закрыт в момент выполнения функции.
  • CKR_SESSION_HANDLE_INVALID – недопустимый дескриптор сеанса.
  • CKR_SESSION_READ_ONLY – сеанс открыт только на чтение.
  • CKR_TEMPLATE_INCOMPLETE – шаблон, указанный для создания объекта, неполон.
  • CKR_TEMPLATE_INCONSISTENT – шаблон, указанный для создания объекта, содержит конфликтующие атрибуты.
  • CKR_TOKEN_WRITE_PROTECTED – данный токен защищен от записи.
  • CKR_USER_NOT_LOGGED_IN – действие не может быть выполнено, т.к. пользователь не залогинен.

Совет

Полный список ошибок см. в приложении.

Примеры Криптотокен

Пример выработки ключа согласования на языке C:

static CK_BYTE id_Gost28147_89_CryptoPro_A_ParamSet[] = { 0x06, 0x07, 0x2A, 0x85, 0x03, 0x02, 0x02, 0x1F, 0x01 };

// результат выполнения функции
CK_RV rv = CKR_OK;

// механизм выработки ключа согласования
CK_MECHANISM pkcs11DeriveKeyMechanism;

// дескрипторы открытого и закрытого ключа ключавой пары PKCS#11
CK_OBJECT_HANDLE pkcs11PubKeyHandle, pkcs11PrivKeyHandle;

// шаблон ключа согласования
CK_ATTRIBUTE pkcs11DerivedKeyTemplate[] =
{
  {CKA_GOST28147_PARAMS, id_Gost28147_89_CryptoPro_A_ParamSet, sizeof(id_Gost28147_89_CryptoPro_A_ParamSet)}
};

// дескриптор ключа согласования PKCS#11
CK_OBJECT_HANDLE pkcs11DerivedKeyHandle;

// параметры для выработки ключа согласования
CK_GOSTR3410_DERIVE_PARAMS pkcs11DeriveParams;

// устанавливаем параметры для создания ключа согласования
pkcs11DeriveParams.kdf = NULL;
pkcs11DeriveParams.pPublicData = cpPubKeyValue;
pkcs11DeriveParams.ulPublicDataLen = 64;
pkcs11DeriveParams.pUKM = ukm;
pkcs11DeriveParams.ulUKMLen = 8;

// устанавливаем механизм создания ключа согласования
pkcs11DeriveKeyMechanism.mechanism = CKM_GOSTR3410_DERIVE;
pkcs11DeriveKeyMechanism.pParameter = &pkcs11DeriveParams;
pkcs11DeriveKeyMechanism.ulParameterLen = sizeof(pkcs11DeriveParams);

// создаем ключ согласования
rv = C_DeriveKey(pkcs11SessionHandle,
                 &pkcs11DeriveKeyMechanism,
                 pkcs11PrivKeyHandle,
                 pkcs11DerivedKeyTemplate, sizeof(pkcs11DerivedKeyTemplate)/sizeof(CK_ATTRIBUTE),
                 &pkcs11DerivedKeyHandle);

if(rv != CKR_OK)
{
  PrintError("C_DeriveKey", rv);
  return;
}
Возможные значения атрибута CKA_GOST28147_PARAMS описаны в приложении.
Более полную информацию о работе с объектами смотри в приложении.

Примеры Криптотокен 2 ЭП

Пример выработки ключа согласования с использованием дескриптора открытого ключа Получателя для ключей ГОСТ Р 34.10–2001, ГОСТ Р 34.10–2012 на языке C:

static CK_BYTE id_Gost28147_89_CryptoPro_A_ParamSet[] = { 0x06, 0x07, 0x2A, 0x85, 0x03, 0x02, 0x02, 0x1F, 0x01 };

CK_BBOOL bTrue = CK_TRUE;
CK_BBOOL bFalse = CK_FALSE;

// результат выполнения функции
CK_RV rv = CKR_OK;

// дескриптор сессии
CK_SESSION_HANDLE pkcs11SessionHandle;

// дескриптор закрытого ключа ключевой пары Отправителя
CK_OBJECT_HANDLE hPrivateKey;

// дескриптор открытого ключа Получателя
CK_OBJECT_HANDLE hPublicKey;

// механизм диверсификации ключа
CK_EC_KDF_TYPE kdf = CKD_NULL;

CK_BYTE ukm[] = {1, 2, 3, 4, 5, 6, 7, 8};

// дескриптор ключа согласования PKCS#11
CK_OBJECT_HANDLE hDerivedKey;

// ...
// генерация ключевой пары Отправителя
// получение дескриптора открытого ключа Получателя
// ...

// параметры для создания ключа согласования
JC_KT2_GOSTR3410_DERIVE_PARAMS jcCT2DeriveParams;
jcCT2DeriveParams.kdf = kdf;
jcCT2DeriveParams.hPublicKey = hPublicKey;
jcCT2DeriveParams.pUKM = CK_BYTE_PTR(&ukm[0]);
jcCT2DeriveParams.ulUKMLen = 8;

CK_MECHANISM ckDeriveMechanism = {CKM_GOSTR3410_DERIVE, &jcCT2DeriveParams, sizeof(jcCT2DeriveParams)};

// шаблон ключа согласования
CK_ULONG secretKeyClass = CKO_SECRET_KEY;
CK_KEY_TYPE keyType = CKK_GOST28147;

CK_ATTRIBUTE derivedKeyTemplate[] = {
   {CKA_CLASS, &secretKeyClass, sizeof(secretKeyClass)},
   {CKA_TOKEN, &bFalse, sizeof(bFalse)},
   {CKA_GOST28147_PARAMS, id_Gost28147_89_CryptoPro_A_ParamSet, sizeof(id_Gost28147_89_CryptoPro_A_ParamSet)},
   {CKA_KEY_TYPE, &keyType, sizeof(keyType)},
   {CKA_WRAP, &bTrue, sizeof(bTrue)},
   {CKA_UNWRAP, &bTrue, sizeof(bTrue)}
};

rv = C_DeriveKey(pkcs11SessionHandle,
                 &ckDeriveMechanism,
                 hPrivateKey,
                 derivedKeyTemplate, sizeof(derivedKeyTemplate)/sizeof(CK_ATTRIBUTE),
                 &hDerivedKey);
if(rv != CKR_OK)
{
  PrintError("C_DeriveKey", rv);
  return;
}

Пример выработки ключа с использованием значения открытого ключа Получателя для ключей ГОСТ Р 34.10–2001 на языке C:

static CK_BYTE id_Gost28147_89_CryptoPro_A_ParamSet[] = { 0x06, 0x07, 0x2A, 0x85, 0x03, 0x02, 0x02, 0x1F, 0x01 };

// значение открытого ключа Получателя, ГОСТР 34.10-2001
CK_BYTE publicKeyValue2001[] =
{
  0xA9, 0x4E, 0x0C, 0x00, 0xD7, 0x19, 0x5E, 0x14, 0x6E, 0xA0, 0x4B, 0x43, 0x80, 0x57, 0xAA, 0x8E,
  0x59, 0x08, 0xF8, 0x0A, 0x92, 0x12, 0xF0, 0xAC, 0x02, 0x1D, 0xC0, 0x56, 0x47, 0x31, 0xB1, 0xC0,
  0x00, 0xB9, 0x77, 0x43, 0x16, 0x34, 0xD1, 0xFA, 0x58, 0x46, 0x1F, 0x37, 0xA3, 0xFD, 0x38, 0xDC,
  0x0B, 0xA0, 0x54, 0xC3, 0x51, 0x65, 0xCF, 0x26, 0x2A, 0x13, 0x99, 0x57, 0xD3, 0x2E, 0xF1, 0xC2
};

CK_BBOOL bTrue = CK_TRUE;
CK_BBOOL bFalse = CK_FALSE;

// результат выполнения функции
CK_RV rv = CKR_OK;

// дескриптор сессии
CK_SESSION_HANDLE pkcs11SessionHandle;

// дескриптор закрытого ключа ключевой пары Отправителя
CK_OBJECT_HANDLE hPrivateKey;

// механизм диверсификации ключа
CK_EC_KDF_TYPE kdf = CKD_NULL;

CK_BYTE ukm[] = {1, 2, 3, 4, 5, 6, 7, 8};

// дескриптор ключа согласования PKCS#11
CK_OBJECT_HANDLE hDerivedKey;

// ...
// генерация ключевой пары Отправителя
// ...

// параметры для создания ключа согласования
CK_GOSTR3410_DERIVE_PARAMS deriveParams;
deriveParams.kdf = kdf;
deriveParams.pPublicData = CK_BYTE_PTR(&publicKeyValue2001[0]);
deriveParams.ulPublicDataLen = sizeof(publicKeyValue2001);
deriveParams.pUKM = CK_BYTE_PTR(&ukm[0]);
deriveParams.ulUKMLen = 8;

CK_MECHANISM ckDeriveMechanism = {CKM_GOSTR3410_DERIVE, &deriveParams, sizeof(deriveParams)};

// шаблон ключа согласования
CK_ULONG secretKeyClass = CKO_SECRET_KEY;
CK_KEY_TYPE keyType = CKK_GOST28147;

CK_ATTRIBUTE derivedKeyTemplate[] =
{
  {CKA_CLASS, &secretKeyClass, sizeof(secretKeyClass)},
  {CKA_TOKEN, &bFalse, sizeof(bFalse)},
  {CKA_GOST28147_PARAMS, id_Gost28147_89_CryptoPro_A_ParamSet, sizeof(id_Gost28147_89_CryptoPro_A_ParamSet)},
  {CKA_KEY_TYPE, &keyType, sizeof(keyType)},
  {CKA_WRAP, &bTrue, sizeof(bTrue)},
  {CKA_UNWRAP, &bTrue, sizeof(bTrue)}
};

rv = C_DeriveKey(pkcs11SessionHandle,
                 &ckDeriveMechanism,
                 hPrivateKey,
                 derivedKeyTemplate, sizeof(derivedKeyTemplate)/sizeof(CK_ATTRIBUTE),
                 &hDerivedKey);
if(rv != CKR_OK)
{
  PrintError("C_DeriveKey", rv);
  return;
}

Пример выработки ключа с использованием значения открытого ключа Получателя для ключей ГОСТ Р 34.10–2012 на языке C:

static CK_BYTE id_Gost28147_89_CryptoPro_A_ParamSet[] = { 0x06, 0x07, 0x2A, 0x85, 0x03, 0x02, 0x02, 0x1F, 0x01 };

// значение открытого ключа Получателя, ГОСТР 34.10-2012
CK_BYTE publicKeyValue[] =
{
  0x41, 0x40, 0x90, 0x36, 0x0E, 0x5E, 0x61, 0x82, 0x1C, 0xC6, 0xD6, 0x91, 0x11, 0x04, 0x71, 0xBB,
  0xF0, 0xE3, 0x5F, 0x31, 0xDF, 0x94, 0x79, 0x7E, 0xE9, 0x5D, 0x24, 0xEB, 0x67, 0xC4, 0x38, 0xA1,
  0xC5, 0xAA, 0x23, 0xC2, 0xFF, 0x33, 0xBA, 0x95, 0x27, 0x79, 0x36, 0x6E, 0x9A, 0x9F, 0xC6, 0x76,
  0xF2, 0x8C, 0x2B, 0x6A, 0xC2, 0x5D, 0x61, 0x7F, 0xC1, 0xF3, 0x10, 0x50, 0x34, 0x35, 0x67, 0x1B
};

CK_BBOOL bTrue = CK_TRUE;
CK_BBOOL bFalse = CK_FALSE;

// результат выполнения функции
CK_RV rv = CKR_OK;

// дескриптор сессии
CK_SESSION_HANDLE pkcs11SessionHandle;

// дескриптор закрытого ключа ключевой пары Отправителя
CK_OBJECT_HANDLE hPrivateKey;

// механизм диверсификации ключа
CK_EC_KDF_TYPE kdf = CKD_NULL;

CK_BYTE ukm[] = {1, 2, 3, 4, 5, 6, 7, 8};

// дескриптор ключа согласования PKCS#11
CK_OBJECT_HANDLE hDerivedKey;

// ...
// генерация ключевой пары Отправителя
// ...

// параметры для создания ключа согласования
// представлены в соответствии с рекомендациями ТК26
uint32_t tc26DeriveParams[21] = {0};
tc26DeriveParams[0] = kdf;
tc26DeriveParams[1] = sizeof(publicKeyValue);
memcpy(tc26DeriveParams + 2, &publicKeyValue[0], sizeof(publicKeyValue));
tc26DeriveParams[18] = 8;
memcpy(tc26DeriveParams + 19, &ukm[0], 8);

CK_MECHANISM deriveMechanism = {CKM_GOSTR3410_2012_DERIVE, &tc26DeriveParams, sizeof(tc26DeriveParams)};

// шаблон ключа согласования
CK_ULONG secretKeyClass           = CKO_SECRET_KEY;
CK_KEY_TYPE keyType               = CKK_GOST28147;
CK_ATTRIBUTE derivedKeyTemplate[] = {
  {CKA_CLASS, &secretKeyClass, sizeof(secretKeyClass)},
  {CKA_TOKEN, &bFalse, sizeof(bFalse)},
  {CKA_GOST28147_PARAMS, id_Gost28147_89_CryptoPro_A_ParamSet, sizeof(id_Gost28147_89_CryptoPro_A_ParamSet)},
  {CKA_KEY_TYPE, &keyType, sizeof(keyType)},
  {CKA_WRAP, &bTrue, sizeof(bTrue)},
  {CKA_UNWRAP, &bTrue, sizeof(bTrue)}
};

rv = C_DeriveKey(pkcs11SessionHandle,
                 &ckDeriveMechanism,
                 hPrivateKey,
                 derivedKeyTemplate, sizeof(derivedKeyTemplate)/sizeof(CK_ATTRIBUTE),
                 &hDerivedKey);
if(rv != CKR_OK)
{
  PrintError("C_DeriveKey", rv);
  return;
}

Оглавление