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. 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 gotten from UT_GetTokenList instead of manually input.
Therefore, this function cannot be called before UT_GetTokenList.

Sample

See also 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 also 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 also 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 also 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 also 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 password

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 also 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 also 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 attempt times

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 gotten by UT_RSAGetPubKeyByPriKey
instead of manually input. 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 gotten by 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 gotten by UT_RSAGetPriKeyByPubKey
instead of manually input. 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 gotten by UT_RSAGetPubKeyByPriKey
instead of manually input. 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.
Besides, UniToken device can store 16 RSA key pairs. If there’re already 16 key pairs inside, calling this function, return UT_KEY_FULL.

Sample
See also 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_FS_CloseFile

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