UniToken API Reference: Difference between revisions

From SecuTech Wiki
Jump to navigationJump to search
← Older editNewer edit →

Damien (talk | contribs)

2 user groups
0 edits
No edit summary
Line 1: Line 1:
[[Category:UniToken_APIs]]
<br>


== UT_GetLibraryVersion ==
== UT_GetLibraryVersion ==


'''API Prototype'''  
'''API Prototype'''  
 
<p>unsigned long UT_API UT_GetLibraryVersion().</p>
unsigned long UT_API UT_GetLibraryVersion().
 
'''Description'''
'''Description'''  
 
<p>To get the version of the present library</p>
To get the version of the present library
 
'''Parameters'''
'''Parameters'''  
 
<p>n/a</p>
n/a
 
'''Returned value'''
'''Returned value'''  


{| cellspacing="0" cellpadding="0" border="0" width=""
{| cellspacing="0" cellpadding="0" border="0" width=""
|-
|-
|width="180"|RETURNED VALUE
| width="180" | RETURNED VALUE  
|DESCRIPTION
| DESCRIPTION
|-  
|-
|Library version
| Library version  
|the version of the current library
| the version of the current library
|}  
|}
 
'''Sample'''
'''Sample'''  
<p>
 
unsigned long ulLibraryVersion;<br>
unsigned long ulLibraryVersion;<br> ulLibraryVersion = UT_GetLibraryVersion();  
ulLibraryVersion = UT_GetLibraryVersion();
</p>


== UT_Initialize ==
== UT_Initialize ==


'''API Prototype'''  
'''API Prototype'''  
 
<p>UT_RV UT_API UT_Initialize()</p>
UT_RV UT_API UT_Initialize()
 
'''Description'''
'''Description'''  
 
<p>To initialize the UniToken. It should be called before all the other functions except UT_GetLibraryVersion.</p>
To initialize the UniToken. It should be called before all the other functions except UT_GetLibraryVersion.
 
'''Parameters'''
'''Parameters'''  
 
<p>n/a</p>
n/a
 
'''Returned value'''
'''Returned value'''  


{| cellspacing="0" cellpadding="0" border="0" width=""
{| cellspacing="0" cellpadding="0" border="0" width=""
|-
|-
|width="180"|RETURNED VALUE
| width="180" | RETURNED VALUE  
|DESCRIPTION
| DESCRIPTION
|-  
|-
|UT_OK
| UT_OK  
|Successful operation
| Successful operation
|-
|-
|UT_ALREADY_INITIALIZE
| UT_ALREADY_INITIALIZE  
|Library already initialized
| Library already initialized
|}  
|}
 
'''Sample'''
'''Sample'''  
<p>
UT_RV ret; <br>
ret = UT_Initialize();
</p>


== UT_Finalize ==
UT_RV ret; <br> ret = UT_Initialize();
 
== UT_Finalize ==


'''API Prototype'''  
'''API Prototype'''  
 
<p>UT_RV UT_API UT_Finalize()</p>
UT_RV UT_API UT_Finalize()
 
'''Description'''
'''Description'''  
 
<p>Call this function to end any interaction with UniToken and free the memory.</p>
Call this function to end any interaction with UniToken and free the memory.
 
'''Parameters'''
'''Parameters'''  
 
<p>n/a</p>
n/a
 
'''Returned value'''
'''Returned value'''  


{| cellspacing="0" cellpadding="0" border="0" width=""
{| cellspacing="0" cellpadding="0" border="0" width=""
|-
|-
|width="180"|RETURNED VALUE
| width="180" | RETURNED VALUE  
|DESCRIPTION
| DESCRIPTION
|-  
|-
|UT_OK
| UT_OK  
|Successful operation
| Successful operation
|-
|-
|UT_NOT_INITIALIZE
| UT_NOT_INITIALIZE  
|Library not initialized
| Library not initialized
|}  
|}
'''Sample'''
<p>
UT_RV ret; <br>
ret = UT_Finalize();
</p>


== UT_GetTokenList ==
'''Sample'''
 
UT_RV ret; <br> ret = UT_Finalize();
 
== UT_GetTokenList ==


'''API Prototype'''  
'''API Prototype'''  
 
<p>UT_RV UT_API UT_GetTokenList(UT_SLOT_ID* lpSlotID, unsigned long* lpTokenCount)</p>
UT_RV UT_API UT_GetTokenList(UT_SLOT_ID* lpSlotID, unsigned long* lpTokenCount)
 
'''Description'''
'''Description'''  
 
<p>To get the list of Slot ID and the number of Slot ID</p>
To get the list of Slot ID and the number of Slot ID
 
'''Parameters'''
'''Parameters'''  
 
{| cellspacing="0" cellpadding="0" border="0" width=""
{| cellspacing="0" cellpadding="0" border="0" width=""
|-
|-
|width="180"|PARAMETERS
| width="180" | PARAMETERS  
|DESCRIPTION
| DESCRIPTION
|-  
|-
|lpSlotID
| lpSlotID  
|[out] slot ID list
| [out] slot ID list
|-
|-
|lpTokenCount
| lpTokenCount  
|[in] size of buffer (0~32 bytes)<br>
| [in] size of buffer (0~32 bytes)<br>  
[out]number of token
[out]number of token  
 
|}
|}
 
'''Returned value'''
'''Returned value'''  


{| cellspacing="0" cellpadding="0" border="0" width=""
{| cellspacing="0" cellpadding="0" border="0" width=""
|-
|-
|width="180"|RETURNED VALUE
| width="180" | RETURNED VALUE  
|DESCRIPTION
| DESCRIPTION
|-
|UT_OK 
|Successful operation
|-
|-
|UT_NOT_INITIALIZE
| UT_OK
|Library not initialized
| Successful operation
|-
| UT_NOT_INITIALIZE  
| Library not initialized
|}
|}
 
'''Sample'''
'''Sample'''  
<p>
 
UT_RV ret; <br>
UT_RV ret; <br> UT_HANDLE utHandle; <br> UT_SLOT_ID* lpSlotID = NULL; <br> unsigned long ulTokenCount = 0; <br> ret = UT_GetTokenList(lpSlotID,&amp;ulTokenCount); <br> if (ret == UT_BUFFER_TOO_SMALL){ <br> &nbsp;&nbsp;&nbsp;&nbsp; lpSlotID = new UT_SLOT_ID[ulTokenCount]; <br> &nbsp;&nbsp;&nbsp;&nbsp; ret = UT_GetTokenList(lpSlotID,&amp;ulTokenCount); <br> }<br> ret = UT_OpenDevice(lpSlotID[0],&amp;utHandle); <br> ret = UT_GetHandle(lpSlotID[0],&amp;utHandle); <br> ret = UT_GetSlotID(utHandle,&amp;lpSlotID[0]); <br> ret = UT_CloseDevice(utHandle); <br>  
UT_HANDLE utHandle; <br>
UT_SLOT_ID* lpSlotID = NULL; <br>
unsigned long ulTokenCount = 0; <br>
ret = UT_GetTokenList(lpSlotID,&ulTokenCount); <br>
if (ret == UT_BUFFER_TOO_SMALL){ <br>
&nbsp;&nbsp;&nbsp;&nbsp;   lpSlotID = new UT_SLOT_ID[ulTokenCount]; <br>
&nbsp;&nbsp;&nbsp;&nbsp;   ret = UT_GetTokenList(lpSlotID,&ulTokenCount); <br>
}<br>
ret = UT_OpenDevice(lpSlotID[0],&utHandle); <br>
ret = UT_GetHandle(lpSlotID[0],&utHandle); <br>
ret = UT_GetSlotID(utHandle,&lpSlotID[0]); <br>
ret = UT_CloseDevice(utHandle); <br>
</p>


== UT_OpenDevice  ==
== UT_OpenDevice  ==


'''Prototype '''<br> <br>UT_RV UT_API UT_OpenDevice( <br>UT_SLOT_ID SlotID, <br> UT_HANDLE* lputHandle <br> ) <br> <br>'''Description '''<br> <br>To open the device in the specified slot <br> <br>'''Parameters '''<br> <br>PARAMETERS DESCRIPTION <br>SlotID [in] the specified slot <br>lputHandle [out] device handle <br> <br>'''Returned value '''<br> <br>RETURNED VALUE DESCRIPTION <br>UT_OK Successful operation <br>UT_NOT_INITIALIZE Library not initialized <br>UT_ARGUMENTS_BAD Invalid argument <br>UT_SLOT_ID_INVALUD Invalid slot ID <br> <br>'''Usage note '''<br> <br>SlotID should be gotten from UT_GetTokenList instead of manually input. <br>Therefore, this function cannot be called before UT_GetTokenList. <br> <br>'''Sample'''<br>
'''Prototype '''<br> <br>UT_RV UT_API UT_OpenDevice( <br>UT_SLOT_ID SlotID, <br> UT_HANDLE* lputHandle <br> ) <br> <br>'''Description '''<br> <br>To open the device in the specified slot <br> <br>'''Parameters '''<br> <br>PARAMETERS DESCRIPTION <br>SlotID [in] the specified slot <br>lputHandle [out] device handle <br> <br>'''Returned value '''<br> <br>RETURNED VALUE DESCRIPTION <br>UT_OK Successful operation <br>UT_NOT_INITIALIZE Library not initialized <br>UT_ARGUMENTS_BAD Invalid argument <br>UT_SLOT_ID_INVALUD Invalid slot ID <br> <br>'''Usage note '''<br> <br>SlotID should be gotten from UT_GetTokenList instead of manually input. <br>Therefore, this function cannot be called before UT_GetTokenList. <br> <br>'''Sample'''<br>
 
See also the sample of UT_GetTokenList <br>
 
== UT_CloseDevice  ==
 
'''Prototype '''<br> <br>UT_RV UT_API UT_CloseDevice(UT_HANDLE utHandle) <br> <br>'''Description '''<br> <br>To close the specified device <br> <br>'''Parameters '''<br> <br>n/a <br> <br>'''Returned value '''<br> <br>RETURNED VALUE DESCRIPTION <br>UT_OK Successful operation <br>UT_NOT_INITIALIZE Library not initialized <br>UT_TOKEN_HANDLE_INVALID Invalid token handle <br> <br>'''Sample '''<br> <br>See also the sample of UT_GetTokenList <br>
 
== UT_GetHandle  ==
 
'''Prototype '''<br>UT_RV UT_API UT_GetHandle( <br>UT_SLOT_ID SlotID, <br> UT_HANDLE* lputHandle <br> ) <br> <br>'''Description '''<br>To get device handle by Slot ID<br>
 
<br>
 
'''Parameters '''<br>PARAMETERS DESCRIPTION <br>SlotID [in] the specified slot <br>lputHandle [out] device handle <br> <br>'''Returned value '''<br>RETURNED VALUE DESCRIPTION <br>UT_OK Successful operation <br>UT_NOT_INITIALIZE Library not initialized <br>UT_ARGUMENTS_BAD Invalid argument <br> <br>'''Sample '''<br>See also the sample of UT_GetTokenList<br>
 
== UT_GetSlotID  ==
 
'''Prototype '''<br>UT_RV UT_API UT_GetSlotID( <br>UT_HANDLE utHandle, <br> UT_SLOT_ID* lpSlotID <br> ) <br> <br>'''Description '''<br>To get Slot ID by device handle <br> <br>'''Parameters '''<br>PARAMETERS DESCRIPTION <br>utHandle [in] the specified handle <br>lpSlotID [out] Slot ID <br> <br>'''Returned value '''<br>
 
RETURNED VALUE DESCRIPTION<br>
 
UT_OK Successful operation <br>UT_NOT_INITIALIZE Library not initialized <br>UT_ARGUMENTS_BAD Invalid argument <br>UT_TOKEN_HANDLE_INVALID Invalid token handle <br> <br>'''Sample '''<br>See also the sample of UT_GetTokenList<br>
 
== UT_GetSlotStatus  ==
 
'''Prototype '''<br>UT_RV UT_API UT_GetSlotStatus( <br>UT_STATUS* lpStatus, <br> UT_SLOT_ID* lpSlotID <br> ) <br> <br>'''Description '''<br>To get the status of Slot <br> <br>'''Parameters '''<br>PARAMETERS DESCRIPTION <br>lpStatus [out]the current status of slot <br>lpSlotID [out] Slot ID <br> <br>'''Notes: '''<br>lpStatus can be <br>a. Inserted, when UniToken is inserted into the slot; <br>b. Removed, when UniToken is removed from the slot; <br>c. No change, when there’s no change to the status of slot. In this case, lpSlotID is undefined.<br>
 
<br>
 
'''Returned value '''<br>RETURNED VALUE DESCRIPTION <br>UT_OK Successful operation <br>UT_NOT_INITIALIZE Library not initialized <br>UT_ARGUMENTS_BAD Invalid argument <br> <br>'''Sample '''<br>UT_RV rv; <br>UT_STATUS status; <br>UT_SLOT_ID slotID; <br>rv = UT_GetSlotStatus(&amp;status,&amp; slotID); <br>if ( rv == UT_OK ){ <br> if ( status == TOKEN_NO_EVENT ) { <br> // no change of status <br> } else if ( status == TOKEN_INSERT ) { <br> // token inserted <br> } else if ( status == TOKEN_REMOVE ) { <br> // token removed <br> } <br>} <br>
 
== UT_GetTokenType  ==
 
'''Prototype '''<br>UT_RV UT_API UT_GetTokenType( <br>UT_HANDLE utHandle, <br> char* lpszTokenType <br> ) <br> <br>'''Description '''<br>To get the type of the current device, e.g. UniToken STD, PRO <br> <br>'''Parameters '''<br>PARAMETERS DESCRIPTION <br>utHandle [in]device handle <br>lpszTokenType [out]UniToken type (string, 32 <br>bytes) <br>
 
<br>
 
'''Returned value '''<br>RETURNED VALUE DESCRIPTION <br>UT_OK Successful operation <br>UT_NOT_INITIALIZE Library not initialized <br>UT_ARGUMENTS_BAD Invalid argument <br>UT_TOKEN_HANDLE_INVALID Invalid token handle <br> <br>'''Sample '''<br>UT_RV ret; <br>UT_HANDLE utHandle; <br>char TokenType[33]={0}; <br>ret = UT_GetTokenType(utHandle,(char *)TokenType);<br>
 
== UT_GetFirmwareVersion  ==
 
'''Prototype '''<br>UT_RV UT_API UT_GetFirmwareVersion( <br>UT_HANDLE utHandle, <br> unsigned long* lpVersion <br> ) <br> <br>'''Description '''<br>To get the version of firmware <br> <br>'''Parameters '''<br>PARAMETERS DESCRIPTION <br>utHandle [in] device handle <br>lpVersion [out] firmware version <br>
 
<br>
 
'''Returned value '''<br>RETURNED VALUE DESCRIPTION <br>UT_OK Successful operation <br>UT_NOT_INITIALIZE Library not initialized <br>UT_ARGUMENTS_BAD Invalid argument <br>UT_TOKEN_HANDLE_INVALID Invalid token handle <br> <br>'''Sample '''<br>UT_RV ret; <br>UT_HANDLE utHandle; <br>unsigned long Version; <br>ret = UT_GetFirmwareVersion(utHandle,&amp;Version);<br>
 
== UT_Logoff  ==
 
'''Prototype '''<br>UT_RV UT_API UT_Logoff(UT_HANDLE utHandle) <br> <br>'''Description '''<br>To log off the specified Token <br> <br>'''Parameters '''<br>PARAMETERS DESCRIPTION <br>utHandle [in]device handle <br> <br>'''Returned value '''<br>RETURNED VALUE DESCRIPTION <br>UT_OK Successful operation <br>UT_NOT_INITIALIZE Library not initialized <br>UT_TOKEN_HANDLE_INVALID Invalid token handle <br> <br>'''Sample '''<br>See also the sample of UT_Logon<br>
 
== UT_Logon  ==
 
'''Prototype '''<br>UT_RV UT_API UT_Logon( <br>UT_HANDLE utHandle, <br> unsigned long UserLevel, <br> unsigned char* lpszPin <br> ) <br> <br>'''Description '''<br>To logon the specified token <br> <br>'''Parameters '''<br>PARAMETERS DESCRIPTION <br>utHandle [in]device handle <br>UserLevel [in] levels of permission <br>lpszPin [in]the corresponding password with <br>certain permission level <br> <br>'''Note: '''<br>lpszPin is made up with strings, and the minimum size is 1 byte. <br> <br>'''Returned value '''<br>RETURNED VALUE DESCRIPTION <br>UT_OK Successful operation <br>UT_NOT_INITIALIZE Library not initialized <br>UT_ARGUMENTS_BAD Invalid argument <br>UT_TOKEN_HANDLE_INVALID Invalid token handle <br>UT_PIN_ERROR Wrong password <br>UT_USER_FULL No more sessions <br>allowed <br>UT_USER_LOCKED Token locked<br>
 
<br>
 
'''Usage note '''<br>UniToken provides three levels of user permission: GUEST permission, USER <br>permission and ADMIN permission. <br> <br>The default permission is GUEST. To log on as USER or ADMIN, the <br>corresponding PINs are required. <br> <br>'''Sample '''<br>UT_RV ret; <br>UT_HANDLE utHandle; <br>unsigned char Pin[] = UT_DEFAULT_USER; <br>unsigned long UserLevel; <br>ret = UT_Logon( <br> utHandle, <br> UT_USER_LEVEL_USER, <br> (unsigned char*)Pin <br> ); <br>ret = UT_GetCurrentUserLevel(utHandle,&amp;UserLevel); <br>ret = UT_Logoff(utHandle);<br>
 
== UT_GetCurrentUserLevel  ==
 
'''Prototype '''<br>UT_RV UT_API UT_GetCurrentUserLevel( <br>UT_HANDLE utHandle, <br> unsigned long* lpUserLevel <br> ) <br> <br>'''Description '''<br>To get the current permission level <br> <br>'''Parameters '''<br>PARAMETERS DESCRIPTION <br>utHandle [in]device handle <br>lpUserLevel [out] permission level <br>


See also the sample of UT_GetTokenList <br>
<br>


== UT_CloseDevice ==
'''Returned value '''<br>RETURNED VALUE DESCRIPTION <br>UT_OK Successful operation <br>UT_NOT_INITIALIZE Library not initialized <br>UT_ARGUMENTS_BAD Invalid argument <br>UT_TOKEN_HANDLE_INVALID Invalid token handle <br> <br>'''Sample '''<br>See also the sample of UT_Logon<br>


== UT_GetHandle ==
== UT_ChangePin  ==


== UT_GetSlotID ==
'''Prototype '''<br>UT_RV UT_API UT_ChangePin( <br>UT_HANDLE utHandle, <br> unsigned char UserLevel, <br> unsigned long ChangeMode, <br> unsigned char* OldPin, <br> unsigned char* NewPin <br> ) <br> <br>'''Description '''<br>To change password <br> <br>'''Parameters '''<br>PARAMETERS DESCRIPTION <br>utHandle [in]device handle <br>UserLevel [in]permission level <br>ChangeMode [in]mode of changing <br>OldPin [in] old PIN <br>NewPin [in]new PIN <br>


== UT_GetSlotStatus ==
'''Notes: '''<br>Change Mode an be UT_CHANGE_PIN_MODE_BYSELF or <br>UT_CHANGE_PIN_MODE_ADMIN_CHANGE_USER <br> <br>'''Returned value '''<br>RETURNED VALUE DESCRIPTION <br>UT_OK Successful operation <br>UT_NOT_INITIALIZE Library not initialized <br>UT_ARGUMENTS_BAD Invalid argument <br>UT_TOKEN_HANDLE_INVALID Invalid token handle <br>UT_NOT_ALLOWED Operation not allowed <br>


== UT_GetTokenType ==
<br>


== UT_GetFirmwareVersion ==
'''Usage note '''<br> <br>Two ways of changing password: <br> <br>1. User/Admin changes his own password <br>Log on as USER or ADMIN and type in the old password and the new one. <br>Here, the mode of changing PIN is UT_CHANGE_PIN_MODE_BYSELF <br>2. Admin resets user password <br>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. <br> <br>'''Sample '''<br>UT_RV ret; <br>UT_HANDLE utHandle; <br>unsigned char Pin[] = UT_DEFAULT_USER; <br>unsigned char NewPin[] = "1234"; <br>unsigned long UserLevel; <br>ret = UT_Logon( <br> utHandle, <br> UT_USER_LEVEL_USER, <br>(unsigned char*)Pin <br>); <br>ret = UT_ChangePin( <br>utHandle, <br> UT_USER_LEVEL_USER, <br> UT_CHANGE_PIN_MODE_BYSELF, <br> (unsigned char*)Pin, <br> (unsigned char*)newPin <br>);<br>


== UT_Logoff ==
== UT_GetID  ==


== UT_Logon ==
'''Prototype '''<br>UT_RV UT_API UT_GetID( <br>UT_HANDLE utHandle, <br> char* lpszId <br> ) <br> <br>'''Description '''<br>To get the token ID of specified device <br> <br>'''Parameters '''<br>PARAMETERS DESCRIPTION <br>utHandle [in]device handle <br>lpszId [out] UniToken ID (string, 32 <br>bytes) <br> <br>'''Returned value '''<br>RETURNED VALUE DESCRIPTION <br>UT_OK Successful operation <br>UT_NOT_INITIALIZE Library not initialized <br>UT_ARGUMENTS_BAD Invalid argument <br>UT_TOKEN_HANDLE_INVALID Invalid token handle <br> <br>'''Sample '''<br>See also the sample of UT_SetID<br>


== UT_GetCurrentUserLevel ==
== UT_SetID  ==


== UT_ChangePin ==
'''Prototype '''<br>UT_RV UT_API UT_SetID( <br>UT_HANDLE utHandle, <br> char* lpszId <br> ) <br> <br>'''Description '''<br>To set the token ID of the specified device <br> <br>'''Parameters '''<br>PARAMETERS DESCRIPTION <br>utHandle [in]device handle <br>lpszId [out] UniToken ID (string, 32 <br>bytes) <br> <br>'''Returned value '''<br>RETURNED VALUE DESCRIPTION <br>UT_OK Successful operation <br>UT_NOT_INITIALIZE Library not initialized <br>UT_ARGUMENTS_BAD Invalid argument <br>UT_TOKEN_HANDLE_INVALID Invalid token handle <br> <br>'''Sample '''<br>UT_RV ret; <br>UT_HANDLE utHandle; <br>char Id[33] = "UniTokenPRO"; <br>unsigned long UserLevel; <br>ret = UT_SetID(utHandle,Id); <br>ret = UT_GetID(utHandle,Id); <br>


== UT_GetID ==
== UT_GetHID  ==


== UT_SetID ==
'''Prototype '''<br>UT_RV UT_API UT_GetHID( <br>UT_HANDLE utHandle, <br> unsigned long* lpHid <br> ) <br> <br>'''Description '''<br>To get the Hardware ID of the specified device <br> <br>'''Parameters '''<br>PARAMETERS DESCRIPTION <br>utHandle [in]device handle <br>lpHid [out] Hardware ID <br> <br>'''Returned value '''<br>RETURNED VALUE DESCRIPTION <br>UT_OK Successful operation <br>UT_NOT_INITIALIZE Library not initialized <br>UT_ARGUMENTS_BAD Invalid argument <br>UT_TOKEN_HANDLE_INVALID Invalid token handle <br> <br>'''Sample '''<br>UT_RV ret; <br>UT_HANDLE utHandle; <br>unsigned long Hid; <br>ret = UT_GetHID(utHandle,&amp;Hid);<br>


== UT_GetHID ==
== UT_GetSoftID  ==


== UT_GetSoftID ==
== UT_SetSoftID  ==


== UT_SetSoftID ==
== UT_LED  ==


== UT_LED ==
== UT_SetAttemptCount  ==


== UT_SetAttemptCount ==
== UT_GetAttemptCount  ==


== UT_GetAttemptCount ==
== UT_Format  ==


== UT_Format ==
== UT_Rand  ==


== UT_Rand ==
== UT_DESGenerateKey  ==


== UT_DESGenerateKey ==
== UT_DESEncrypt  ==


== UT_DESEncrypt ==
== UT_DESDecrypt  ==


== UT_DESDecrypt ==
== UT_DESImportKey  ==


== UT_DESImportKey ==
== UT_DESDeleteKey  ==


== UT_DESDeleteKey ==
== UT_DESGetKeyCount  ==


== UT_DESGetKeyCount ==
== UT_DESGetFirstKeyHandle  ==


== UT_DESGetFirstKeyHandle ==
== UT_DESGetNextKeyHandle  ==


== UT_DESGetNextKeyHandle ==
== UT_DES3GenerateKey  ==


== UT_DES3GenerateKey ==
== UT_DES3Encrypt  ==


== UT_DES3Encrypt ==
== UT_DES3Decrypt  ==


== UT_DES3Decrypt ==
== UT_DES3ImportKey  ==


== UT_DES3ImportKey ==
== UT_DES3DeleteKey  ==


== UT_DES3DeleteKey ==
== UT_DES3GetKeyCount  ==


== UT_DES3GetKeyCount ==
== UT_DES3GetFirstKeyHandle  ==


== UT_DES3GetFirstKeyHandle ==
== UT_DES3GetNextKeyHandle  ==


== UT_DES3GetNextKeyHandle ==
== UT_AESGenerateKey  ==


== UT_AESGenerateKey ==
== UT_AESEncrypt  ==


== UT_AESEncrypt ==
== UT_AESDecrypt  ==


== UT_AESDecrypt ==
== UT_AESImportKey  ==


== UT_AESImportKey ==
== UT_AESDeleteKey  ==


== UT_AESDeleteKey ==
== UT_AESGetKeyCount  ==


== UT_AESGetKeyCount ==
== UT_AESGetKeyLen  ==


== UT_AESGetKeyLen ==
== UT_AESGetFirstKeyHandle  ==


== UT_AESGetFirstKeyHandle ==
== UT_AESGetNextKeyHandle  ==


== UT_AESGetNextKeyHandle ==
== UT_RSAGenerateKeyPair  ==


== UT_RSAGenerateKeyPair ==
== UT_RSAPubKeyEncrypt  ==


== UT_RSAPubKeyEncrypt ==
== UT_RSAPriKeyDecrypt  ==


== UT_RSAPriKeyDecrypt ==
== UT_RSAPriKeyEncrypt  ==


== UT_RSAPriKeyEncrypt ==
== UT_RSAPubKeyDecrypt  ==


== UT_RSAPubKeyDecrypt ==
== UT_RSAGetKeyPairCount  ==


== UT_RSAGetKeyPairCount ==
== UT_RSAGetFirstKeyPairHandle  ==


== UT_RSAGetFirstKeyPairHandle ==
== UT_RSAGetNextKeyPairHandle  ==


== UT_RSAGetNextKeyPairHandle ==
== UT_RSAPubKeyImport  ==


== UT_RSAPubKeyImport ==
== UT_RSAPriKeyImport  ==


== UT_RSAPriKeyImport ==
== UT_RSAPubKeyExport  ==


== UT_RSAPubKeyExport ==
== UT_RSAGetPubKeyHandle  ==


== UT_RSAGetPubKeyHandle ==
== UT_RSAGetPriKeyHandle  ==


== UT_RSAGetPriKeyHandle ==
== UT_RSAGetKeyPairModulus  ==


== UT_RSAGetKeyPairModulus ==
== UT_RSADeleteKeyPair  ==


== UT_RSADeleteKeyPair ==
== UT_MD5HMACGenerateKey  ==


== UT_MD5HMACGenerateKey ==
== UT_MD5HMAC  ==


== UT_MD5HMAC ==
== UT_MD5  ==


== UT_MD5 ==
== UT_MD5GetKeyCount  ==


== UT_MD5GetKeyCount ==
== UT_MD5GetKeyLen  ==


== UT_MD5GetKeyLen ==
== UT_MD5GetFirstKeyHandle  ==


== UT_MD5GetFirstKeyHandle ==
== UT_MD5GetNextKeyHandle  ==


== UT_MD5GetNextKeyHandle ==
== UT_MD5DeleteKey  ==


== UT_MD5DeleteKey ==
== UT_MD5ImportKey  ==


== UT_MD5ImportKey ==
== UT_SHA1HMACGenerateKey  ==


== UT_SHA1HMACGenerateKey ==
== UT_SHA1HMAC  ==


== UT_SHA1HMAC ==
== UT_SHA1  ==


== UT_SHA1 ==
== UT_SHA1GetKeyCount  ==


== UT_SHA1GetKeyCount ==
== UT_SHA1GetKeyLen  ==


== UT_SHA1GetKeyLen ==
== UT_SHA1GetFirstKeyHandle  ==


== UT_SHA1GetFirstKeyHandle ==
== UT_SHA1GetNextKeyHandle  ==


== UT_SHA1GetNextKeyHandle ==
== UT_SHA1DeleteKey  ==


== UT_SHA1DeleteKey ==
== UT_SHA1ImportKey  ==


== UT_SHA1ImportKey ==
== UT_FS_GetSpace  ==


== UT_FS_GetSpace ==
== UT_FS_GetFileCount  ==


== UT_FS_GetFileCount ==
== UT_FS_GetFirstFileName  ==


== UT_FS_GetFirstFileName ==
== UT_FS_GetNextFileName  ==


== UT_FS_GetNextFileName ==
== UT_FS_GetFileSize  ==


== UT_FS_GetFileSize ==
== UT_FS_GetFilePermission  ==


== UT_FS_GetFilePermission ==
== UT_FS_CreatFile  ==


== UT_FS_CreatFile ==
== UT_FS_DeleteFile  ==


== UT_FS_DeleteFile ==
== UT_FS_OpenFile  ==


== UT_FS_OpenFile ==
== UT_FS_WriteFile  ==


== UT_FS_WriteFile ==
== UT_FS_ReadFile  ==


== UT_FS_ReadFile ==
== UT_FS_CloseFile  ==


== UT_FS_CloseFile ==
&lt;a _fcknotitle="true" href="Category:UniToken_APIs"&gt;UniToken_APIs&lt;/a&gt;

Revision as of 13:57, 12 April 2012


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

UT_SetSoftID

UT_LED

UT_SetAttemptCount

UT_GetAttemptCount

UT_Format

UT_Rand

UT_DESGenerateKey

UT_DESEncrypt

UT_DESDecrypt

UT_DESImportKey

UT_DESDeleteKey

UT_DESGetKeyCount

UT_DESGetFirstKeyHandle

UT_DESGetNextKeyHandle

UT_DES3GenerateKey

UT_DES3Encrypt

UT_DES3Decrypt

UT_DES3ImportKey

UT_DES3DeleteKey

UT_DES3GetKeyCount

UT_DES3GetFirstKeyHandle

UT_DES3GetNextKeyHandle

UT_AESGenerateKey

UT_AESEncrypt

UT_AESDecrypt

UT_AESImportKey

UT_AESDeleteKey

UT_AESGetKeyCount

UT_AESGetKeyLen

UT_AESGetFirstKeyHandle

UT_AESGetNextKeyHandle

UT_RSAGenerateKeyPair

UT_RSAPubKeyEncrypt

UT_RSAPriKeyDecrypt

UT_RSAPriKeyEncrypt

UT_RSAPubKeyDecrypt

UT_RSAGetKeyPairCount

UT_RSAGetFirstKeyPairHandle

UT_RSAGetNextKeyPairHandle

UT_RSAPubKeyImport

UT_RSAPriKeyImport

UT_RSAPubKeyExport

UT_RSAGetPubKeyHandle

UT_RSAGetPriKeyHandle

UT_RSAGetKeyPairModulus

UT_RSADeleteKeyPair

UT_MD5HMACGenerateKey

UT_MD5HMAC

UT_MD5

UT_MD5GetKeyCount

UT_MD5GetKeyLen

UT_MD5GetFirstKeyHandle

UT_MD5GetNextKeyHandle

UT_MD5DeleteKey

UT_MD5ImportKey

UT_SHA1HMACGenerateKey

UT_SHA1HMAC

UT_SHA1

UT_SHA1GetKeyCount

UT_SHA1GetKeyLen

UT_SHA1GetFirstKeyHandle

UT_SHA1GetNextKeyHandle

UT_SHA1DeleteKey

UT_SHA1ImportKey

UT_FS_GetSpace

UT_FS_GetFileCount

UT_FS_GetFirstFileName

UT_FS_GetNextFileName

UT_FS_GetFileSize

UT_FS_GetFilePermission

UT_FS_CreatFile

UT_FS_DeleteFile

UT_FS_OpenFile

UT_FS_WriteFile

UT_FS_ReadFile

UT_FS_CloseFile

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

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