UniToken API Usage

From SecuTech Wiki
Jump to: navigation, search


UniToken provides a set of UniToken APIs to manage the secure file system for general usage, apart from PKI applications. Please install the UniToken API package or the UniToken full package to enable features. The UniToken API package installs UniToken.dll for general UniToken API implementation and UniTokenAx.dll for ActiveX usage.

API Usage

Initialize the library to release resources by calling UT_Initialize and UT_Finalize. UT_Initialize needs to be called before using the library and UT_Finalize needs to be called by end of the operation. Both functions need to be called only once. Calling UT_GetTokenList and UT_OpenDevice will get device and open it to obtain the device handle. Get all the slots having devices by calling UT_GetTokenList. Open the device of the specified slot to obtain the device handle. Start operating the device.

Prototype Specification

UT_HANDLE

UT_HANDLE is specified by UniToken library and used for detecting devices. It is defined as follows:

typedef unsigned long UT_HANDLE;

KEY_HANDLE, KEY_HANDLE_PTR
KEY_HANDLE is specified by UniToken library and used for detecting keys. It is defined as follows:

typedef unsigned long KEY_HANDLE;

KEY_HANDLE_PTR is the pointer of KEY_HANDLE.

UT_RV

UT_RV is specified by UniToken library and used for identifying the return value of library. It is defined as follows:

typedef unsigned long UT_RV;

UT_SLOT_ID

UT_SLOT_ID is specified by UniToken library and used for identifying slots. It is defined as follows:

typedef unsigned long UT_SLOT_ID;

UT_STATUS

UT_STATUS is specified by UniToken library and used for identifying the status of slot. It is defined as follows:

typedef unsigned long UT_STATUS;

We defined some values for this UniToken library version.

  • define TOKEN_NO_EVENT 0
  • define TOKEN_INSERT 1
  • define TOKEN_REMOVE 2

About Macro

Size

  • define UT_MAX_PIN_LEN 128
  • define UT_MAX_ID_LEN 32
  • define MAX_SLOT_NUMBER 32
  • define FS_MEMORY (256*1024)
Parameter Meaning
  • UT_MAX_PIN_LEN the maximum password length
  • UT_MAX_ID_LEN the maximum UniToken ID length
  • MAX_SLOT_NUMBER the maximum volume of slot
  • FS_MEMORY the maximum capacity of file system

Password

  • define UT_DEFAULT_SO "admin"
  • define UT_DEFAULT_USER "user"
Parameter Meaning
  • UT_DEFAULT_SO the admin default password of UniToken
  • T_DEFAULT_USER the user default password of UniToken

Slot Status

  • define TOKEN_NO_EVENT 0
  • define TOKEN_INSERT 1
  • define TOKEN_REMOVE 2
Parameter Meaning
  • TOKEN_NO_EVENT No slot status has changed
  • TOKEN_INSERT A device is inserted in a slot
  • TOKEN_REMOVE The device in the slot is removed

User Level

  • define UT_USER_LEVEL_GUEST 0x0
  • define UT_USER_LEVEL_USER 0x1
  • define UT_USER_LEVEL_ADMIN 0x2
Parameter Meaning
  • UT_USER_LEVEL_GUEST GUEST Level
  • UT_USER_LEVEL_USER USER Level
  • UT_USER_LEVEL_ADMIN ADMIN ADMIN Level

Modes of Changing Passwords

  • define UT_CHANGE_PIN_MODE_BYSELF 0x1
  • define UT_CHANGE_PIN_MODE_ADMIN_CHANGE_USER 0x2
Parameter Meaning
  • UT_CHANGE_PIN_MODE_BYSELF Current user changes his password
  • UT_CHANGE_PIN_MODE_ADMIN_CHANGE_USER Changing user password requires admin permission

LED On-off

  • define LED_ON 1
  • define LED_OFF 0
Parameter Meaning
  • LED_ON turn on LED
  • LED_OFF turn off LED

DES Key Length

  • define DES_KEY_LEN_8_BYTE 8
  • define DES3_KEY_LEN_24_BYTE 24
Parameter Meaning
  • DES_KEY_LEN_8_BYTE DES key length
  • DES3_KEY_LEN_24_BYTE DES3 key length

DES Data Length

  • define DES_DATA_LEN_8_BYTE 8
Parameter Meaning
  • DES_DATA_LEN_8_BYTE BYTE DES en/decrypt data length

AES Key Length

  • define AES_KEY_LEN_128_BIT 16
  • define AES_KEY_LEN_192_BIT 24
Parameter Meaning
  • AES_KEY_LEN_128_BIT default key length
  • AES_KEY_LEN_192_BIT maximum key length

AES Data Length

  • define AES_DATA_LEN_16_BYTE 16
Parameter Meaning
  • AES_DATA_LEN_16_BYTE AES en/decrypt data length

RSA Modulus Length

  • define RSA_MODULUS_LEN_1024_BIT 128
  • define RSA_MODULUS_LEN_2048_BIT 256
Parameter Meaning
  • RSA_MODULUS_LEN_1024_BIT default modulus length
  • RSA_MODULUS_LEN_2048_BIT Maximum modulus length

RSA Public Exponent

  • define RSA_PUBEXP_LEN_65537_BIT 65537
Parameter Meaning
  • RSA_PUBEXP_LEN_65537_BIT RSA public exponent

RSA Data Length

  • define RSA_DATA_LEN_1024_BIT 128
  • define RSA_DATA_LEN_2048_BIT 256
Parameter Meaning
  • RSA_DATA_LEN_1024_BIT default data length
  • RSA_DATA_LEN_2048_BIT maximum data length

RSA Import New Key Pair

  • define RSA_IMPORT_NEW 0
Parameter Meaning
  • RSA_IMPORT_NEW newly imported key pair

File Name Length

  • define UT_FILE_NAME_LENGTH 16
Parameter Meaning
  • UT_FILE_NAME_LENGTH file name maximum length not including string terminator

File Permission

  • define FILE_PERMISSION_GUEST 0x0
  • define FILE_PERMISSION_USER 0x1
  • define FILE_PERMISSION_ADMIN 0x2
Parameter Meaning
  • FILE_PERMISSION_GUEST GUEST permission file
  • FILE_PERMISSION_USER USER permission file
  • FILE_PERMISSION_ADMIN ADMIN permission file