Функции для работы с ключами

C_GenerateKeyPair()

Синтаксис

CK_DEFINE_FUNCTION(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
);

Параметры

Назначение

Функция генерирует пару «открытый/закрытый» ключ.

Примечание

Поскольку тип генерируемых ключей зависит от механизма генерации ключевой пары, в шаблонах необязательно указывать тип ключа. Если в шаблоне все-таки задан тип ключа, и он противоречит используемому механизму генерации, C_GenerateKeyPair завершается с ошибкой и возвращает код CKR_TEMPLATE_INCONSISTENT. Атрибут CKA_CLASS обрабатывается аналогично.

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

Ключевые объекты, созданные успешным вызовом C_GenerateKeyPair, получают атрибут CKA_LOCAL, установленный в значение CK_TRUE. 

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

CKR_OK – функция выполнена успешно.

Стандартные коды ошибок:

CKR_ARGUMENTS_BAD,

CKR_ATTRIBUTE_READ_ONLY,

CKR_ATTRIBUTE_TYPE_INVALID,

CKR_ATTRIBUTE_VALUE_INVALID,

CKR_CRYPTOKI_NOT_INITIALIZED,

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_OPERATION_ACTIVE,

CKR_PIN_EXPIRED,

CKR_SESSION_CLOSED,

CKR_SESSION_HANDLE_INVALID,

CKR_SESSION_READ_ONLY,

CKR_TEMPLATE_INCOMPLETE,

CKR_TEMPLATE_INCONSISTENT,

CKR_USER_NOT_LOGGED_IN.

Пример

CK_SESSION_HANDLE hSession;
CK_OBJECT_HANDLE hPublicKey, hPrivateKey;
CK_MECHANISM mechanism = {
  CKM_RSA_PKCS_KEY_PAIR_GEN, NULL_PTR, 0
};

CK_ULONG modulusBits = 768;
CK_BYTE publicExponent[] = { 3 };
CK_BYTE subject[] = {...};
CK_BYTE id[] = {123};
CK_BBOOL true = CK_TRUE;
CK_ATTRIBUTE publicKeyTemplate[] = {
  {CKA_ENCRYPT, &true, sizeof(true)},
  {CKA_VERIFY, &true, sizeof(true)},
  {CKA_WRAP, &true, sizeof(true)},
  {CKA_MODULUS_BITS, &modulusBits, sizeof(modulusBits)},
  {CKA_PUBLIC_EXPONENT, publicExponent, sizeof (publicExponent)}
};

CK_ATTRIBUTE privateKeyTemplate[] = {
  {CKA_TOKEN, &true, sizeof(true)},
  {CKA_PRIVATE, &true, sizeof(true)},
  {CKA_SUBJECT, subject, sizeof(subject)},
  {CKA_ID, id, sizeof(id)},
  {CKA_SENSITIVE, &true, sizeof(true)},
  {CKA_DECRYPT, &true, sizeof(true)},
  {CKA_SIGN, &true, sizeof(true)},
  {CKA_UNWRAP, &true, sizeof(true)}
};

CK_RV rv;

rv = C_GenerateKeyPair(
  hSession, &mechanism,
  publicKeyTemplate, 5,
  privateKeyTemplate, 8,
  &hPublicKey, &hPrivateKey);
if (rv == CKR_OK) {
  .
  .
}

к содержанию ↑

C_DeriveKey()

Синтаксис

CK_DEFINE_FUNCTION(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
);

Параметры

Назначение

Функция вырабатывает новый ключ из существующего.

Примечание

Значения атрибутов CKA_SENSITIVE, CKA_ALWAYS_SENSITIVE, CKA_EXTRACTABLE и CKA_NEVER_EXTRACTABLE существующего ключа влияют на то, какие значения могут принимать эти же атрибуты у вырабатываемого ключа.

Если вызов C_DeriveKey не может полноценно поддержать переданный ему шаблон, он завершается с ошибкой и возвращается без создания какого‑либо ключа.

Ключевой объект, созданный успешным вызовом C_DeriveKey, получает атрибут CKA_LOCAL, установленный в значение CK_FALSE.

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

CKR_OK – функция выполнена успешно.

Стандартные коды ошибок:

CKR_ARGUMENTS_BAD,

CKR_ATTRIBUTE_READ_ONLY,

CKR_ATTRIBUTE_TYPE_INVALID,

CKR_ATTRIBUTE_VALUE_INVALID,

CKR_CRYPTOKI_NOT_INITIALIZED,

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_OPERATION_ACTIVE,

CKR_PIN_EXPIRED,

CKR_SESSION_CLOSED,

CKR_SESSION_HANDLE_INVALID,

CKR_SESSION_READ_ONLY,

CKR_TEMPLATE_INCOMPLETE,

CKR_TEMPLATE_INCONSISTENT,

CKR_USER_NOT_LOGGED_IN.

Пример

CK_SESSION_HANDLE hSession;
CK_OBJECT_HANDLE hPublicKey, hPrivateKey, hKey;
CK_MECHANISM keyPairMechanism = {
  CKM_DH_PKCS_KEY_PAIR_GEN, NULL_PTR, 0
};

CK_BYTE prime[] = {...};
CK_BYTE base[] = {...};
CK_BYTE publicValue[128];
CK_BYTE otherPublicValue[128];
CK_MECHANISM mechanism = {
  CKM_DH_PKCS_DERIVE, otherPublicValue, sizeof(otherPublicValue)
};

CK_ATTRIBUTE pTemplate[] = {
  CKA_VALUE, &publicValue, sizeof(publicValue)}
};

CK_OBJECT_CLASS keyClass = CKO_SECRET_KEY;
CK_KEY_TYPE keyType = CKK_DES;
CK_BBOOL true = CK_TRUE;
CK_ATTRIBUTE publicKeyTemplate[] = {
  {CKA_PRIME, prime, sizeof(prime)},
  {CKA_BASE, base, sizeof(base)}
};

CK_ATTRIBUTE privateKeyTemplate[] = {
  {CKA_DERIVE, &true, sizeof(true)}
};

CK_ATTRIBUTE template[] = {
  {CKA_CLASS, &keyClass, sizeof(keyClass)},
  {CKA_KEY_TYPE, &keyType, sizeof(keyType)},
  {CKA_ENCRYPT, &true, sizeof(true)},
  {CKA_DECRYPT, &true, sizeof(true)}
};

CK_RV rv;

.
.
rv = C_GenerateKeyPair(
  hSession, &keyPairMechanism,
  publicKeyTemplate, 2,
  privateKeyTemplate, 1,
  &hPublicKey, &hPrivateKey);

if (rv == CKR_OK) {
  rv = C_GetAttributeValue(hSession, hPublicKey, &pTemplate, 1);
  if (rv == CKR_OK) {
    .
    .
    rv = C_DeriveKey(
      hSession, &mechanism,
      hPrivateKey, template, 4, &hKey);
    if (rv == CKR_OK) {
      .
      .
    }
  }
}

к содержанию ↑