Функции для работы с сессиями
Table of Contents | ||||||||
---|---|---|---|---|---|---|---|---|
|
...
Для управления сессиями стандартом предоставляются следующие функции.
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 | ||||||
---|---|---|---|---|---|---|
|
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 | |||||
---|---|---|---|---|---|
|
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 | ||
---|---|---|
| ||
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 | ||
---|---|---|
| ||
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 | ||
---|---|---|
| ||
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 | ||
---|---|---|
| ||
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-кода пользовтеля.
Назначение
Функция авторизует пользователя на токене.
...
- Если ulPinLen != 0 и pPin != NULL_PTR, то проверяется длина PIN-кода. Если длина не является допустимой, то возвращается значение CKR_ARGUMENTS_BAD. Если длина удовлетворяет условиям проверки, то проверяются права доступа для пользователя с идентификатором userType.
- Если ulPinLen != 0 и pPin == NULL_PTR, то возвращается ошибка CKR_ARGUMENTS_BAD.
- Если ulPinLen == 0 и pPin != NULL_PTR, то возвращается ошибка CKR_ARGUMENTS_BAD.
- Если ulPinLen == 0 и pPin == NULL_PTR, то отображается PIN Pad.
Возвращаемые значения
CKR_OK – функция выполнена успешно.
...
CKR_USER_TYPE_INVALID.
Расширенные коды ошибок
Пример
Code Block | ||
---|---|---|
| ||
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 | ||
---|---|---|
| ||
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) { . . } } |
...