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

C_CreateObject()

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_CreateObject)(
	CK_SESSION_HANDLE		hSession,
	CK_ATTRIBUTE_PTR		pTemplate,
	CK_ULONG				ulCount,
	CK_OBJECT_HANDLE_PTR	phObject
);

Параметры

hSession	[in]	Дескриптор сессии
pTemplate	[in]	Указатель на шаблон объекта
ulCount	[in]	Количество атрибутов в шаблоне
phObject	[out]	Указатель на дескриптор нового объекта

Назначение

Функция создает новый объект.

Примечание

Если переданный в функцию шаблон не поддерживается функцией, то функция завершится ошибкой и новый объект не будет создан.

Если функция используется для создания объекта ключа, то значение атрибута CKA_LOCAL созданного объекта будет равно CK_FALSE. Если объект является секретным или закрытым ключом, то значения атрибутов CKA_ALWAYS_SENSITIVE и CKA_NEVER_EXTRACTABLE нового ключа будут равны 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_FAILED,

CKR_GENERAL_ERROR,

CKR_HOST_MEMORY,

CKR_PIN_EXPIRED,

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 hSession;
CK_OBJECT_HANDLE
	hData,
	hCertificate,
	hKey;
CK_OBJECT_CLASS
	dataClass = CKO_DATA,
	certificateClass = CKO_CERTIFICATE,
	keyClass = CKO_PUBLIC_KEY;
CK_KEY_TYPE keyType = CKK_RSA;
CK_UTF8CHAR application[] = {“My Application”};
CK_BYTE dataValue[] = {...};
CK_BYTE subject[] = {...};
CK_BYTE id[] = {...};
CK_BYTE certificateValue[] = {...};
CK_BYTE modulus[] = {...};
CK_BYTE exponent[] = {...};
CK_BBOOL IsTrue = CK_TRUE;
CK_ATTRIBUTE dataTemplate[] = {
	{CKA_CLASS, &dataClass, sizeof(dataClass)},
	{CKA_TOKEN, &IsTrue, sizeof(IsTrue)},
	{CKA_APPLICATION, application, sizeof(application)-1},
	{CKA_VALUE, dataValue, sizeof(dataValue)}
};
CK_ATTRIBUTE certificateTemplate[] = {
	{CKA_CLASS, &certificateClass, sizeof(certificateClass)},
	{CKA_TOKEN, &IsTrue, sizeof(IsTrue)},
	{CKA_SUBJECT, subject, sizeof(subject)},
	{CKA_ID, id, sizeof(id)},
	{CKA_VALUE, certificateValue, sizeof(certificateValue)}
};
CK_ATTRIBUTE keyTemplate[] = {
	{CKA_CLASS, &keyClass, sizeof(keyClass)},
	{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
	{CKA_WRAP, &IsTrue, sizeof(IsTrue)},
	{CKA_MODULUS, modulus, sizeof(modulus)},
	{CKA_PUBLIC_EXPONENT, exponent, sizeof(exponent)}
};
CK_RV rv;

...
rv = C_CreateObject(hSession, &dataTemplate, 4, &hData);
if (rv == CKR_OK) {
	...
}

rv = C_CreateObject(hSession, &certificateTemplate, 5, &hCertificate);
if (rv == CKR_OK) {
	...
}

rv = C_CreateObject(hSession, &keyTemplate, 5, &hKey);
if (rv == CKR_OK) {
	...
}

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

C_DestroyObject()

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_DestroyObject)(
  CK_SESSION_HANDLE hSession,
  CK_OBJECT_HANDLE hObject
);

Параметры

hSession	[in]	Дескриптор сессии
hObject	[in]	Дескриптор объекта

Назначение

Функция уничтожает объект.

Примечание

Во время сессии «только чтение» могут быть уничтожены только объекты сессии. До авторизации пользователя могут быть уничтожены только открытые объекты.

Некоторые объекты не могут быть уничтожены — в этом случае функция вернет код ошибки CKR_ACTION_PROHIBITED. Приложение может обратиться к атрибуту объекта CKA_DESTROYABLE, чтобы определить, можно ли уничтожить этот объект.

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

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

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

CKR_CRYPTOKI_NOT_INITIALIZED,

CKR_DEVICE_ERROR,

CKR_DEVICE_MEMORY,

CKR_DEVICE_REMOVED,

CKR_FUNCTION_FAILED,

CKR_GENERAL_ERROR,

CKR_HOST_MEMORY,

CKR_OBJECT_HANDLE_INVALID,

CKR_PIN_EXPIRED,

CKR_SESSION_CLOSED,

CKR_SESSION_HANDLE_INVALID,

CKR_SESSION_READ_ONLY,

CKR_TOKEN_WRITE_PROTECTED.

Пример

CK_SESSION_HANDLE hSession;
CK_OBJECT_HANDLE hObject;
CK_OBJECT_CLASS dataClass = CKO_DATA;
CK_UTF8CHAR application[] = {“My Application”};
CK_BYTE dataValue[] = {...};
CK_BYTE value[] = {...};
CK_BBOOL true = CK_TRUE;
CK_ATTRIBUTE template[] = {
  {CKA_CLASS, &dataClass, sizeof(dataClass)},
  {CKA_TOKEN, &true, sizeof(true)},
  {CKA_APPLICATION, application, sizeof(application)-1},
  {CKA_VALUE, value, sizeof(value)}
};

CK_ULONG ulSize;
CK_RV rv; 

.
.
rv = C_CreateObject(hSession, &template, 4, &hObject);
if (rv == CKR_OK) {
  rv = C_GetObjectSize(hSession, hObject, &ulSize);
  if (rv != CKR_INFORMATION_SENSITIVE) {
    .
    .
  }
 
  rv = C_DestroyObject(hSession, hObject);
  .
  .
}

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

C_FindObjectsInit()

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_FindObjectsInit)(
    CK_SESSION_HANDLE hSession,
    CK_ATTRIBUTE_PTR pTemplate,
    CK_ULONG ulCount
);

Параметры

hSession	[in]	Дескриптор сессии
pTemplate	[in]	Указатель на шаблон объекта
ulCount	[in]	Количество атрибутов в шаблоне

Назначение

Функция инициализирует поиск объектов, которые совпадают с указанным шаблоном объекта.

Примечание

Критерий соответствия — это точное побайтовое совпадение со всеми атрибутами в шаблоне. Чтобы найти все объекты, в параметре ulCount укажите 0.

После вызова C_FindObjectsInit приложение может вызывать C_FindObjects один или несколько раз, чтобы получить дескрипторы всех объектов, которые совпадают с заданным шаблоном, а затем завершить активный поиск вызовом C_FindObjectsFinal. Одновременно в сессии можно проводить только одну операцию поиска объектов.

Операция поиска объектов может найти только те объекты, которые видны в сессии. Например, поиск в сессии типа "R/W Public Session" не найдет закрытые объекты, даже если в шаблоне, по которому ищутся объекты, указаны атрибуты закрытых объектов.

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

C_FindObjectsInit может возвращать значения CKR_ATTRIBUTE_TYPE_INVALID и CKR_ATTRIBUTE_VALUE_INVALID, но это необязательно. Например, если передать в шаблоне несуществующие атрибуты, функция может или вернуть значение CKR_ATTRIBUTE_TYPE_INVALID, или выполнить поиск, в результате которого не будет найден ни один объект, и вернуть значение CKR_OK.

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

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

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

CKR_ARGUMENTS_BAD,

CKR_ATTRIBUTE_TYPE_INVALID,

CKR_ATTRIBUTE_VALUE_INVALID,

CKR_CRYPTOKI_NOT_INITIALIZED,

CKR_DEVICE_ERROR,

CKR_DEVICE_MEMORY,

CKR_DEVICE_REMOVED,

CKR_FUNCTION_FAILED,

CKR_GENERAL_ERROR,

CKR_HOST_MEMORY,

CKR_OK,

CKR_OPERATION_ACTIVE,

CKR_PIN_EXPIRED,

CKR_SESSION_CLOSED,

CKR_SESSION_HANDLE_INVALID.

Пример

См. C_FindObjectsFinal()

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

C_FindObjects()

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_FindObjects)(
	CK_SESSION_HANDLE hSession,
	CK_OBJECT_HANDLE_PTR phObject,
	CK_ULONG ulMaxObjectCount,
	CK_ULONG_PTR pulObjectCount
);

Параметры

hSession	[in]	Дескриптор сессии
phObject	[out]	Указатель на массив дескрипторов объектов
ulMaxObjectCount	[in]	Максимальное количество дескрипторов объектов
pulObjectCount	[out]	Указатель на количество найденных дескрипторов объектов

Назначение

Функция продолжает поиск объектов в соответствии с шаблоном, переданным в C_FindObjectsInit.

Если не нашлось больше объектов, совпадающих с шаблоном, тогда по адресу, на который указывает pulObjectCount, передается значение 0.

Поиск обязательно нужно инициализировать с помощью функции C_FindObjectsInit.

Примечание

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

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

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

CKR_ARGUMENTS_BAD,

CKR_CRYPTOKI_NOT_INITIALIZED,

CKR_DEVICE_ERROR,

CKR_DEVICE_MEMORY,

CKR_DEVICE_REMOVED,

CKR_FUNCTION_FAILED,

CKR_GENERAL_ERROR,

CKR_HOST_MEMORY,

CKR_OPERATION_NOT_INITIALIZED,

CKR_SESSION_CLOSED,

CKR_SESSION_HANDLE_INVALID.

Пример

См. C_FindObjectsFinal()

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

C_FindObjectsFinal()

Синтаксис

CK_DEFINE_FUNCTION(CK_RV, C_FindObjectsFinal)(
    CK_SESSION_HANDLE hSession
);

Параметры

hSession

[in]

Дескриптор сессии

Назначение

Функция завершает поиск объектов.

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

CKR_OK – функция выполнена успешно.
Стандартные коды ошибок:

CKR_CRYPTOKI_NOT_INITIALIZED,

CKR_DEVICE_ERROR,

CKR_DEVICE_MEMORY,

CKR_DEVICE_REMOVED,

CKR_FUNCTION_FAILED,

CKR_GENERAL_ERROR,

CKR_HOST_MEMORY,

CKR_OPERATION_NOT_INITIALIZED,

CKR_SESSION_CLOSED,

CKR_SESSION_HANDLE_INVALID.

Пример

CK_SESSION_HANDLE hSession;
CK_OBJECT_HANDLE hObject;
CK_ULONG ulObjectCount;
CK_RV rv;

.
.
rv = C_FindObjectsInit(hSession, NULL_PTR, 0);
assert(rv == CKR_OK);
while (1) {
	rv = C_FindObjects(hSession, &hObject, 1, &ulObjectCount);
	if (rv != CKR_OK || ulObjectCount == 0)
		break;
	.
	.
}

rv = C_FindObjectsFinal(hSession);
assert(rv == CKR_OK);

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

Page tree

C_CreateObject()

Синтаксис

Параметры

Назначение

Примечание

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

Пример

C_DestroyObject()

Синтаксис

Параметры

Назначение

Примечание

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

Пример

C_FindObjectsInit()

Синтаксис

Параметры

Назначение

Примечание

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

Пример

C_FindObjects()

Синтаксис

Параметры

Назначение

Примечание

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

Пример

C_FindObjectsFinal()

Синтаксис

Параметры

Назначение

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

Пример