UniToken API Reference

From SecuTech Wiki
Revision as of 12:13, 1 May 2012 by Joseph (talk | contribs)
Jump to navigationJump to search


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. It should be called before all the other functions except 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_INVALID 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
a. Inserted, when UniToken is inserted into the slot;
b. Removed, when UniToken is removed from the slot;
c. 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 of changing
OldPin [in] old PIN
NewPin [in]new PIN

Notes:
Change Mode an 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
SoftID [in] Software ID

Returned Value
RETURNED VALUE DESCRIPTION
UT_OK Successful operation
UT_NOT_INITIALIZE Library not initialized
UT_NO_PERMISSION No permission
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 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
byte)
lpOut [out] random number
lpReserve reserved for future 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

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 key 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] plain text
DataLength [in]length of plain text
lpEncryptedData [out] cipher text
lpEncryptedDataLength [out] length of cipher text

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 [out] plain text
EncryptedDataLength [out] length of plain text
lpData [in] cipher text
lpDataLength [in]length of cipher text

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 key 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_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 key 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] plain text
DataLength [in]length of plain text
lpEncryptedData [out] cipher text
lpEncryptedDataLength [out] length of cipher text

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] cipher text
EncryptedDataLength [in]length of cipher text
lpData [out] plain text
lpDataLength [out] length of plain text

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 key 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 [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_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 key 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
PARAMETERS DESCRIPTION
utHandle [in] device handle
KeyHandle [in] key handle
lpData [in] plaintext
DataLength [in]length of plaintext
lpEncryptedData [out] cipher text
lpEncryptedDataLength [out] length of cipher text

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(
ANDLE utHandle,
KEY_HANDLE KeyHandle,
unsigned char* lpEncryptedData,
nsigned 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] cipher text
EncryptedDataLength [in]length of cipher text
lpData [out] plaintext
lpDataLength [out] length of plain text

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(
ndle,
KeyHandle,
EncryptedData,
AES_DATA_LEN_16_BYTE,
Data,
&DataLength
);

UT_AESImportKey

Prototype
UT_RV UT_API UT_AESImportKey(
ANDLE 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
lpKey [in] AES key
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 key 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
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_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 key 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
PubKeyHandle [in] public key handle
lpData [in] plain text
DataLength [in]length of plain text
lpEncryptedData [out] cipher text
lpEncryptedDataLength [out] length of cipher text

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
PriKeyHandle [in] private key handle
lpEncryptedData [in] cipher text
EncryptedDataLength [in]length of cipher text
lpData [out] plaintext
lpDataLength [out] length of plain text

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
PriKeyHandle [in] private key handle
lpData [in] plain text
DataLength [in]length of plain text
lpEncryptedData [out] cipher text
lpEncryptedDataLength [out] length of cipher text

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
PubKeyHandle [in] public key handle
lpEncryptedData [in] cipher text
EncryptedDataLength [in]length of cipher text
lpData [out] plain text
lpDataLength [out] length of plain text

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
lpRsaKey [in] RSA key
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 key 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
lpRsaKey [in] RSA key
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 key 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 key 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 key 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] the 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] the 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

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
lpKey [in]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 key 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 key 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]the 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] the 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

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_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 key 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
utHandle [in]device handle
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] file name (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] file name (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 file 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]file name (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 File name 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] name of the specified file
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 File name 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]file name (string, 16 bytes)
FileSize [in] file size
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_FS_NOSPACE No room in file system
UT_TOKEN_HANDLE_INVALID Invalid token handle
UT_FS_NAME_LEN_RANGE File name too long
UT_FS_FILE_EXIST The file already exists

Usage Note
File permission types:
a. FILE_PERMISSION_GUEST
With GUEST and higher permissions, reading the file is allowed;
With USER and higher permissions, writing file is allowed.
b. FILE_PERMISSION_USER
With USER and higher permissions, reading and writing file are allowed.
c. 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] file name (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 File name 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] file name (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 File name 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] the starting 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 starting point of
specified file
UT_FS_NO_OPEN No 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] the starting point for reading
files
Length [in]length of data
Buffer [out]data to be read
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 starting point of
specified file
UT_FS_DATA_LEN_RANGE Out of range of data
length
UT_FS_NO_OPEN No open file
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 No 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);

<a _fcknotitle="true" href="Category:UniToken_APIs">UniToken_APIs</a>

Retrieved from "https://esecutech.com/wiki/index.php?title=UniToken_API_Reference&oldid=1054"