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

`C_GenerateKey`¶

C_GenerateKey(CK_SESSION_HANDLE hSession, CK_MECHANISM_PTR pMechanism, CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulCount, CK_OBJECT_HANDLE_PTR phKey, CKA_VALUE pSecretKey)¶

Параметры:

hSession (in) – дескриптор сеанса.
pMechanism (in) – указатель на механизм.
pTemplate (in) – указатель на шаблон объекта ключа.
ulCount (in) – количество атрибутов в шаблоне.
phKey (in/out) – идентификатор создаваемого ключа.
pSecretKey (out) – значение секретного ключа.

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

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

Криптотокен
- CKM_GOST28147_KEY_GEN (0x00001220) – механизм генерации ключей, соответствующий стандарту ГОСТ 28147-89.
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 – функция не может быть выполнена, т.к. библиотека Cryptoki еще не была инициализирована (см. 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 – действие не может быть выполнено, т.к. пользователь не залогинен.

Совет

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

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

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

// дескриптор сессии
CK_SESSION_HANDLE pkcs11SessionHandle;
// механизм генерации ключей
CK_MECHANISM pkcs11GenKeyMechanism = {CKM_GOST28147_KEY_GEN, NULL, 0};
// шаблон ключа
CK_ATTRIBUTE pkcs11SessionKeyTemplate[] =
{
  {CKA_GOST28147_PARAMS, STR_CRYPTO_PRO_GOST28147_A, sizeof(STR_CRYPTO_PRO_GOST28147_A)}
};
// дескриптор сессионного ключа PKCS#11
CK_OBJECT_HANDLE pkcs11SessionKeyHandle;
// функция генерирует ключ, используя заданный шаблон
rv = C_GenerateKey(pkcs11SessionHandle,
  &pkcs11GenKeyMechanism,
  pkcs11SessionKeyTemplate,
  sizeof(pkcs11SessionKeyTemplate)/sizeof(CK_ATTRIBUTE),
  &pkcs11SessionKeyHandle);

if(rv != CKR_OK)
{
  throw runtime_error("C_GenerateKey failed.");
}

Возможные значения атрибута CKA_GOST28147_PARAMS смотри в приложении.

Более полную информацию о работе с объектами смотри в приложении.

Пример генерации сессионного ключа на языке Java под ОС Android:

// дескриптор сессии
LongRef session = new LongRef();
// переменные атрибута, определяющего место сохранения объекта
boolean bToken = true;
boolean bSession = !bToken;
// дескриптор сессионного ключа
LongRef sessionKeyHandle = new LongRef();
// механизм для генерации сессионного ключа
CKM sessionKeyGenMech = new CKM(CKM.GOST28147_KEY_GEN, null);
// атрибуты сессионного ключа
CKA[] sessionKeyAttribs = new CKA[3];
sessionKeyAttribs[0] = new CKA(CKA.CLASS, CKO.SECRET_KEY);           // сессионный ключ
sessionKeyAttribs[1] = new CKA(CKA.TOKEN, bSession);                 // как сессионный объект
sessionKeyAttribs[2] = new CKA(CKA.GOST28147_PARAMS, Default.STR_CRYPTO_PRO_GOST_28147_A);   // тип ключа согласно rfc 4357

// генерация сессионного ключа
rv = C.GenerateKey(session.value, sessionKeyGenMech, sessionKeyAttribs, sessionKeyHandle);
if(rv != CKR.OK)
{
   throw new CKRException("C.GenerateKey", rv);
}

`C_GenerateKeyPair`¶

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.
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 – функция не может быть выполнена, т.к. библиотека Cryptoki еще не была инициализирована (см. 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 – действие не может быть выполнено, т.к. пользователь не залогинен.

Совет

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

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

Пример генерации ключевой пары на языке С:

// открытый ключ должен храниться в памяти устройства
CK_BBOOL pkcs11KeyGenToken = TRUE;
// дескриптор сессии
CK_SESSION_HANDLE pkcs11SessionHandle;
// механизм генерации ключевой пары
CK_MECHANISM pkcs11GenKeyPairMechanism = {CKM_GOSTR3410_KEY_PAIR_GEN, NULL, 0};
// шаблон закрытого ключа
CK_ATTRIBUTE pkcs11PrivKeyTemplate[] =
{
  {CKA_TOKEN, &pkcs11KeyGenToken, sizeof(pkcs11KeyGenToken)},
  {CKA_GOSTR3410_PARAMS, STR_CRYPTO_PRO_A, sizeof(STR_CRYPTO_PRO_A)}
};
// шаблон открытого ключа
CK_ATTRIBUTE pkcs11PubKeyTemplate[] =
{
  {CKA_TOKEN, &pkcs11KeyGenToken, sizeof(pkcs11KeyGenToken)},
  {CKA_GOSTR3410_PARAMS, STR_CRYPTO_PRO_A, sizeof(STR_CRYPTO_PRO_A)}
};
// дескрипторы открытого и закрытого ключа ключевой пары PKCS#11
CK_OBJECT_HANDLE pkcs11PubKeyHandle, pkcs11PrivKeyHandle;

// функция генерирует ключевую пару
rv = C_GenerateKeyPair(pkcs11SessionHandle,
      &pkcs11GenKeyPairMechanism,
      pkcs11PubKeyTemplate, sizeof(pkcs11PubKeyTemplate)/sizeof(CK_ATTRIBUTE),
      pkcs11PrivKeyTemplate, sizeof(pkcs11PrivKeyTemplate)/sizeof(CK_ATTRIBUTE),
      &pkcs11PubKeyHandle,
      &pkcs11PrivKeyHandle);

if(rv != CKR_OK)
{
  throw runtime_error("C_GenerateKeyPair failed.");
}

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

Более полную информацию о работе с объектами смотри в приложении.

Пример генерации ключевой пары на языке Java:

// дескриптор сессии
LongRef session = new LongRef();
// механизм для генерации ключевой пары
CKM mech = new CKM(CKM.GOSTR3410_KEY_PAIR_GEN, null);
// атрибуты открытого ключа
CKA[] pubKeyAttribs = new CKA[5];
pubKeyAttribs[0] = new CKA(CKA.CLASS, CKO.PUBLIC_KEY);       // открытый ключ
pubKeyAttribs[1] = new CKA(CKA.TOKEN, bToken);                       // в токене
pubKeyAttribs[2] = new CKA(CKA.LABEL, "Public key");         // метка для отображения
pubKeyAttribs[3] = new CKA(CKA.GOSTR3410_PARAMS, Default.STR_CRYPTO_PRO_A);          // тип ключевой пары согласно rfc 4357
pubKeyAttribs[4] = new CKA(CKA.ID, relatedID);                       // общий идентификатор
// атрибуты закрытого ключа
CKA[] prKeyAttribs = new CKA[5];
prKeyAttribs[0] = new CKA(CKA.CLASS, CKO.PRIVATE_KEY);       // закрытый ключ
prKeyAttribs[1] = new CKA(CKA.TOKEN, bToken);                        // в токене
prKeyAttribs[2] = new CKA(CKA.LABEL, "Private key");         // метка для отображения
prKeyAttribs[3] = new CKA(CKA.GOSTR3410_PARAMS, Default.STR_CRYPTO_PRO_A);           // тип ключевой пары согласно rfc 4357
prKeyAttribs[4] = new CKA(CKA.ID, relatedID);                        // общий идентификатор
// дескрипторы создаваемых объектов
LongRef pubKeyHandle = new LongRef();
LongRef prKeyHandle = new LongRef();

// генерация ключевой пары
rv = C.GenerateKeyPair(session.value, mech, pubKeyAttribs, prKeyAttribs, pubKeyHandle, prKeyHandle);
if(rv != CKR.OK)
{
   throw new CKRException("C.GenerateKeyPair", rv);
}

`C_WrapKey`¶

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.
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 – функция не может быть выполнена, т.к. библиотека Cryptoki еще не была инициализирована (см. 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 – библиотека Cryptoki не может экспортировать данный ключ.
CKR_KEY_SIZE_RANGE – размер ключа лежит за пределами, поддерживаемыми библиотекой Cryptoki.
CKR_KEY_UNEXTRACTABLE – библиотека Cryptoki не может экспортировать данный ключ, так как атрибут 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 – размер ключа экспорта лежит за пределами, поддерживаемыми библиотекой Cryptoki.

Примечание

Данный аргумент возвращается только функцией C_WrapKey.
CKR_WRAPPING_KEY_TYPE_INCONSISTENT – данный ключ экспорта невозможно использовать с указанным механизмом.

Примечание

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

Совет

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

`C_UnwrapKey`¶

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.
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 – функция не может быть выполнена, т.к. библиотека Cryptoki еще не была инициализирована (см. 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 – размер ключа импорта лежит за пределами, поддерживаемыми библиотекой Cryptoki.

Примечание

Данный аргумент возвращается только функцией 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 – размер исходного (экспортированного) ключа лежит за пределами, поддерживаемыми библиотекой Cryptoki.

Примечание

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

Совет

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

`C_DeriveKey`¶

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) – механизм для генерации псевдослучайных данных произвольной длины защищенным образом, соответствующий стандарту ГОСТ.
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 – функция не может быть выполнена, т.к. библиотека Cryptoki еще не была инициализирована (см. 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 – размер ключа лежит за пределами, поддерживаемыми библиотекой Cryptoki.
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 – действие не может быть выполнено, т.к. пользователь не залогинен.

Совет

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

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

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

Данный раздел актуален только при работе с апплетом Криптотокен.

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

// механизм выработки ключа согласования
CK_MECHANISM pkcs11DeriveKeyMechanism;
// дескрипторы открытого и закрытого ключа ключавой пары PKCS#11
CK_OBJECT_HANDLE pkcs11PubKeyHandle, pkcs11PrivKeyHandle;
// шаблон ключа согласования
CK_ATTRIBUTE pkcs11DerivedKeyTemplate[] =
{
  {CKA_GOST28147_PARAMS, STR_CRYPTO_PRO_GOST28147_A, sizeof(STR_CRYPTO_PRO_GOST28147_A)}
};
// дескриптор ключа согласования 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)
{
  throw runtime_error("C_DeriveKey failed.");
}

Возможные значения атрибута CKA_GOST28147_PARAMS смотри в приложении.

Более полную информацию о работе с объектами смотри в приложении.

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

// дескриптор сессии
LongRef session = new LongRef();
// атрибуты ключа согласования
CKA[] deriveKeyAttribs = new CKA[5];
deriveKeyAttribs[0] = new CKA(CKA.CLASS, CKO.SECRET_KEY);    // ключ согласования
deriveKeyAttribs[1] = new CKA(CKA.TOKEN, bSession);                  // как сессионный объект
deriveKeyAttribs[2] = new CKA(CKA.ENCRYPT, true);                    // использование ключа для шифрования
deriveKeyAttribs[3] = new CKA(CKA.DECRYPT, true);                    // использование ключа для расшифрования
deriveKeyAttribs[4] = new CKA(CKA.GOST28147_PARAMS, Default.STR_CRYPTO_PRO_GOST_28147_A);    // тип ключа согласно rfc 4357
// параметры механизма для создания ключа согласования
CK_PARAMS deriveParams = null;
// механизм для создания ключа согласования
CKM deriveKeyMech = null;
// дескрипторы объектов
LongRef pubKeyHandle = new LongRef();
LongRef prKeyHandle = new LongRef();
LongRef drvKeyHandle = new LongRef();

// формирование ключа согласования
rv = C.DeriveKey(session.value, deriveKeyMech, prKeyHandle.value, deriveKeyAttribs, drvKeyHandle);
if(rv != CKR.OK)
{
   throw new CKRException("C.DeriveKey", rv);
}

Навигация

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

C_GenerateKey¶

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

C_GenerateKeyPair¶

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

C_WrapKey¶

C_UnwrapKey¶

C_DeriveKey¶

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

Оглавление

Быстрый поиск

`C_GenerateKey`¶

`C_GenerateKeyPair`¶

`C_WrapKey`¶

`C_UnwrapKey`¶

`C_DeriveKey`¶