UniToken API Reference

UT_GetLibraryVersion

API Prototype

unsigned long UT_API UT_GetLibraryVersion()

Description

To get the version of the present library.

Parameters

n/a

Returned Value

RETURNED VALUE	DESCRIPTION
Library version	the version of the current library

Sample

unsigned long ulLibraryVersion;
ulLibraryVersion = UT_GetLibraryVersion();

UT_Initialize

API Prototype

UT_RV UT_API UT_Initialize()

Description

To initialize the UniToken. This should be called before any other function, with the exception UT_GetLibraryVersion

Parameters

n/a

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_ALREADY_INITIALIZE	Library already initialized

Sample

UT_RV ret;
ret = UT_Initialize();

UT_Finalize

API Prototype

UT_RV UT_API UT_Finalize()

Description

Call this function to end any interaction with UniToken and free the memory.

Parameters

n/a

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized

Sample

UT_RV ret;
ret = UT_Finalize();

UT_GetTokenList

API Prototype

UT_RV UT_API UT_GetTokenList(UT_SLOT_ID* lpSlotID, unsigned long* lpTokenCount)

Description

To get the list of Slot ID and the number of Slot ID.

Parameters

PARAMETERS	DESCRIPTION
lpSlotID	[out] slot ID list
lpTokenCount	* [in] size of buffer (0~32 bytes) * [out]number of token

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized

Sample

UT_RV ret;
UT_HANDLE utHandle;
UT_SLOT_ID* lpSlotID = NULL;
unsigned long ulTokenCount = 0;
ret = UT_GetTokenList(lpSlotID, &ulTokenCount);

if (ret == UT_BUFFER_TOO_SMALL)
{
   lpSlotID = new UT_SLOT_ID[ulTokenCount];
   ret = UT_GetTokenList(lpSlotID, &ulTokenCount);
}

ret = UT_OpenDevice(lpSlotID[0], &utHandle);
ret = UT_GetHandle(lpSlotID[0], &utHandle);
ret = UT_GetSlotID(utHandle, &lpSlotID[0]);
ret = UT_CloseDevice(utHandle);

UT_OpenDevice

Prototype

UT_RV UT_API UT_OpenDevice(
  UT_SLOT_ID SlotID,
  UT_HANDLE* lputHandle
);

Description

To open the device in the specified slot.

Parameters

PARAMETERS	DESCRIPTION
SlotID	[in] the specified slot
lputHandle	[out] device handle

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_SLOT_ID_INVALUD	Invalid slot ID

Usage Note

SlotID should be retrieved from UT_GetTokenList instead manually entered. Therefore, this function cannot be called before UT_GetTokenList

Sample

See the sample of UT_GetTokenList

UT_CloseDevice

Prototype

UT_RV UT_API UT_CloseDevice(UT_HANDLE utHandle);

Description

To close the specified device.

Parameters

n/a

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_TOKEN_HANDLE_INVALID	Invalid token handle

Sample

See also the sample of UT_GetTokenList

UT_GetHandle

Prototype

UT_RV UT_API UT_GetHandle(
  UT_SLOT_ID SlotID,
  UT_HANDLE* lputHandle
);

Description

To get device handle by Slot ID.

Parameters

PARAMETERS	DESCRIPTION
SlotID [in]	the specified slot
lputHandle [out]	device handle

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument

Sample

See the sample of UT_GetTokenList

UT_GetSlotID

Prototype

UT_RV UT_API UT_GetSlotID(
  UT_HANDLE utHandle,
  UT_SLOT_ID* lpSlotID
);

Description

To get Slot ID by device handle.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	the specified handle
lpSlotID [out]	Slot ID

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALIDM	Invalid token handle

Sample

See the sample of UT_GetTokenList

UT_GetSlotStatus

Prototype

UT_RV UT_API UT_GetSlotStatus(
  UT_STATUS* lpStatus,
  UT_SLOT_ID* lpSlotID
);

Description

To get the status of Slot.

Parameters

PARAMETERS	DESCRIPTION
lpStatus [out]	the current status of slot
lpSlotID [out]	Slot ID

Notes:

lpStatus can be:

1. Inserted, when UniToken is inserted into the slot;
2. removed, when UniToken is removed from the slot;
3. no change, when there’s no change to the status of slot. In this case, lpSlotID is undefined.

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument

Sample

UT_RV rv;
UT_STATUS status;
UT_SLOT_ID slotID;
rv = UT_GetSlotStatus(&status, & slotID);
if (rv == UT_OK)
{
  if (status == TOKEN_NO_EVENT)
  {
  // no change of status
  }
  else if (status == TOKEN_INSERT)
  {
  // token inserted
  }
  else if (status == TOKEN_REMOVE)
  {
  // token removed
  }
}

UT_GetTokenType

Prototype

UT_RV UT_API UT_GetTokenType(
  UT_HANDLE utHandle,
  char* lpszTokenType
);

Description

To get the type of the current device, e.g. UniToken STD, PRO.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpszTokenType [out]	UniToken type (string, 32 bytes)

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle

Sample

UT_RV ret;
UT_HANDLE utHandle;
char TokenType[33] = {0};
ret = UT_GetTokenType(utHandle, (char *)TokenType);

UT_GetFirmwareVersion

Prototype

UT_RV UT_API UT_GetFirmwareVersion(
  UT_HANDLE utHandle,
  unsigned long* lpVersion
);

Description

To get the version of firmware.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpVersion [out]	firmware version

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle

Sample

UT_RV ret;
UT_HANDLE utHandle;
unsigned long Version;
ret = UT_GetFirmwareVersion(utHandle, &Version);

UT_Logoff

Prototype

UT_RV UT_API UT_Logoff(UT_HANDLE utHandle);

Description

To log off the specified Token.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_TOKEN_HANDLE_INVALID	Invalid token handle

Sample

See the sample of UT_Logon

UT_Logon

Prototype

UT_RV UT_API UT_Logon(
  UT_HANDLE utHandle,
  unsigned long UserLevel,
  unsigned char* lpszPin
);

Description

To logon the specified token.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
UserLevel [in]	levels of permission
lpszPin [in]	the corresponding password with certain permission level

Note:

lpszPin is made up with strings, and the minimum size is 1 byte.

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_PIN_ERROR	Wrong password
UT_USER_FULL	No more sessions allowed
UT_USER_LOCKED	Token locked

Usage Note

UniToken provides three levels of user permission: GUEST permission, USER permission and ADMIN permission. The default permission is GUEST. To log on as USER or ADMIN, the corresponding PINs are required.

Sample

UT_RV ret;
UT_HANDLE utHandle;
unsigned char Pin[] = UT_DEFAULT_USER;
unsigned long UserLevel;
ret = UT_Logon(utHandle, UT_USER_LEVEL_USER, (unsigned char*) Pin);
ret = UT_GetCurrentUserLevel(utHandle, &UserLevel);
ret = UT_Logoff(utHandle);

UT_GetCurrentUserLevel

Prototype

UT_RV UT_API UT_GetCurrentUserLevel(
  UT_HANDLE utHandle,
  unsigned long* lpUserLevel
);

Description

To get the current permission level.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpUserLevel [out]	Permission level

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle

Sample

See the sample of UT_Logon.

UT_ChangePin

Prototype

UT_RV UT_API UT_ChangePin(
  UT_HANDLE utHandle,
  unsigned char UserLevel,
  unsigned long ChangeMode,
  unsigned char* OldPin,
  unsigned char* NewPin
);

Description

To change the PIN.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
UserLevel [in]	permission level
ChangeMode [in]	mode to change to
OldPIN [in]	old PIN
NewPin [in]	new PIN

Notes:

Change Mode can be UT_CHANGE_PIN_MODE_BYSELF or UT_CHANGE_PIN_MODE_ADMIN_CHANGE_USER

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NOT_ALLOWED	Operation not allowed

Usage Note

Two ways of changing password:

1. User/Admin changes his own password. Log on as USER or ADMIN and type in the old password and the new one. Here, the mode of changing PIN is UT_CHANGE_PIN_MODE_BYSELF
2. Admin resets user password. Log on as ADMIN and type in new password of USER. Here, the mode of changing PIN is UT_CHANGE_PIN_MODE_ADMIN_CHANGE_USER In this case, OldPin is not required.

Sample

UT_RV ret;
UT_HANDLE utHandle;
unsigned char Pin[] = UT_DEFAULT_USER;
unsigned char NewPin[] = "1234";
unsigned long UserLevel;
ret = UT_Logon(utHandle, UT_USER_LEVEL_USER, (unsigned char*) Pin);
ret = UT_ChangePin(utHandle, UT_USER_LEVEL_USER, UT_CHANGE_PIN_MODE_BYSELF, (unsigned char*) Pin, (unsigned char*) newPin);

UT_GetID

Prototype

UT_RV UT_API UT_GetID(
  UT_HANDLE utHandle,
  char* lpszId
);

Description

To get the token ID of specified device.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpszId [out]	UniToken ID (string, 32 bytes)

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle

Sample

See the sample of UT_SetID

UT_SetID

Prototype

UT_RV UT_API UT_SetID(
  UT_HANDLE utHandle,
  char* lpszId
);

Description

To set the token ID of the specified device

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpszId [out]	UniToken ID (string, 32 bytes)

Returned value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle

Sample

UT_RV ret;
UT_HANDLE utHandle;
char Id[33] = "UniTokenPRO";
unsigned long UserLevel;
ret = UT_SetID(utHandle, Id);
ret = UT_GetID(utHandle, Id);

UT_GetHID

Prototype

UT_RV UT_API UT_GetHID(
  UT_HANDLE utHandle,
  unsigned long* lpHid
);

Description

To get the Hardware ID of the specified device

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpHid [out]	Hardware ID

Returned value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle

Sample

UT_RV ret;
UT_HANDLE utHandle;
unsigned long Hid;
ret = UT_GetHID(utHandle, &Hid);

UT_GetSoftID

Prototype

UT_RV UT_API UT_GetSoftID(
  UT_HANDLE utHandle,
  unsigned long* lpSoftID
);

Description

To get the Software ID of the specified device

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpSoftID [out]	Software ID

Returned value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle

Sample

See also the sample of UT_SetSoftID

UT_SetSoftID

Prototype

UT_RV UT_API UT_SetSoftID(
  UT_HANDLE utHandle,
  unsigned long SoftID
);

Description

To set the Software ID of the specified device.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpSoftID [out]	Software ID

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle

Sample

UT_RV ret;
UT_HANDLE utHandle;
unsigned long SoftID = 0;
ret = UT_GetSoftID(utHandle, &SoftID);
ret = UT_SetSoftID(utHandle, SoftID);

UT_LED

Prototype

UT_RV UT_API UT_LED(
  UT_HANDLE utHandle,
  unsigned char On
);

Description

To turn on/off LED.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
On [in]	the status of the LED

Notes:

The parameter On can be LED_ON or LED_OFF

Returned value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_TOKEN_HANDLE_INVALID	Invalid token handle

Sample

UT_RV ret;
UT_HANDLE utHandle;
ret = UT_LED(utHandle, LED_ON);

UT_SetAttemptCount

Prototype

UT_RV UT_API UT_SetAttemptCount(
  UT_HANDLE utHandle,
  unsigned long MaxAttempt
);

Description

To set the maximum times of PIN attempt

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
MaxAttempt [in]	maximum attempt times

Notes:

The maximum times of attempt UniToken allows is 15 times. If a user types in wrong PIN consecutively for 15 times, the UniToken will be locked.

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission

Usage Note

This function is used for unlocking the token.

Sample

See the sample of UT_GetAttemptCount

UT_GetAttemptCount

Prototype

UT_RV UT_API UT_GetAttemptCount(
  UT_HANDLE utHandle,
  unsigned long* lpUserAttempt,
  unsigned long* lpAdminAttempt
);

Description

To count the number of failed login attempts.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpUserAttempt [out]	User PIN attempt times
lpAdminAttempt [out]	Admin PIN attempt times

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle

Sample

UT_RV ret;
UT_HANDLE utHandle;
unsigned long UserAttempt;
unsigned long AdminAttempt;
ret = UT_SetAttemptCount(utHandle, 15);
ret = UT_GetAttemptCount(utHandle, &UserAttempt, &AdminAttempt);

UT_Format

Prototype

UT_RV UT_API UT_Format(UT_HANDLE utHandle);

Description

To format a UniToken.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission

Usage Note: After formatting, the PINs of User and Admin are set back to the default ones as well as the whole file system and all the keys inside.

Sample

UT_RV ret;
UT_HANDLE utHandle;
ret = UT_Format(utHandle);

UT_Rand

Prototype

UT_RV UT_API UT_Rand(
  UT_HANDLE utHandle,
  unsigned long Length,
  unsigned char* lpOut,
  void* lpReserve
);

Description

To generate random numbers.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
Length [in]	length of random number (in bytes)
lpOut [out]	random number
lpReserve	reserved for future use

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle

Sample

UT_RV ret;
UT_HANDLE utHandle;
unsigned char OutRand[8];
ret = UT_Rand(utHandle, 8, OutRand, NULL);

UT_DESGenerateKey

Prototype

UT_RV UT_API UT_DESGenerateKey(
  UT_HANDLE utHandle,
  KEY_HANDLE_PTR lpKeyHandle
);

Description

To generate a DES key.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpKeyHandle [out]	key handle

Note:

The length of generated DES key is 8 bytes.

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_KEY_FULL	no more keys can be generated

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_DESGenerateKey(utHandle, &KeyHandle);

UT_DESEncrypt

Prototype

UT_RV UT_API UT_DESEncryptZ(
  UT_HANDLE utHandle,
  KEY_HANDLE KeyHandle,
  unsigned char* lpData,
  unsigned long DataLength,
  unsigned char* lpEncryptedData,
  unsigned long* lpEncryptedDataLength
);

Description

To encrypt data with DES.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
KeyHandle [in]	key handle
lpData [in]	plaintext
DataLength [in]	length of plaintext in bytes
lpEncryptedData [out]	ciphertext
lpEncryptedDataLength [out]	length of ciphertext

Notes:

DateLength is DES_DATA_LEN_8_BYTE

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_KEY_HANDLE_INVALID	Invalid key handle

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
unsigned char Data[DES_DATA_LEN_8_BYTE];
unsigned char EncryptedData[DES_DATA_LEN_8_BYTE];
unsigned long EncryptedDataLength;
ret = UT_DESEncrypt(utHandle,
                  keyHandle,
                  Data,
                  DES_DATA_LEN_8_BYTE,
                  EncryptedData,
                  &EncryptedDataLength
                  );

UT_DESDecrypt

Prototype

UT_RV UT_API UT_DESDecrypt(
  UT_HANDLE utHandle,
  KEY_HANDLE KeyHandle,
  unsigned char* lpEncryptedData,
  unsigned long EncryptedDataLength,
  unsigned char* lpData,
  unsigned long* lpDataLength
);

Description

To decrypt data with DES.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
KeyHandle [in]	key handle
lpEncryptedData [in]	ciphertext
EncryptedDataLength [in]	length of ciphertext in bytes
lpData [out]	plaintext
lpDataLength [out]	length of plaintext

Notes:

EncryptedDataLength is DES_DATA_LEN_8_BYTE

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_KEY_HANDLE_INVALID	Invalid key handle

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
unsigned char Data[DES_DATA_LEN_8_BYTE];
unsigned char EncryptedData[DES_DATA_LEN_8_BYTE];
unsigned long DataLength;
ret = UT_DESDecrypt(utHandle,
                  KeyHandle,
                  EncryptedData,
                  DES_DATA_LEN_8_BYTE,
                  Data,
                  &DataLength
                  );

UT_DESImportKey

Prototype

UT_RV UT_API UT_DESImportKey(
  UT_HANDLE utHandle,
  unsigned char* lpKey,
  KEY_HANDLE_PTR lpKeyHandle
);

Description

To import a DES key to UniToken device.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpKey [in]	DES key
lpKeyHandle [out]	key handle

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_KEY_FULL	No more keys can be generated

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
unsigned char Key[DES_KEY_LEN_8_BYTE];
ret = UT_DESImportKey(utHandle, Key, &KeyHandle);

UT_DESDeleteKey

Prototype

UT_RV UT_API UT_DESDeleteKey(
  UT_HANDLE utHandle,
  KEY_HANDLE KeyHandle
);

Description

To delete a DES key.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
KeyHandle [in]	key handle

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_KEY_HANDLE_INVALID	Invalid key handle

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_DESDeleteKey(utHandle, KeyHandle);

UT_DESGetKeyCount

Prototype

UT_RV UT_API UT_DESGetKeyCount(
  UT_HANDLE utHandle,
  unsigned long* lpKeyCount
);

Description

To count DES keys.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpKeyCount [out]	the number of keys

Notes:

The maximum number of DES keys is 16.

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_KEY	No key found

Sample

UT_RV ret;
UT_HANDLE utHandle;
unsigned long KeyCount;
ret = UT_DESGetKeyCount(utHandle, &KeyCount);

UT_DESGetFirstKeyHandle

Prototype

UT_RV UT_API UT_DESGetFirstKeyHandle(
  UT_HANDLE utHandle,
  KEY_HANDLE_PTR lpKeyHandle
);

Description

To get the handle of the first DES key.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpKeyHandle [out]	key handle

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_KEY	No key found

Sample

See also the sample of UT_DESGetNextKeyHandle

UT_DESGetNextKeyHandle

Prototype

UT_RV UT_API UT_DESGetNextKeyHandle(
  UT_HANDLE utHandle,
  KEY_HANDLE_PTR lpKeyHandle
);

Description

To get the handle of the next DES key.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpKeyHandle [out]	key handle

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_KEY	No key found
UT_OPERATE_INVALID	Invalid operation

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_DESGetFirstKeyHandle(utHandle, &KeyHandle);
ret = UT_DESGetNextKeyHandle(utHandle, &KeyHandle);

UT_DES3GenerateKey

Prototype

UT_RV UT_API UT_DES3GenerateKey(
  UT_HANDLE utHandle,
  KEY_HANDLE_PTR lpKeyHandle
);

Description

To generate a 3DES key.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpKeyHandle [out]	key handle

Note:

The length of generated 3DES key is 24 bytes.

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_KEY_FULL	no more keys can be generated

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_DES3GenerateKey(utHandle, &KeyHandle);

UT_DES3Encrypt

Prototype

UT_RV UT_API UT_DES3Encrypt(
  UT_HANDLE utHandle,
  KEY_HANDLE KeyHandle,
  unsigned char* lpData,
  unsigned long DataLength,
  unsigned char* lpEncryptedData,
  unsigned long* lpEncryptedDataLength
);

Description

To encrypt data with 3DES.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
KeyHandle [in]	key handle
lpData [in]	plaintext
DataLength [in]	length of plaintext
lpEncryptedData [out]	ciphertext
lpEncryptedDataLength [out]	length of ciphertext

Notes:

DateLength is DES_DATA_LEN_8_BYTE

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_KEY_HANDLE_INVALID	Invalid key handle

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
unsigned char Data[DES_DATA_LEN_8_BYTE];
unsigned char EncryptedData[DES_DATA_LEN_8_BYTE];
unsigned long EncryptedDataLength;
ret = UT_DES3Encrypt(utHandle,
                   keyHandle,
                   Data,
                   DES_DATA_LEN_8_BYTE,
                   EncryptedData,
                   &EncryptedDataLength
                   );

UT_DES3Decrypt

Prototype

UT_RV UT_API UT_DES3Decrypt(
  UT_HANDLE utHandle,
  KEY_HANDLE KeyHandle,
  unsigned char* lpEncryptedData,
  unsigned long EncryptedDataLength,
  unsigned char* lpData,
  unsigned long* lpDataLength
);

Description

To decrypt data with 3DES.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
KeyHandle [in]	key handle
lpEncryptedData [in]	ciphertext
EncryptedDataLength [in]	length of ciphertext
lpData [out]	plaintext
lpDataLength [out]	length of plaintext

Notes:

EncryptedDataLength is DES_DATA_LEN_8_BYTE

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_KEY_HANDLE_INVALID	Invalid key handle

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
unsigned char Data[DES_DATA_LEN_8_BYTE];
unsigned char EncryptedData[DES_DATA_LEN_8_BYTE];
unsigned long DataLength;
ret = UT_DES3Decrypt(utHandle,
                   keyHandle,
                   EncryptedData,
                   DES_DATA_LEN_8_BYTE,
                   Data,
                   &DataLength
                   );

UT_DES3ImportKey

Prototype

UT_RV UT_API UT_DES3ImportKey(
  UT_HANDLE utHandle,
  unsigned char* lpKey,
  KEY_HANDLE_PTR lpKeyHandle
);

Description

To import 3DES keys to UniToken device.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpKey [in]	3DES key
lpKeyHandle [out]	key handle

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_KEY_FULL	No more keys can be generated

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
unsigned char Key[DES3_KEY_LEN_24_BYTE];
ret = UT_DES3ImportKey(utHandle, Key, &KeyHandle);

UT_DES3DeleteKey

Prototype

UT_RV UT_API UT_DES3DeleteKey(
  UT_HANDLE utHandle,
  KEY_HANDLE KeyHandle
);

Description

To delete a 3DES key.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
KeyHandle [in]	key handle

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_KEY_HANDLE_INVALID	Invalid key handle

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_DES3DeleteKey(utHandle, KeyHandle);

UT_DES3GetKeyCount

Prototype

UT_RV UT_API UT_DES3GetKeyCount(
  UT_HANDLE utHandle,
  unsigned long* lpKeyCount
);

Description

To count 3DES keys.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpKeyCount [out]	the number of keys

Notes:

The maximum number of 3DES keys is 16.

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_KEY	No key found

Sample

UT_RV ret;
UT_HANDLE utHandle;
unsigned long KeyCount;
ret = UT_DES3GetKeyCount(utHandle, &KeyCount);

UT_DES3GetFirstKeyHandle

Prototype

UT_RV UT_API UT_DES3GetFirstKeyHandle(
  UT_HANDLE utHandle,
  KEY_HANDLE_PTR lpKeyHandle
);

Description

To get the handle of the first 3DES key.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpKeyHandle [out]	key handle

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_KEY	No key found

Sample

See also the samples of UT_DES3GetNextKeyHandle

UT_DES3GetNextKeyHandle

Prototype

UT_RV UT_API UT_DES3GetNextKeyHandle(
  UT_HANDLE utHandle,
  KEY_HANDLE_PTR lpKeyHandle
);

Description

To get the handle of the next 3DES key.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpKeyHandle [out]	key handle

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_KEY	No key found
UT_OPERATE_INVALID	Invalid operation

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_DES3GetFirstKeyHandle(utHandle, &KeyHandle);
ret = UT_DES3GetNextKeyHandle(utHandle, &KeyHandle);

UT_AESGenerateKey

Prototype

UT_RV UT_API UT_AESGenerateKey(
  UT_HANDLE utHandle,
  unsigned long KeyLength,
  KEY_HANDLE_PTR lpKeyHandle
);

Description

To generate an AES key.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
KeyLength [in]	key length
lpKeyHandle [out]	key handle

Notes:

KeyLength can be AES_KEY_LEN_128_BIT or AES_KEY_LEN_192_BIT

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_KEY_FULL	No more keys can be generated

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_AESGenerateKey(utHandle, AES_KEY_LEN_128_BIT, &KeyHandle);

UT_AESEncrypt

Prototype

UT_RV UT_API UT_AESEncrypt(
  UT_HANDLE utHandle,
  KEY_HANDLE KeyHandle,
  unsigned char* lpData,
  unsigned long DataLength,
  unsigned char* lpEncryptedData,
  unsigned long* lpEncryptedDataLength
);

Description

To encrypt data with AES.

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
KeyHandle [in]	key handle
lpData [in]	plaintext
DataLength [in]	length of plaintext
lpEncryptedData [out]	ciphertext
lpEncryptedDataLength [out]	length of ciphertext

Notes:

DateLength is AES_DATA_LEN_16_BYTE

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_KEY_HANDLE_INVALID	Invalid key handle

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
unsigned char Data[AES_DATA_LEN_16_BYTE];
unsigned char EncryptedData[AES_DATA_LEN_16_BYTE];
unsigned long EncryptedDataLength;
ret = UT_AESEncrypt(utHandle,
                  KeyHandle,
                  Data,
                  AES_DATA_LEN_16_BYTE,
                  EncryptedData,
                  &EncryptedDataLength
                  );

UT_AESDecrypt

Prototype

UT_RV UT_API UT_AESDecrypt(
  HANDLE utHandle,
  KEY_HANDLE KeyHandle,
  unsigned char* lpEncryptedData,
  unsigned long EncryptedDataLength,
  unsigned char* lpData,
  unsigned long* lpDataLength
);

Description

To decrypt data with AES.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
KeyHandle [in]	key handle
lpEncryptedData [in]	ciphertext
EncryptedDataLength [in]	length of ciphertext
lpData [out]	plaintext
lpDataLength [out]	length of plaintext

Notes:

DateLength is AES_DATA_LEN_16_BYTE

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_KEY_HANDLE_INVALID	Invalid key handle

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
unsigned char Data[AES_DATA_LEN_16_BYTE];
unsigned char EncryptedData[AES_DATA_LEN_16_BYTE];
unsigned long DataLength;
ret = UT_AESDecrypt(handle,
                  KeyHandle,
                  EncryptedData,
                  AES_DATA_LEN_16_BYTE,
                  Data,
                  &DataLength
                  );

UT_AESImportKey

Prototype

UT_RV UT_API UT_AESImportKey(
  HANDLE utHandle,
  unsigned char* lpKey,
  unsigned long KeyLength,
  KEY_HANDLE_PTR lpKeyHandle
);

Description

To import AES key to UniToken device.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
KeyLength [in]	key length
lpKeyHandle [out]	key handle

Notes:

KeyLength can be AES_KEY_LEN_128_BIT or AES_KEY_LEN_192_BIT

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_KEY_FULL	No more keys can be generated

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
unsigned char key[AES_KEY_LEN_128_BIT];
Ret = UT_AESImportKey(utHandle, key, AES_KEY_LEN_128_BIT, &KeyHandle);

UT_AESDeleteKey

Prototype

UT_RV UT_API UT_AESDeleteKey(UT_HANDLE utHandle, KEY_HANDLE KeyHandle);

Description

To delete an AES key.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
KeyHandle [in]	key handle

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_KEY_HANDLE_INVALID	Invalid key handle

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_AESDeleteKey(utHandle, KeyHandle);

UT_AESGetKeyCount

Prototype

UT_RV UT_API UT_AESGetKeyCount(UT_HANDLE utHandle, unsigned long* lpKeyCount);

Description

To count AES keys.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpKeyCount [out]	the number of keys

Notes:

The maximum number of 3DES keys is 32.

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_KEY	No key found

Sample

UT_RV ret;
UT_HANDLE utHandle;
unsigned long KeyCount;
ret = UT_AESGetKeyCount(utHandle, &KeyCount);

UT_AESGetKeyLen

Prototype

UT_RV UT_API UT_AESGetKeyLen(
  UT_HANDLE utHandle,
  KEY_HANDLE KeyHandle,
  unsigned long* lpKeyLength
);

Description

To get the length of AES key.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpKeyHandle [out]	key handle
lpKeyLength [out]	key length

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_KEY_HANDLE_INVALID	Invalid key handle

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
unsigned long KeyLength;
ret = UT_AESGetKeyLen(utHandle, KeyHandle, &KeyLength);

UT_AESGetFirstKeyHandle

Prototype

UT_RV UT_API UT_AESGetFirstKeyHandle(UT_HANDLE utHandle, KEY_HANDLE_PTR lpKeyHandle);

Description

To get the handle of the first AES key.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpKeyHandle [out]	key handle

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_KEY	No key found

Sample

See also the sample of UT_AESGetNextKeyHandle

UT_AESGetNextKeyHandle

Prototype

UT_RV UT_API UT_AESGetNextKeyHandle(UT_HANDLE utHandle, KEY_HANDLE_PTR lpKeyHandle);

Description

To get the handle of the next AES key.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpKeyHandle [out]	key handle

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_KEY	No key found
UT_OPERATE_INVALID	Invalid operation

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_AESGetFirstKeyHandle(utHandle, &KeyHandle);
ret = UT_AESGetNextKeyHandle(utHandle, &KeyHandle);

UT_RSAGenerateKeyPair

Prototype

UT_RV UT_API UT_RSAGenerateKeyPair(
  UT_HANDLE utHandle,
  unsigned long ModulusBits,
  unsigned long PubExp,
  KEY_HANDLE_PTR lpPubKeyHandle,
  KEY_HANDLE_PTR lpPriKeyHandle
);

Description

To generate RSA key pair.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
ModulusBits [in]	modulus length
PubExp [in]	public exponent
lpPubKeyHandle [out]	public key handle
lpPriKeyHandle [out]	private key handle

Notes:

1. UniToken device can store as many as 16 RSA key pairs
2. ModulusBits can be RSA_MODULUS_LEN_1024_BIT or RSA_MODULUS_LEN_2048_BIT
3. PubExp is RSA_PUBEXP_LEN_65537_BIT

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_KEY_FULL	No more keys can be generated

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE PubKeyHandle;
KEY_HANDLE PriKeyHandle;
ret = UT_RSAGenerateKeyPair(utHandle,
                          RSA_KEY_LEN_1024_BIT,
                          RSA_PUBEXP_LEN_65537_BIT,
                          &PubKeyHandle,
                          &PriKeyHandle
                          );

UT_RSAPubKeyEncrypt

Prototype

UT_RV UT_API UT_RSAPubKeyEncrypt(
  UT_HANDLE utHandle,
  KEY_HANDLE PubKeyHandle,
  unsigned char* lpData,
  unsigned long DataLength,
  unsigned char* lpEncryptedData,
  unsigned long* lpEncryptedDataLength
);

Description

To encrypt data with RSA public key.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
KeyHandle [in]	key handle
lpData [in]	plaintext
lpDataLength [in]	length of plaintext
lpEncryptedData [out]	ciphertext
EncryptedDataLength [out]	length of ciphertext

Notes:

DataLength can be RSA_DATA_LEN_1024_BIT or SA_DATA_LEN_2048_BIT

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_KEY_HANDLE_INVALID	Invalid key handle

Usage Note

The handle of public key should be retrieved with UT_RSAGetPubKeyByPriKey instead manually entered. A 1024-bit RSA public key can only encrypt 1024-bit data. It is also true for 2048-bit RSA public keys.

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE PubKeyHandle;
unsigned char Data[RSA_DATA_LEN_1024_BIT];
unsigned char EncryptedData[RSA_DATA_LEN_1024_BIT];
unsigned long EncryptedDataLength;
ret = UT_RSAPubKeyEncrypt(utHandle,
                        PubKeyHandle,
                        Data,
                        RSA_DATA_LEN_1024_BIT,
                        EncryptedData,
                        &EncryptedDataLength
                        );

UT_RSAPriKeyDecrypt

Prototype

UT_RV UT_API UT_RSAPriKeyDecrypt(
  UT_HANDLE utHandle,
  KEY_HANDLE PriKeyHandle,
  unsigned char* lpEncryptedData,
  unsigned long EncryptedDataLength,
  unsigned char* lpData,
  unsigned long* lpDataLength
);

Description

To decrypt data with RSA private key.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
KeyHandle [in]	key handle
lpEncryptedData [in]	ciphertext
EncryptedDataLength [in]	length of ciphertext
lpData [out]	plaintext
lpDataLength [out]	length of plaintext

Notes:

DataLength can be RSA_DATA_LEN_1024_BIT or SA_DATA_LEN_2048_BIT

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_KEY_HANDLE_INVALID	Invalid key handle

Usage Note

The handle of private key should be retrieved with RSAGetPriKeyByPubKey instead of manually input. A 1024-bit RSA private key can only decrypt 1024-bit data. It is also true for 2048-bit RSA private keys.

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE PriKeyHandle;
unsigned char Data[RSA_DATA_LEN_1024_BIT];
unsigned char EncryptedData[RSA_DATA_LEN_1024_BIT];
unsigned long DataLength;
ret = UT_RSAPriKeyDecrypt(utHandle,
                        PriKeyHandle,
                        EncryptedData,
                        RSA_DATA_LEN_1024_BIT,Data,
                        &DataLength
                        );

UT_RSAPriKeyEncrypt

Prototype

UT_RV UT_API UT_RSAPriKeyEncrypt(
  UT_HANDLE utHandle,
  KEY_HANDLE PriKeyHandle,
  unsigned char* lpData,
  unsigned long DataLength,
  unsigned char* lpEncryptedData,
  unsigned long* lpEncryptedDataLength
);

Description

To encrypt data with RSA private key.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
KeyHandle [in]	key handle
lpData [in]	plaintext
lpDataLength [in]	length of plaintext
lpEncryptedData [out]	ciphertext
EncryptedDataLength [out]	length of ciphertext

Notes:

DataLength can be RSA_DATA_LEN_1024_BIT or SA_DATA_LEN_2048_BIT

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_KEY_HANDLE_INVALID	Invalid key handle

Usage Note

The handle of private key should be retrieved with UT_RSAGetPriKeyByPubKey instead manually entered. A 1024-bit RSA private key can only encrypt 1024-bit data. It is also true for 2048-bit RSA private keys.

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE PriKeyHandle;
unsigned char Data[RSA_DATA_LEN_1024_BIT];
unsigned char EncryptedData[RSA_DATA_LEN_1024_BIT];
unsigned long EncryptedDataLength;
ret = UT_RSAPriKeyEncrypt(utHandle,
                        PriKeyHandle,Data,
                        RSA_DATA_LEN_1024_BIT,
                        EncryptedData,
                        &EncryptedDataLength
                        );

UT_RSAPubKeyDecrypt

Prototype

UT_RV UT_API UT_RSAPubKeyDecrypt(
  UT_HANDLE utHandle,
  KEY_HANDLE PubKeyHandle,
  unsigned char* lpEncryptedData,
  unsigned long EncryptedDataLength,
  unsigned char* lpData,
  unsigned long* lpDataLength
);

Description

To decrypt data with RSA public key.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
KeyHandle [in]	key handle
lpEncryptedData [in]	ciphertext
EncryptedDataLength [in]	length of ciphertext
lpData [out]	plaintext
lpDataLength [out]	length of plaintext

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_KEY_HANDLE_INVALID	Invalid key handle

Usage Note

The handle of public key should be retrieved with UT_RSAGetPubKeyByPriKey instead manually entered. A 1024-bit RSA public key can only decrypt 1024-bit data. It is also true for 2048-bit RSA public keys.

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE PubKeyHandle;
unsigned char Data[RSA_DATA_LEN_1024_BIT];
unsigned char EncryptedData[RSA_DATA_LEN_1024_BIT];
unsigned long DataLength;
ret = UT_RSAPubKeyDecrypt(utHandle,
                        PubKeyHandle,
                        EncryptedData,
                        RSA_DATA_LEN_1024_BIT,
                        Data,
                        &DataLength
                        );

UT_RSAGetKeyPairCount

Prototype

UT_RV UT_API UT_RSAGetKeyPairCount(UT_HANDLE utHandle, unsigned long* lpKeyCount);

Description

To count RSA keys.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpKeyCount [out]	the number of key pairs

Notes

The maximum number of RSA key pairs is 16.

Returned value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_KEY	No key found

Sample

UT_RV ret;
UT_HANDLE utHandle;
unsigned long KeyCount;
ret = UT_RSAGetKeyPairCount(utHandle, &KeyCount);

UT_RSAGetFirstKeyPairHandle

Prototype

UT_RV UT_API UT_RSAGetFirstKeyPairHandle(
  UT_HANDLE utHandle,
  KEY_HANDLE_PTR lpPubKeyHandle,
  KEY_HANDLE_PTR lpPriKeyHandle
);

Description

To get the handles of the first RSA key pair.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpPubKeyHandle [out]	public key handle
lpPriKeyHandle [out]	private key handle

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_KEY	No key found

Sample

See also the sample of UT_RSAGetNextKeyPairHandle

UT_RSAGetNextKeyPairHandle

Prototype

UT_RV UT_API UT_RSAGetNextKeyPairHandle(
  UT_HANDLE utHandle,
  KEY_HANDLE_PTR lpPubKeyHandle,
  KEY_HANDLE_PTR lpPriKeyHandle
);

Description

To get the handles of the next RSA key pair.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpPubKeyHandle [out]	public key handle
lpPriKeyHandle [out]	private key handle

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_KEY	No key found
UT_OPERATE_INVALID	Invalid operation

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE PubKeyHandle;
KEY_HANDLE PriKeyHandle;
ret = UT_RSAGetFirstKeyPairHandle(utHandle, &PubKeyHandle, &PriKeyHandle);
ret = UT_RSAGetNextKeyPairHandle(utHandle, &PubKeyHandle, &PriKeyHandle);

UT_RSAPubKeyImport

Prototype

UT_RV UT_API UT_RSAPubKeyImport(
  UT_HANDLE utHandle,
  UT_RSA* lpRsaKey,
  KEY_HANDLE PriKeyHandle,
  KEY_HANDLE_PTR lpPubKeyHandle
);

Description

To import RSA public key to UniToken device.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
PriKeyHandle [in]	private key handle
lpPubKeyHandle [out]	public key handle

Notes

PriKeyHandle can be the existing private key handle or RSA_IMPORT_NEW

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_KEY_HANDLE_INVALID	Invalid key handle
UT_KEY_EXIST	Key already exists
UT_KEY_FULL	No more keys can be generated

Usage Note

In this function, the public key can be imported either by the corresponding private key handle or by creating a new key pair (if there’s enough memory). If the key pair already exists, import the public key and return the handle of the public key; if there’s no corresponding key pair in the device, return UT_KEY_HANDLE_INVALID If PriKeyHandle is RSA_IMPORT_NEW create a new key pair and import the public key. The UniToken device can store up to 16 RSA key pairs; if there arere already 16 key pairs stored, calling this function will return UT_KEY_FULL

Sample

See the sample of UT_RSAPriKeyImport

UT_RSAPriKeyImport

Prototype

UT_RV UT_API UT_RSAPriKeyImport(
  UT_HANDLE utHandle,
  UT_RSA* lpRsaKey,
  KEY_HANDLE PubKeyHandle,
  KEY_HANDLE_PTR lpPriKeyHandle
);

Description

To import RSA private key to UniToken device.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
PubKeyHandle [in]	public key handle
lpPriKeyHandle [out]	private key handle

Notes:

PubKeyHandle can be the existing public key handle or RSA_IMPORT_NEW

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_KEY_HANDLE_INVALID	Invalid key handle
UT_KEY_EXIST	Key already exists
UT_KEY_FULL	No more keys can be generated

Sample

UT_RV ret;
UT_HANDLE utHandle;
UT_RSA RsaKey;
KEY_HANDLE PubKeyHandle;
KEY_HANDLE PriKeyHandle;
ret = UT_RSAPubKeyImport(utHandle,
                       &RsaKey,
                       RSA_IMPORT_NEW,
                       &PubKeyHandle
                       );
ret = UT_RSAPriKeyImport(utHandle,
                       &RsaKey,
                       PubKeyHandle,
                       &PriKeyHandle
                       );

UT_RSAPubKeyExport

Prototype

UT_RV UT_API UT_RSAPubKeyExport(
  UT_HANDLE utHandle,
  KEY_HANDLE PubKeyHandle,
  unsigned long* lpModulusBits,
  UT_RSA* lpRsaKey
);

Description

To export RSA public key from UniToken device.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
PubKeyHandle [in]	public key handle
lpModulusBits [out]	modulus length
lpRsaKey [out]	RSA public key structure

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_KEY_HANDLE_INVALID	Invalid key handle
UT_KEY_EXIST	Key already exists
UT_KEY_FULL	No more keys can be generated

Sample

UT_RV ret;
UT_HANDLE utHandle;
UT_RSA RsaKey;
KEY_HANDLE PubKeyHandle;
unsigned long ModulusBits;
ret = UT_RSAPubKeyExport(utHandle, PubKeyHandle, &ModulusBits, &RsaKey);

UT_RSAGetPubKeyHandle

Prototype

UT_RV UT_API UT_RSAGetPubKeyHandle(
  UT_HANDLE utHandle,
  KEY_HANDLE PriKeyHandle,
  KEY_HANDLE_PTR lpPubKeyHandle
);

Description

To get the public key handle by the corresponding private key handle.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
PriKeyHandle [in]	private key handle
lpPubKeyHandle [out]	the corresponding public key handle

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_KEY_HANDLE_INVALID	Invalid key handle
UT_NO_KEY	No key found

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE PubKeyHandle;
KEY_HANDLE PriKeyHandle;
ret = UT_RSAGetPubKeyHandle(utHandle, PriKeyHandle, &PubKeyHandle);

UT_RSAGetPriKeyHandle

Prototype

UT_RV UT_API UT_RSAGetPriKeyHandle(
  UT_HANDLE utHandle,
  KEY_HANDLE PubKeyHandle,
  KEY_HANDLE_PTR lpPriKeyHandle
);

Description

To get the public key handle by the corresponding private key handle.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
PubKeyHandle [in]	public key handle
lpPriKeyHandle [out]	the corresponding private key handle

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_KEY_HANDLE_INVALID	Invalid key handle
UT_NO_KEY	No key found

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE PubKeyHandle;
KEY_HANDLE PriKeyHandle;
ret = UT_RSAGetPriKeyHandle(utHandle, PubKeyHandle, &PriKeyHandle);

UT_RSAGetKeyPairModulus

Prototype

UT_RV UT_API UT_RSAGetKeyPairModulus(
  UT_HANDLE utHandle,
  KEY_HANDLE PubKeyHandle,
  unsigned long* lpModulusBits
);

Description

To get RSA key pair modulus.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
PubKeyHandle [in]	public key handle
lpModulusBits [out]	modulus length

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_KEY_HANDLE_INVALID	Invalid key handle

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE PubKeyHandle;
unsigned long ModulusBits;
ret = UT_RSAGetKeyPairModulus(utHandle, PubKeyHandle, &ModulusBits);

UT_RSADeleteKeyPair

Prototype

UT_RV UT_API UT_RSADeleteKeyPair(
  UT_HANDLE utHandle,
  KEY_HANDLE PubKeyHandle,
  KEY_HANDLE PriKeyHandle
);

Description

To delete the RSA key pair.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
PubKeyHandle [in]	public key handle
PriKeyHandle [in]	private key handle

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_KEY_HANDLE_INVALID	Invalid key handle

Usage Note

In this function, the handles of a key pair are required. If the handles belong to the keys from different key pairs, return UT_KEY_HANDLE_INVALID if only one key handle provided, the other key handle must be 0 to delete the key pair.

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE PubKeyHandle;
KEY_HANDLE PriKeyHandle;
ret = UT_RSADeleteKeyPair(utHandle, PubKeyHandle, PriKeyHandle);

UT_MD5HMACGenerateKey

Prototype

UT_RV UT_API UT_MD5HMACGenerateKey(
  UT_HANDLE utHandle,
  unsigned long KeyLength,
  KEY_HANDLE_PTR lpKeyHandle
);

Description

To generate HMAC-MD5 key.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
KeyLength [in]	key length
lpKeyHandle [out]	key handle

Notes:

The length of key is <= 128 bytes

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_KEY_FULL	No more keys can be generated

Usage Note

UniToken device can store as many as 8 HMAC-MD5 keys. If there are already 8 keys in the device, calling the function will return UT_KEY_FULL

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_MD5HMACGenerateKey(utHandle, 128, &KeyHandle);

UT_MD5HMAC

Prototype

UT_RV UT_API UT_MD5HMAC(
  UT_HANDLE utHandle,
  KEY_HANDLE KeyHandle,
  unsigned char* lpData,
  unsigned long DataLength,
  unsigned char* lpDigest
);

Description

To run HMAC-MD5 algorithm.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
KeyHandle [in]	key handle
lpData [in]	data to be digested
DataLength [in]	data length
lpDigest [out]	digested data

Notes:

DataLength is 1~128 bytes. lpDigest is 16 bytes

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_KEY_HANDLE_INVALID	Invalid key handle

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
unsigned char Data[128];
unsigned char Digest[16];
ret = UT_MD5HMAC(utHandle, KeyHandle, Data, 128, Digest);

UT_MD5

Prototype

UT_RV UT_API UT_MD5(
  UT_HANDLE utHandle,
  unsigned char* lpData,
  unsigned long DataLength,
  unsigned char* lpDigest
);

Description

To run MD5 algorithm.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpData [in]	data to be digested
DataLength [in]	data length
lpDigest [out]	digested data

Notes

DataLength is 1~128 bytes. lpDigest is 16 bytes

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission

Sample

UT_RV ret;
UT_HANDLE utHandle;
unsigned char Data[128];
unsigned char Digest[16];
ret = UT_MD5(utHandle, Data, 128, Digest);

UT_MD5GetKeyCount

Prototype

UT_RV UT_API UT_MD5GetKeyCount(UT_HANDLE utHandle, unsigned long* lpKeyCount);

Description

To count HMAC-MD5 keys.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpKeyCount [out]	the number of keys

Notes:

The maximum number of MD5 keys is 8.

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_KEY	No key found

Sample

UT_RV ret;
UT_HANDLE utHandle;
unsigned long KeyCount;
ret = UT_MD5GetKeyCount(utHandle, &KeyCount);

UT_MD5GetKeyLen

Prototype

UT_RV UT_API UT_MD5GetKeyLen(
  UT_HANDLE utHandle,
  KEY_HANDLE KeyHandle,
  unsigned long* lpKeyLength
);

Description

To get the length of HMAC-MD5 key.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
KeyHandle [in]	key handle
lpKeyLength [out]	key length

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_KEY_HANDLE_INVALID	Invalid key handle

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
unsigned long KeyLength;
ret = UT_MD5GetKeyLen(utHandle, KeyHandle, &KeyLength);

UT_MD5GetFirstKeyHandle

Prototype

UT_RV UT_API UT_MD5GetFirstKeyHandle(UT_HANDLE utHandle, KEY_HANDLE_PTR lpKeyHandle);

Description

To get the handle of the first HMAC-MD5 key.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpKeyHandle [out]	key handle

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_KEY	No key found

Sample

See the samples of UT_MD5GetNextKeyHandle

UT_MD5GetNextKeyHandle

Prototype

UT_RV UT_API UT_MD5GetNextKeyHandle(UT_HANDLE utHandle, KEY_HANDLE_PTR lpKeyHandle);

Description

To get the handle of the next HMAC-MD5 key.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpKeyHandle [out]	key handle

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_KEY	No key found
UT_OPERATE_INVALID	Invalid operation

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_MD5GetFirstKeyHandle(utHandle, &KeyHandle);
ret = UT_MD5GetNextKeyHandle(utHandle, &KeyHandle);

UT_MD5DeleteKey

Prototype

UT_RV UT_API UT_MD5DeleteKey(UT_HANDLE utHandle, KEY_HANDLE KeyHandle);

Description

To delete HMAC-MD5 key.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
KeyHandle [in]	key handle

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_KEY_HANDLE_INVALID	Invalid key handle

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_MD5DeleteKey(utHandle, KeyHandle);

UT_MD5ImportKey

Prototype

UT_RV UT_API UT_MD5ImportKey(
  UT_HANDLE utHandle,
  unsigned char* lpKey,
  unsigned long KeyLength,
  KEY_HANDLE_PTR lpKeyHandle
);

Description

To import HMAC-MD5 key to UniToken device.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
KeyLength [in]	key length
lpKeyHandle [out]	key handle

Notes:

KeyLength is 1~128 bytes.

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_KEY_FULL	No more keys can be generated

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
unsigned char Key[128];
ret = UT_MD5ImportKey(utHandle, Key, 128, &KeyHandle);

UT_SHA1HMACGenerateKey

Prototype

UT_RV UT_API UT_SHA1HMACGenerateKey(
  UT_HANDLE utHandle,
  unsigned long KeyLength,
  KEY_HANDLE_PTR lpKeyHandle
);

Description

To generate HMAC-SHA1 key.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
KeyLength [in]	key length
lpKeyHandle [out]	key handle

Notes:

The length of key is <=128 bytes.

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_KEY_FULL	No more keys can be generated

Usage Note

UniToken device can store as many as 8 HMAC-SHA1 keys. If there are already 8 keys in the device, calling the function will return UT_KEY_FULL

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_SHA1HMACGenerateKey(utHandle, 128, &KeyHandle);

UT_SHA1HMAC

Prototype

UT_RV UT_API UT_SHA1HMAC(
  UT_HANDLE utHandle,
  KEY_HANDLE KeyHandle,
  unsigned char* lpData,
  unsigned long DataLength,
  unsigned char* lpDigest
);

Description

To run HMAC-SHA1 algorithm.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
KeyHandle [in]	key handle
lpData [in]	data to be digested
DataLength [in]	data length
lpDigest [out]	digested data

Notes:

DataLength is 1~128 bytes. lpDigest is 20 bytes.

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_KEY_HANDLE_INVALID	Invalid key handle

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
unsigned char Data[128];
unsigned char Digest[20];
ret = UT_SHA1HMAC(utHandle, KeyHandle, Data, 128, Digest);

UT_SHA1

Prototype

UT_RV UT_API UT_SHA1(
  UT_HANDLE utHandle,
  unsigned char* lpData,
  unsigned long DataLength,
  unsigned char* lpDigest
);

Description

To run SHA1 algorithm.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpData [in]	data to be digested
DataLength [in]	data length
lpDigest [out]	digested data

Notes:

DataLength is 1~128 bytes. lpDigest is 20 bytes.

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_KEY_HANDLE_INVALID	Invalid key handle

Sample

UT_RV ret;
UT_HANDLE utHandle;
unsigned char Data[128];
unsigned char Digest[20];
ret = UT_SHA1(utHandle, Data, 128, Digest);

UT_SHA1GetKeyCount

Prototype

UT_RV UT_API UT_SHA1GetKeyCount(UT_HANDLE utHandle, unsigned long* lpKeyCount);

Description

To count HMAC-SHA1 keys

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpKeyCount [out]	the number of keys

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_KEY	No key found

Sample

UT_RV ret;
UT_HANDLE utHandle;
unsigned long KeyCount;
ret = UT_SHA1GetKeyCount(utHandle, &KeyCount);

UT_SHA1GetKeyLen

Prototype

UT_RV UT_API UT_SHA1GetKeyLen(
  UT_HANDLE utHandle,
  KEY_HANDLE KeyHandle,
  unsigned long* lpKeyLength
);

Description

To get the length of HMAC-SHA1 key.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
KeyHandle [in]	key handle
lpKeyLength [out]	key length

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_KEY_HANDLE_INVALID	Invalid key handle

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
unsigned long KeyLength;
ret = UT_SHA1GetKeyLen(utHandle, KeyHandle, &KeyLength);

UT_SHA1GetFirstKeyHandle

Prototype

UT_RV UT_API UT_SHA1GetFirstKeyHandle(UT_HANDLE utHandle, KEY_HANDLE_PTR lpKeyHandle);

Description

To get the handle of the first HMAC-SHA1 key.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpKeyHandle [out]	key handle

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_KEY	No key found

Sample

See also the sample of UT_SHA1GetNextKeyHandle

UT_SHA1GetNextKeyHandle

Prototype

UT_RV UT_API UT_SHA1GetNextKeyHandle(UT_HANDLE utHandle, KEY_HANDLE_PTR lpKeyHandle);

Description

To get the handle of the next HMAC-SHA1 key.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpKeyHandle [out]	key handle

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_KEY	No key found
UT_OPERATE_INVALID	Invalid operation

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_SHA1GetFirstKeyHandle(utHandle, &KeyHandle);
ret = UT_SHA1GetNextKeyHandle(utHandle, &KeyHandle);

UT_SHA1DeleteKey

Prototype

UT_RV UT_API UT_SHA1DeleteKey(UT_HANDLE utHandle, KEY_HANDLE KeyHandle);

Description

To delete HMAC-SHA1 key.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
KeyHandle [in]	key handle

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_KEY_HANDLE_INVALID	Invalid key handle

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_SHA1DeleteKey(utHandle, KeyHandle);

UT_SHA1ImportKey

Prototype

UT_RV UT_API UT_SHA1ImportKey(
  UT_HANDLE utHandle,
  unsigned char* lpKey,
  unsigned long KeyLength,
  KEY_HANDLE_PTR lpKeyHandle
);

Description

To import HMAC-SHA1 key to UniToken device.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpKey [in]	SHA1 key
KeyLength [in]	key length
lpKeyHandle [out]	key handle

Notes:

KeyLength is 1~128 bytes.

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_KEY_FULL	No more keys can be generated

Sample

UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
unsigned char Key[128];
ret = UT_SHA1ImportKey(utHandle, Key, 128, &KeyHandle);

UT_FS_GetSpace

Prototype

UT_RV UT_API UT_FS_GetSpace(
  UT_HANDLE utHandle,
  unsigned long* UsedSpace,
  unsigned long* FreeSpace
);

Description

To get the size of the free memory.

Parameters

PARAMETERS	DESCRIPTION
UsedSize [out]	size of used memory
FreeSize [out]	size of free memory

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle

Sample

UT_RV ret;
UT_HANDLE utHandle;
unsigned long UsedSpace;
unsigned long FreeSpace;
ret = UT_FS_GetSpace(utHandle, &UsedSpace, &FreeSpace);

UT_FS_GetFileCount

Prototype

UT_RV UT_API UT_FS_GetFileCount(UT_HANDLE utHandle, unsigned long* lpFileCount);

Description

To get the number of files.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpFileCount [out]	the number of files

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_FS_NO_FILE	No file found

Sample

UT_RV ret;
UT_HANDLE utHandle;
unsigned long FileCount;
ret = UT_FS_GetFileCount(utHandle, &FileCount);

UT_FS_GetFirstFileName

Prototype

UT_RV UT_API UT_FS_GetFirstFileName(UT_HANDLE utHandle, char* lpszFileName);

Description

To get the name of the first file.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpszFileName [out]	filename (string, 16 bytes)

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_FS_NO_FILE	No file found

Sample

See also the sample of UT_GetNextFileName

UT_FS_GetNextFileName

Prototype

UT_RV UT_API UT_FS_GetNextFileName(UT_HANDLE utHandle, char* lpszFileName);

Description To get the name of the next file.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpszFileName [out]	filename (string, 16 bytes)

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_FS_LIST_END	End of fire list
UT_OPERATE_INVALID	Invalid operation

Sample

UT_RV ret;
UT_HANDLE utHandle;
char FileName[17];
ret = UT_FS_GetFirstFileName(utHandle, FileName);
ret = UT_FS_GetNextFileName(utHandle, FileName);

UT_FS_GetFileSize

Prototype

UT_RV UT_API UT_FS_GetFileSize(
  UT_HANDLE utHandle,
  char* lpszFileName,
  unsigned long* lpFileSize
);

Description

To get the file size.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpszFileName [in]	filename (string, 16 bytes)
lpFileSize [out]	size of file

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_FS_NAME_LEN_RANGE	Filename too long
UT_FS_NO_FILE	No file found

Sample

UT_RV ret;
UT_HANDLE utHandle;
char FileName[17];
unsigned long FileSize;
ret = UT_FS_GetFileSize(utHandle, FileName, &FileSize);

UT_FS_GetFilePermission

Prototype

UT_RV UT_API UT_FS_GetFilePermission(
  UT_HANDLE utHandle,
  char* lpszFileName,
  unsigned char* lpFilePermission
);

Description

To get the file permission of the specified file.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpszFileName [in]	filename (string, 16 bytes)
lpFilePermission [out]	file permission

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_FS_NAME_LEN_RANGE	Filename too long
UT_FS_NO_FILE	No file found

Sample

UT_RV ret;
UT_HANDLE utHandle;
char FileName[17];
unsigned char FilePermission;
ret = UT_FS_GetFilePermission(utHandle, FileName, &FilePermission);

UT_FS_CreatFile

Prototype

UT_RV UT_API UT_FS_CreateFile(
  UT_HANDLE utHandle,
  char* lpszFileName,
  unsigned long FileSize,
  unsigned char FilePermission
);

Description

To create a file.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpszFileName [in]	filename (string, 16 bytes)
FileSize [in]	size of file
FilePermission [in]	file permission

Notes:

1. The max. File size is 262112 bytes;
2. FilePermission can be FILE_PERMISSION_GUEST, FILE_PERMISSION_USER or FILE_PERMISSION_ADMIN.

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_NO_PERMISSION	No permission
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_FS_NAME_LEN_RANGE	Filename too long
UT_FS_FILE_EXIST	The file already exists

Usage Note File permission types:

1. FILE_PERMISSION_GUEST: With GUEST and higher permissions, reading the file is allowed; With USER and higher permissions, writing file is allowed.
2. FILE_PERMISSION_USER: With USER and higher permissions, reading and writing file are allowed.
3. FILE_PERMISSION_ADMIN: Only ADMIN is allowed to read and write the file.

Sample

UT_RV ret;
UT_HANDLE utHandle;
char FileName[17];
ret = UT_FS_CreateFile(utHandle, FileName, 200, FILE_PERMISSION_GUEST);

UT_FS_DeleteFile

Prototype

UT_RV UT_API UT_FS_DeleteFile(UT_HANDLE utHandle, char* lpszFileName);

Description

To delete a file.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpszFileName [in]	filename (string, 16 bytes)

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_FS_NAME_LEN_RANGE	Filename too long
UT_FS_NO_FILE	No file found

Usage Note

To call the function, it is required that the current permission be higher than or at the same level with the one of writing the file.

Sample

UT_RV ret;
UT_HANDLE utHandle;
char FileName[17];
ret = UT_FS_DeleteFile(utHandle, FileName);

UT_FS_OpenFile

Prototype

UT_RV UT_API UT_FS_OpenFile(
  UT_HANDLE utHandle,
  char* lpszFileName,
  void* lpReserve
);

Description

To open a file.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpszFileName [in]	filename (string, 16 bytes)
lpReserve		reserved for further usage

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_FS_NAME_LEN_RANGE	Filename too long
UT_FS_NO_FILE	No file found

Usage Note

To call the function, it is required that the current permission be higher than or at the same level with the one of writing the file. Files can be read and written only when opened.

Sample

UT_RV ret;
UT_HANDLE utHandle;
char FileName[17];
ret = UT_FS_OpenFile(utHandle, FileName, NULL);

UT_FS_WriteFile

Prototype

UT_RV UT_API UT_FS_WriteFile(
  UT_HANDLE utHandle,
  unsigned long Offset,
  unsigned long Length,
  unsigned char* Buffer,
  void* lpReserve
);

Description

To write or modify a file.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
Offset [in]	start position for writing
Length [in]	length of data
Buffer [in]	data to write
lpReserve	reserved for further usage

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_FS_OFFSET_INVALID	Invalid start point for specified file
UT_FS_NO_OPEN	Cannot open file
UT_FS_NOSPACE	No room in file system
UT_FS_NO_FILE	No file found

Usage Note

To call the function, it is required that the current permission be higher than or at the same level with the one of writing the file. New function of appending is added.

Sample

UT_RV ret;
UT_HANDLE utHandle;
unsigned long Offset;
unsigned char Buffer[200];
ret = UT_FS_WriteFile(utHandle, 0, 200, Buffer, NULL);

UT_FS_ReadFile

Prototype

UT_RV UT_API UT_FS_ReadFile(
  UT_HANDLE utHandle,
  unsigned long Offset,
  unsigned long Length,
  unsigned char* Buffer,
  void* lpReserve
);

Description

To read a file.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
Offset [in]	start position for writing
Length [in]	length of data
Buffer [in]	data to write
lpReserve	reserved for further usage

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_ARGUMENTS_BAD	Invalid argument
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_FS_OFFSET_INVALID	Invalid start point for specified file
UT_FS_NO_OPEN	Cannot open file
UT_FS_DATA_LEN_RANGE	Out of range of data length
UT_FS_NO_FILE	No file found

Usage Note

To call the function, it is required that the current permission be higher than or at the same level with the one of writing the file.

Sample

UT_RV ret;
UT_HANDLE utHandle;
unsigned long Offset;
unsigned char Buffer[200];
ret = UT_FS_ReadFile(utHandle, 0, 200, Buffer, NULL);

UT_FS_CloseFile

Prototype

UT_RV UT_API UT_FS_CloseFile(UT_HANDLE utHandle, void* lpReserve);

Description

To close a file.

Parameters

PARAMETERS	DESCRIPTION
utHandle [in]	device handle
lpReserve	reserved for further usage

Returned Value

RETURNED VALUE	DESCRIPTION
UT_OK	Successful operation
UT_NOT_INITIALIZE	Library not initialized
UT_TOKEN_HANDLE_INVALID	Invalid token handle
UT_NO_PERMISSION	No permission
UT_FS_NO_OPEN	Cannot open file

Usage Note

To call the function, it is required that the current permission be higher than or at the same level with the one of writing the file.

Sample

UT_RV ret;
UT_HANDLE utHandle;
ret = UT_FS_CloseFile(utHandle, NULL);