Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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

Table of Contents
minLevel2
outlinetrue
stylenone
separatorbraces

...

Для управления сессиями стандартом предоставляются следующие функции.

C_OpenSession()

Code Block
CK_DEFINE_FUNCTION(CK_RV, C_OpenSession)(
	CK_SLOT_ID 				slotID,
	CK_FLAGS 				flags,
	CK_VOID_PTR 			pApplication,
	CK_NOTIFY 				Notify,
	CK_SESSION_HANDLE_PTR 	phSession
);
  • slotID - ID слота, к которому подключен токен;
  • flags - указатель на тип сессии;
  • pApplication - зависящий от приложения указатель на обратный вызов уведомления (в текущей реализации Рутокен параметр игнорируется);
  • Notify - адрес функции обратного вызова уведомлений (в текущей реализации Рутокен параметр игнорируется);
  • phSession - указатель на идентификатор (дескриптор, хэндл) новой сессии.

Назначение

Функция открывает сессию между приложением и токеном, подключенным к данному слоту.

...

Функция обратного вызова Notify использует библиотеку для уведомления приложения об определенных событиях. Если приложение не поддерживает обратную связь, параметр Notify должен иметь значение NULL_PTR. В текущей реализации Рутокен значение данного параметра игнорируется.

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

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

...

CKR_TOKEN_WRITE_PROTECTED.

Расширенные коды ошибок

Пример

Excerpt Include
3-3 Функции для работы с сессиями
3-3 Функции для работы с сессиями
nopaneltrue

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

C_CloseSession()

Code Block
CK_DEFINE_FUNCTION(CK_RV, C_CloseSession)(
	CK_SESSION_HANDLE	hSession
);
  • hSession - дескриптор открытой сессии.

Назначение

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

...

Возвращаемое значение CKR_SESSION_CLOSED означает, пока функция выполнялась, сессия была закрыта другим вызовом C_CloseSession, завершившимся первым.

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

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

...

CKR_SESSION_HANDLE_INVALID.

Расширенные коды ошибок

Пример

Excerpt
Code Block
collapsetrue
CK_SLOT_ID slotID;
CK_BYTE application;
CK_NOTIFY MyNotify;
CK_SESSION_HANDLE hSession;
CK_RV rv;
.
.
application = 17;
MyNotify = &EncryptionSessionCallback;
rv = C_OpenSession(slotID, CKF_SERIAL_SESSION | CKF_RW_SESSION, (CK_VOID_PTR) &application, MyNotify, &hSession);
if (rv == CKR_OK) {
	.
	.
	C_CloseSession(hSession);
}

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

C_CloseAllSessions()

Code Block
CK_DEFINE_FUNCTION(CK_RV, C_CloseAllSessions)(
	CK_SLOT_ID	slotID
);
  • slotID - ID слота, к которому подключен токен.

Назначение

Функция закрывает все сессии приложения, открытые для данного токена.

...

После удачного завершения вызова функции C_CloseAllSessions состояние "залогиненности" токена для приложения вернется к публичной сессии. Любая новая сессия, открытая приложением, будет публичной сессией типа R/O или R/W.

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

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

...

CKR_TOKEN_NOT_PRESENT.

Расширенные коды ошибок

Пример

Code Block
collapsetrue
CK_SLOT_ID slotID;
CK_RV rv;
.
.
rv = C_CloseAllSessions(slotID);

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

C_GetSessionInfo()

Code Block
CK_DEFINE_FUNCTION(CK_RV, C_GetSessionInfo)(
	CK_SESSION_HANDLE hSession,
	CK_SESSION_INFO_PTR pInfo
);
  • hSession - дескриптор открытой сессии;
  • pInfo - указатель на данные сессии.

Назначение

Функция получает информацию о сессии.

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

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

...

CKR_SESSION_HANDLE_INVALID.

Расширенные коды ошибок

Пример

Code Block
collapsetrue
CK_SESSION_HANDLE hSession;
CK_SESSION_INFO info;
CK_RV rv;
.
.
rv = C_GetSessionInfo(hSession, &info);
if (rv == CKR_OK) {
	if (info.state == CKS_RW_USER_FUNCTIONS) {
	.
	.
	}
.
.
}

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

C_GetOperationState()

Code Block
CK_DEFINE_FUNCTION(CK_RV, C_GetOperationState)(
	CK_SESSION_HANDLE hSession,
	CK_BYTE_PTR pOperationState,
	CK_ULONG_PTR pulOperationStateLen
);
  • hSession - дескриптор открытой сессии;
  • pOperationState - указатель на состояние криптографических операций;
  • pulOperationStateLen - указатель на длину значения состояния криптографических операций.

Назначение

Функция получает копию состояния криптографических операций сессии, представленную строкой байтов, для дальнейшего его восстановления функцией C_SetOperationState.

...

Note

Функция C_GetOperationState поддерживается библиотекой rtPKCS11 начиная с версии 2.30.

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

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

...

CKR_STATE_UNSAVEABLE.

Расширенные коды ошибок

Пример

Code Block
collapsetrue
CK_SESSION_HANDLE hSession;
CK_MECHANISM digestMechanism;
CK_ULONG ulStateLen;
CK_BYTE data1[] = {0x01, 0x03, 0x05, 0x07};
CK_BYTE data2[] = {0x02, 0x04, 0x08};
CK_BYTE data3[] = {0x10, 0x0F, 0x0E, 0x0D, 0x0C};
CK_BYTE pDigest[20];
CK_ULONG ulDigestLen;
CK_RV rv;

.
.
/* Инициализация операции хеширования */
rv = C_DigestInit(hSession, &digestMechanism);
assert(rv == CKR_OK);

/* Начало хеширования */
rv = C_DigestUpdate(hSession, data1, sizeof(data1));
assert(rv == CKR_OK);

/* Определение длины состояния криптографических функций */
rv = C_GetOperationState(hSession, NULL_PTR, &ulStateLen);
assert(rv == CKR_OK);

/* Назначение памяти и получение состояния */
pState = (CK_BYTE_PTR) malloc(ulStateLen);
rv = C_GetOperationState(hSession, pState, &ulStateLen);

/* Продолжение хеширования */
rv = C_DigestUpdate(hSession, data2, sizeof(data2));
assert(rv == CKR_OK);

/* Восстановление состояния. Дескрипторы ключей не нужны */
rv = C_SetOperationState(hSession, pState, ulStateLen, 0, 0);
assert(rv == CKR_OK);

/* Продолжение хеширования с сохраненного момента */
rv = C_DigestUpdate(hSession, data3, sizeof(data3));
assert(rv == CKR_OK);

/* Завершение хеширования */
ulDigestLen = sizeof(pDigest);
rv = C_DigestFinal(hSession, pDigest, &ulDigestLen);
if (rv == CKR_OK) {
	/* pDigest[] сейчас содержить хеш-значение 0x01030507100F0E0D0C */
.
.
}

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

C_SetOperationState()

Code Block
CK_DEFINE_FUNCTION(CK_RV, C_SetOperationState)(
	CK_SESSION_HANDLE hSession,
	CK_BYTE_PTR pOperationState,
	CK_ULONG ulOperationStateLen,
	CK_OBJECT_HANDLE hEncryptionKey,
	CK_OBJECT_HANDLE hAuthenticationKey
);
  • hSession - дескриптор открытой сессии;
  • pOperationState - указатель на сохраненное состояние криптографических операций;
  • pulOperationStateLen - указатель на длину сохраненного состояния криптографических операций;
  • hEncryptionKey - дескриптор ключа, используемого для текущей операции шифрования/расшифрования в восстановленной сессии (или 0, если не требуется ключ шифрования/расшифрования, или нет такой операции в восстановленной сессии, или вся необходимая ключевая информация есть в сохраненном состоянии);
  • hAuthenticationKey - дескриптор ключа, используемого для подписи, вычисления значения MAC-кода (имитовставки), проверки подписи в восстановленной сессии (или 0, если такой ключ не требуется, или нет такой операции в восстановленной сессии, или вся необходимая ключевая информация есть в сохраненном состоянии).

Назначение

Функция восстанавливает состояние криптографических операций сессии из строки байтов, полученных функцией C_SetOperationState.

...

Note

Функция C_SetOperationState поддерживается библиотекой rtPKCS11 начиная с версии 2.30.

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

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

...

CKR_SESSION_HANDLE_INVALID.

Расширенные коды ошибок

Пример

Code Block
collapsetrue
CK_SESSION_HANDLE hSession;
CK_MECHANISM digestMechanism;
CK_ULONG ulStateLen;
CK_BYTE data1[] = {0x01, 0x03, 0x05, 0x07};
CK_BYTE data2[] = {0x02, 0x04, 0x08};
CK_BYTE data3[] = {0x10, 0x0F, 0x0E, 0x0D, 0x0C};
CK_BYTE pDigest[20];
CK_ULONG ulDigestLen;
CK_RV rv;

.
.
/* Инициализация операции хеширования */
rv = C_DigestInit(hSession, &digestMechanism);
assert(rv == CKR_OK);

/* Начало хеширования */
rv = C_DigestUpdate(hSession, data1, sizeof(data1));
assert(rv == CKR_OK);

/* Определение длины состояния криптографических функций */
rv = C_GetOperationState(hSession, NULL_PTR, &ulStateLen);
assert(rv == CKR_OK);

/* Назначение памяти и получение состояния */
pState = (CK_BYTE_PTR) malloc(ulStateLen);
rv = C_GetOperationState(hSession, pState, &ulStateLen);

/* Продолжение хеширования */
rv = C_DigestUpdate(hSession, data2, sizeof(data2));
assert(rv == CKR_OK);

/* Восстановление состояния. Дескрипторы ключей не нужны */
rv = C_SetOperationState(hSession, pState, ulStateLen, 0, 0);
assert(rv == CKR_OK);

/* Продолжение хеширования с сохраненного момента */
rv = C_DigestUpdate(hSession, data3, sizeof(data3));
assert(rv == CKR_OK);

/* Завершение хеширования */
ulDigestLen = sizeof(pDigest);
rv = C_DigestFinal(hSession, pDigest, &ulDigestLen);
if (rv == CKR_OK) {
	/* pDigest[] сейчас содержит хеш-значение 0x01030507100F0E0D0C */
.
.
}

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

C_Login()

Code Block
CK_DEFINE_FUNCTION(CK_RV, C_Login)(
	CK_SESSION_HANDLE hSession,
	CK_USER_TYPE userType,
	CK_UTF8CHAR_PTR pPin,
	CK_ULONG ulPinLen
);
  • hSession - дескриптор сессии;
  • userType - тип пользователя;
  • pPin - указатель на PIN-код пользователя;
  • ulPinLen - длина значения PIN-кода пользовтеля.

Назначение

Функция авторизует пользователя на токене.

...

  1. Если ulPinLen != 0 и pPin != NULL_PTR, то проверяется длина PIN-кода. Если длина не является допустимой, то возвращается значение CKR_ARGUMENTS_BAD. Если длина удовлетворяет условиям проверки, то проверяются права доступа для пользователя с идентификатором userType.
  2. Если ulPinLen != 0 и pPin == NULL_PTR, то возвращается ошибка CKR_ARGUMENTS_BAD.
  3. Если ulPinLen == 0 и pPin != NULL_PTR, то возвращается ошибка CKR_ARGUMENTS_BAD.
  4. Если ulPinLen == 0 и pPin == NULL_PTR, то отображается PIN Pad.

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

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

...

CKR_USER_TYPE_INVALID.

Расширенные коды ошибок

Пример

Code Block
collapsetrue
CK_SESSION_HANDLE hSession;
CK_UTF8CHAR userPIN[] = {"MyPIN"};
CK_RV rv;

rv = C_Login(hSession, CKU_USER, userPIN, sizeof(userPIN)-1);
if (rv == CKR_OK) { 
	.
	.
	rv == C_Logout(hSession);
	if (rv == CKR_OK) {
		.
		.
	}
}

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

C_Logout()

Code Block
CK_DEFINE_FUNCTION(CK_RV, C_Logout)(
	CK_SESSION_HANDLE hSession
);
  • hSession - дескриптор сессии.

Назначение

Функция завершает авторизацию пользователя на токене.

...

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

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

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

...

CKR_USER_NOT_LOGGED_IN.

Расширенные коды ошибок

Пример

Code Block
collapsetrue
CK_SESSION_HANDLE hSession;
CK_UTF8CHAR userPIN[] = {"MyPIN"};
CK_RV rv;

rv = C_Login(hSession, CKU_USER, userPIN, sizeof(userPIN)-1);
if (rv == CKR_OK) { 
	.
	.
	rv == C_Logout(hSession);
	if (rv == CKR_OK) {
		.
		.
	}
}

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