Общие структуры

USB-токены и смарт-карты JaCartaAPI и SDKUSB-токены и смарт-карты JaCarta

CK_C_INITIALIZE_ARGS

typedef struct CK_C_INITIALIZE_ARGS {
    CK_CREATEMUTEX CreateMutex;
    CK_DESTROYMUTEX DestroyMutex;
    CK_LOCKMUTEX LockMutex;
    CK_UNLOCKMUTEX UnlockMutex;
    CK_FLAGS flags;
    CK_VOID_PTR pReserved;
} CK_C_INITIALIZE_ARGS;

Поддерживаются следующие флаги (flags):

CKF_LIBRARY_CANT_CREATE_OS_THREADS (0x00000001) – True, если потоки исполнения приложения, которые осуществляют вызовы к библиотеке, не могут использовать родные вызовы операционной системы для создания новых потоков. False – в обратном случае.
CKF_OS_LOCKING_OK (0x00000002) – True, если библиотека может использовать родную систему потоков операционной системы для захвата ресурса. False – в противном случае.
CKF_DEVELOPER_MODE (0x80000000) – установка этого флага ускоряет выполнение функций: C_Login() и C_Sign()/C_SignUpdate(). Ускорение обеспечивается за счет отключения проверки целостности и корректности функционирования. Рекомендуется использовать только для целей разработки и тестирования. Используется в:
C_Initialize().

CK_VERSION

typedef struct CK_VERSION {
    CK_BYTE major;
    CK_BYTE minor;
} CK_VERSION;

CK_BYTE major — целая часть номера версии.
CK_BYTE minor — 1/100 часть номера версии.

CK_INFO_PTR

Указатель на структуру CK_INFO. typedef CK_INFO CK_PTR CK_INFO_PTR; CK_INFO

typedef struct CK_INFO {
    CK_VERSION cryptokiVersion;
    CK_UTF8CHAR manufacturerID[32];
    CK_FLAGS flags;
    CK_UTF8CHAR libraryDescription[32];
    CK_VERSION libraryVersion;
} CK_INFO;

CK_VERSION cryptokiVersion — версия стандарта PKCS #11, с которым совместима библиотека Cryptoki.
CK_UTF8CHAR manufacturerID (32) — идентификатор, определяющий разработчика библиотеки Cryptoki. Всегда принимает значение: Aladdin R.D..
CK_FLAGS flags — зарезервированное поле флагов. Должно принимать значение 0.
CK_UTF8CHAR libraryDescription (32) — описание библиотеки. Всегда принимает значение: JaCarta PKCS#11 module.
CK_VERSION libraryVersion — версия библиотеки jcPKCS11-2. Используется в:
C_GetInfo().

CK_ATTRIBUTE

Указатель на структуру CK_ATTRIBUTE. typedef CK_ATTRIBUTE CK_PTR CK_ATTRIBUTE_PTR; CK_ATTRIBUTE

typedef struct CK_ATTRIBUTE {
    CK_ATTRIBUTE_TYPE type;
    CK_VOID_PTR pValue;
    CK_ULONG ulValueLen;
} CK_ATTRIBUTE;

CK_ATTRIBUTE_TYPE type — тип атрибута.
CK_VOID_PTR pValue — значение атрибута.
CK_ULONG ulValueLen — размер значения. Используется в:
C_CreateObject();
C_GetAttributeValue();
C_SetAttributeValue();
C_FindObjectsInit();
C_GenerateKey();
C_GenerateKeyPair();
C_UnwrapKey();
C_DeriveKey();

CK_DATE

Структура, описывающая дату.

typedef struct CK_DATE {
    CK_CHAR year[4];
    CK_CHAR month[2];
    CK_CHAR day[2];
} CK_DATE;

CK_CHAR year (4) — год. Возможные значения: “1900” – “9999”.
CK_CHAR month (2) — месяц. Возможные значения: “01” – “12”.
CK_CHAR day (2) — день. Возможные значения: “01” – “31”.

CK_MECHANISM

Указатель на структуру CK_MECHANISM. typedef CK_MECHANISM CK_PTR CK_MECHANISM_PTR; CK_MECHANISM

typedef struct CK_MECHANISM {
    CK_MECHANISM_TYPE mechanism;
    CK_VOID_PTR pParameter;
    CK_ULONG ulParameterLen;
} CK_MECHANISM;

CK_MECHANISM_TYPE mechanism — тип механизма.
CK_VOID_PTR pParameter — указатель на параметр, если требуется.
CK_ULONG ulParameterLen — размер параметра в байтах. Используется в:
C_EncryptInit();
C_DecryptInit();
C_DigestInit();
C_SignInit();
C_VerifyInit();
C_GenerateKey();
C_GenerateKeyPair();
C_WrapKey();
C_UnwrapKey();
C_DeriveKey();
createCSREx();
JC_CreateCertificateRequest();
verifyReqEx();
genCertEx().

CK_MECHANISM_INFO

Указатель на структуру CK_MECHANISM_INFO. typedef CK_MECHANISM_INFO CK_PTR CK_MECHANISM_INFO_PTR; CK_MECHANISM_INFO

typedef struct CK_MECHANISM_INFO {
    CK_ULONG ulMinKeySize;
    CK_ULONG ulMaxKeySize;
    CK_FLAGS flags;
} CK_MECHANISM_INFO;

CK_ULONG ulMinKeySize — минимальный размер ключа для механизма.
CK_ULONG ulMaxKeySize — максимальный размер ключа для механизма.
CK_FLAGS flags — флаги, определяющие возможности механизма. Поле flags может содержать следующие флаги:
CKF_HW (0x00000001) – аппаратно реализуемый механизм.
CKF_ENCRYPT (0x00000100) – механизм зашифрования данных.
CKF_DECRYPT (0x00000200) – механизм расшифрования данных.
CKF_DIGEST (0x00000400) – механизм хэширования.
CKF_SIGN (0x00000800) – механизм формирования ЭП и имитовставки.
CKF_SIGN_RECOVER (0x00001000) – для поддерживаемых библиотекой Cryptoki механизмов этот флаг не установлен.
CKF_VERIFY (0x00002000) – механизм проверки ЭП и имитовставки.
CKF_VERIFY_RECOVER (0x00004000) – для поддерживаемых библиотекой Cryptoki механизмов этот флаг не установлен.
CKF_GENERATE (0x00008000) – механизм выработки симметричных ключей.
CKF_GENERATE_KEY_PAIR (0x00010000) – механизм генерации ключевой пары.
CKF_WRAP (0x00020000) – механизм экспорта симметричных ключей.
CKF_UNWRAP (0x00040000) – механизм импорта зашифрованных криптографических ключей.
CKF_DERIVE (0x00080000) – механизм выработки общего ключа.
CKF_EXTENSION (0x80000000) – для поддерживаемых библиотекой Cryptoki механизмов этот флаг не установлен. Используется в:
C_GetMechanismInfo().

CK_SLOT_INFO

Указатель на структуру CK_SLOT_INFO. typedef CK_SLOT_INFO CK_PTR CK_SLOT_INFO_PTR; CK_SLOT_INFO

typedef struct CK_SLOT_INFO {
    CK_UTF8CHAR slotDescription[64];
    CK_UTF8CHAR manufacturerID[32];
    CK_FLAGS flags;
    CK_VERSION hardwareVersion;
    CK_VERSION firmwareVersion;
} CK_SLOT_INFO;

CK_UTF8CHAR slotDescription (64) — строка символов с описанием слота.
CK_UTF8CHAR manufacturerID (32) — идентификатор, определяющий разработчика библиотеки Cryptoki. Поле идентификатора принимает значение Aladdin R.D..
CK_FLAGS flags — битовые флаги, определяющие возможности и состояние устройства.
CK_VERSION hardwareVersion — номер аппаратной версии слота.
CK_VERSION firmwareVersion — номер версии прошивки слота. Поле flags может содержать следующие флаги:
CKF_TOKEN_PRESENT (0x00000001) – True, если в слоте наличествует токен.
CKF_REMOVABLE_DEVICE (0x00000002) – True, если ридер поддерживает извлекаемые устройства.
CKF_HW_SLOT (0x00000004) – True, если слот аппаратный. Используется в:
C_GetSlotInfo().

CK_TOKEN_INFO

Указатель на структуру CK_TOKEN_INFO. typedef CK_TOKEN_INFO CK_PTR CK_TOKEN_INFO_PTR; CK_TOKEN_INFO

typedef struct CK_TOKEN_INFO {
    CK_UTF8CHAR label[32];
    CK_UTF8CHAR manufacturerID[32];
    CK_UTF8CHAR model[16];
    CK_CHAR serialNumber[16];
    CK_FLAGS flags;
    CK_ULONG ulMaxSessionCount;
    CK_ULONG ulSessionCount;
    CK_ULONG ulMaxRwSessionCount;
    CK_ULONG ulRwSessionCount;
    CK_ULONG ulMaxPinLen;
    CK_ULONG ulMinPinLen;
    CK_ULONG ulTotalPublicMemory;
    CK_ULONG ulFreePublicMemory;
    CK_ULONG ulTotalPrivateMemory;
    CK_ULONG ulFreePrivateMemory;
    CK_VERSION hardwareVersion;
    CK_VERSION firmwareVersion;
    CK_CHAR utcTime[16];
} CK_TOKEN_INFO;

CK_UTF8CHAR label (32) — назначаемая приложением метка токена. Присваивается в момент инициализации.
CK_UTF8CHAR manufacturerID (32) — идентификатор, определяющий разработчика библиотеки Cryptoki. Поле идентификатора принимает значение Aladdin R.D..
CK_UTF8CHAR model (16) — модель устройства. Для поддерживаемых Cryptoki-библиотекой апплетов/устройств принимает следующие значения:
- JaCarta GOST 2.0 – для приложения GOST (макрос JC_MODEL_CRYPTOTOKEN_2);
- JaCarta Laser – для приложения PKI (макрос JC_MODEL_LASER);
- JaCarta DS – для приложения LT (макрос JC_MODEL_DATASTORE).
CK_CHAR serialNumber (16) — серийный номер.
CK_FLAGS flags — битовые флаги, определяющие возможности и состояние устройства.
CK_ULONG ulMaxSessionCount — максимальное количество сеансов работы одного приложения с устройством. Для поддерживаемых Cryptoki-библиотекой устройств принимает предусмотренное стандартом PKCS #11 значение CK_EFFECTIVELY_INFINITE.
CK_ULONG ulSessionCount — количество открытых сеансов работы данного приложения с устройством. Для поддерживаемых Cryptoki-библиотекой устройств принимает предусмотренное стандартом PKCS #11 значение CK_UNAVAILABLE_INFORMATION.
CK_ULONG ulMaxRwSessionCount — максимальное количество сеансов одного приложения для чтения и записи в устройство. Принимает значение CK_EFFECTIVELY_INFINITE.
CK_ULONG ulRwSessionCount — количество открытых в данный момент сеансов для чтения и записи. Принимает значение CK_UNAVAILABLE_INFORMATION.
CK_ULONG ulMaxPinLen — максимальная длина PIN-кода в байтах. Может принимать значение 16 или 32 в зависимости от апплета.
CK_ULONG ulMinPinLen — минимальная длина PIN-кода в байтах. Может принимать значение 4 или 6 в зависимости от апплета.
CK_ULONG ulTotalPublicMemory — общий размер памяти для хранения публичных объектов. В поддерживаемых устройствах публичная и приватная память общая; поле принимает значение CK_UNAVAILABLE_INFORMATION.
CK_ULONG ulFreePublicMemory — размер памяти, доступной для хранения публичных объектов. Записывается количество байтов, доступных как для приватных, так и для публичных объектов; если размер больше 32 КБ — значение 32767.
CK_ULONG ulTotalPrivateMemory — общий размер памяти для хранения приватных объектов. Принимает значение CK_UNAVAILABLE_INFORMATION.
CK_ULONG ulFreePrivateMemory — размер памяти, доступной для хранения приватных объектов. Записывается количество байтов, доступных как для приватных, так и для публичных объектов; если размер больше 32 КБ — значение 32767.
CK_VERSION hardwareVersion — номер версии устройства.
CK_VERSION firmwareVersion — номер версии прошивки.
CK_CHAR utcTime (16) — поддерживаемые устройства не содержат встроенных часов. Поле заполняется нулями. Поле flags может содержать следующие флаги:
CKF_RNG (0x00000001) – флаг установлен, если в токене присутствует встроенный генератор случайных чисел. Всегда установлен.
CKF_WRITE_PROTECTED (0x00000002) – флаг установлен, когда устройство работает в гостевом режиме, и не установлен, когда устройство работает в режимах, требующих ввода PIN-кода.
CKF_LOGIN_REQIURED (0x00000004) – флаг установлен, если выполнение некоторых криптографических функций требует, чтобы пользователь был залогинен. Всегда установлен.
CKF_USER_PIN_INITIALIZED (0x00000008) – флаг установлен, если инициализирован PIN-код пользователя, и не установлен в противном случае.
CKF_RESTORE_KEY_NOT_NEEDED (0x00000020) – установлен, если успешное сохранение состояния криптографических операций сеанса всегда содержит все ключи, необходимые для восстановления сессии. Всегда не установлен.
CKF_CLOCK_ON_TOKEN (0x00000040) – флаг установлен, если в токене присутствуют встроенные аппаратные часы. Всегда не установлен.
CKF_PROTECTED_AUTHENTICATION_PATH (0x00000100) – установлен, если токен поддерживает возможность аутентификации без ввода PIN-кода. Всегда не установлен.
CKF_DUAL_CRYPTO_OPERATIONS (0x00000200) – флаг установлен, если токен поддерживает выполнение двух криптографических функций одновременно. Всегда не установлен.
CKF_TOKEN_INITIALIZED (0x00000400) – установлен, если токен был инициализирован функцией C_InitToken(). Всегда установлен.
CKF_SECONDARY_AUTHENTICATION (0x00000800) – флаг установлен, если токен поддерживает вторичную аутентификацию для приватных объектов ключей. Всегда не установлен.
CKF_USER_PIN_COUNT_LOW (0x00010000) – флаг установлен, если со времени последней успешной попытки ввода PIN-кода пользователя была предпринята, по меньшей мере, одна неудачная попытка ввода этого PIN-кода, и не установлен в противном случае.
CKF_USER_PIN_FINAL_TRY (0x00020000) – флаг установлен, если у пользователя осталась последняя попытка ввода PIN-кода, и не установлен в других случаях.
CKF_USER_PIN_LOCKED (0x00040000) – флаг установлен, если PIN-код пользователя заблокирован, и не установлен, если PIN-код пользователя не заблокирован.
CKF_USER_PIN_TO_BE_CHANGED (0x00080000) – установлен, если PIN-код пользователя установлен по умолчанию при инициализации или срок его действия истек, т.е. PIN-код необходимо изменить. Всегда не установлен.
CKF_SO_PIN_COUNT_LOW (0x00100000) – флаг установлен, если со времени последней успешной попытки ввода PIN-кода администратора была предпринята, по меньшей мере, одна неудачная попытка ввода этого PIN-кода, и не установлен в противном случае.
CKF_SO_PIN_FINAL_TRY (0x00200000) – флаг установлен, если у администратора осталась последняя попытка ввода PIN-кода, и не установлен в других случаях.
CKF_SO_PIN_LOCKED (0x00400000) – флаг установлен, если PIN-код администратора заблокирован, и не установлен в противном случае.
CKF_SO_PIN_TO_BE_CHANGED (0x00800000) – установлен, если PIN-код администратора установлен по умолчанию при инициализации или срок его действия истек, т.е. PIN-код необходимо изменить. Всегда не установлен.
CKF_ERROR_STATE (0x01000000) – установлен, если токен не прошел самопроверку FIPS 140-2 и находится в состоянии ошибки. Всегда не установлен. Используется в:
C_GetTokenInfo().

CK_SESSION_INFO

Указатель на структуру CK_SESSION_INFO. typedef CK_SESSION_INFO CK_PTR CK_SESSION_INFO_PTR; CK_SESSION_INFO

typedef struct CK_SESSION_INFO {
    CK_SLOT_ID slotID;
    CK_STATE state;
    CK_FLAGS flags;
    CK_ULONG ulDeviceError;
} CK_SESSION_INFO;

CK_SLOT_ID slotID — идентификатор слота.
CK_STATE state — состояние сеанса.
CK_FLAGS flags — флаги, определяющие тип сессии.
CK_ULONG ulDeviceError — код ошибки, определяемый криптографическим устройством. Не поддерживается. Поле flags может содержать следующие флаги:
CKF_RW_SESSION (0x00000002) – установлен, если сеанс поддерживает и чтение, и запись. Не установлен, если сеанс поддерживает только чтение.
CKF_SERIAL_SESSION (0x00000004) – этот флаг добавлен для обратной совместимости и должен быть всегда установлен. Используется в:
C_GetSessionInfo().

JC_ISD_DATA

Указатель на структуру JC_ISD_DATA. typedef JC_ISD_DATA CK_PTR JC_ISD_DATA_PTR; JC_ISD_DATA

typedef struct JC_ISD_DATA {
    CK_UTF8CHAR model[32];
    CK_BYTE manufacturingDate[8];
} JC_ISD_DATA;

CK_UTF8CHAR model (32) — название модели.
CK_BYTE manufacturingDate (8) — дата производства в формате ГГГГММДД. Используется в:
JC_GetISD().

JC_TOKEN_PROPERTIES

Указатель на структуру JC_TOKEN_PROPERTIES. typedef JC_TOKEN_PROPERTIES CK_PTR JC_TOKEN_PROPERTIES_PTR; JC_TOKEN_PROPERTIES

typedef struct JC_TOKEN_PROPERTIES {
    CK_BYTE_PTR pAttr;
    CK_ULONG ulAttrSize;
    CK_BYTE_PTR pJaCartaTag;
    CK_ULONG ulJaCartaTagSize;
    CK_BYTE_PTR pSerialNumber;
    CK_ULONG ulSerialNumberSize;
    CK_ULONG ulManufactureDate;
    CK_ULONG ulAppletCount;
    JC_APPLET_TYPE_PTR pApplets;
} JC_TOKEN_PROPERTIES;

CK_BYTE_PTR pAttr — массив атрибутов.
CK_ULONG ulAttrSize — размер массива атрибутов в байтах.
CK_BYTE_PTR pJaCartaTag — тег считывателя.
CK_ULONG ulJaCartaTagSize — размер тега в байтах.
CK_BYTE_PTR pSerialNumber — серийный номер считывателя.
CK_ULONG ulSerialNumberSize — размер серийного номера считывателя в байтах.
CK_ULONG ulManufactureDate — дата производства в секундах начиная с 01.01.1970.
CK_ULONG ulAppletCount — количество апплетов, установленных на токене.
JC_APPLET_TYPE_PTR pApplets — типы приложений (апплетов). Возможные значения:
- JC_APPLET_TYPE_CRYPTO_TOKEN (1) – приложение Криптотокен;
- JC_APPLET_TYPE_CRYPTO_TOKEN_2 (2) – приложение GOST;
- JC_APPLET_TYPE_LASER (3) – приложение PKI;
- JC_APPLET_TYPE_DATA_STORE (4) – приложение LT;
- JC_APPLET_TYPE_FKH (5) – FKH;
- JC_APPLET_TYPE_PRO_JAVA (6) – приложение PRO Java
- JC_APPLET_TYPE_PRO (7) – приложение PRO
- JC_APPLET_TYPE_VASCO_CARDLESS (8) – Антифрод-терминал в бескарточном режиме
- JC_APPLET_TYPE_WEBPASS (9) – приложение Webpass.

Внимание! Отмеченные звездочкой приложения являются устаревшими, и их поддержка со временем будет прекращена!

Используется в:

JC_GetReaderProperties().

JC_VERSION_INFO

Указатель на структуру JC_VERSION_INFO. typedef JC_VERSION_INFO CK_PTR JC_VERSION_INFO_PTR; JC_VERSION_INFO Версия библиотеки.

typedef struct JC_VERSION_INFO {
    CK_ULONG ulMajor;
    CK_ULONG ulMinor;
    CK_ULONG ulRelease;
    CK_ULONG ulBuild;
} JC_VERSION_INFO;

CK_ULONG ulMajor — главная версия библиотеки.
CK_ULONG ulMinor — дополнительная версия библиотеки.
CK_ULONG ulRelease — номер релиза.
CK_ULONG ulBuild — номер сборки. Используется в:
JC_GetVersionInfo().

CK_GOSTR3410_DERIVE_PARAMS Параметры для выработки ключа согласования.

typedef struct CK_GOSTR3410_DERIVE_PARAMS {
    CK_EC_KDF_TYPE kdf;
    CK_BYTE_PTR pPublicData;
    CK_ULONG ulPublicDataLen;
    CK_BYTE_PTR pUKM;
    CK_ULONG ulUKMLen;
} CK_GOSTR3410_DERIVE_PARAMS;

CK_EC_KDF_TYPE kdf — идентификатор используемой диверсификации ключа. Может принимать значения:
- CKD_NULL – диверсификация ключа не применяется;
- CKD_CPDIVERSIFY_KDF – диверсификация выполняется по алгоритму из RFC 4357 (раздел 6.5).
CK_BYTE_PTR pPublicData — указатель на буфер, содержащий ключ проверки ЭП получателя. Ключ представлен последовательной записью координат точки X и Y; каждая координата — вектор длиной 32 байта в порядке от младшего к старшему (little-endian).
CK_ULONG ulPublicDataLen — длина буфера, содержащего открытый ключ получателя (в байтах). Должна равняться 64.
CK_BYTE_PTR pUKM — указатель на буфер с данными UKM в представлении от младшего к старшему (little-endian).
CK_ULONG ulUKMLen — размер буфера для UKM. Должен принимать значение 8.

CK_GOSTR3410_KEY_WRAP_PARAMS

Параметры экспорта ключа.

typedef struct CK_GOSTR3410_KEY_WRAP_PARAMS {
    CK_BYTE_PTR pWrapOID;
    CK_ULONG ulWrapOIDLen;
    CK_BYTE_PTR pUKM;
    CK_ULONG ulUKMLen;
    CK_OBJECT_HANDLE hKey;
} CK_GOSTR3410_KEY_WRAP_PARAMS;

CK_BYTE_PTR pWrapOID — объектный идентификатор (OID) для обозначения параметров создания общего ключа.
CK_ULONG ulWrapOIDLen — длина объектного идентификатора.
CK_BYTE_PTR pUKM — указатель на буфер с данными UKM (little-endian). При NULL_PTR используется случайное значение UKM. При экспорте виртуального секретного ключа параметр не передаётся.
CK_ULONG ulUKMLen — размер буфера для UKM. Должен принимать значение 8.
CK_OBJECT_HANDLE hKey — указатель на исходный ключ.

CK_ECDH1_DERIVE_PARAMS Параметры механизм согласования ключей CKM_GOST_KEG

typedef struct CK_ECDH1_DERIVE_PARAMS {
    CK_EC_KDF_TYPE kdf;
    CK_ULONG ulSharedDataLen;
    CK_BYTE_PTR pSharedData;
    CK_ULONG ulPublicDataLen;
    CK_BYTE_PTR pPublicData;
} CK_ECDH1_DERIVE_PARAMS;

CK_EC_KDF_TYPE kdf — механизм диверсификации. В структуре не используется и должен быть установлен в CKD_NULL.
CK_ULONG ulSharedDataLen — длина используемой величины UKM в байтах.
CK_BYTE_PTR pSharedData — указатель на величину UKM.
CK_ULONG ulPublicDataLen — длина ключа проверки ЭП в байтах (64 или 128).
CK_BYTE_PTR pPublicData — указатель на ключ проверки ЭП.