SecuTech Wiki - User contributions [en]

UniOTP Server APIs

2016-08-23T06:42:12Z

Bao: Medium rework of overall structure

[[Category:UniOTP_API]]

== How to use C/C++ SDK ==

==== Preparation ====

# The SDK server needs to operate a database. Inside the C/C++ version SDK uses ODBC to access to the database. That’s why, before beginning to develop, it is required to install a database(for now, UniOTP supports Oracle/MySQL/Postgresql/SQL Server) and to configure the ODBC driver for database products access.
# In the distributable package, you can find a file named initsqlscript that contains the SQL initialization script for the 4 types of database described before. You must use your database administration tool (for example SQLPlus, MySQL Client, etc.) to create a new database, or you can use one of your own databases. Use the SQL file inside the folder initsqlscript to initialize the database tables for UniOTP for UniOTP dynamic password authentication system.
# Once you finish preparing the database, create an ODBC data source for this newly created database. (Use the database prepared in step 2).
# Before beginning developing using the SDK, you need to create a configuration file (use the file otp_conf.com as an example)

You just need to use the configuration file created in step 2 to reconfigure the information related to the settings file. Use the function secuinitenv(char *pszConfpath) to add settings file (such as otp_conf.con) and to complete initialization of information in the SDK.

==== Add support for UniOTP dynamic password authentication ====

# Add the Server SDK library files (dynamic or static library) and its header files (otp_corec32.h) to the project.
# Copy the database configuration file created in the “preparation” part step 4 to the appropriate place in your project. (you can actually put the configuration file anywhere, but it is recommended to put it in the project directory )
# Use API introduced later in this document to perform operations related to authentication.

==== SDK Operation procedure and Important points ====

'''Operation procedure'''

# Use the API secuotp_initenv(char *pszConfpath) to initialize the SDK Settings information.
# Use other interface to complete business related treatments.
# Use Secuotp_cleanup()API to perform maintenance operations such as releasing resources.

For more details about other interfaces way of use, please see the sample.

'''Important points'''

# The function secuotp_initenv(char *pszConfpath) is used to initialize settings information, when using the SDK, you only need to call the function once.
# Once you finish using UniOTP SDK, call the secuotp_cleanup() function to perform cleaning operations.
# secuotp_tokenimport(char*pszTokenfile, char *pszSecret, char **pstrErrinfo) function is used to import token in batch, pstrErrinfo is assigned a value by the internal API. If you don’t need this memory area any longer, please use secuotp_free(void **spsbuf) to release it.
# secuotp_userimport(char *pszUserfile, char *pszSecret, char **pstrErrinfo) this function is used to import users in batch, pstrErrinfo is assigned a value by the internal API. If you don’t need this memory area any longer, please use secuotp_free(void **spsbuf) to release it.
# secuotp_userimport(char *pszUserfile, char *pszSecret, char **pstrErrinfo) this function is used to import users in batch, pszSecret points to the user record file decryption key, if pzSecret is NULL or the buffer data is null, then it shows the file isn't encrypted . We recommend not to use encryption.

==== API:SECUOTP_INITENV() ====

'''Prototype'''

<source lang="C">int secuotp_initenv(char *pszConfpath);</source>

'''Description'''

Initialize environment, set the path for the configuration file.

'''Parameters'''

PARAMETERS DESCRIPTION

* char *pszConfpath [IN] configuration file path

'''Return Value'''

RETURN VALUE DESCRIPTION

* SECUOTP_ERROR_SUCCESS the function was executed successfully
* SECUOTP_ERROR_INVALID_PARAM Invalid parameters
* SECUOTP_ERROR_ALLOCHANDLE_FAILED Failed to allocate database handle(ODBC)
* SECUOTP_ERROR_SETENVATTR_FAILED Failed to configure ODBC driver version
* SECUOTP_ERROR_GETCONFIGFAILED Configuration file error or failed to read configuration information

==== API:SECUOTP_CLEANUP() ====

'''Prototype'''

<source lang="C">int secuotp_cleanup();</source>

'''Description'''

Complete a few cleaning operations, before the process ends or before uninstalling dynamic libraries, you need to call this function to release handles that haven’t been unreleased.

'''Parameters'''

none

'''Return value'''

RETURN VALUE DESCRIPTION

* SECUOTP_ERROR_SUCCESS function executed successfully
* SECUOTP_ERROR_FREEHANDLE_FAILED error while releasing handles

==== API:SECUOTP_GETLASTERROR() ====

'''Prototype'''

<source lang="C">unsigned long secuotp_getlasterror();</source>

'''Description'''

Get last error code

'''Parameters:'''

None

'''Return value:'''

Code of the last error that happened.

==== API:SECUOTP_AUTH() ====

'''Prototype'''

<source lang="C">int secuotp_auth(char *pszUsername, char *pszPwd, unsigned int *pChallenge);</source>

'''Description'''

Perform dynamic password user authentication

'''Parameters'''

PARAMETERS DESCRIPTION

* char *pszUsername [IN] Username for the user waiting to be authenticated
* char *pszPwd [IN] password (OTP or OTP+PIN)
* unsigned int *pChallenge [OUT] challenge code returned by the server

'''Return value'''

RETURN VALUE DESCRIPTION

* SECUOTP_ERROR_SUCCESS Authentication succeeded
* SECUOTP_ERROR_CHALLENGE the challenge information from the client is needed

Others (See the error code list for more details). Authentication failed or error happened when authenticating.

==== API:SECUOTP_SYNCHRONIZE() ====

'''Prototype'''

<source lang="C">int secuotp_synchronize(char *pszUsername, char *pszOtp1, char *pszOtp2);</source>

'''Description'''

Perform user token synchronization

'''Parameters'''

PARAMETERS DESCRIPTION

* char *pszUsername [IN] username of the user’s token that needs to be synchronized
* char *pszOtp1 [IN] For the synchronization to be completed, you need to provide two consecutive dynamic passwords. This parameter is the first of the two passwords
* char *pszOtp2 [IN] The second of the two passwords

'''Return Value'''

RETURN VALUE DESCRIPTION

* SECUOTP_ERROR_SUCCESS Synchronization succeeded

Others (See the error code list for more details): Synchronization failed or error happened while synchronizing.

==== API:SECUOTP_SETUSERPIN() ====

'''Prototype'''

<source lang="C">int secuotp_setuserpin(char *pszUsername, char *pszPin);</source>

'''Description'''

Configure user static PIN

'''Parameters'''

PARAMETERS DESCRIPTION

* char *pszUsername [IN] Username
* char *pszPin [IN] new static PIN for this user

'''Return Value'''

RETURN VALUE DESCRIPTION

* SECUOTP_ERROR_SUCCESS Static PIN configured correctly

Others (See the error code list for more details): Failed to configure the static PIN

==== API:SECUOTP_RESETPIN() ====

'''Prototype'''

<source lang="C">int secuotp_resetpin(char *pszUsername, char *pszOldpin, char *pszNewpin);</source>

'''Description'''

Reset user static PIN

'''Parameters'''

PARAMETERS DESCRIPTION

* char *pszUsername [IN] Username
* char *pszOldpin [IN] old static PIN
* char *pszNewpin [IN] new static PIN

'''Return value'''

RETURN VALUE DESCRIPTION

* SECUOTP_ERROR_SUCCESS New PIN set successfully

Others(See the error code list for more details) Failed to set the new static PIN

==== API:SECUOTP_SETAUTHTYPE() ====

'''Prototype'''

<source lang="C">int secuotp_setauthtype(char *pszUsername, int nAuthtype);</source>

'''Description'''

Set authentication type

'''Parameters '''

PARAMETERS DESCRIPTION

* char *pszUsername [IN] Username
* int nAuthtype [IN] Authentication type(1- use only OTP, 2-use OTP+PIN)

'''Return value'''

RETURN VALUE DESCRIPTION

* SECUOTP_ERROR_SUCCESS authentication type set successfully
Others (See the error code list for more details) failed to set authentication type

==== API:SECUOTP_ADDUSER() ====

'''Prototype'''

<source lang="C">
int secuotp_adduser(
char *pszUsername,
char *pszUserid,
char *pszContacttel,
char *pszSerialnum,
char *pszRemark,
char *pszEmail,
char *pszDomain,
char *pszPin,
char *pszPreusedate,
int nAuthtype
);
</source>

'''Description'''

Add a new user

Remark: Before adding a user into the UniOTP Authentication System, Please make sure that the token allocated to the user has been imported into the database using the '''secuotp_tokenimport()''' function.

'''Parameters'''

PARAMETERS DESCRIPTION

* char *pszUsername [IN] username of the user you want to add
* char *pszUserid [IN] User ID, for example Identity card number
* char *pszContacttel [IN] Phone number
* char *pszSerialnum [IN] serial number of the token allocated to the user
* char *pszRemark [IN] remarks/comments about the user
* char *pszEmail [IN] user Email address
* char *pszDomain [IN] reserved, NULL
* char *pszPin [IN] User static PIN
* char *pszPreusedate [IN] User registration date
* int nAuthtype [IN] Authentication date

'''Return value'''

RETURN VALUE DESCRIPTION

* SECUOTP_ERROR_SUCCESS User registration successful

Others (See the error code list for more details) failed to register user

==== API:SECUOTP_DELETEUSER() ====

'''Prototype'''

<source lang="C">int secuotp_deleteuser(char *pszUsername);</source>

'''Description'''

Delete a user

'''Parameters'''

PARAMETERS DESCRIPTION

* char *pszUsername [IN] username of the user you want to delete

'''Return value'''

RETURN VALUE DESCRIPTION

* SECUOTP_ERROR_SUCCESS user deleted successfully

Others (See the error code list for more details) failed to delete user

==== API:SECUOTP_SETUSERINVALID() ====

'''Prototype'''

<source lang="C">int secuotp_setuserinvalid(char *pszUsername, int nvalid);</source>

'''Description'''

Set user validity status (used to report a token as “lost”)

'''Parameters'''

PARAMETERS DESCRIPTION

* char *pszUsername [IN] Username
* int nvalid [IN] User validity status (0-valid, 1-invalid)

'''Return value'''

RETURN VALUE DESCRIPTION

* SECUOTP_ERROR_SUCCESS function called successfully

Others (See the error code list for more details) failed to call the function

==== API:SECUOTP_SETUSERLOCK() ====

'''Prototype'''

<source lang="C">int secuotp_setuserlock(char *pszUsername, int nlock);</source>

'''Description'''

Lock a user

Remark: If nlock is set 1, then the user will be locked for 10 minutes

'''Parameters'''

PARAMETERS DESCRIPTION

* char *pszUsername [IN] Username
* int nlock [IN] lock (0-not locked 1-locked)

'''Return value'''

RETURN VALUE DESCRIPTION

* SECUOTP_ERROR_SUCCESS function called successfully

Others (See the error code list for more details) failed to call the function

==== API:SECUOTP_FREE() ====

'''Prototype'''

<source lang="C">void secuotp_free(void **psbuf);</source>

'''Description'''

Release the buffer (release the space created by the caller)

'''Parameters'''

PARAMETERS DESCRIPTION

* void **psbuf [IN] first address of the area that you want to release

'''Return value'''

none

==== API:SECUOTP_TOKENIMPORT() ====

'''Prototype'''

<source lang="C">
int secuotp_tokenimport(
char *pszTokenfile,
char *pszSecret,
char **pstrErrinfo
);
</source>

'''Description'''

Import tokens by batch

'''Parameters'''

PARAMETERS DESCRIPTION

* char *pszTokenfile [IN] Token file path
* char *pszSecret [IN] decryption secret key
* char *pstrErrinfo [OUT] invalid records occur in batch import

note: this function for internal using assigns space used for storing invalid record for the caller, when caller no longer uses the space, please use secuotp_free(void **psbuf) to release the space pointed by pstrErrinfo

'''Return Value'''

RETURN VALUE DESCRIPTION

* SECUOTP_ERROR_SUCCESS token batch import succeeded.
* SECUOTP_ERROR_SUCCESS_WITHINFO token batch import partially succeeded. (use pstrErrinfo to search for invalid entries)

Others (See the error code list for more details) token batch import failed

==== API:SECUOTP_USERIMPORT() ====

'''Prototype'''

<source lang="C">int secuotp_userimport(char *pszUserfile, char *pszSecret, char **pstrErrinfo);</source>

'''Description'''

User batch import

'''Parameters'''

PARAMETERS DESCRIPTION

* char *pszUserfile [IN] User file path
* char *pszSecret [IN] Decryption secret key
* char **pstrErrinfo [OUT] invalid records occur in batch import

note: this function for internal using assigns space used for storing invalid record for the caller, when caller no longer uses the space, please use secuotp_free(void **psbuf) to release the space pointed by pstrErrinfo

'''Return value'''

RETURN VALUE DESCRIPTION

* SECUOTP_ERROR_SUCCESS user batch import successful
* SECUOTP_ERROR_SUCCESS_WITHINFO user batch import partially succeeded. (use pstrErrinfo to search for invalid entries)

Others (See the error code list for more details) user batch import failed

==== API:SECUOTP_TOKENDELETE() ====

'''Prototype'''

<source lang="C">int secuotp_tokendelete(char *pszTokenserialnum);</source>

'''Description'''

Delete a token

'''Parameters'''

PARAMETERS DESCRIPTION

* char *pszTokenserialnum [IN] serial number of the token you want to delete

'''Return value'''

RETURN VALUE DESCRIPTION

* SECUOTP_ERROR_SUCCESS token deleted successfully

Others (See the error code list for more details) failed to delete the token

==== API:SECUOTP_MAKELOG() ====

'''Prototype'''

<source lang="C">int secuotp_makelog(int nLoglev, char *pszOperator, int nOptype, char *pszContent, char *pszSrvip);</source>

'''Description'''

write logs

'''Parameters'''

PARAMETERS DESCRIPTION

* int nLoglev [IN] logs level (1 or SECUOTP_PRI_SUPER super administrator level; 4 or SECUOTP_PRI_ADMIN administrator level; 10 or SECUOTP_PRI_OPERATOR operator level; 100 or SECUOTP_PRI_USER user level)
* char *pszOperator [IN] operator ID, if no user is authenticated, set the username.
* int nOptype [IN] operator type code (see operations list)
* char *pszContent [IN] logs contents
* char *pszSrvip [IN] IP address of the computer performing the operation, if the user is authenticated, set the IP address of the authenticated client.

'''Return value'''

RETURN VALUE DESCRIPTION

* SECUOTP_ERROR_SUCCESS log file written successfully

Others (See the error code list for more details) Failed to create log file

==== API:SECUOTP_REBIND() ====

'''Prototype'''

<source lang="C">int secuotp_rebind(const char *pszUsername, const char *pszNewserialnum);</source>

'''Description'''

Rebind a token to an user

'''Parameters'''

PARAMETERS DESCRIPTION

* const char *pszUsername [IN] Username
* const char *pszNewserialnum [IN] new token serial number used

'''Return value'''

RETURN VALUE DESCRIPTION

* SECUOTP_ERROR_SUCCESS token rebound successfully

Others (See the error code list for more details) Failed to rebind the token

==== Operation code list ====

{| class="wikitable" width="600"
|-
| '''Operation code'''
| '''Operation '''
|-
| 1
| User authentication
|-
| 11
| Add user
|-
| 12
| Delete user
|-
| 13
| Token synchronization
|-
| 15
| Set User static PIN
|-
| 16
| Set User authentication method
|-
| 17
| Set User usability
|-
| 18
| Set User lock
|-
| 23
| User batch import
|-
| 25
| Token batch import
|-
| 26
| Token deletion
|}

==== Error code list ====

{| class="wikitable" width="500"
|-
| '''Error code'''
| '''value'''
| '''meaning'''
|-
| SECUOTP_ERROR_SUCCESS
| 0
| success
|-
| SECUOTP_ERROR_ALLOCHANDLE_FAILED
| 11
| Failed to request ODBC source
|-
| SECUOTP_ERROR_FREEHANDLE_FAILED
| 12
| Failed to release ODBC source
|-
| SECUOTP_ERROR_SETENVATTR_FAILED
| 13
| Failed to set ODBC properties
|-
| SECUOTP_ERROR_GETCONFIGFAILED
| 14
| Failed to get setting information
|-
| SECUOTP_ERROR_CONNECTDBFAILED
| 15
| Failed to connect to the database
|-
| SECUOTP_ERROR_SQLEXFAILED
| 16
| Failed to execute SQL query
|-
| SECUOTP_ERROR_NORELATEITEM
| 17
| unrelated record
|-
| SECUOTP_ERROR_GETUSERINFO_FAILED
| 18
| Failed to get user information
|-
| SECUOTP_ERROR_USERREGLOST
| 19
| User token reported lost
|-
| SECUOTP_ERROR_USERLOCKED
| 20
| User is locked
|-
| SECUOTP_ERROR_UNLOCK_FAILED
| 21
| Failed to unlock the user
|-
| SECUOTP_ERROR_UPDATEUSEDATE_FAILED
| 22
| Failed to update operation time
|-
| SECUOTP_ERROR_UNKNOWNTKTYPE
| 23
| Unknown token type
|-
| SECUOTP_ERROR_UPCHALLENG_FAILED
| 24
| Failed to update user challenge information
|-
| SECUOTP_ERROR_INVALID_PASSWORD
| 25
| Authentication password error
|-
| SECUOTP_ERROR_SYNCHRONIZE_FAILED
| 26
| Synchronization failed
|-
| SECUOTP_ERROR_INVALID_OLDPWD
| 27
| Wrong old password
|-
| SECUOTP_ERROR_INVALID_AUTHTYPE
| 28
| Unable to use this authentication method
|-
| SECUOTP_ERROR_USEREXIST
| 29
| Username already exists
|-
| SECUOTP_ERROR_INVALID_TOKEN
| 30
| Invalid Token (the Token doesn’t exist, is already bound or is disabled.)
|-
| SECUOTP_ERROR_INVALID_PARAM
| 31
| Invalid parameters
|-
| SECUOTP_ERROR_ADDUSER_FAILED
| 32
| Failed to add user
|-
| SECUOTP_ERROR_UPDATETOKEN_FAILED
| 33
| Failed to update token state
|-
| SECUOTP_ERROR_DELETETOKEN_FAILED
| 34
| Failed to delete token
|-
| SECUOTP_ERROR_GETTOKENSTATE_FAILED
| 35
| Failed to get token state
|-
| SECUOTP_ERROR_TOKENINUSE
| 36
| Token is already bound
|-
| SECUOTP_ERROR_INVALIDKEY
| 37
| Invalid secret key
|-
| SECUOTP_ERROR_OPENTOKENFILE_FAILED
| 38
| Failed to open token file
|-
| SECUOTP_ERROR_AESMKKEY_FAILED
| 39
| AES process private key error
|-
| SECUOTP_ERROR_AESDECRYPT_FAILED
| 40
| Failed to decrypt file
|-
| SECUOTP_ERROR_AESGETPLAIN_FAILED
| 41
| Failed to read plain text
|-
| SECUOTP_ERROR_AUTHSUCCESS_WITHINFO
| 42
| Authentication succeeded but with warning message
|-
| SECUOTP_ERROR_UPDATEKEYINFO_FAILED
| 43
| Failed to upgrade counter
|-
| SECUOTP_ERROR_NOTNEEDSYNCHRONIZE
| 44
| Try to synchronize the challenge/response Token.
|-
| SECUOTP_ERROR_SETUSERPIN_FAILED
| 45
| Failed to set static PIN
|-
| SECUOTP_ERROR_UPDATEPIN_FAILED
| 46
| Failed to update static PIN
|-
| SECUOTP_ERROR_SUCCESS_WITHINFO
| 47
| Token/User batch import partially succeeded. There are some invalid records returned
|-
| SECUOTP_ERROR_OPENUSERFILE_FAILED
| 48
| Failed to open the user filefor batch import
|-
| SECUOTP_ERROR_GETFILESIZE_FAILED
| 49
| Failed to get the size of the file.
|-
| SECUOTP_ERROR_SRVIPNULL
| 50
| Client IP address error
|-
| SECUOTP_ERROR_GETERRINFOBUF_FAILED
| 51
| Failed to apply for space
|-
| SECUOTP_ERROR_GETFILECONT_FAILED
| 52
| Failed to get the file contents.
|-
| SECUOTP_ERROR_UPDATEUSERBINDINFO_FAILED
| 53
| Failed to rebind the token with the user
|-
| SECUOTP_ERROR_UPDATENEWTKSTATE_FAILED
| 54
| Failed to update the token state after rebinding
|-
| SECUOTP_ERROR_INVALIDLOGLEV
| 55
| Invalid log level
|-
| SECUOTP_ERROR_CHALLENGE
| 100
| Challenge error for the user requesting authentication
|}

==== Static data definition ====

{| class="wikitable" width="500"
|-
| '''Static data'''
| '''value'''
| '''meaning'''
|-
| MAX_PATH
| 260
| Path maximum length
|-
| MAXLEN_56
| 56
|
|-
| MAXLEN_32
| 32
|
|-
| MAXLEN_10
| 10
|
|-
| MAX_DATEBUF_LEN
| 56
| Maximum size for the buffer
|-
| COUNTER_SIZE
| 8
| Counter(number of bytes)
|}

== How to use PHP SDK ==

==== Preparation ====
1. Use the sql file inside the distributable package to create the database for UniOTP dynamic password authentication.
2. The PHP version SDK uses PHP to access to the database. Before beginning, we should make sure that the appropriate PHP database modules are running.
3. Create a configuration file (or modify the existing configuration file) and set the parameters to access the database.

==== Add support for UniOTP dynamic password ====
1. Add the SDK files (include otp_const.php, otp_corefunc.php, folder config, folder dbinterface and folder encrypt) to the project in which you want to implement dynamic password authentication.
2. Modify the configuration file.
3. Use the provided API to perform authentication related operations and others.

'''Call procedure'''

When you need to perform some business treatments, you just need to call the related API. (for details about calls, please see the sample)

'''Important points'''

1. You need to set the database type inside the configuration file. (This is because, depending on the database type, the connection interface used by the database is not the same)
2. Call the function secuotp_userimport($sUserfile, &$sErrinfo, $sSecret="") to perform batch import for user. If $sSecret value is not empty, this means that the file is encrypted. We recommend not to use file encryption feature.

==== API:SECUOTP_AUTH() ====

'''Prototype'''

<source lang="C">Function secuotp_auth($susername, $sPassword, &$challenge);</source>

'''Description'''

Dynamic password authentication.

'''Parameters'''

PARAMETERS DESCRIPTION

* $sUsername name of user to be authenticated
* $sPassword authentication password(OTP or OTP+PIN. Depends on the user’s
authentication mode)
* &$Challenge challenge number. if SECUOTP_ERROR_CHALLENGE is returned, challenge number will be set in $Challenge

'''Return value'''

RETURN VALUE DESCRIPTION

* SECUOTP_ERROR_SUCCESS authentication successful
* SECUOTP_ERROR_CHALLENGE a challenge should be sent to the user

Others: failed

==== API:SECUOTP_SYNCHRONIZE() ====

'''Prototype'''

<source lang="C">Function secuotp_synchronize($sUsername, $sOtp1, $sOtps)</source>

'''Description'''

Synchronize the token

'''Parameters'''

PARAMETERS DESCRIPTION

* $sUsername name of user whose token is to be synchronized
* $sOtp1 the first OTP
* $sOtp2 the second OTP

'''Return value'''

RETURN VALUE DESCRIPTION

* SECUOTP_ERROR_SUCCESS synchronized successfully

Others: failed

Remark: the two OTPs must be consecutive

==== API:SECUOTP_SETUSERPIN() ====

'''Prototype'''

<source lang="C">Function secuotp_setuserpin($sUsername, $sPin)</source>

'''Description'''

Set PIN for user

'''Parameters'''

PARAMETERS DESCRIPTION

* $sUsername user name
* $sPin PIN for $sUsername

'''Return value'''

RETURN VALUE DESCRIPTION

* SECUOTP_ERROR_SUCCESS New PIN set successfully

Others: failed

==== API:SECUOTP_RESETPIN() ====

'''Prototype'''

<source lang="C">Function secuotp_resetpin($sUsername, $sOldpin, $sNewpin)</source>

'''Description'''

Reset PIN

'''Parameters'''

PARAMETERS DESCRIPTION

* $sUsername Username of the user you want to reset the PIN for
* $sOldpin old PIN
* $sNewpin new PIN

'''Return value'''

RETURN VALUE DESCRIPTION

* SECUOTP_ERROR_SUCCESS PIN reset successfully

Others: failed

==== API:SECUOTP_SETAUTHTYPE() ====

'''Prototype'''

<source lang="C">Function secuotp_setauthtype($sUsername, $nAuthtype)</source>

'''Description'''

Set authentication type (1—use OTP only 2—user OTP+PIN)

'''Parameters'''

PARAMETERS DESCRIPTION

* $sUsername Username of the user you want to reset the PIN for
* $nAuthtype authentication type (1-OTP, 2-OTP+PIN)

'''Return value'''

RETURN VALUE DESCRIPTION

* SECUOTP_ERROR_SUCCESS Authentication type set successfully

Others: failed

==== API:SECUOTP_ADDUSER() ====

'''Prototype'''

<source lang="C">Function secuotp_adduser(
$sUsername,
$sUserid,
$sContacttel,
$sSerialnum,
$sRemark,
$sEmail,
$sDomain,
$sPin,
$sPreusedate,
$nAuthtype
)
</source>

'''Description'''

Add a new user

'''Parameters'''

PARAMETERS DESCRIPTION

* $sUsername username
* $sUserid identity number such as personal ID
* $sContacttel contact phone number
* $sSerialnum serial number of a usable token allocated to the user
* $sRemark remark
* $sEmail email address
* $sDomain reserved, you should set it null string(“”)
* $sPin static PIN
* $nAuthtype authentication type (1-OTP, 2-OTP+PIN)

'''Return value'''

RETURN VALUE DESCRIPTION

* SECUOTP_ERROR_SUCCESS User added successfully

Others: failed

==== API:SECUOTP_DELETEUSER() ====

'''Prototype'''

<source lang="C">Function secuotp_deleteuser($sUsername)</source>

'''Description'''

Delete a user

'''Parameters'''

PARAMETERS DESCRIPTION

* $sUsername username of user to be deleted

'''Return value'''

RETURN VALUE DESCRIPTION

* SECUOTP_ERROR_SUCCESS User deleted successfully

Others: failed

==== API:SECUOTP_SETUSERINVALID() ====

'''Prototype'''

<source lang="C">Function secuotp_setuserinvalid($nUsername, $nValid)</source>

'''Description'''

Set user validity status (0 valid, 1 invalid)

'''Parameters'''

PARAMETERS DESCRIPTION

* $sUsername username
* $nValid validity status (0 valid, 1 invalid)

'''Return value'''

RETURN VALUE DESCRIPTION

* SECUOTP_ERROR_SUCCESS Validity status set successfully

Others failed

==== API:SECUOTP_SETUSERLOCK() ====

'''Prototype'''

<source lang="C">Function secuotp_setuserlock($sUsername, $nLock)</source>

'''Description'''

Set user’s lock status

'''Parameters'''

PARAMETERS DESCRIPTION

* $sUsername username
* $nLock lock status (0 unlocked, 1 locked)

'''Return value'''

RETURN VALUE DESCRIPTION

* SECUOTP_ERROR_SUCCESS Lock status set successfully

Others: failed

Remark: If nLock is set to 1, the user will be locked for 10 minutes

==== API:SECUOTP_TOKENIMPORT() ====

'''Prototype'''

<source lang="C">Function secuotp_tokenimport($sTokenfile, $sSecret, &$sErrinfo)</source>

'''Description'''

Import token items into the UniOTP system

'''Parameters'''

PARAMETERS DESCRIPTION

* $sTokenfile token file path
* $sSecret decrypt share key
* &$sErrinfo error information. It often contains invalid token items if
* SECUOTP_ERROR_SUCCESS_WITHINFO is returned

'''Return value'''

RETURN VALUE DESCRIPTION

* SECUOTP_ERROR_SUCCESS Token imported successfully
* SECUOTP_ERROR_SUCCESS_WITHINFO the token file has some invalid
token item

Others: failed

==== API:SECUOTP_USERIMPORT() ====

'''Prototype'''

<source lang="C">Function secuotp_userimport($sUserfile, &$sErrinfo, $sSecret)</source>

'''Description'''

Batch user import

'''Parameters'''

PARAMETERS DESCRIPTION

* $sUserfile path of file which contains user items
* &$sErrinfo If SECUOTP_ERROR_SUCCESS_WITHINFO is returned, it contains the bad user items
* $sSecret decrypt secret, if a null string is given, the user file will be deal with as a plain text

'''Return value'''

RETURN VALUE DESCRIPTION

* SECUOTP_ERROR_SUCCESS User(s) imported successfully
* SECUOTP_ERROR_SUCCESS_WITHINFO The user file has some invalid user items. Invalid items have been stored in $sErrinfo

==== API:SECUOTP_TOKENDELETE() ====

'''Prototype'''

<source lang="C">Function secuotp_tokendelete($sTokenserialnum)</source>

'''Description'''

Remove a token from the database

'''Parameters'''

PARAMETERS DESCRIPTION

* $sTokenserialnum serial number of the token to be removed

'''Return value'''

PARAMETERS DESCRIPTION

* SECUOTP_ERROR_SUCCESS Token deleted from database successfully

Others: failed

==== API:SECUOTP_MAKELOG() ====

'''Prototype'''

<source lang="C">Function secuotp_makelog($nLoglev, $sOperator, $nOptype, $sContent, $sSrvip)</source>

'''Description'''

Add log information

'''Parameters'''

PARAMETERS DESCRIPTION

* $nLoglev log level (1 super administrator, 4 administrator, 10 operator,100 user)
* $sOperator operator id or name of user
* $nOptype operation type (see the operation type definition in file otp_const.php)
* $sContent log content
* $sSrvip IP address of operator’s computer or user’s computer

'''Return value'''

RETURN VALUE DESCRIPTION

* SECUOTP_ERROR_SUCCESS Log created successfully

Others: failed

==== API:SECUOTP_REBIND() ====

'''Prototype'''

<source lang="C">Function secuotp_rebind($sUsername, $sNewserialnum)</source>

'''Description'''

Allocated a new token to the user

'''Parameters'''

PARAMETERS DESCRIPTION

* $sUsername username
* $sNewserialnum new token serial number

'''Return value'''

RETURN VALUE DESCRIPTION

0 success

== How to use PHP Extension SDK ==

==== Preparation ====

# Use the SQL file inside the distributable package to create the database for the UniOTP dynamic password authentication system.
# Install the driver corresponding to the database you are using and choose to use this driver.
# Create an ODBC data source for the newly created database.
# Create a configuration file (or modify the existing configuration file) and define the database access settings.

==== Add support for UniOTP dynamic password ====

# Copy UniOTP SDK extension modules to the PHP extension modules directory.
# Modify the PHP configuration file and add support for UniOTP extension modules.
# Restart the server to enable extension modules.
# Modify the configuration file. the configuration file contains the database connection and authentication parameters.
# Use API to perform operations related to authentication.

'''Call procedure'''

# Call the function secuotp_initenv($Confpath) to initialize database settings.
# Use other interfaces to perform business-related operations.
# Call the function secuotp_cleanup() to perform cleaning operations such as releasing the memory.

'''Important points'''

# The first time you call functions from the SDK, you should first call the function secuotp_initenv($Confpath) to initialize database settings. You only need to call it once in each PHP page where you will use functions of the SDK.
# When you finish using the SDK, use secuotp_cleanup() to perform cleaning operations.

==== API:SECUOTP_INITENV() ====

'''Prototype'''

<source lang="C">function secuotp_initenv($Confpath);</source>

'''Description'''

Initialize configuration file. Only need to be called once.

'''Parameters'''

PARAMETERS DESCRIPTION

* $Confpath [IN] configuration file path

'''Return value'''

RETURN VALUE DESCRIPTION

0 success

Others: failure, use ErrorCode2Msg($index) to check the error.

==== API:SECUOTP_CLEANUP() ====

'''Prototype'''

<source lang="C">function secuotp_cleanup();</source>

'''Description'''

This function is in charge of freeing assigned global resources (apply initialization settings)

'''Parameters'''

None

'''Return value'''

RETURN VALUE DESCRIPTION

0 success

Others: failure, use ErrorCode2Msg($index) to check the error.

==== API:SECUOTP_GETLASTERROR() ====

'''Prototype'''

<source lang="C">function secuotp_getlasterror();</source>

'''Description'''

Return the last error message

'''Parameters'''

None

'''Return value'''

RETURN VALUE DESCRIPTION

0 success

Others: failure, use ErrorCode2Msg($index) to check the error.

==== API:SECUOTP_AUTH() ====

'''Prototype'''

<source lang="C">function secuotp_auth($Username, $Pwd, &$Challenge);</source>

'''Description'''

Dynamic password authentication

'''Parameters'''

PARAMETERS DESCRIPTION

* $Username [IN] Username
* $Pwd [IN] Authentication password for this time
* $Challenge [OUT] Use to save the challenge message returned by the server

'''Return value'''

RETURN VALUE DESCRIPTION

0 success

==== API:SECUOTP_SYNCHRONIZE() ====

'''Prototype'''

<source lang="C">function secuotp_synchronize($Username, $Otp1, $Otp2);</source>

'''Description'''

Synchronize the token

'''Parameters'''

PARAMETERS DESCRIPTION

* $Username [IN] Username
* $Otp1 [IN] For the synchronization to be completed, you need to provide 2
consecutive dynamic passwords. This parameter is the first of the two passwords $Otp2 [IN] The second of the two passwords

'''Return Value'''

RETURN VALUE DESCRIPTION

0 success

Others: failure, use ErrorCode2Msg($index) to check the error

==== API:SECUOTP_SETUSERPIN() ====

'''Prototype'''

<source lang="C">function secuotp_setuserpin($Username, $Pin);</source>

'''Description'''

Set the user PIN

'''Parameters'''

PARAMETERS DESCRIPTION

* $Username [IN] Username
* $Pin [IN] User PIN

'''Return Value'''

RETURN VALUE DESCRIPTION

0 success

Others: failure, use ErrorCode2Msg($index) to check the error

==== API:SECUOTP_RESETPIN() ====

'''Prototype'''

<source lang="C">function secuotp_resetpin($Username, $Oldpin, $Newpin);</source>

'''Description'''

Set a new PIN

'''Parameters'''

PARAMETERS DESCRIPTION

* $Username [IN] Username
* $Oldpin [IN] old PIN
* $Newpin [IN] new PIN

'''Return Value'''

RETURN VALUE DESCRIPTION

0 success

Others: failure, use ErrorCode2Msg($index) to check the error

==== API:SECUOTP_SETAUTHTYPE() ====

'''Prototype'''

<source lang="C">function secuotp_setauthtype($Username, $nAuthtype);</source>

'''Description'''

Set authentication type

'''Parameters'''

PARAMETERS DESCRIPTION

* $Username [IN] Username
* $nAuthtype [IN] Authentication type 1- Use only OTP to perform
authentication, 2- Use both OTP and PIN to perform authentication

'''Return Value'''

RETURN VALUE DESCRIPTION

0 success

Others: failure, use ErrorCode2Msg($index) to check the error

==== API:SECUOTP_ADDUSER() ====

'''Prototype'''

<source lang="C">function secuotp_adduser(
$Username,
$Userid,
$Contacttel,
$Serialnum,
$Remark,
$Email,
$Domain,
$Pin,
$Preusedate,
$nAuthtype
);
</source>

'''Description'''

Add a new user; this operation will bind a new user and a new token.

Remark: Before adding a user, make sure the token allocated to the user has been imported into the database using the function secuotp_tokenimport().

'''Parameters'''

PARAMETERS DESCRIPTION

* $Username [IN] Username
* $Userid [IN] User ID (Unique)
* $Contacttel [IN] User phone number
* $Serialnum [IN] Token serial number attributed to this user
* $Remark [IN] Remark/Comment
* $Email [IN]Email address
* $Domain [IN]Reserved, always NULL
* $Pin [IN]User PIN
* $Preusedate [IN]User registration date
* $nAuthtype [IN]Authentication type,1- only use OTP to perform
authentication 2- Use OTP+PIN to perform authentication.

Return value
RETURN VALUE DESCRIPTION

0 success

Others: failure, check error through ErrorCode2Msg($index)

==== API:SECUOTP_DELETEUSER() ====

'''Prototype'''

<source lang="C">function secuotp_deleteuser($Username);</source>

'''Description'''

Delete a user

'''Parameters'''

PARAMETERS DESCRIPTION

* $Username [IN] Username

'''Return value'''

RETURN VALUE DESCRIPTION

0 success

Others: failure, check error through ErrorCode2Msg($index)

==== API:SECUOTP_SETUSERINVALID() ====

'''Prototype'''

<source lang="C">function secuotp_setuserinvalid($Username, $nValid);</source>

'''Description'''

Set user validity status

'''Parameters'''

PARAMETERS DESCRIPTION

* $Username [IN] Username
* $ nValid [IN]User validity status 0-valid, 1-invalid

'''Return value'''

RETURN VALUE DESCRIPTION

0 success

Others: failure, check error through ErrorCode2Msg($index)

==== API:SECUOTP_SETUSERLOCK() ====

'''Protoype'''

function secuotp_setuserlock($Username, $nLock);

'''Description'''

Set the user lock state

Remark: If nLock has been set to 1, the user will be locked for 10 minutes.

'''Parameters'''

PARAMETERS DESCRIPTION

* $Username [IN] Username
* $nLock [IN]lock state (0-unlocked, 1-locked)

'''Return value'''

RETURN VALUE DESCRIPTION

0 success

Others: failure, check error through ErrorCode2Msg($index)

==== API:SECUOTP_TOKENIMPORT() ====

'''Prototype'''

<source lang="C">function secuotp_tokenimport($Tokenfile, $Secret, $invalid_items);</source>

'''Description'''

import token

'''Parameters'''

PARAMETERS DESCRIPTION

* $Tokenfile [IN]Token file path
* $Secret [IN] secret key used for decryption
* $invalid_items [OUT] invalid token record inside the token file

'''Return value'''

RETURN VALUE DESCRIPTION

0 success

Others: failure, check error through ErrorCode2Msg($index)

==== API:SECUOTP_USERIMPORT() ====

'''Prototype'''

<source lang="C">function secuotp_userimport($Userfile, $Secret, $invalid_items);</source>

'''Description'''

User import

'''Parameters'''

PARAMETERS DESCRIPTION

* $Userfile [IN] User file
* $Secret [IN] Decryption secret key, let empty if the file is not encrypted
* $invalid_items [OUT] invalid token record inside the user file

'''Return value'''

RETURN VALUE DESCRIPTION

0 success

Others: failure, check error through ErrorCode2Msg($index)

==== API:SECUOTP_TOKENDELETE() ====

'''Prototype'''

<source lang="C">function secuotp_tokendelete($Tokenserialnum);</source>

'''Description'''

Delete a token

'''Parameters'''

PARAMETERS DESCRIPTION

* $Tokenserialnum [IN] token that you want to delete

'''Return value'''

RETURN VALUE DESCRIPTION

0 success

Others: failure, check error through ErrorCode2Msg($index)

==== API:SECUOTP_MAKELOG() ====

'''Prototype'''

<source lang="C">function secuotp_makelog($nLoglev, $pszOperator, $nOptype, $pszContent, $pszSrvip);</source>

'''Description'''

Write logs

'''Parameters'''

PARAMETERS DESCRIPTION

* $nLoglev [IN]logs level .The following values are usable: 1 (super administrator), 2 (administrator), 3 (operator), 4 (user)
* $pszOperator [IN]Operator
* $nOptype [IN]Operation type
* $pszContent [IN]logs data
* $pszSrvip [IN]Server IP

'''Return value'''

RETURN VALUE DESCRIPTION

0 success

Others: failure, check error through ErrorCode2Msg($index)

==== API:SECUOTP_REBIND() ====

'''Prototype'''

<source lang="C">function secuotp_rebind($Username, $Newtokenserial);</source>

'''Description'''

Rebind a token with a user

'''Parameters'''

PARAMETERS DESCRIPTION

* $Username [IN] Username
* $Newtokenserial [IN]New Token serial number

'''Return value'''

RETURN VALUE DESCRIPTION

0 success

Others: failure, check error through ErrorCode2Msg($index)

UniToken Integration Guide Windows XP Client Smart Card Configuration

2016-08-23T06:08:42Z

Bao:

[[Category:UniToken_Integration_Guide]]

== Configure Windows XP to join your Windows Domain ==

Please note that the following guide requires the configured computer to be Windows XP Professional to be able to join a Windows domain. From the Start Menu, right-click on [My Computer] select [Properties].

[[Image:tokensmart img63.jpg|370px]]

In the "System Properties" window, under the tab "Computer Name", click on [Change]

[[Image:tokensmart img64.jpg|370px]]

Below "Member of" in the field "Domain", input the name of your Windows domain to join. In this example, 'secutech' was entered. Click on [OK] to continue.

[[Image:tokensmart img65.jpg|370px]]

A pop-up window will appear asking to enter the name and password of the account to join the domain with. Input the corresponding username and the password for the user account and click [OK] to continue.

[[Image:tokensmart img66.jpg|370px]]

The confirmation window containing the message [Welcome to (domain name) domain.] will appear when joining the domain was successful.

[[Image:tokensmart img67.jpg|370px]]

To apply the new settings, it is necessary to restart the computer.

[[Image:tokensmart img68.jpg|370px]]

== Install the PKI Package ==

This section explains how to install the PKI package that can be found inside the UniToken SDK. The End User package can be found inside the folder "Redist/Enduser/". First, ensure the account logged into the computer is the same as the above connected to the Windows domain.
Right-click on the PKI package installation file and choose [Run as...].

[[Image:tokensmart img69.jpg|370px]]

Execute the file with an account that has administrator rights on the computer.

[[Image:tokensmart img70.jpg|370px]]

Click on [Next] in the InstallShield Wizard welcome screen.

[[Image:tokensmart img71.jpg|370px]]

Input your User Name and Company Name and click on [Next].

[[Image:tokensmart img72.jpg|370px]]

Select [Complete] and click on [Next].

[[Image:tokensmart img73.jpg|370px]]

Click on [Install] to begin the installation of the PKI package.

[[Image:tokensmart img74.jpg|370px]]

A "Hardware Installation" warning message will appear, asking to confirm installing "UniToken Virtual Reader". Click on [Continue Anyway] to continue the installation.

[[Image:tokensmart img75.jpg|370px]]

Verify that the InstallShield Wizard completed successfully and click on [Finish].

[[Image:tokensmart img76.jpg|370px]]

== Request and Install the Certificate from the CA ==

Launch your internet browser of your choice and navigate to "https://[address of domain server]/certsr". Input your username and password to log in when requested.

[[Image:tokensmart img77.jpg|370px]]

On the "Microsoft Active Directory Certificate Services" main page, under "Select a task", click on [Request a certificate].

[[Image:tokensmart img78.jpg|370px]]

Under "Request a certificate", click on [advanced certificate request].

[[Image:tokensmart img79.jpg|370px]]

Under "Advanced Certificate Request" on the page, select [Create and submit a request to this CA].

[[Image:tokensmart img80.jpg|370px]]

Under the subheading "Key Options" on the "Advanced Certificate Request" page, select [Smartcard User] from the drop-down list for "Certificate Template", and [UniToken PRO CSP v2.0] from the drop-down list for "CSP". Continue with the default settings and click on [Submit] to apply for the certificate.

[[Image:tokensmart img81.jpg|370px]]

A "Web Access Confirmation" warning message will appear, asking to confirm the operation. Click on [Yes] to continue.

[[Image:tokensmart img82.jpg|370px]]

A window requesting the PIN for the UniToken device will appear. Input the User PIN and click on [OK] to continue.

[[Image:tokensmart img83.jpg|370px]]

Click on [Install this certificate] on the "Certificate Issued" page to install the certificate within the token.

[[Image:tokensmart img84.jpg|370px]]

Click on [Yes] when the warning message [Do you want to allow the actions performed by this website] appears.

[[Image:tokensmart img85.jpg|370px]]

The "Certificate Installed" page will appear when the installation is complete.

[[Image:tokensmart img86.jpg|370px]]

== Configure Smart Card Logon ==

In the start menu, click on [Run].

[[Image:tokensmart img87.jpg|370px]]

Input "gpedit.msc", without the quotation marks, in "Open" and click [OK].

[[Image:tokensmart img89.jpg|370px]]

On the [Group Policy] page, in [Computer Configuration], [Windows Settings], [Security Settings],[Local Policies], [Security Options], right-click on [Interactive Logon: Requires smart card] and select [Properties].

[[Image:tokensmart img90.jpg|370px]]

Under the [Local Security Setting] tab, select [Enabled] and click on [OK] to apply.

[[Image:tokensmart img91.jpg|370px]]

In the same directory, right-click [Interactive logon: Smart card removal behavior] and select [properties]

[[Image:tokensmart img92.jpg|370px]]

Under the [Local Security Setting] tab, select the action to perform when the UniToken device is removed from the computer, then click on [OK] to apply.

[[Image:tokensmart img93.jpg|370px]]

UniToken Integration Guide Windows 7 Client Smart Card Configuration

2016-08-23T06:08:05Z

Bao:

[[Category:UniToken_Integration_Guide]]

== Configure Windows 7 to join your Windows Domain ==

Please note that the following guide requires the configured computer to be Windows 7 Professional or a higher edition to be able to join a Windows domain.

From the Start Menu, right-click on [My Computer] and select [Properties].

[[Image:tokensmart img94.jpg|370px]]

Under the subheading "Computer name, domain, and workgroup settings" near the bottom right of the window, click on [Change settings].

[[Image:tokensmart img95.jpg|370px]]

Under the tab "Computer name" in the "System Properties" window, click on [Change].

[[Image:tokensmart img96.jpg|370px]]

Below "Member of" in the field "Domain", input the name of your Windows domain to join. In this example, 'secutech' was entered. Click on [OK] to continue.

[[Image:tokensmart img97.jpg|370px]]

A pop-up window will appear asking to enter the name and password of the account to join the domain with. Input the corresponding username and the password for the user account and click [OK] to continue.

[[Image:tokensmart img98.jpg|370px]]

The confirmation window containing the message [Welcome to (domain name) domain.] will appear when joining the domain was successful.

[[Image:tokensmart img99.jpg|370px]]

To apply the new settings, it is necessary to restart the computer.

[[Image:tokensmart img100.jpg|370px]]

== Install the PKI Package ==

This section explains how to install the PKI package that can be found inside the UniToken SDK. The End User package can be found inside the folder "Redist/Enduser/". First, ensure the account logged into the computer is the same as the above connected to the Windows domain. Right-click on the PKI package installation file and choose [Run as administrator].

[[Image:tokensmart img101.jpg|370px]]

Click on [Next] in the InstallShield Wizard welcome screen.

[[Image:tokensmart img102.jpg|370px]]

Input your User Name and Company Name and click on [Next].

[[Image:tokensmart img103.jpg|370px]]

Select [Complete] and click on [Next].

[[Image:tokensmart img104.jpg|370px]]

Click on [Install] to begin the installation of the PKI package.

[[Image:tokensmart img105.jpg|370px]]

Verify that the InstallShield Wizard completed successfully and click on [Finish].

[[Image:tokensmart img106.jpg|370px]]

== Request and Install the Certificate from the CA ==

Launch Internet Explorer and navigate to "https://[address of domain server]/certsr".

E.g. The URL "https://192.168.1.229/certsrv", without the quotation marks, was entered in this example.

[[Image:tokensmart img107.jpg|370px]]

Input your username and password to log in when requested.

[[Image:tokensmart img108.jpg|370px]]

On the "Microsoft Active Directory Certificate Services" main page, under "Select a task", click on [Request a certificate].

[[Image:tokensmart img109.jpg|370px]]

Under "Request a certificate", click on [advanced certificate request].

[[Image:tokensmart img110.jpg|370px]]

Under "Advanced Certificate Request" on the page, select [Create and submit a request to this CA].

[[Image:tokensmart img111.jpg|370px]]

A "Web Access Confirmation" warning message will appear, asking to confirm the operation. Click on [Yes] to continue.

[[Image:tokensmart img112.jpg|370px]]

Under the subheading "Key Options" on the "Advanced Certificate Request" page, select [Smartcard User] from the drop-down list for "Certificate Template", and [UniToken PRO CSP v2.0] from the drop-down list for "CSP". Continue with the default settings and click on [Submit] to apply for the certificate.

[[Image:tokensmart img113.jpg|370px]]

A window requesting the PIN for the UniToken device will appear. Input the User PIN and click on [OK] to continue.

[[Image:tokensmart img114.jpg|370px]]

A "Web Access Confirmation" warning message will appear, asking to confirm the operation. Click on [Yes] to continue.

[[Image:tokensmart img115.jpg|370px]]

Click on [Install this certificate] on the "Certificate Issued" page to install the certificate within the token.

[[Image:tokensmart img116.jpg|370px]]

The "Certificate Installed" page will appear when the installation is complete.

[[Image:tokensmart img117.jpg|370px]]

== Configure Smart Card Logon ==

In the start menu, type "gpedit.msc", without the quotation marks, in the search field, and right-click on "gpedit" and select [Run as administrator].

[[Image:tokensmart img118.jpg|370px]]

On the [Group Policy] page, in [Computer Configuration], [Windows Settings], [Security Settings],[Local Policies], [Security Options], right-click on [Interactive Logon: Requires smart card] and select [Properties].

[[Image:tokensmart img119.jpg|370px]]

Under the [Local Security Setting] tab, select [Enabled] and click on [OK] to apply.

[[Image:tokensmart img120.jpg|370px]]

In the same directory, right-click [Interactive logon: Smart card removal behavior] and select [properties]

[[Image:tokensmart img121.jpg|370px]]

Under the [Local Security Setting] tab, select the action to perform when the UniToken device is removed from the computer, then click on [OK] to apply.

[[Image:tokensmart img122.jpg|370px]]

UniToken Integration Guide Windows 2008 Server Smart Card Configuration

2016-08-23T06:07:28Z

Bao:

[[Category:UniToken Integration Guide]]

== Network Configuration ==

From the Start Menu, and click on [Server Manager].

[[Image:tokensmart img01.jpg|370px]]

Click on [View Network Connections]on the right-hand side of the window under "Server Summary", "Computer Information".

[[Image:tokensmart img02.jpg|370px]]

Right-click on the connection interface used between clients and the server and select [Properties].

[[Image:tokensmart img03.jpg|370px]]

In the properties window of the connection, highlight [Internet Protocol (TCP/IPv4)] and click on [Properties] below.

[[Image:tokensmart img04.jpg|370px]]

In the "Internet Protocol Version 4 (TCP/IPv4) Properties" window, select [Use the following IP address] and input a static IP address, subnet mask and default gateway for your server.

Select [Use the following DNS server addresses] and input the same IP address as your static IP address. This server will be used as the main DNS server.

Click on [OK] on all windows to finish.

[[Image:tokensmart img05.jpg|370px]]

== Active Directory Installation ==

From the Start Menu, click [Run...] or in the search box from the Start Menu, type "dcpromo", without quotation marks, and press [Enter].

[[Image:tokensmart img06.jpg|370px]]

Wait while the binaries for Active Directory Services are being installed.

[[Image:tokensmart img07.jpg|370px]]

On the "Active Directory Domain Services Installation Wizard" welcome screen, click on [Next].

[[Image:tokensmart img08.jpg|370px]]

On "Operating System Compatibility" step, click on [next].

[[Image:tokensmart img09.jpg|370px]]

On the "Choose a Deployment Configuration" step, verify that [Create a new domain in a new forest] is selected and click [Next].

[[Image:tokensmart img10.jpg|370px]]

On the "Name the Forest Root Domain" step, input a name for the domain and click on [Next].

[[Image:tokensmart img11.jpg|370px]]

On the "Set Forest Functional Level" step, keep the default settings and click on [Next].

[[Image:tokensmart img12.jpg|370px]]

On the following "Set Forest Functional Level" step, keep the default settings and click on [Next].

[[Image:tokensmart img13.jpg|370px]]

In the screen [Additional Domain Controller Options], check the option [DNS Server] and click on [Next]

[[Image:tokensmart img14.jpg|370px]]

In the dialog box "Active Directory Domain Services Installation Wizard", click on [Yes] when asked "Do you want to continue?" to continue.

Please note, in this tutorial, we are assuming the preferred DNS on the local network is our server and that DNS information is distributed to clients by the DHCP service installed on this server.

[[Image:tokensmart img15.jpg|370px]]

On the "Location for Database, Log Files, and SYSVOL" step, click on [Next].

[[Image:tokensmart img16.jpg|370px]]

On the "Directory Service Restore Mode Administrator Password" ste[, set the password for the administrator of restore mode and click on [Next].

[[Image:tokensmart img17.jpg|370px]]

In the "Summary" screen , verify the settings up to now are correct, then click [Next] to continue.

[[Image:tokensmart img18.jpg|370px]]

Wait until the configuration of Active Directory is completed.

[[Image:tokensmart img19.jpg|370px]]

Click [Finish] to close the wizard.

[[Image:tokensmart img20.jpg|370px]]

== Certification Authority Installation ==

From the Start Menu, click on [Server Manager].

[[Image:tokensmart img21.jpg|370px]]

From the left-hand side pane, click on [Roles].

[[Image:tokensmart img22.jpg|200px]]

In the right-hand side of the window, click on [Add Roles].

[[Image:tokensmart img23.jpg|370px]]

Click [Next] on the screen [Before You Begin] to begin.

[[Image:tokensmart img24.jpg|370px]]

On the "Select Server Roles" step, select [Active Directory Certificate Services], then click [Next].

[[Image:tokensmart img25.jpg|370px]]

On the "Introduction to Active Directory Certificates Services" page, click on [Next]

[[Image:tokensmart img26.jpg|370px]]

On the "Select Role Services" page, check [Certification Authority] and [Certification Authority Web Enrollment], then click [Next].

[[Image:tokensmart img27.jpg|370px]]

In the "Add Roles Wizard" dialog box, click on [Add Required Role Services].

[[Image:tokensmart img28.jpg|370px]]

Make sure that [Certification Authority Web Enrollment] and click on [Next].

[[Image:tokensmart img29.jpg|370px]]

On the "Specify Setup Type" page, select [Enterprise], then click [Next].

[[Image:tokensmart img30.jpg|370px]]

On the "Specify CA Type" page, select [Root CA], and click [Next].

[[Image:tokensmart img31.jpg|370px]]

On the "Set Up Private Key" page, click [Next].

[[Image:tokensmart img32.jpg|370px]]

On the "Configure Cryptography for CA" page, click [Next].

[[Image:tokensmart img33.jpg|370px]]

On the "Configure CA Name" page, accept the proposed CA Name or otherwise input a new CA name. Click on [Next].

[[Image:tokensmart img34.jpg|370px]]

On the "Set Validity Period" page, click on [Next].

[[Image:tokensmart img35.jpg|370px]]

On the "Configure Certificate Database" page, click on [Next].

[[Image:tokensmart img36.jpg|370px]]

On the "Web Server(IIS)" page, click on [Next]

[[Image:tokensmart img37.jpg|370px]]

On the "Select Role Services", verify that the required services have been selected and click on [Next].

[[Image:tokensmart img38.jpg|370px]]

On the "Confirm Installation Selections" page, verify installation information is correct, then click on [Install] to begin the installation.

[[Image:tokensmart img39.jpg|370px]]

On the "Installation Results" page, verify that the installation has been completed successfully, then click on [Close] to complete.

[[Image:tokensmart img40.jpg|370px]]

== Secure Access to Certsrv with SSL ==

From the Start Menu, click [Administrative Tools], [Internet Information Services (IIS) Manager].

[[Image:tokensmart img41.jpg|370px]]

In the left pane, select the corresponding server under "Connection", then in the main window double-click on [Server Certificates].

[[Image:tokensmart img42.jpg|370px]]

On the [Server Certificates] page, from the "Actions" menu on the right, click on [Create Self-Signed Certificate...].

[[Image:tokensmart img43.jpg|370px]]

In the "Create Self-Signed Certificate" window, on the "Specify Friendly Name" step, enter a name for the certificate and click on [OK].

[[Image:tokensmart img44.jpg|370px]]

In the left pane, under "Sites", right-click on [Default Web Site] and click [Edit Bindings...].

[[Image:tokensmart img45.jpg|370px]]

On the [Site Bindings] window, click [Add].

[[Image:tokensmart img46.jpg|370px]]

Modify the following settings:

* Type: https
* IP address: All Unassigned
* Port: 443
* Certificate: (the certificate created earlier)

Click [OK].

[[Image:tokensmart img47.jpg|370px]]

Click on [CertSrv] within [Default Web Site] from the left pane. Double-click on [SSL settings].

[[Image:tokensmart img48.jpg|370px]]

On the "SSL Settings" page, check [Require SSL] and [Require 128-bit SSL]. Under "Client certificates", select [Ignore] and click on [Apply] to save changes.

[[Image:tokensmart img49.jpg|370px]]

== Create Users in Active Directory ==

From the Start Menu, click [Administrative tools], [Active directory Users and Computers].

[[Image:tokensmart img50.jpg|370px]]

From the tree list on the left under the "Active Directory Users and Computers" window, right click on [(Domain)], [Users], then from the popup menu [New], [User].

[[Image:tokensmart img51.jpg|370px]]

Complete the form on the new user and click [Next].

[[Image:tokensmart img52.jpg|370px]]

Fill in the [Password] and [Confirm password] fields. Choose the corresponding options as needed and click on [Next].

[[Image:tokensmart img53.jpg|370px]]

Verify information about the new user is correct and click [Finish] to close the window.

[[Image:tokensmart img54.jpg|370px]]

== Set Access Rights for Certificate Templates ==

From the Start Menu, click [Run...] or in the search box from the Start Menu, type "certtmpl", without quotation marks, and press [Enter].

[[Image:tokensmart img55.jpg|370px]]

In the "Certificate Templates Console" window, right-click [Smartcard User] from the list on the right and click [Properties].

[[Image:tokensmart img56.jpg|370px]]

Under the [Security] tab, click on [Add] to add a new user to the list.

[[Image:tokensmart img57.jpg|370px]]

Select the user previously created (UniTokenPRO in this example) and click [OK] to apply.

[[Image:tokensmart img58.jpg|370px]]

Back on the [Security] tab, select the newly added user and check [Read] and [Enroll] for the user's permissions. Click on [OK] to finish.

[[Image:tokensmart img59.jpg|370px]]

From the Start Menu, click on [Administrative Tools], [Certification Authority].

[[Image:tokensmart img60.jpg|370px]]

On the "Certification Authority" window, right-click on [Certificate Template], and select [New], [Certificate Template to Issue].

[[Image:tokensmart img61.jpg|370px]]

Under the "Enable Certificate Templates" window, select [Smartcard User] and click [OK] to finish.

[[Image:tokensmart img62.jpg|370px]]

UniToken Integration Guide Windows 2003 Server Smart Card Configuration

2016-08-23T06:07:02Z

Bao:

[[Category:UniToken Integration Guide]]

== Network Configuration ==

From the Start Menu, click on [Connect To], [Show all connections].

[[Image:tokensmart img123.jpg|370px]]

Right-click on the connection interface between the domain controller and client and select [Properties].

[[Image:tokensmart img124.jpg|370px]]

In the properties window of the connection, select [Internet Protocol (TCP/IP)] and click on [Properties].

[[Image:tokensmart img125.jpg|370px]]

In the "Internet Protocol Version 4 (TCP/IPv4) Properties" window, select [Use the following IP address] and input a static IP address, subnet mask and default gateway for your server.

Select [Use the following DNS server addresses] and input the same IP address as your static IP address. This server will be used as the main DNS server.

Click on [OK] on all windows to finish.

[[Image:tokensmart img126.jpg|370px]]

== Active Directory Installation ==

From the start menu, click on “Run...”

[[Image:tokensmart img127.jpg|370px]]

Input "dcpromo", without quotation marks, and click [OK] to launch the Active Directory wizard.

[[Image:tokensmart img128.jpg|370px]]

On the "Active Directory Installation Wizard" welcome screen, click on [Next].

[[Image:tokensmart img129.jpg|370px]]

On the "Operating System Compatibility" page, click on [Next].

[[Image:tokensmart img130.jpg|370px]]

On the "Domain Controller Type" page, verify that [Controller for a new domain] is selected, then click [Next].

[[Image:tokensmart img131.jpg|370px]]

On the "Create New Domain" page, verify that [Domain in a new forest] is selected, then click [Next].

[[Image:tokensmart img132.jpg|370px]]

On the [New Domain Name] page, input a name for your domain, then click [Next].

[[Image:tokensmart img133.jpg|370px]]

On the "NetBIOS Domain Name" page, input a NetBIOS name or otherwise leave the suggested name, then click on [Next].

[[Image:tokensmart img134.jpg|370px]]

On the "Database and Log Folders" page, click on [Next].

[[Image:tokensmart img135.jpg|370px]]

On the "Shared System Volume" page, click on [Next].

[[Image:tokensmart img136.jpg|370px]]

On the [DNS Registration Diagnostics] page, select [Install and configure the DNS server on this computer, and set this computer to use this DNS server as its preferred DNS server], then click on [Next].

[[Image:tokensmart img137.jpg|370px]]

On the "Permissions" page, select [Permissions compatible only with Windows 2000 or Windows Server 2003], then click on [Next].

[[Image:tokensmart img138.jpg|370px]]

On the "Directory Service Restore Mode Administrator Password" page, input a restore mode password, then click on [Next].

[[Image:tokensmart img139.jpg|370px]]

On the "Summary" page, confirm the entered settings, then click on [Next].

[[Image:tokensmart img140.jpg|370px]]

After the configuration of Active Directory is completed, the Windows Server 2003 CD-ROM is required to complete the procedure.

[[Image:tokensmart img141.jpg|370px]]

Verify that the Active Directory has been installed successfully, then click on [Finish] to close the wizard.

[[Image:tokensmart img142.jpg|370px]]

== IIS Installation ==

From the Start Menu, click on [Control Panel], [Add or Remove Programs].

[[Image:tokensmart img143.jpg|370px]]

Under the "Add or Remove Programs" window, choose [Add/Remove Windows Components] from the left-hand side menu.

[[Image:tokensmart img144.jpg|370px]]

Check [Application Server] and click on [Next].

[[Image:tokensmart img145.jpg|370px]]

Verify the installation was successful after completion.

[[Image:tokensmart img146.jpg|370px]]

== Certification Authority Installation ==

If continuing from the previous step, return to the "Add/Remove Windows Components" window. Otherwise, from the Start Menu, click on [Control Panel], [Add or Remove Programs], then choose [Add/Remove Windows Components] from the left-hand side menu.

In the "Add/Remove Windows Components" window, check [Certificate Services]. A warning message indicating the computer name and domain may not be changed once Certificate Services is installed will appear. Click [Yes] to continue.

[[Image:tokensmart img147.jpg|370px]]

Verify that [Certificate Services] has been checked, and click on [Next].

[[Image:tokensmart img148.jpg|370px]]

In the "CA Type" step, select [Enterprise root CA], then click on [Next].

[[Image:tokensmart img149.jpg|370px]]

In the "CA Identifying Information" step, input the name for the CA in the field [Common name for this CA], and check that [Distinguish name suffix] corresponds to the domain name. Click on [Next] when done.

[[Image:tokensmart img150.jpg|370px]]

On the "Certificate Database Settings" page, click on [Next]

[[Image:tokensmart img151.jpg|370px]]

During the installation, a warning message indicating the IIS service must be stopped temporarily will be displayed. Click on “Yes” to continue the installation.

[[Image:tokensmart img152.jpg|370px]]

The installation changes will be applied.

[[Image:tokensmart img153.jpg|370px]]

A warning message asking if Active Server Pages is to be enabled will appear. Click on [Yes] to continue.

[[Image:tokensmart img154.jpg|370px]]

Verify that the component has been installed successfully and click on [Finish] to close the wizard.

[[Image:tokensmart img155.jpg|370px]]

== Update CertSrv for Windows Vista/7 ==

An update available from Microsoft configures the CA web interface to be resolve an issue with enrolling web certificates against a Windows Server 2003 Certificate Services Web enrollment, and improves the CA's compatibility with Windows XP to Windows Vista and 7. The file can be downloaded from https://www.microsoft.com/en-us/download/details.aspx?id=4758.

Back up your data before installing this update! SecuTech cannot be held as responsible for any data loss caused by this update.

Double-click the downloaded file to launch the installation.

[[Image:tokensmart img156.jpg|170px]]

Click on [Next] in the "Software Update Installation Wizard" screen.

[[Image:tokensmart img157.jpg|370px]]

On the [License Agreement] step, select [I agree] and click on [Next] to continue.

[[Image:tokensmart img158.jpg|370px]]

Changes will be applied.

[[Image:tokensmart img159.jpg|370px]]

Verify that the update has been successfully installed and click on [Finish] to complete.

[[Image:tokensmart img160.jpg|370px]]

== Secure Access to Certsrv with SSL ==

From the Start Menu, click on [Administrative Tools], [Internet Information Services (IIS) Manager].

[[Image:tokensmart img161.jpg|370px]]

In the "Internet Information Services (IIS) Manager" window, navigate to [Web Sites], [Default Website] in the tree list on the left. Right-click on [Default Website], then click on [Properties].

[[Image:tokensmart img162.jpg|370px]]

Under the [Directory Security] tab, in the [Secure communications] section, click on [Server Certificate].

[[Image:tokensmart img163.jpg|370px]]

Click on [Next] in the Web Server Certificate Wizard to begin.

[[Image:tokensmart img164.jpg|370px]]

On the "Server Certificate" page, select [Create a new certificate], then click on [Next].

[[Image:tokensmart img165.jpg|370px]]

In the "Delayed or Immediate Request" step, select [Prepare the request now, but send it later] and click on [Next].

[[Image:tokensmart img166.jpg|370px]]

On the "Name and Security Settings" page, enter the name of the certificate, then click on [Next].

[[Image:tokensmart img167.jpg|370px]]

On the "Organization Information" step, input the organization and organizational unit information and click on [Next].

[[Image:tokensmart img168.jpg|370px]]

In the "Your Site's Common Name" step, input the name of your website and click on [Next].

[[Image:tokensmart img169.jpg|370px]]

Input the [Country/region], [State/province], [City/locality] and click on [Next].

[[Image:tokensmart img170.jpg|370px]]

Indicate the certificate request file path and name in the "Certificate Request File Name" page. Click on [Next] afterwards.

[[Image:tokensmart img171.jpg|370px]]

On the "Request File Summary" page, verify the information is correct, then click on [Next].

[[Image:tokensmart img172.jpg|370px]]

Click on [Finish] to complete the wizard.

[[Image:tokensmart img173.jpg|370px]]

Launch your internet browser of your choice and navigate to "https://[address of domain server]/certsr".

[[Image:tokensmart img174.jpg|370px]]

On the "Microsoft Active Directory Certificate Services" main page, under "Select a task", click on [Request a certificate]. Under "Request a certificate", click on [advanced certificate request].

[[Image:tokensmart img175.jpg|370px]]

On the page “Advanced Certificate Request”, choose [Submit a certificate request by using a base 64 encoded CMC or PKCS#10 file, or submit a renewal request by using a base 64 encoded CMC or PKCS#7 file]

[[Image:tokensmart img176.jpg|370px]]

Navigate to the folder where the "certreq.txt" file is located and open it.

[[Image:tokensmart img177.jpg|370px]]

Excluding the first and last line, copy the whole contents of "certreq.txt" and paste it in the corresponding text area in the web page.

[[Image:tokensmart img178.jpg|370px]]

Under "Certificate Template", choose [Web server] from the drop-down list and click on [Submit].

[[Image:tokensmart img179.jpg|370px]]

Select [DER encoded] and click on [Download certificate].

[[Image:tokensmart img180.jpg|370px]]

Save the file [certnew.cer] to a destination for later use.

[[Image:tokensmart img181.jpg|370px]]

Return to the [Default Web Site Properties] window, and click on [Server Certificate] under "Secure communications".

[[Image:tokensmart img182.jpg|370px]]

Under the "Welcome to the Web Server Certificate Wizard" welcome screen, click [Next].

[[Image:tokensmart img183.jpg|370px]]

On the "Pending Certificate Request" step, select [Process the pending request and install the certificate].

[[Image:tokensmart img184.jpg|370px]]

On the "Process a Pending Request" step, check or otherwise enter the path to the "certnew.cer" file created eariler. Click on [Next].

[[Image:tokensmart img185.jpg|370px]]

On the [SSL Port] step, check the correct SSL port used on the server is correct and click on [Next].

[[Image:tokensmart img186.jpg|370px]]

Click on [Finish] to complete the wizard.

[[Image:tokensmart img187.jpg|370px]]

Return to the [Internet Information Service (IIS) Manager] window and expand [Default Web Site], right-click on the element [CertSrv], and select [Properties].

[[Image:tokensmart img188.jpg|370px]]

In the tab [Directory Security], click on the [Edit…] button located under "Secure communications."

[[Image:tokensmart img189.jpg|370px]]

In the [Secure Communications] window, check [Require secure channel (SLL)] and [Require 128-bit encryption]. Verify that [Ignore client certificates] is selected under "Client certificates" and select [Enable client certificate mapping]. Click [OK] to finish.

[[Image:tokensmart img190.jpg|370px]]

== Create Users in Active Directory ==

From the Start Menu, click [Administrative tools], [Active directory Users and Computers].

[[Image:tokensmart img191.jpg|370px]]

From the tree list on the left under the "Active Directory Users and Computers" window, right click on [(Domain)], [Users], then from the popup menu [New], [User].

[[Image:tokensmart img192.jpg|370px]]

Complete the form on the new user and click [Next].

[[Image:tokensmart img193.jpg|370px]]

Fill in the [Password] and [Confirm password] fields. Choose the corresponding options as needed and click on [Next].

[[Image:tokensmart img194.jpg|370px]]

Verify information about the new user is correct and click [Finish] to close the window.

[[Image:tokensmart img195.jpg|370px]]

== Set Access Rights for Certificate Templates ==

From the start menu, select [Run...].

[[Image:tokensmart img196.jpg|370px]]

Type "certtmpl.msc", without quotation marks, then click [OK].

[[Image:tokensmart img197.jpg|370px]]

On the "certtmpl - [Certificate Templates}" window, right-click [Smartcard User] from the list on the right and select [Properties].

[[Image:tokensmart img198.jpg|370px]]

Under the [Security] tab, click on [Add] to add a new user to the list.

[[Image:tokensmart img199.jpg|370px]]

Select the user previously created (UniTokenPRO in this example) and click [OK] to apply.

[[Image:tokensmart img200.jpg|370px]]

Back on the [Security] tab, select the newly added user and check [Read] and [Enroll] for the user's permissions. Click on [OK] to finish.

[[Image:tokensmart img201.jpg|370px]]

From the Start Menu, click on [Administrative Tools], [Certification Authority].

[[Image:tokensmart img202.jpg|370px]]

On the "Certification Authority" window, right-click on [Certificate Template], and select [New], [Certificate Template to Issue].

[[Image:tokensmart img203.jpg|370px]]

Under the "Enable Certificate Templates" window, select [Smartcard User] and click [OK] to finish.

[[Image:tokensmart img204.jpg|370px]]

UniToken Integration TrueCrypt Keyfile

2016-08-23T06:05:10Z

Bao:

[[category:UniToken_Integration_Guide]]

== Install the PKI Package ==

This section explains how to install the PKI package that can be found inside the UniToken SDK. The End User package can be found inside the folder "Redist/Enduser/".

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | Right-click on the PKI package installation file and choose [Run as administrator].Execute the file with an account that has administrator rights on this computer.
| [[Image:Bitlocker img01.jpg|370x259px]]
|-
| width="50" | '''2'''
| width="400" | Click on [Next] in the InstallShield Wizard welcome screen.
| [[Image:Bitlocker img02.jpg|370px]]
|-
| width="50" | '''3'''
| width="400" | Input your User Name and Company Name and click on [Next].
| [[Image:Bitlocker img03.jpg|370px]]
|-
| width="50" | '''4'''
| width="400" | Select [Complete] and click on [Next].
| [[Image:Bitlocker img04.jpg|370px]]
|-
| width="50" | '''5'''
| width="400" | Click on [Install] to begin the installation of the PKI package.
| [[Image:Bitlocker img05.jpg|370px]]
|-
| width="50" | '''6'''
| width="400" | Verify that the InstallShield Wizard completed successfully and click on [Finish].
| [[Image:Bitlocker img06.jpg|370px]]
|}

== Configure PKCS Support in TrueCrypt ==

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | In the main menu of TrueCrypt, click on [Settings],[Security Tokens].
| <center>[[Image:truecrypt img01.jpg|370px]]</center>
|-
| width="50" | '''2'''
| width="400" | In the [TrueCrypt - Security Token Preferences] window, click [Select Library...] and select the library file to be used. By default, the PKI package will install this file in the Windows%System32% directory, library file "utp11.dll". Click [OK].
| [[Image:truecrypt img02.jpg|370px]]
|}

== Create an Encrypted Volume with TrueCrypt ==

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | To create a new encrypted volume, in the main window, click [Create Volume]. Then, on the first page of the wizard, click [New].
| [[Image:freeotfe img03.jpg|370px]]
|-
| width="50" | '''2'''
| width="400" | On the [Volume Type] page, click on [Next] to continue the volume creation procedure.
| [[Image:freeotfe img04.jpg|370px]]
|-
| width="50" | '''3'''
| width="400" | Click [Select File] to choose where to store the encrypted volume. Click [Next] to continue.
| [[Image:freeotfe img05.jpg|370px]]
|-
| width="50" | '''4'''
| width="400" | Choose a file name for your encrypted volume and click [Next] to continue.
| [[Image:freeotfe img06.jpg|370px]]
|-
| width="50" | '''5'''
| width="400" | Once you’ve chosen where to save your file. Click [Next] to continue.
| [[Image:freeotfe img07.jpg|370px]]
|-
| width="50" | '''6'''
| width="400" | Keep the default encryption algorithms or change it depending on your needs. Click on [Next] to continue.
| [[Image:freeotfe img08.jpg|370px]]
|-
| width="50" | '''7'''
| width="400" | Choose the size for your volume. Click [Next].
| [[Image:freeotfe img09.jpg|370px]]
|-
| width="50" | '''8'''
| width="400" | Choose a password for your volume, make sure that [Use keyfiles] is checked and click on [Keyfiles] in order to create a keyfile for your volume (later we will store this keyfile inside the UniToken).
| [[Image:freeotfe img10.jpg|370px]]
|-
| width="50" | '''9'''
| width="400" | Click [Generate Random Keyfile…] to generate a new keyfile.
| [[Image:freeotfe img11.jpg|370px]]
|-
| width="50" | '''10'''
| width="400" | Click [Generate and Save Keyfile] to save the file.
| [[Image:freeotfe img12.jpg|370px]]
|}

== Create a keyfile for the encrypted volume and store it inside UniToken ==

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | In the main menu, click on [Tools] [Create keyfile…]
| [[Image:freeotfe img13.jpg|370px]]
|-
| width="50" | '''2'''
| width="400" | Choose the type of your encrypted volume (file or partition) and click on [Next].
| [[Image:freeotfe img14.jpg|370px]]
|-
| width="50" | '''3'''
| width="400" | Indicate where your encrypted volume is located and click on [Next].
| [[Image:freeotfe img15.jpg|370px]]
|-
| width="50" | '''4'''
| width="400" | Input the password of your volume and click on [Next].
| [[Image:freeotfe img16.jpg|370px]]
|-
| width="50" | '''5'''
| width="400" | Choose where you want to store the keyfile (At this step you cannot directly store the keyfile directly to the Token, you first have to save it to your computer and import it to your Token later).
| [[Image:freeotfe img17.jpg|370px]]
|-
| width="50" | '''6'''
| width="400" | Input a password for your keyfile and confirm it. Click on [Next] to continue.
| [[Image:freeotfe img18.jpg|370px]]
|-
| width="50" | '''7'''
| width="400" | Choose the elements that you want to use for password salting and random padding data. We have decided to choose Microsoft CrytoAPI and PKCS#11 Token. Click on [Next].
| [[Image:freeotfe img19.jpg|370px]]
|-
| width="50" | '''8'''
| width="400" | Check that the correct UniToken is selected and click on [Finish].
| [[Image:freeotfe img20.jpg|370px]]
|-
| width="50" | '''9'''
| width="400" | In the main menu, choose [Tools] [PKCS#11 token management].
| [[Image:freeotfe img21.jpg|370px]]
|-
| width="50" | '''10'''
| width="400" | Input the PIN for the UniToken and click on [OK].
| [[Image:freeotfe img22.jpg|370px]]
|-
| width="50" | '''11'''
| width="400" | In the [Keyfiles] tab, click on [Import] and select the keyfile that you just created.
| [[Image:freeotfe img23.jpg|370px]]
|-
| width="50" | '''12'''
| width="400" | When the dialog box [Keyfile imported successfully as : (name of the keyfile)] appears, the import is finished. For more security, you can choose to delete the keyfile stored on your computer and keep only the one inside the UniToken.
| [[Image:freeotfe img24.jpg|370px]]
|}

== Unlock the encrypted volume with the keyfile stored in UniToken ==

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | If you lost the password for your volume, you can now use your UniToken to access the data. Click on [Mount file] (or [Mount Partition] if you encrypted a whole partition).
| <center>[[Image:freeotfe img25.jpg|370px]]</center>
|-
| width="50" | '''2'''
| width="400" | Check [PKCS#11] and when the [Security Token/SmartCard PIN] dialog box appears, fill in your PIN and click on OK.
| [[Image:freeotfe img26.jpg|370px]]
|-
| width="50" | '''3'''
| width="400" | Input the password for the keyfile in the password field and select the right keyfile in the PKCS#11 file. Click on [OK] to confirm and get access to your encrypted volume.
| [[Image:freeotfe img27.jpg|370px]]
|}

== Glossary ==

'''Public Key Infrastructure (PKI)''': a set of hardware, software, people, policies, and procedures needed to create, manage, distribute, use, store, and revoke digital certificates.

'''Microsoft Cryptography API, MS-CAPI''': an application programming interface included with Microsoft Windows operating systems that provides services to enable developers to secure Windows-based applications using cryptography.

'''PKCS''': refers to a group of public-key cryptography standards devised and published by RSA Security.

UniToken Integration Outlook Express

2016-08-23T06:02:00Z

Bao:

[[category:UniToken_Integration_Guide]]

== Install the PKI package ==

This section explains how to install the PKI package that can be found inside the UniToken SDK. The End User package can be found inside the folder "Redist/Enduser/".

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | Right-click on the PKI package installation file and choose [Run as administrator].Execute the file with an account that has administrator rights on this computer.
| [[Image:Bitlocker img01.jpg|370x259px]]
|-
| width="50" | '''2'''
| width="400" | Click on [Next] in the InstallShield Wizard welcome screen.
| [[Image:Bitlocker img02.jpg|370px]]
|-
| width="50" | '''3'''
| width="400" | Input your User Name and Company Name and click on [Next].
| [[Image:Bitlocker img03.jpg|370px]]
|-
| width="50" | '''4'''
| width="400" | Select [Complete] and click on [Next].
| [[Image:Bitlocker img04.jpg|370px]]
|-
| width="50" | '''5'''
| width="400" | Click on [Install] to begin the installation of the PKI package.
| [[Image:Bitlocker img05.jpg|370px]]
|-
| width="50" | '''6'''
| width="400" | Verify that the InstallShield Wizard completed successfully and click on [Finish].
| [[Image:Bitlocker img06.jpg|370px]]
|}

== Request a VeriSign Certificate ==

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | Open your internet browser of your choice and navigate to the page https://digitalid.verisign.com/client/class1MS.htm With VeriSign, you have the option of either buying a digital certificate, or obtaining a free evaluation digital certificate usable for 60 days.
| [[Image:adobepdf img01.jpg|370px]]
|-
| width="50" | '''2'''
| width="400" | In the field "Cryptographic Service Provider Name", choose [UniToken PRO CSP v2.0].
| [[Image:adobepdf img02.jpg|370px]]
|-
| width="50" | '''3'''
| width="400" | Click on [Accept] to request the certificate.
| [[Image:adobepdf img03.jpg|370px]]
|-
| width="50" | '''4'''
| width="400" | Type the corresponding User PIN for the UniToken PRO device and click [OK].
| [[Image:adobepdf img04.jpg|370px]]
|-
| width="50" | '''5'''
| width="400" | An email containing a Digital ID PIN and explaining how to continue the request procedure will be sent to the email address specified earlier. Copy the Digital ID PIN from the email and navigate to the URL specified in the email, https://digitalid.verisign.com/enrollment/mspickup.htm .
| [[Image:adobepdf img05.jpg|370px]]
|-
| width="50" | '''6'''
| width="400" | Paste the Digital ID PIN copied from the email in the corresponding field and click on [Submit].
| [[Image:adobepdf img06.jpg|370px]]
|-
| width="50" | '''7'''
| width="400" | Click on [INSTALL] to import the certificate inside your UniToken PRO. If UniToken Monitor is running, a "Certificate Imported Successfully" message will appear. The request procedure is complete. You can now use this certificate to protect documents, sign and encrypt emails and related applications.
| [[Image:adobepdf img07.jpg|370px]]
|}

== Sign and Encrypt Emails ==

In the case an evaluation certificate from VeriSign was used, you must add it to the list of trusted certificates in it in Outlook Express (and other associated programs, if necessary). Please find in the [[#Attachments|attachments]] the certificates to install. '''Certificates to install:'''
* VeriSign Class 1 Individual Subscriber CA - G3.cer
* VeriSign Class 1 Public Primary Certification Authority - G3.cer

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | '''User 1's Mailbox (receiver.secutech)'''In Microsoft Outlook 2003, select [New] to compose a new email.
| [[Image:outlookexpress img01.jpg|370px]]
|-
| width="50" | '''2'''
| width="400" | Below the main menu in the tool bar, click [Options].
| [[Image:outlookexpress img02.jpg|370px]]
|-
| width="50" | '''3'''
| width="400" | On the [Message Options] page, click [Security Settings].
| [[Image:outlookexpress img03.jpg|370px]]
|-
| width="50" | '''4'''
| width="400" | On the [Security Properties] page, check [Add digital
signature to this message] and click on [Change Settings].
| [[Image:outlookexpress img04.jpg|370px]]
|-
| width="50" | '''5'''
| width="400" | Click on [Choose] to select the certificate stored inside
the UniToken and click on [OK] consecutively until you get back to [New Message] window.
| [[Image:outlookexpress img05.jpg|370px]]
|-
| width="50" | '''6'''
| width="400" | In the new mail window, click on [Send] to send the
signed mail. You will be asked for the UniToken password.
| [[Image:outlookexpress img06.jpg|370px]]
|-
| width="50" | '''7'''
| width="400" | '''User 2's Mailbox (helper.secutech)''' Go the mail account that you’ve just sent the signed mail to, and click on [Send/Recv]. Open the signed mail, right-click on the sender name and choose [Add to Outlook Contacts]
| [[Image:outlookexpress img07.jpg|370px]]
|-
| width="50" | '''8'''
| width="400" | Click on [Save and Close] to save the information about User 1 (receiver.secutech) as well as his certificate.
| [[Image:outlookexpress img08.jpg|370px]]
|-
| width="50" | '''9'''
| width="400" | Back to the main window of Microsoft 2003, select the signed email and click on [Reply]. Now that you have received that user’s digital signature, you can send encrypted mails to that user (The public key of that user is included in the signature)
| [[Image:outlookexpress img09.jpg|370px]]
|-
| width="50" | '''10'''
| width="400" | Click on the [ ] icon on the top right of the windows and click on [Send] to send the encrypted message. If the signature and encryption icon doesn’t appear, you can configure message encryption from [Options…] [Security settings] [Encrypt message and attachment]
| [[Image:outlookexpress img10.jpg|370px]]
|}

== Open an encrypted mail ==

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | '''User 1 mailbox (receiver.secutech)''' Go back to User 1’s mailbox and check your mail. You should have received the encrypted mail from User 2. Double-click on it to open it.
| <center>[[Image:outlookexpress img17.jpg|370px]]</center>
|-
| width="50" | '''2'''
| width="400" | A warning security will display “This message has been encrypted by the sender”. Click on [Continue] to see the mail.
| [[Image:outlookexpress img18.jpg|370px]]
|-
| width="50" | '''3'''
| width="400" | If your UniToken is inserted, you will be able to see the content of the mail. Note: If you’ve just inserted UniToken, you will be asked for the user password to decrypt the mail. Otherwise, there is no need to input the password once again.
| [[Image:outlookexpress img19.jpg|370px]]
|-
| width="50" | '''4'''
| width="400" | If you remove the UniToken and try to open the encrypted mail, you will get the error “Error Decrypting Message”
| [[Image:outlookexpress img20.jpg|370px]]
|}

== Glossary ==

'''Digital Signature''': a mathematical scheme for demonstrating the authenticity of a digital message or document. A valid digital signature gives a recipient reason to believe that the message was created by a known sender, and that it was not altered in transit.

'''Public Key Infrastructure (PKI)''': a set of hardware, software, people, policies, and procedures needed to create, manage, distribute, use, store, and revoke digital certificates.

'''Microsoft Cryptography API, MS-CAPI''': an application programming interface included with Microsoft Windows operating systems that provides services to enable developers to secure Windows-based applications using cryptography.

'''PKCS''': refers to a group of public-key cryptography standards devised and published by RSA Security.

== Attachments ==

* [[File:Certificates for Outlook Express Mail.zip]]

UniToken Integration Outlook 2003

2016-08-23T05:59:55Z

Bao:

[[category:UniToken_Integration_Guide]]

== Install the PKI package ==

This section explains how to install the PKI package that can be found inside the UniToken SDK. The End User package can be found inside the folder "Redist/Enduser/".

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | Right-click on the PKI package installation file and choose [Run as administrator].Execute the file with an account that has administrator rights on this computer.
| [[Image:Bitlocker img01.jpg|370x259px]]
|-
| width="50" | '''2'''
| width="400" | Click on [Next] in the InstallShield Wizard welcome screen.
| [[Image:Bitlocker img02.jpg|370px]]
|-
| width="50" | '''3'''
| width="400" | Input your User Name and Company Name and click on [Next].
| [[Image:Bitlocker img03.jpg|370px]]
|-
| width="50" | '''4'''
| width="400" | Select [Complete] and click on [Next].
| [[Image:Bitlocker img04.jpg|370px]]
|-
| width="50" | '''5'''
| width="400" | Click on [Install] to begin the installation of the PKI package.
| [[Image:Bitlocker img05.jpg|370px]]
|-
| width="50" | '''6'''
| width="400" | Verify that the InstallShield Wizard completed successfully and click on [Finish].
| [[Image:Bitlocker img06.jpg|370px]]
|}

== Request a VeriSign Certificate ==

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | Open your internet browser of your choice and navigate to the page https://digitalid.verisign.com/client/class1MS.htm With VeriSign, you have the option of either buying a digital certificate, or obtaining a free evaluation digital certificate usable for 60 days.
| [[Image:adobepdf img01.jpg|370px]]
|-
| width="50" | '''2'''
| width="400" | In the field "Cryptographic Service Provider Name", choose [UniToken PRO CSP v2.0].
| [[Image:adobepdf img02.jpg|370px]]
|-
| width="50" | '''3'''
| width="400" | Click on [Accept] to request the certificate.
| [[Image:adobepdf img03.jpg|370px]]
|-
| width="50" | '''4'''
| width="400" | Type the corresponding User PIN for the UniToken PRO device and click [OK].
| [[Image:adobepdf img04.jpg|370px]]
|-
| width="50" | '''5'''
| width="400" | An email containing a Digital ID PIN and explaining how to continue the request procedure will be sent to the email address specified earlier. Copy the Digital ID PIN from the email and navigate to the URL specified in the email, https://digitalid.verisign.com/enrollment/mspickup.htm.
| [[Image:adobepdf img05.jpg|370px]]
|-
| width="50" | '''6'''
| width="400" | Paste the Digital ID PIN copied from the email in the corresponding field and click on [Submit].
| [[Image:adobepdf img06.jpg|370px]]
|-
| width="50" | '''7'''
| width="400" | Click on [INSTALL] to import the certificate inside your UniToken PRO. If UniToken Monitor is running, a "Certificate Imported Successfully" message will appear. The request procedure is complete. You can now use this certificate to protect documents, sign and encrypt emails and related applications.
| [[Image:adobepdf img07.jpg|370px]]
|}

== Sign and Encrypt Emails ==

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | '''User 1 mailbox (receiver.secutech)'''In Microsoft Outlook 2003, below the main menu, select [New] to create a new message.
| [[Image:mail2003 img01.jpg|370px]]
|-
| width="50" | '''2'''
| width="400" | Below the main menu, in the tool bar click on [Options].
| [[Image:mail2003 img02.jpg|370px]]
|-
| width="50" | '''3'''
| width="400" | On the [Message Options] page, click on [Security Settings]
| [[Image:mail2003 img03.jpg|370px]]
|-
| width="50" | '''4'''
| width="400" | On the [Security Properties] page, check [Add digital signature to this message] and click on [Change Settings]
| [[Image:mail2003 img04.jpg|370px]]
|-
| width="50" | '''5'''
| width="400" | Click on [Choose] to Select the certificate stored inside the UniToken and click on [OK] consecutively until you get back to [New Message] window.
| [[Image:mail2003 img05.jpg|370px]]
|-
| width="50" | '''6'''
| width="400" | In the new mail window, click on [Send] to send the signed mail. You will be asked for the UniToken password.
| [[Image:mail2003 img06.jpg|370px]]
|-
| width="50" | '''7'''
| width="400" | '''User 2 mailbox (helper.secutech)''' Go the mail account that you’ve just sent the signed mail to, and click on [Send/Recv]. Open the signed mail, right-click on the sender name and choose [Add to Outlook Contacts]
| [[Image:mail2003 img07.jpg|370px]]
|-
| width="50" | '''8'''
| width="400" | Click on [Save and Close] to save the information about User 1 (receiver.secutech) as well as his certificate.
| [[Image:mail2003 img08.jpg|370px]]
|-
| width="50" | '''9'''
| width="400" | Back to the main window of Microsoft 2003, select the signed email and click on [Reply]. Now that you have received that user’s digital signature, you can send encrypted mails to that user (The public key of that user is included in the signature)
| [[Image:mail2003 img09.jpg|370px]]
|-
| width="50" | '''10'''
| width="400" | Click on the [ ] icon on the top right of the windows and click on [Send] to send the encrypted message. If the signature and encryption icon doesn’t appear, you can configure message encryption from [Options…] [Security settings] [Encrypt message and attachment]
| [[Image:mail2003 img10.jpg|370px]]
|}

== Open an encrypted mail ==

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | User 1 mailbox (receiver.secutech)Go back to User 1’s mailbox and check your mail. You should have received the encrypted mail from User 2. Double-click on it to open it.
| <center>[[Image:mail2003 img11.jpg|370px]]</center>
|-
| width="50" | '''2'''
| width="400" | If your UniToken is inserted, you will be able to see the content of the mail. ''Note: If you’ve just inserted UniToken, you will be asked for the user password to decrypt the mail. Otherwise, there is no need to input the password once again''

| [[Image:mail2003 img12.jpg|370px]]
|-
| width="50" | '''3'''
| width="400" | If UniToken is not inserted or if the certificate is incorrect, the message [Cannot Open this item. Your digital ID name cannot be found by the underlying system]
| [[Image:mail2003 img13.jpg|370px]]
|}

== Glossary ==

'''Digital Signature''': a mathematical scheme for demonstrating the authenticity of a digital message or document. A valid digital signature gives a recipient reason to believe that the message was created by a known sender, and that it was not altered in transit.

'''Public Key Infrastructure (PKI)''': a set of hardware, software, people, policies, and procedures needed to create, manage, distribute, use, store, and revoke digital certificates.

'''Microsoft Cryptography API, MS-CAPI''': an application programming interface included with Microsoft Windows operating systems that provides services to enable developers to secure Windows-based applications using cryptography.

'''PKCS''': refers to a group of public-key cryptography standards devised and published by RSA Security.

UniToken Integration Guide Word 2003

2016-08-23T05:57:58Z

Bao:

UniToken Integration Guide GINA

2016-08-23T05:56:48Z

Bao:

[[category:UniToken_Integration_Guide]]

== UniToken GINA Package Installation ==

This section explains how to install the standalone authentication package for Windows XP/2k, which can be found inside the UniToken SDK.

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | Navigate to the folder "Integration Guides/Smart Card Logon Feature/Standalone SmartCard logon(GINA)". Find the file "UniTokenGina.exe" and execute it to begin the installation.
| [[Image:GINA img01.jpg|370px]]
|-
| width="50" | '''2'''
| width="400" | Click [Next] in the InstallShield welcome screen.
| [[Image:GINA img02.jpg|370px]]
|-
| width="50" | '''3'''
| width="400" | Click on [Install] to begin the installation.
| [[Image:GINA img04.jpg|370px]]
|-
| width="50" | '''4'''
| width="400" | After installation has completed, the computer must be restarted. Choose either option and click [Finish] to complete the wizard.
| [[Image:GINA img05.jpg|370px]]
|}

== Bind UniToken PRO to a Windows Account ==

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | Insert your UniToken PRO device into your computer, input the PIN code for the token and click on [Settings].
| <center>[[Image:GINA img06.jpg|370px]]</center>
|-
| width="50" | '''2'''
| width="400" | In the "UniToken Settings" window, under the "Add WinLogon User into Token", input the username, domain (leave domain blank if the computer is not member of a domain) and password. Click [Add] to bind the user with the token. Click [OK] to finish. Note: You can also delete a user from the token and change your token PIN using this tool.
| [[Image:GINA img07.jpg|370px]]
|}

== Logging onto Windows ==

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | When logging onto your computer, insert your UniToken, input your PIN and click on [OK].
| [[Image:GINA img08.jpg|370px]]
|-
| width="50" | '''2'''
| width="400" | Select the user account that you wish to log in as (You can store numerous Windows account settings within your UniToken). Click on [OK] to log in. Logging onto the computer now only requires the correct UniToken device with it's corresponding password and no longer the Windows account password to log on.
| [[Image:GINA img09.jpg|370px]]
|}

== Glossary ==

'''Graphical Identification and Authentication (GINA)''': a component of some Microsoft Windows operating systems that provides secure authentication and interactive logon services. GINA is also responsible for starting initial processes for a user (such as the Windows Shell) when they first log on. In Windows Vista, GINA has been entirely replaced by '''Credential Providers''', which allow for significantly increased flexibility in supporting multiple credential collection methods. GINA libraries do not work with Windows Vista and later Windows versions. One difference, however, is that GINA could completely replace the Windows logon user interface; Credential Providers cannot.

== Attachments ==

*[[File:UniToken_Gina_WinXP_X86.zip]]
*[[File:UniToken_Gina_WinXP_X64.zip]]

UniToken Integration Guide FreeOTFE Secretfile

2016-08-23T05:54:28Z

Bao:

[[category:UniToken_Integration_Guide]]
[[category:UniToken_FreeOTFE_Integration]]

== Install the PKI Package ==

This section explains how to install the PKI package that can be found inside the UniToken SDK. The End User package can be found inside the folder "Redist/Enduser/".

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | Right-click on the PKI package installation file and choose [Run as administrator].Execute the file with an account that has administrator rights on this computer.
| [[Image:Bitlocker img01.jpg|370x259px]]
|-
| width="50" | '''2'''
| width="400" | Click on [Next] in the InstallShield Wizard welcome screen.
| [[Image:Bitlocker img02.jpg|370px]]
|-
| width="50" | '''3'''
| width="400" | Input your User Name and Company Name and click on [Next].
| [[Image:Bitlocker img03.jpg|370px]]
|-
| width="50" | '''4'''
| width="400" | Select [Complete] and click on [Next].
| [[Image:Bitlocker img04.jpg|370px]]
|-
| width="50" | '''5'''
| width="400" | Click on [Install] to begin the installation of the PKI package.
| [[Image:Bitlocker img05.jpg|370px]]
|-
| width="50" | '''6'''
| width="400" | Verify that the InstallShield Wizard completed successfully and click on [Finish].
| [[Image:Bitlocker img06.jpg|370px]]
|}

== Configure PKCS Support in FreeOTFE ==

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | In the main menu, go to [Settings], [Security Tokens].
| <center>[[Image:freeotfe img01.jpg|370px]]</center>
|-
| width="50" | '''2'''
| width="400" | In the [Options] window, under the [PKCS#11] tab, check [Enable PKCS#11 support] and locate and select the library file. By default, the PKI package will install this file in the Windows\System32\ directory. Choose where to save the settings in the field [Save above settings to] and click on [OK] to apply the settings.
| [[Image:freeotfe img02.jpg|370px]]
|}

== Create an Encrypted Volume with FreeOTFE ==

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | To create a new encrypted volume under FreeOTFE, click on [New].
| [[Image:freeotfe img03.jpg|370px]]
|-
| width="50" | '''2'''
| width="400" | On the FreeOTFE Volume Creation Wizard welcome page, click on [Next] to begin the volume creation procedure.

| [[Image:freeotfe img04.jpg|370px]]
|-
| width="50" | '''3'''
| width="400" | You can choose to store the encrypted volume as a file or to encrypt a whole partition/disk. Choose the option that best fits your purposes. In this example, we have chosen to store the encrypted volume as a file. Click on [Next] to continue.
| [[Image:freeotfe img05.jpg|370px]]
|-
| width="50" | '''4'''
| width="400" | Choose where you want to store the volume and click on [Next] to continue.
| [[Image:freeotfe img06.jpg|370px]]
|-
| width="50" | '''5'''
| width="400" | Choose the size of your encrypted volume and click on [Next] to continue.
| [[Image:freeotfe img07.jpg|370px]]
|-
| width="50" | '''6'''
| width="400" | Select the encryption algorithm you wish to use to best fit your needs, otherwise continue with the default option. Click on [Next] to continue.
| [[Image:freeotfe img08.jpg|370px]]
|-
| width="50" | '''7'''
| width="400" | Choose the elements used to secure your volume. The more number of options you select, the more you can secure your volume.
We have chosen to use the "Microsoft CryptoAPI" and "PKCS#11 token" options. Click on [Next] to continue.
| [[Image:freeotfe img09.jpg|370px]]
|-
| width="50" | '''8'''
| width="400" | Check that you have selected the right UniToken device and click on [Next] to continue.
| [[Image:freeotfe img10.jpg|370px]]
|-
| width="50" | '''9'''
| width="400" | Input a password for your encrypted volume. This password doesn’t have to be the same password used on your UniToken. Click on [Next] to continue.
| [[Image:freeotfe img11.jpg|370px]]
|-
| width="50" | '''10'''
| width="400" | Check that the details for the new volume are correct and click on [Finish] to create the volume.
| [[Image:freeotfe img12.jpg|370px]]
|}

== Create a Secret File within UniToken to Secure a Volume ==

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | Under FreeOTFE, select [Tools], [PKCS#11 token management].
| [[Image:freeotfe img28.jpg|370px]]
|-
| width="50" | '''2'''
| width="400" | In the "Security Token/Smartcard PIN" window, input your User PIN of your UniToken device and click on [OK].
| [[Image:freeotfe img29.jpg|370px]]
|-
| width="50" | '''3'''
| width="400" | In the [Secret Keys] tab, click on [New]. In the [New PKCS#11 Secret Key] window, input a name for your Secret Key and click on [OK].
| [[Image:freeotfe img30.jpg|370px]]
|-
| width="50" | '''4'''
| width="400" | A confirmation window will appear confirming that the Secret Key was successfully created. Click on [OK] to close window.
| [[Image:freeotfe img31.jpg|370px]]
|-
| width="50" | '''5'''
| width="400" | Select the Secret File that you created and click on [Secure].
| [[Image:freeotfe img32.jpg|370px]]
|-
| width="50" | '''6'''
| width="400" | Click on the icon corresponding to your type of volume (file or partition) and select the volume that you want to protect with the Secret Key. Click on [OK] to confirm.
| [[Image:freeotfe img33.jpg|370px]]
|-
| width="50" | '''7'''
| width="400" | A pop-up window will appear asking to confirm the volume you have selected to protect. Click on [Yes] to confirm the selected volume. A dialog pop will appear to confirm that the volume has been correctly protected.
| [[Image:freeotfe img34.jpg|370px]]
|}

== Mount the Encrypted Volume ==

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | Under FreeOTFE, click on [Mount file] and select your volume.
| <center>[[Image:freeotfe img35.jpg|370px]]</center>
|-
| width="50" | '''2'''
| width="400" | Enter the password for the volume, then click on [Advanced].
| [[Image:freeotfe img36.jpg|370px]]
|-
| width="50" | '''3'''
| width="400" | In the "Security Token/Smartcard PIN" window, input your User PIN of your UniToken device and click on [OK].
| [[Image:freeotfe img37.jpg|370px]]
|-
| width="50" | '''4'''
| width="400" | Select the corresponding Secret Key for the volume and click on [OK] to mount the volume. If the incorrect password is entered or incorrect key is selected, you will not be able to access the volume. Both the corresponding password for the volume and the secret key stored within UniToken are required to access the volume.
| [[Image:freeotfe img38.jpg|370px]]
|}

== Glossary ==

'''Public Key Infrastructure (PKI)''': a set of hardware, software, people, policies, and procedures needed to create, manage, distribute, use, store, and revoke digital certificates.

'''Microsoft Cryptography API, MS-CAPI''': an application programming interface included with Microsoft Windows operating systems that provides services to enable developers to secure Windows-based applications using cryptography.

'''PKCS''': refers to a group of public-key cryptography standards devised and published by RSA Security.

UniToken Integration Guide FreeOTFE Keyfile

2016-08-23T05:52:53Z

Bao:

[[category:UniToken_Integration_Guide]]
[[category:UniToken_FreeOTFE_Integration]]

== Install the PKI Package ==

This section explains how to install the PKI package that can be found inside the UniToken SDK. The End User package can be found inside the folder "Redist/Enduser/".

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | Right-click on the PKI package installation file and choose [Run as administrator].Execute the file with an account that has administrator rights on this computer.
| [[Image:Bitlocker img01.jpg|370x259px]]
|-
| width="50" | '''2'''
| width="400" | Click on [Next] in the InstallShield Wizard welcome screen.
| [[Image:Bitlocker img02.jpg|370px]]
|-
| width="50" | '''3'''
| width="400" | Input your User Name and Company Name and click on [Next].
| [[Image:Bitlocker img03.jpg|370px]]
|-
| width="50" | '''4'''
| width="400" | Select [Complete] and click on [Next].
| [[Image:Bitlocker img04.jpg|370px]]
|-
| width="50" | '''5'''
| width="400" | Click on [Install] to begin the installation of the PKI package.
| [[Image:Bitlocker img05.jpg|370px]]
|-
| width="50" | '''6'''
| width="400" | Verify that the InstallShield Wizard completed successfully and click on [Finish].
| [[Image:Bitlocker img06.jpg|370px]]
|}

== Configure PKCS Support in FreeOTFE ==

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | In the main menu, go to [Settings], [Security Tokens].
| <center>[[Image:freeotfe img01.jpg|370px]]</center>
|-
| width="50" | '''2'''
| width="400" | In the [Options] window, under the [PKCS#11] tab, check [Enable PKCS#11 support] and locate and select the library file. By default, the PKI package will install this file in the Windows\System32\ directory. Choose where to save the settings in the field [Save above settings to] and click on [OK] to apply the settings.
| [[Image:freeotfe img02.jpg|370px]]
|}

== Create an Encrypted Volume with FreeOTFE ==

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | To create a new encrypted volume under FreeOTFE, click on [New].
| [[Image:freeotfe img03.jpg|370px]]
|-
| width="50" | '''2'''
| width="400" | On the FreeOTFE Volume Creation Wizard welcome page, click on [Next] to begin the volume creation procedure.

| [[Image:freeotfe img04.jpg|370px]]
|-
| width="50" | '''3'''
| width="400" | You can choose to store the encrypted volume as a file or to encrypt a whole partition/disk. Choose the option that best fits your purposes. In this example, we have chosen to store the encrypted volume as a file. Click on [Next] to continue.
| [[Image:freeotfe img05.jpg|370px]]
|-
| width="50" | '''4'''
| width="400" | Choose where you want to store the volume and click on [Next] to continue.
| [[Image:freeotfe img06.jpg|370px]]
|-
| width="50" | '''5'''
| width="400" | Choose the size of your encrypted volume and click on [Next] to continue.
| [[Image:freeotfe img07.jpg|370px]]
|-
| width="50" | '''6'''
| width="400" | Select the encryption algorithm you wish to use to best fit your needs, otherwise continue with the default option. Click on [Next] to continue.
| [[Image:freeotfe img08.jpg|370px]]
|-
| width="50" | '''7'''
| width="400" | Choose the elements used to secure your volume. The more number of options you select, the more you can secure your volume.
We have chosen to use the "Microsoft CryptoAPI" and "PKCS#11 token" options. Click on [Next] to continue.
| [[Image:freeotfe img09.jpg|370px]]
|-
| width="50" | '''8'''
| width="400" | Check that you have selected the right UniToken device and click on [Next] to continue.
| [[Image:freeotfe img10.jpg|370px]]
|-
| width="50" | '''9'''
| width="400" | Input a password for your encrypted volume. This password doesn’t have to be the same password used on your UniToken. Click on [Next] to continue.
| [[Image:freeotfe img11.jpg|370px]]
|-
| width="50" | '''10'''
| width="400" | Check that the details for the new volume are correct and click on [Finish] to create the volume.
| [[Image:freeotfe img12.jpg|370px]]
|}

== Creating and Storing a Keyfile for the Encrypted Volume within UniToken ==

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | In the main menu of FreeOTFE, click on [Tools], [Create keyfile…].
| [[Image:freeotfe img13.jpg|370px]]
|-
| width="50" | '''2'''
| width="400" | Choose the type of your encrypted volume, either a file or a partition. In this step, we have chosen "File". Click on [Next] to continue.
| [[Image:freeotfe img14.jpg|370px]]
|-
| width="50" | '''3'''
| width="400" | Indicate where your encrypted volume is located and click on [Next].
| [[Image:freeotfe img15.jpg|370px]]
|-
| width="50" | '''4'''
| width="400" | Input the password of your volume and change the supplementary options if desired, then click on [Next].
| [[Image:freeotfe img16.jpg|370px]]
|-
| width="50" | '''5'''
| width="400" | Choose the directory where you wish to store the keyfile (At this step you cannot directly store the keyfile to the token. You must first save it to your computer and then import it onto your token later).
| [[Image:freeotfe img17.jpg|370px]]
|-
| width="50" | '''6'''
| width="400" | Input a password for your keyfile and change the supplementary options if desired. Click on [Next] to continue.
| [[Image:freeotfe img18.jpg|370px]]
|-
| width="50" | '''7'''
| width="400" | Choose the elements that you want to use for password salting and random padding data. We have decided to choose "Microsoft CrytoAPI" and "PKCS#11 Token". Click on [Next].
| [[Image:freeotfe img19.jpg|370px]]
|-
| width="50" | '''8'''
| width="400" | Check that the correct UniToken is selected and click on [Finish].
| [[Image:freeotfe img20.jpg|370px]]
|-
| width="50" | '''9'''
| width="400" | In the main menu, choose [Tools], [PKCS#11 token management].
| [[Image:freeotfe img21.jpg|370px]]
|-
| width="50" | '''10'''
| width="400" | Input the PIN for the UniToken and click on [OK].
| [[Image:freeotfe img22.jpg|370px]]
|-
| width="50" | '''11'''
| width="400" | In the [Keyfiles] tab in the "Security Token/Smartcard Management" window, click on [Import] and select the keyfile that you just created.
| [[Image:freeotfe img23.jpg|370px]]
|-
| width="50" | '''12'''
| width="400" | When the dialog box [Keyfile imported successfully as: (Name of the keyfile)] appears, importing of the keyfile has finished.
For improved security, you can choose to securely delete the keyfile stored on your computer and keep only the one inside the UniToken.

| [[Image:freeotfe img24.jpg|370px]]
|}

== Unlock the Encrypted Volume with the Keyfile stored in UniToken ==

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | You can now use your UniToken to access the encrypted data. Click on [Mount file] (or [Mount Partition] if you encrypted a whole partition) in FreeOTFE.
| <center>[[Image:freeotfe img25.jpg|370px]]</center>
|-
| width="50" | '''2'''
| width="400" | Select [PKCS#11] in the "FreeOTFE Key Entry" window, and under the "Security Token/SmartCard PIN" dialog box, input your PIN and click [OK].
| [[Image:freeotfe img26.jpg|370px]]
|-
| width="50" | '''3'''
| width="400" | Input the password for the keyfile in the "Password" field and select the correct keyfile in the PKCS#11 file. Click [OK] to confirm and access your encrypted volume.
| [[Image:freeotfe img27.jpg|370px]]
|}

== Glossary ==

'''[[PKI|Public Key Infrastructure (PKI)]]''': a set of hardware, software, people, policies, and procedures needed to create, manage, distribute, use, store, and revoke digital certificates.

'''Microsoft Cryptography API, MS-CAPI''': an application programming interface included with Microsoft Windows operating systems that provides services to enable developers to secure Windows-based applications using cryptography.

'''PKCS''': refers to a group of public-key cryptography standards devised and published by RSA Security.

UniToken Integration Guide Excel 2003

2016-08-23T05:51:12Z

Bao:

UniToken Integration PKCS

2016-08-23T05:48:44Z

Bao:

[[category:UniToken_Integration_Guide]]

==PKCS Encrypt and Decrypt==

Samples illustrating how to use UniToken with PKCS for encryption and decryption can be found in UniToken SDK under the directory <code>UniToken SDK/Samples/PKCS/EDcrypt/</code>

==PKCS Get Token Info==

Samples illustrating how to fetch information using UniToken with PKCS can be found in the UniToken SDK under the directory <code>UniToken SDK/Samples/PKCS/TokenInfo/</code>

==PKCS Init Token==

Samples illustrating how to initialize UniToken with PKCS can be found in the UniToken SDK under the directory <code>UniToken SDK/Samples/PKCS/InitToken</code>

==PKCS Signature Verify==

Samples illustrating how to verify digital signatures using UniToken with PKCS can be found in the UniToken SDK under the directory <code>UniToken SDK/Samples/PKCS/SignVerify/</code>

UniToken Integration Web Authentication Windows Server

2016-08-23T05:48:16Z

Bao:

[[category:UniToken_Integration_Guide]]

== Server Setup ==

[[File:Video Tutorial for UniTokenLite Server.swf]]

== Burn UniToken ==

[[File:Video Tutorial for burning UniTokenLite.swf]]

== Client Usage ==

'''Note:'''

The password for the login page is 123456. The username is administrator.

[[File:Video Tutorial for UniTokenLite Client.swf]]

UniToken Integration Web Authentication Linux Server

2016-08-23T05:46:52Z

Bao:

[[category:UniToken_Integration_Guide]]

https://files.esecutech.com/videos/UniTokenPROWebAuthentication.flv

UniToken Integration Guide BitLocker Drive Encryption

2016-08-23T05:46:30Z

Bao:

[[category:UniToken_Integration_Guide]]



== Install the PKI Package ==

This section explains how to install the PKI package that can be found inside the UniToken SDK. The End User package can be found inside the folder "Redist/Enduser/".

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | Right-click on the PKI package installation file and choose [Run as administrator]. Execute the file with an account that has administrator rights on this computer.
| [[Image:Bitlocker img01.jpg|370x259px]]
|-
| width="50" | '''2'''
| width="400" | Click on [Next] in the InstallShield Wizard welcome screen.
| [[Image:Bitlocker img02.jpg|370px]]
|-
| width="50" | '''3'''
| width="400" | Input your User Name and Company Name and click on [Next].
| [[Image:Bitlocker img03.jpg|370px]]
|-
| width="50" | '''4'''
| width="400" | Select [Complete] and click on [Next].
| [[Image:Bitlocker img04.jpg|370px]]
|-
| width="50" | '''5'''
| width="400" | Click on [Install] to begin the installation of the PKI package.
| [[Image:Bitlocker img05.jpg|370px]]
|-
| width="50" | '''6'''
| width="400" | Verify that the InstallShield Wizard completed successfully and click on [Finish].
| [[Image:Bitlocker img06.jpg|370px]]
|}

== Create a Compatible Smartcard Certificate ==

In this tutorial, we will use a self-signed certificate to encrypt the disk with BitLocker. A smart card certificate signed by a Certificate Authority can also be used, but ensure it is supported by BitLocker. More information about the requirements for a compatible BitLocker certificate can be found on Microsoft's website.

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | From the Start Menu, type "regedit", without quotation marks, in the search field, then right-click on "regedit" and click [Run as administrator].
| <center>[[Image:Bitlocker img07.jpg|370x259px]]</center>
|-
| width="50" | '''2'''
| width="400" | Navigate to "HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\FVE" and right click in the right pane. Choose [New] [DWORD(32-bit Value)].
| [[Image:Bitlocker img08.jpg|370px]]
|-
| width="50" | '''3'''
| width="400" | Name the DWORD value as “SelfSignedCertificates”.
| [[Image:Bitlocker img09.jpg|370px]]
|-
| width="50" | '''4'''
| width="400" | Double click on the value and set the field [Value data] to "1". Click on [OK] to confirm and close regedit.
| [[Image:Bitlocker img10.jpg|370px]]
|-
| width="50" | '''5'''
| width="400" | Copy and save the text to the right as "blcert.txt".
| [NewRequest]

<code>
Subject = "CN=BitLocker"

KeyLength = 2048

ProviderName = "UniToken PRO CSP v2.0"

KeySpec = "AT_KEYEXCHANGE"

KeyUsage = "CERT_KEY_ENCIPHERMENT_KEY_USAGE"

KeyUsageProperty = "NCRYPT_ALLOW_DECRYPT_FLAG"

RequestType = Cert

SMIME = FALSE

[EnhancedKeyUsageExtension]

OID=1.3.6.1.4.1.311.67.1.1
</code>

|-
| width="50" | '''6'''
| width="400" | From the Start Menu, type "cmd.exe", without quotation marks, in the search field, then right-click on "cmd" and click [Run as administrator].
| <center>[[Image:Bitlocker img12.jpg|300px]]</center>
|
|-
| width="50" | '''7'''
| width="400" | Retrieve the path of the "blcert.txt" file saved earlier. To do so, navigate to where "blcert.txt" is saved, right-click on the file and select [Properties], search for the field [Location] and copy the path of your file.
| <center>[[Image:Bitlocker img13.jpg|300px]]</center>
|-
| width="50" | '''8'''
| width="400" | On the cmd console, type "cd " followed by the path of your file" to go to the directory where it is saved. For example "cd C:\Users\SecuTech\Desktop", without quotation marks (, at this point, make sure that the corresponding UniToken is correctly plugged in before executing the following operation). Afterwards, type "certreq –new blcert.txt" to request the BitLocker certificate.
.
| <center>[[Image:Bitlocker img14.jpg|300px]]</center>
|}

== Encrypt the Hard Disk with BitLocker ==

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | From the Start Menu, type "BitLocker", and from the results that appear, choose [Manage BitLocker].
| [[Image:Bitlocker img15.jpg|370x259px]]
|-
| width="50" | '''2'''
| width="400" | Choose the disk that you wish to enable BitLocker on and click on [Turn on BitLocker].
| [[Image:Bitlocker img16.jpg|370px]]
|-
| width="50" | '''3'''
| width="400" | On the screen "Choose how you want to unlock this drive", check [Use my smart card to unlock the drive] and click on [Next].
''Options differ depending if you encrypt a partition from an internal or an external disk. For now, UniToken cannot be used to encrypt the system partition.''
| [[Image:Bitlocker img17.jpg|370px]]
|-
| width="50" | '''4'''
| width="400" | On the screen "How do you want to store your recovery key?", choose where you want to save the file containing the recovery key - you can also choose to print it. ''Be sure to keep the recovery key in a safe place. If you lose your smart card, it is the only way to decrypt the data on the encrypted drive: otherwise, all data will be lost.''
| [[Image:Bitlocker img18.jpg|370px]]
|-
| width="50" | '''5'''
| width="400" | On the screen "Are you ready to encrypt this drive", click [Start Encrypting].
| [[Image:Bitlocker img19.jpg|370px]]
|-
| width="50" | '''6'''
| width="400" | The encryption process will take place. This may take a long time depending on the characteristics of your computer and the disk size to be encrypted. (On the tested configuration, encrypting a 8GB partition took approximately 30 minutes).
| [[Image:Bitlocker img20.jpg|370px]]
|-
| width="50" | '''7'''
| width="400" | When the dialog window "Encryption of (disk) is complete" appears, the disk is now protected. Click on [Close] to finish.
| [[Image:Bitlocker img21.jpg|370px]]
|}

== Access to the Encrypted Disk ==

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | When attempting to access the encrypted disk, the following window will appear (You can also choose to unlock the disk automatically when the smart card is inserted.
Insert your UniToken device and click on [Unlock].

| [[Image:Bitlocker img22.jpg|370px]]
|-
| width="50" | '''2'''
| width="400" | You will be asked to type the User PIN for your UniToken to unlock the drive. The drive will be unlocked only if the correct password is entered. Enter the User PIN and click [OK] to access the encrypted drive.
| [[Image:Bitlocker img23.jpg|370px]]
|}

== Glossary ==

'''Smart Card''': any pocket-sized card with embedded integrated circuits. There are two broad categories of ICCs. Memory cards contain only non-volatile memory storage components, and perhaps dedicated security logic. Microprocessor cards contain volatile memory and microprocessor components.

'''Public Key Infrastructure (PKI)''': a set of hardware, software, people, policies, and procedures needed to create, manage, distribute, use, store, and revoke digital certificates.

'''Microsoft Cryptography API, MS-CAPI''': an application programming interface included with Microsoft Windows operating systems that provides services to enable developers to secure Windows-based applications using cryptography.

'''PKCS''': refers to a group of public-key cryptography standards devised and published by RSA Security.

UniToken Integration Guide BitLocker Drive Encryption

2016-08-23T05:46:07Z

Bao:

[[category:UniToken_Integration_Guide]]

{{Infobox
|title = UniToken BitLocker Integration
|image = [[Image:Flex.png|50px]]
|label1 = Models
|data1 = UniToken Pro, UniToken Drive
|label2 = Compatible Systems
|data2 = Windows 7, Windows Server 2008
}}

== Install the PKI Package ==

This section explains how to install the PKI package that can be found inside the UniToken SDK. The End User package can be found inside the folder "Redist/Enduser/".

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | Right-click on the PKI package installation file and choose [Run as administrator]. Execute the file with an account that has administrator rights on this computer.
| [[Image:Bitlocker img01.jpg|370x259px]]
|-
| width="50" | '''2'''
| width="400" | Click on [Next] in the InstallShield Wizard welcome screen.
| [[Image:Bitlocker img02.jpg|370px]]
|-
| width="50" | '''3'''
| width="400" | Input your User Name and Company Name and click on [Next].
| [[Image:Bitlocker img03.jpg|370px]]
|-
| width="50" | '''4'''
| width="400" | Select [Complete] and click on [Next].
| [[Image:Bitlocker img04.jpg|370px]]
|-
| width="50" | '''5'''
| width="400" | Click on [Install] to begin the installation of the PKI package.
| [[Image:Bitlocker img05.jpg|370px]]
|-
| width="50" | '''6'''
| width="400" | Verify that the InstallShield Wizard completed successfully and click on [Finish].
| [[Image:Bitlocker img06.jpg|370px]]
|}

== Create a Compatible Smartcard Certificate ==

In this tutorial, we will use a self-signed certificate to encrypt the disk with BitLocker. A smart card certificate signed by a Certificate Authority can also be used, but ensure it is supported by BitLocker. More information about the requirements for a compatible BitLocker certificate can be found on Microsoft's website.

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | From the Start Menu, type "regedit", without quotation marks, in the search field, then right-click on "regedit" and click [Run as administrator].
| <center>[[Image:Bitlocker img07.jpg|370x259px]]</center>
|-
| width="50" | '''2'''
| width="400" | Navigate to "HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\FVE" and right click in the right pane. Choose [New] [DWORD(32-bit Value)].
| [[Image:Bitlocker img08.jpg|370px]]
|-
| width="50" | '''3'''
| width="400" | Name the DWORD value as “SelfSignedCertificates”.
| [[Image:Bitlocker img09.jpg|370px]]
|-
| width="50" | '''4'''
| width="400" | Double click on the value and set the field [Value data] to "1". Click on [OK] to confirm and close regedit.
| [[Image:Bitlocker img10.jpg|370px]]
|-
| width="50" | '''5'''
| width="400" | Copy and save the text to the right as "blcert.txt".
| [NewRequest]

<code>
Subject = "CN=BitLocker"

KeyLength = 2048

ProviderName = "UniToken PRO CSP v2.0"

KeySpec = "AT_KEYEXCHANGE"

KeyUsage = "CERT_KEY_ENCIPHERMENT_KEY_USAGE"

KeyUsageProperty = "NCRYPT_ALLOW_DECRYPT_FLAG"

RequestType = Cert

SMIME = FALSE

[EnhancedKeyUsageExtension]

OID=1.3.6.1.4.1.311.67.1.1
</code>

|-
| width="50" | '''6'''
| width="400" | From the Start Menu, type "cmd.exe", without quotation marks, in the search field, then right-click on "cmd" and click [Run as administrator].
| <center>[[Image:Bitlocker img12.jpg|300px]]</center>
|
|-
| width="50" | '''7'''
| width="400" | Retrieve the path of the "blcert.txt" file saved earlier. To do so, navigate to where "blcert.txt" is saved, right-click on the file and select [Properties], search for the field [Location] and copy the path of your file.
| <center>[[Image:Bitlocker img13.jpg|300px]]</center>
|-
| width="50" | '''8'''
| width="400" | On the cmd console, type "cd " followed by the path of your file" to go to the directory where it is saved. For example "cd C:\Users\SecuTech\Desktop", without quotation marks (, at this point, make sure that the corresponding UniToken is correctly plugged in before executing the following operation). Afterwards, type "certreq –new blcert.txt" to request the BitLocker certificate.
.
| <center>[[Image:Bitlocker img14.jpg|300px]]</center>
|}

== Encrypt the Hard Disk with BitLocker ==

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | From the Start Menu, type "BitLocker", and from the results that appear, choose [Manage BitLocker].
| [[Image:Bitlocker img15.jpg|370x259px]]
|-
| width="50" | '''2'''
| width="400" | Choose the disk that you wish to enable BitLocker on and click on [Turn on BitLocker].
| [[Image:Bitlocker img16.jpg|370px]]
|-
| width="50" | '''3'''
| width="400" | On the screen "Choose how you want to unlock this drive", check [Use my smart card to unlock the drive] and click on [Next].
''Options differ depending if you encrypt a partition from an internal or an external disk. For now, UniToken cannot be used to encrypt the system partition.''
| [[Image:Bitlocker img17.jpg|370px]]
|-
| width="50" | '''4'''
| width="400" | On the screen "How do you want to store your recovery key?", choose where you want to save the file containing the recovery key - you can also choose to print it. ''Be sure to keep the recovery key in a safe place. If you lose your smart card, it is the only way to decrypt the data on the encrypted drive: otherwise, all data will be lost.''
| [[Image:Bitlocker img18.jpg|370px]]
|-
| width="50" | '''5'''
| width="400" | On the screen "Are you ready to encrypt this drive", click [Start Encrypting].
| [[Image:Bitlocker img19.jpg|370px]]
|-
| width="50" | '''6'''
| width="400" | The encryption process will take place. This may take a long time depending on the characteristics of your computer and the disk size to be encrypted. (On the tested configuration, encrypting a 8GB partition took approximately 30 minutes).
| [[Image:Bitlocker img20.jpg|370px]]
|-
| width="50" | '''7'''
| width="400" | When the dialog window "Encryption of (disk) is complete" appears, the disk is now protected. Click on [Close] to finish.
| [[Image:Bitlocker img21.jpg|370px]]
|}

== Access to the Encrypted Disk ==

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | When attempting to access the encrypted disk, the following window will appear (You can also choose to unlock the disk automatically when the smart card is inserted.
Insert your UniToken device and click on [Unlock].

| [[Image:Bitlocker img22.jpg|370px]]
|-
| width="50" | '''2'''
| width="400" | You will be asked to type the User PIN for your UniToken to unlock the drive. The drive will be unlocked only if the correct password is entered. Enter the User PIN and click [OK] to access the encrypted drive.
| [[Image:Bitlocker img23.jpg|370px]]
|}

== Glossary ==

'''Smart Card''': any pocket-sized card with embedded integrated circuits. There are two broad categories of ICCs. Memory cards contain only non-volatile memory storage components, and perhaps dedicated security logic. Microprocessor cards contain volatile memory and microprocessor components.

'''Public Key Infrastructure (PKI)''': a set of hardware, software, people, policies, and procedures needed to create, manage, distribute, use, store, and revoke digital certificates.

'''Microsoft Cryptography API, MS-CAPI''': an application programming interface included with Microsoft Windows operating systems that provides services to enable developers to secure Windows-based applications using cryptography.

'''PKCS''': refers to a group of public-key cryptography standards devised and published by RSA Security.

UniToken Integration Guide Adobe PDF

2016-08-23T05:43:11Z

Bao:

[[category:UniToken_Integration_Guide]]

== Install the PKI package ==

This section explains how to install the PKI package that can be found inside the UniToken SDK. The End User package can be found inside the folder "Redist/Enduser/".

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | Right-click on the PKI package installation file and choose [Run as administrator]. Execute the file with an account that has administrator rights on this computer.
| [[Image:Bitlocker img01.jpg|370x259px]]
|-
| width="50" | '''2'''
| width="400" | Click on [Next] in the InstallShield Wizard welcome screen.
| [[Image:Bitlocker img02.jpg|370px]]
|-
| width="50" | '''3'''
| width="400" | Input your User Name and Company Name and click on [Next].
| [[Image:Bitlocker img03.jpg|370px]]
|-
| width="50" | '''4'''
| width="400" | Select [Complete] and click on [Next].
| [[Image:Bitlocker img04.jpg|370px]]
|-
| width="50" | '''5'''
| width="400" | Click on [Install] to begin the installation of the PKI package.
| [[Image:Bitlocker img05.jpg|370px]]
|-
| width="50" | '''6'''
| width="400" | Verify that the InstallShield Wizard completed successfully and click on [Finish].
| [[Image:Bitlocker img06.jpg|370px]]
|}

== Request a VeriSign Certificate ==

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | Open your internet browser of your choice and navigate to the page https://digitalid.verisign.com/client/class1MS.htm With VeriSign, you have the option of either buying a digital certificate, or obtaining a free evaluation digital certificate usable for 60 days.
| [[Image:adobepdf img01.jpg|370px]]
|-
| width="50" | '''2'''
| width="400" | In the field "Cryptographic Service Provider Name", choose [UniToken PRO CSP v2.0].

| [[Image:adobepdf img02.jpg|370px]]
|-
| width="50" | '''3'''
| width="400" | Click on [Accept] to request the certificate.
| [[Image:adobepdf img03.jpg|370px]]
|-
| width="50" | '''4'''
| width="400" | Type the corresponding User PIN for the UniToken PRO device and click [OK].
| [[Image:adobepdf img04.jpg|370px]]
|-
| width="50" | '''5'''
| width="400" | An email containing a Digital ID PIN and explaining how to continue the request procedure will be sent to the email address specified earlier. Copy the Digital ID PIN from the email and navigate to the URL specified in the email: https://digitalid.verisign.com/enrollment/mspickup.htm.
| [[Image:adobepdf img05.jpg|370px]]
|-
| width="50" | '''6'''
| width="400" | Paste the Digital ID PIN copied from the email in the corresponding field and click on [Submit].
| [[Image:adobepdf img06.jpg|370px]]
|-
| width="50" | '''7'''
| width="400" | Click on [INSTALL] to import the certificate inside your UniToken PRO. If UniToken Monitor is running, a "Certificate Imported Successfully" message will appear. The request procedure is complete. You can now use this certificate to protect documents, sign and encrypt emails and related applications.
| [[Image:adobepdf img07.jpg|370px]]
|}

== Encrypt a PDF Document ==

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | With Adobe Acrobat Pro, open the PDF document you wish to protect.
| [[Image:adobepdf img08.jpg|370px]]
|-
| width="50" | '''2'''
| width="400" | In the menu, click on [Advanced], [Security], [Encrypt with Certificate]. ''In Adobe Acrobat PRO X (version 10), this option can be found in [File], [Property], [Security] tab, [Protect with Certificate].''
| [[Image:adobepdf img09.jpg|370px]]
|-
| width="50" | '''3'''
| width="400" | Under "Select Document Components to Encrypt", select the option best suited for your requirements; [Encrypt all document contents] is suggested for utmost security. Under "Encryption Algorithm", choose the encryption algorithm to encrypt the document with. ''The greater the encryption strength, the greater the security of the document, at the expense of compatibility, however.'' Click [Next].
| [[Image:adobepdf img10.jpg|370px]]
|-
| width="50" | '''4'''
| width="400" | Choose the certificate you wish to use to encrypt the document with, then click on [Next].
| [[Image:adobepdf img11.jpg|370px]]
|-
| width="50" | '''5'''
| width="400" | Verify the configured settings are correct, then click on [Finish].
| [[Image:adobepdf img12.jpg|370px]]
|-
| width="50" | '''6'''
| width="400" | A warning message will appear, stating that the document must be saved to apply the security settings. Click [OK] to acknowledge the warning, then proceed to save the file to apply changes.
| [[Image:adobepdf img13.jpg|370px]]
|}

== Open an Encrypted PDF Document ==

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" | When opening an encrypted PDF document, you will be prompted to type the UniToken User’s password. Input the password and click on [OK].
| <center>[[Image:adobepdf img14.jpg|370px]]</center>
|-
| width="50" | '''2'''
| width="400" | The appropriate UniToken device and corresponding password is required to open the document, otherwise, the document cannot be opened.
| [[Image:adobepdf img15.jpg|370px]]
|-
| width="50" | '''3'''
| width="400" | If the token is absent whilst attempting to open the document, an error "You do not have access right to this encrypted document" will appear and will be unable to open the document.
| [[Image:adobepdf img16.jpg|370px]]
|}

== Glossary ==

'''PDF''': Portable document format

'''Public Key Infrastructure (PKI)''': a set of hardware, software, people, policies, and procedures needed to create, manage, distribute, use, store, and revoke digital certificates.

'''Microsoft Cryptography API, MS-CAPI''': an application programming interface included with Microsoft Windows operating systems that provides services to enable developers to secure Windows-based applications using cryptography.

'''PKCS''': refers to a group of public-key cryptography standards devised and published by RSA Security.

UniToken Integration CAPI

2016-08-23T05:36:12Z

Bao:

[[category:UniToken_Integration_Guide]]

Samples illustrating how to integrate UniToken with CAPI can be found in the UniToken SDK under the directory <code>UniToken SDK/Samples/CAPI/</code>

UniToken API Reference

2016-08-23T05:35:29Z

Bao:

[[category:UniToken_API]]

== UT_GetLibraryVersion ==
<b>API Prototype</b>

<code>unsigned long UT_API UT_GetLibraryVersion()</code>

<b>Description</b>

To get the version of the present library.

<b>Parameters</b>

n/a

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>Library version</td>
<td>the version of the current library</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
unsigned long ulLibraryVersion;
ulLibraryVersion = UT_GetLibraryVersion();
</source>

== UT_Initialize ==
<b>API Prototype</b>

<code>UT_RV UT_API UT_Initialize()</code>

<b>Description</b>

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

<b>Parameters</b>

n/a

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_ALREADY_INITIALIZE</td>
<td>Library already initialized</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
ret = UT_Initialize();
</source>

== UT_Finalize ==

<b>API Prototype</b>

<code>UT_RV UT_API UT_Finalize()</code>

<b>Description</b>

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

<b>Parameters</b>

n/a

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
ret = UT_Finalize();
</source>

== UT_GetTokenList ==

<b>API Prototype</b>

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

<b>Description</b>

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

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>lpSlotID</td>
<td>[out] slot ID list</td>
</tr>
<tr>
<td>lpTokenCount</td>
<td>
* [in] size of buffer (0~32 bytes)
* [out]number of token
</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
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);
</source>

== UT_OpenDevice ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_OpenDevice(
UT_SLOT_ID SlotID,
UT_HANDLE* lputHandle
);
</source>

<b>Description</b>

To open the device in the specified slot.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>SlotID</td>
<td>[in] the specified slot</td>
</tr>
<tr>
<td>lputHandle</td>
<td>[out] device handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_SLOT_ID_INVALUD</td>
<td>Invalid slot ID</td>
</tr>
</table>

<b>Usage Note</b>

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

<b>Sample</b>

See the sample of <code>UT_GetTokenList</code>

== UT_CloseDevice ==

<b>Prototype</b>

<code>UT_RV UT_API UT_CloseDevice(UT_HANDLE utHandle);</code>

<b>Description</b>

To close the specified device.

<b>Parameters</b>

n/a

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
</table>

<b>Sample</b>

See also the sample of <code>UT_GetTokenList</code>

== UT_GetHandle ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_GetHandle(
UT_SLOT_ID SlotID,
UT_HANDLE* lputHandle
);
</source>

<b>Description</b>

To get device handle by Slot ID.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>SlotID [in]</td>
<td>the specified slot</td>
</tr>
<tr>
<td>lputHandle [out]</td>
<td>device handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
</table>

<b>Sample</b>

See the sample of <code>UT_GetTokenList</code>

== UT_GetSlotID ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_GetSlotID(
UT_HANDLE utHandle,
UT_SLOT_ID* lpSlotID
);
</source>

<b>Description</b>

To get Slot ID by device handle.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>the specified handle</td>
</tr>
<tr>
<td>lpSlotID [out]</td>
<td>Slot ID</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALIDM</td>
<td>Invalid token handle</td>
</tr>
</table>

<b>Sample</b>

See the sample of <code>UT_GetTokenList</code>

== UT_GetSlotStatus ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_GetSlotStatus(
UT_STATUS* lpStatus,
UT_SLOT_ID* lpSlotID
);
</source>

<b>Description</b>

To get the status of Slot.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>lpStatus [out]</td>
<td>the current status of slot</td>
</tr>
<tr>
<td>lpSlotID [out]</td>
<td>Slot ID</td>
</tr>
</table>

<b>Notes:</b>

lpStatus can be:

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

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
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
}
}
</source>

== UT_GetTokenType ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_GetTokenType(
UT_HANDLE utHandle,
char* lpszTokenType
);
</source>

<b>Description</b>

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

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpszTokenType [out]</td>
<td>UniToken type (string, 32 bytes)</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
char TokenType[33] = {0};
ret = UT_GetTokenType(utHandle, (char *)TokenType);
</source>

== UT_GetFirmwareVersion ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_GetFirmwareVersion(
UT_HANDLE utHandle,
unsigned long* lpVersion
);
</source>

<b>Description</b>

To get the version of firmware.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpVersion [out]</td>
<td>firmware version</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned long Version;
ret = UT_GetFirmwareVersion(utHandle, &Version);
</source>

== UT_Logoff ==

<b>Prototype</b>

<code>UT_RV UT_API UT_Logoff(UT_HANDLE utHandle);</code>

<b>Description</b>

To log off the specified Token.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
</table>

<b>Sample</b>

See the sample of <code>UT_Logon</code>

== UT_Logon ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_Logon(
UT_HANDLE utHandle,
unsigned long UserLevel,
unsigned char* lpszPin
);
</source>

<b>Description</b>

To logon the specified token.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>UserLevel [in]</td>
<td>levels of permission</td>
</tr>
<tr>
<td>lpszPin [in]</td>
<td>the corresponding password with certain permission level</td>
</tr>
</table>

<b>Note:</b>

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

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_PIN_ERROR</td>
<td>Wrong password</td>
</tr>
<tr>
<td>UT_USER_FULL</td>
<td>No more sessions allowed</td>
</tr>
<tr>
<td>UT_USER_LOCKED</td>
<td>Token locked</td>
</tr>
</table>

<b>Usage Note</b>

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.

<b>Sample</b>

<source lang="C">
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);
</source>

== UT_GetCurrentUserLevel ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_GetCurrentUserLevel(
UT_HANDLE utHandle,
unsigned long* lpUserLevel
);
</source>

<b>Description</b>

To get the current permission level.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpUserLevel [out]</td>
<td>Permission level</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
</table>

<b>Sample</b>

See the sample of UT_Logon.

== UT_ChangePin ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_ChangePin(
UT_HANDLE utHandle,
unsigned char UserLevel,
unsigned long ChangeMode,
unsigned char* OldPin,
unsigned char* NewPin
);
</source>

<b>Description</b>

To change the PIN.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>UserLevel [in]</td>
<td>permission level</td>
</tr>
<tr>
<td>ChangeMode [in]</td>
<td>mode to change to</td>
</tr>
<tr>
<td>OldPIN [in]</td>
<td>old PIN</td>
</tr>
<tr>
<td>NewPin [in]</td>
<td>new PIN</td>
</tr>
</table>

<b>Notes:</b>

Change Mode can be <code>UT_CHANGE_PIN_MODE_BYSELF</code> or <code>UT_CHANGE_PIN_MODE_ADMIN_CHANGE_USER</code>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NOT_ALLOWED</td>
<td>Operation not allowed</td>
</tr>
</table>

<b>Usage Note</b>

Two ways of changing password:

# 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 <code>UT_CHANGE_PIN_MODE_BYSELF</code>
# Admin resets user password. Log on as ADMIN and type in new password of USER. Here, the mode of changing PIN is <code>UT_CHANGE_PIN_MODE_ADMIN_CHANGE_USER</code> In this case, OldPin is not required.

<b>Sample</b>

<source lang="C">
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);
</source>

== UT_GetID ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_GetID(
UT_HANDLE utHandle,
char* lpszId
);
</source>

<b>Description</b>

To get the token ID of specified device.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpszId [out]</td>
<td>UniToken ID (string, 32 bytes)</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
</table>

<b>Sample</b>

See the sample of <code>UT_SetID</code>

== UT_SetID ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_SetID(
UT_HANDLE utHandle,
char* lpszId
);
</source>

<b>Description</b>

To set the token ID of the specified device

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpszId [out]</td>
<td>UniToken ID (string, 32 bytes)</td>
</tr>
</table>

<b>Returned value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
char Id[33] = "UniTokenPRO";
unsigned long UserLevel;
ret = UT_SetID(utHandle, Id);
ret = UT_GetID(utHandle, Id);
</source>

== UT_GetHID ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_GetHID(
UT_HANDLE utHandle,
unsigned long* lpHid
);
</source>

<b>Description</b>

To get the Hardware ID of the specified device

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpHid [out]</td>
<td>Hardware ID</td>
</tr>
</table>

<b>Returned value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned long Hid;
ret = UT_GetHID(utHandle, &Hid);
</source>

== UT_GetSoftID ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_GetSoftID(
UT_HANDLE utHandle,
unsigned long* lpSoftID
);
</source>

<b>Description</b>

To get the Software ID of the specified device

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpSoftID [out]</td>
<td>Software ID</td>
</tr>
</table>

<b>Returned value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
</table>

<b>Sample</b>

See also the sample of <code>UT_SetSoftID</code>

== UT_SetSoftID ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_SetSoftID(
UT_HANDLE utHandle,
unsigned long SoftID
);
</source>

<b>Description</b>

To set the Software ID of the specified device.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpSoftID [out]</td>
<td>Software ID</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned long SoftID = 0;
ret = UT_GetSoftID(utHandle, &SoftID);
ret = UT_SetSoftID(utHandle, SoftID);
</source>

== UT_LED ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_LED(
UT_HANDLE utHandle,
unsigned char On
);
</source>

<b>Description</b>

To turn on/off LED.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>On [in]</td>
<td>the status of the LED</td>
</tr>
</table>

<b>Notes:</b>

The parameter On can be <code>LED_ON</code> or <code>LED_OFF</code>

<b>Returned value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
ret = UT_LED(utHandle, LED_ON);
</source>

== UT_SetAttemptCount ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_SetAttemptCount(
UT_HANDLE utHandle,
unsigned long MaxAttempt
);
</source>

<b>Description</b>

To set the maximum times of PIN attempt

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>MaxAttempt [in]</td>
<td>maximum attempt times</td>
</tr>
</table>

<b>Notes:</b>

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.

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
</table>

<b>Usage Note</b>

This function is used for unlocking the token.

<b>Sample</b>

See the sample of <code>UT_GetAttemptCount</code>

== UT_GetAttemptCount ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_GetAttemptCount(
UT_HANDLE utHandle,
unsigned long* lpUserAttempt,
unsigned long* lpAdminAttempt
);
</source>

<b>Description</b>

To count the number of failed login attempts.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpUserAttempt [out]</td>
<td>User PIN attempt times</td>
</tr>
<tr>
<td>lpAdminAttempt [out]</td>
<td>Admin PIN attempt times</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned long UserAttempt;
unsigned long AdminAttempt;
ret = UT_SetAttemptCount(utHandle, 15);
ret = UT_GetAttemptCount(utHandle, &UserAttempt, &AdminAttempt);
</source>

== UT_Format ==

<b>Prototype</b>

<code>UT_RV UT_API UT_Format(UT_HANDLE utHandle);</code>

<b>Description</b>

To format a UniToken.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
</table>

<b>Usage Note:</b>
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.

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
ret = UT_Format(utHandle);
</source>

== UT_Rand ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_Rand(
UT_HANDLE utHandle,
unsigned long Length,
unsigned char* lpOut,
void* lpReserve
);
</source>

<b>Description</b>

To generate random numbers.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>Length [in]</td>
<td>length of random number (in bytes)</td>
</tr>
<tr>
<td>lpOut [out]</td>
<td>random number</td>
</tr>
<tr>
<td>lpReserve</td>
<td>reserved for future use</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned char OutRand[8];
ret = UT_Rand(utHandle, 8, OutRand, NULL);
</source>

== UT_DESGenerateKey ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_DESGenerateKey(
UT_HANDLE utHandle,
KEY_HANDLE_PTR lpKeyHandle
);
</source>

<b>Description</b>

To generate a DES key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Note:</b>

The length of generated DES key is 8 bytes.

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_FULL</td>
<td>no more keys can be generated</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_DESGenerateKey(utHandle, &KeyHandle);
</source>

== UT_DESEncrypt ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_DESEncryptZ(
UT_HANDLE utHandle,
KEY_HANDLE KeyHandle,
unsigned char* lpData,
unsigned long DataLength,
unsigned char* lpEncryptedData,
unsigned long* lpEncryptedDataLength
);
</source>

<b>Description</b>

To encrypt data with DES.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
<tr>
<td>lpData [in]</td>
<td>plaintext</td>
</tr>
<tr>
<td>DataLength [in]</td>
<td>length of plaintext in bytes</td>
</tr>
<tr>
<td>lpEncryptedData [out]</td>
<td>ciphertext</td>
</tr>
<tr>
<td>lpEncryptedDataLength [out]</td>
<td>length of ciphertext</td>
</tr>
</table>

<b>Notes:</b>

DateLength is <code>DES_DATA_LEN_8_BYTE</code>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
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
);
</source>

== UT_DESDecrypt ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_DESDecrypt(
UT_HANDLE utHandle,
KEY_HANDLE KeyHandle,
unsigned char* lpEncryptedData,
unsigned long EncryptedDataLength,
unsigned char* lpData,
unsigned long* lpDataLength
);
</source>

<b>Description</b>

To decrypt data with DES.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
<tr>
<td>lpEncryptedData [in]</td>
<td>ciphertext</td>
</tr>
<tr>
<td>EncryptedDataLength [in]</td>
<td>length of ciphertext in bytes</td>
</tr>
<tr>
<td>lpData [out]</td>
<td>plaintext</td>
</tr>
<tr>
<td>lpDataLength [out]</td>
<td>length of plaintext</td>
</tr>
</table>

<b>Notes:</b>

EncryptedDataLength is <code>DES_DATA_LEN_8_BYTE</code>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
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
);
</source>

== UT_DESImportKey ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_DESImportKey(
UT_HANDLE utHandle,
unsigned char* lpKey,
KEY_HANDLE_PTR lpKeyHandle
);
</source>

<b>Description</b>

To import a DES key to UniToken device.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKey [in]</td>
<td>DES key</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_FULL</td>
<td>No more keys can be generated</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
unsigned char Key[DES_KEY_LEN_8_BYTE];
ret = UT_DESImportKey(utHandle, Key, &KeyHandle);
</source>

== UT_DESDeleteKey ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_DESDeleteKey(
UT_HANDLE utHandle,
KEY_HANDLE KeyHandle
);
</source>

<b>Description</b>

To delete a DES key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_DESDeleteKey(utHandle, KeyHandle);
</source>

== UT_DESGetKeyCount ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_DESGetKeyCount(
UT_HANDLE utHandle,
unsigned long* lpKeyCount
);
</source>

<b>Description</b>

To count DES keys.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyCount [out]</td>
<td>the number of keys</td>
</tr>
</table>

<b>Notes:</b>

The maximum number of DES keys is 16.

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned long KeyCount;
ret = UT_DESGetKeyCount(utHandle, &KeyCount);
</source>

== UT_DESGetFirstKeyHandle ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_DESGetFirstKeyHandle(
UT_HANDLE utHandle,
KEY_HANDLE_PTR lpKeyHandle
);
</source>

<b>Description</b>

To get the handle of the first DES key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
</table>

<b>Sample</b>

See also the sample of <code>UT_DESGetNextKeyHandle</code>

== UT_DESGetNextKeyHandle ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_DESGetNextKeyHandle(
UT_HANDLE utHandle,
KEY_HANDLE_PTR lpKeyHandle
);
</source>

<b>Description</b>

To get the handle of the next DES key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
<tr>
<td>UT_OPERATE_INVALID</td>
<td>Invalid operation</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_DESGetFirstKeyHandle(utHandle, &KeyHandle);
ret = UT_DESGetNextKeyHandle(utHandle, &KeyHandle);
</source>

== UT_DES3GenerateKey ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_DES3GenerateKey(
UT_HANDLE utHandle,
KEY_HANDLE_PTR lpKeyHandle
);
</source>

<b>Description</b>

To generate a 3DES key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Note:</b>

The length of generated 3DES key is 24 bytes.

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_FULL</td>
<td>no more keys can be generated</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_DES3GenerateKey(utHandle, &KeyHandle);
</source>

== UT_DES3Encrypt ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_DES3Encrypt(
UT_HANDLE utHandle,
KEY_HANDLE KeyHandle,
unsigned char* lpData,
unsigned long DataLength,
unsigned char* lpEncryptedData,
unsigned long* lpEncryptedDataLength
);
</source>

<b>Description</b>

To encrypt data with 3DES.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
<tr>
<td>lpData [in]</td>
<td>plaintext</td>
</tr>
<tr>
<td>DataLength [in]</td>
<td>length of plaintext</td>
</tr>
<tr>
<td>lpEncryptedData [out]</td>
<td>ciphertext</td>
</tr>
<tr>
<td>lpEncryptedDataLength [out]</td>
<td>length of ciphertext</td>
</tr>
</table>

<b>Notes:</b>

DateLength is <code>DES_DATA_LEN_8_BYTE</code>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
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
);
</source>

== UT_DES3Decrypt ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_DES3Decrypt(
UT_HANDLE utHandle,
KEY_HANDLE KeyHandle,
unsigned char* lpEncryptedData,
unsigned long EncryptedDataLength,
unsigned char* lpData,
unsigned long* lpDataLength
);
</source>

<b>Description</b>

To decrypt data with 3DES.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
<tr>
<td>lpEncryptedData [in]</td>
<td>ciphertext</td>
</tr>
<tr>
<td>EncryptedDataLength [in]</td>
<td>length of ciphertext</td>
</tr>
<tr>
<td>lpData [out]</td>
<td>plaintext</td>
</tr>
<tr>
<td>lpDataLength [out]</td>
<td>length of plaintext</td>
</tr>
</table>

<b>Notes:</b>

EncryptedDataLength is <code>DES_DATA_LEN_8_BYTE</code>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
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
);
</source>

== UT_DES3ImportKey ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_DES3ImportKey(
UT_HANDLE utHandle,
unsigned char* lpKey,
KEY_HANDLE_PTR lpKeyHandle
);
</source>

<b>Description</b>

To import 3DES keys to UniToken device.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKey [in]</td>
<td>3DES key</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_FULL</td>
<td>No more keys can be generated</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
unsigned char Key[DES3_KEY_LEN_24_BYTE];
ret = UT_DES3ImportKey(utHandle, Key, &KeyHandle);
</source>

== UT_DES3DeleteKey ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_DES3DeleteKey(
UT_HANDLE utHandle,
KEY_HANDLE KeyHandle
);
</source>

<b>Description</b>

To delete a 3DES key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_DES3DeleteKey(utHandle, KeyHandle);
</source>

== UT_DES3GetKeyCount ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_DES3GetKeyCount(
UT_HANDLE utHandle,
unsigned long* lpKeyCount
);
</source>

<b>Description</b>

To count 3DES keys.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyCount [out]</td>
<td>the number of keys</td>
</tr>
</table>

<b>Notes:</b>

The maximum number of 3DES keys is 16.

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned long KeyCount;
ret = UT_DES3GetKeyCount(utHandle, &KeyCount);
</source>

== UT_DES3GetFirstKeyHandle ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_DES3GetFirstKeyHandle(
UT_HANDLE utHandle,
KEY_HANDLE_PTR lpKeyHandle
);
</source>

<b>Description</b>

To get the handle of the first 3DES key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
</table>

<b>Sample</b>

See also the samples of <code>UT_DES3GetNextKeyHandle</code>

== UT_DES3GetNextKeyHandle ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_DES3GetNextKeyHandle(
UT_HANDLE utHandle,
KEY_HANDLE_PTR lpKeyHandle
);
</source>

<b>Description</b>

To get the handle of the next 3DES key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
<tr>
<td>UT_OPERATE_INVALID</td>
<td>Invalid operation</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_DES3GetFirstKeyHandle(utHandle, &KeyHandle);
ret = UT_DES3GetNextKeyHandle(utHandle, &KeyHandle);
</source>

== UT_AESGenerateKey ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_AESGenerateKey(
UT_HANDLE utHandle,
unsigned long KeyLength,
KEY_HANDLE_PTR lpKeyHandle
);
</source>

<b>Description</b>

To generate an AES key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyLength [in]</td>
<td>key length</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Notes:</b>

KeyLength can be <code>AES_KEY_LEN_128_BIT</code> or <code>AES_KEY_LEN_192_BIT</code>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_FULL</td>
<td>No more keys can be generated</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_AESGenerateKey(utHandle, AES_KEY_LEN_128_BIT, &KeyHandle);
</source>

== UT_AESEncrypt ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_AESEncrypt(
UT_HANDLE utHandle,
KEY_HANDLE KeyHandle,
unsigned char* lpData,
unsigned long DataLength,
unsigned char* lpEncryptedData,
unsigned long* lpEncryptedDataLength
);
</source>

<b>Description</b>

To encrypt data with AES.

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
<tr>
<td>lpData [in]</td>
<td>plaintext</td>
</tr>
<tr>
<td>DataLength [in]</td>
<td>length of plaintext</td>
</tr>
<tr>
<td>lpEncryptedData [out]</td>
<td>ciphertext</td>
</tr>
<tr>
<td>lpEncryptedDataLength [out]</td>
<td>length of ciphertext</td>
</tr>
</table>

<b>Notes:</b>

DateLength is <code>AES_DATA_LEN_16_BYTE</code>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
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
);
</source>

== UT_AESDecrypt ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_AESDecrypt(
HANDLE utHandle,
KEY_HANDLE KeyHandle,
unsigned char* lpEncryptedData,
unsigned long EncryptedDataLength,
unsigned char* lpData,
unsigned long* lpDataLength
);
</source>

<b>Description</b>

To decrypt data with AES.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
<tr>
<td>lpEncryptedData [in]</td>
<td>ciphertext</td>
</tr>
<tr>
<td>EncryptedDataLength [in]</td>
<td>length of ciphertext</td>
</tr>
<tr>
<td>lpData [out]</td>
<td>plaintext</td>
</tr>
<tr>
<td>lpDataLength [out]</td>
<td>length of plaintext</td>
</tr>
</table>

<b>Notes:</b>

DateLength is <code>AES_DATA_LEN_16_BYTE</code>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
unsigned char Data[AES_DATA_LEN_16_BYTE];
unsigned char EncryptedData[AES_DATA_LEN_16_BYTE];
unsigned long DataLength;
ret = UT_AESDecrypt(handle,
KeyHandle,
EncryptedData,
AES_DATA_LEN_16_BYTE,
Data,
&DataLength
);
</source>

== UT_AESImportKey ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_AESImportKey(
HANDLE utHandle,
unsigned char* lpKey,
unsigned long KeyLength,
KEY_HANDLE_PTR lpKeyHandle
);
</source>

<b>Description</b>

To import AES key to UniToken device.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyLength [in]</td>
<td>key length</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Notes:</b>

KeyLength can be <code>AES_KEY_LEN_128_BIT</code> or <code>AES_KEY_LEN_192_BIT</code>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_FULL</td>
<td>No more keys can be generated</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
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);
</source>

== UT_AESDeleteKey ==

<b>Prototype</b>

<code>UT_RV UT_API UT_AESDeleteKey(UT_HANDLE utHandle, KEY_HANDLE KeyHandle);</code>

<b>Description</b>

To delete an AES key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_AESDeleteKey(utHandle, KeyHandle);
</source>

== UT_AESGetKeyCount ==

<b>Prototype</b>

<code>UT_RV UT_API UT_AESGetKeyCount(UT_HANDLE utHandle, unsigned long* lpKeyCount);</code>

<b>Description</b>

To count AES keys.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyCount [out]</td>
<td>the number of keys</td>
</tr>
</table>

<b>Notes:</b>

The maximum number of 3DES keys is 32.

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned long KeyCount;
ret = UT_AESGetKeyCount(utHandle, &KeyCount);
</source>

== UT_AESGetKeyLen ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_AESGetKeyLen(
UT_HANDLE utHandle,
KEY_HANDLE KeyHandle,
unsigned long* lpKeyLength
);
</source>

<b>Description</b>

To get the length of AES key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
<tr>
<td>lpKeyLength [out]</td>
<td>key length</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
unsigned long KeyLength;
ret = UT_AESGetKeyLen(utHandle, KeyHandle, &KeyLength);
</source>

== UT_AESGetFirstKeyHandle ==

<b>Prototype</b>

<code>UT_RV UT_API UT_AESGetFirstKeyHandle(UT_HANDLE utHandle, KEY_HANDLE_PTR lpKeyHandle);</code>

<b>Description</b>

To get the handle of the first AES key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
</table>

<b>Sample</b>

See also the sample of <code>UT_AESGetNextKeyHandle</code>

== UT_AESGetNextKeyHandle ==

<b>Prototype</b>

<code>UT_RV UT_API UT_AESGetNextKeyHandle(UT_HANDLE utHandle, KEY_HANDLE_PTR lpKeyHandle);</code>

<b>Description</b>

To get the handle of the next AES key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
<tr>
<td>UT_OPERATE_INVALID</td>
<td>Invalid operation</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_AESGetFirstKeyHandle(utHandle, &KeyHandle);
ret = UT_AESGetNextKeyHandle(utHandle, &KeyHandle);
</source>

== UT_RSAGenerateKeyPair ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_RSAGenerateKeyPair(
UT_HANDLE utHandle,
unsigned long ModulusBits,
unsigned long PubExp,
KEY_HANDLE_PTR lpPubKeyHandle,
KEY_HANDLE_PTR lpPriKeyHandle
);
</source>

<b>Description</b>

To generate RSA key pair.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>ModulusBits [in]</td>
<td>modulus length</td>
</tr>
<tr>
<td>PubExp [in]</td>
<td>public exponent</td>
</tr>
<tr>
<td>lpPubKeyHandle [out]</td>
<td>public key handle</td>
</tr>
<tr>
<td>lpPriKeyHandle [out]</td>
<td>private key handle</td>
</tr>
</table>

<b>Notes:</b>

# UniToken device can store as many as 16 RSA key pairs
# ModulusBits can be <code>RSA_MODULUS_LEN_1024_BIT</code> or <code>RSA_MODULUS_LEN_2048_BIT</code>
# PubExp is <code>RSA_PUBEXP_LEN_65537_BIT</code>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_FULL</td>
<td>No more keys can be generated</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
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
);
</source>

== UT_RSAPubKeyEncrypt ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_RSAPubKeyEncrypt(
UT_HANDLE utHandle,
KEY_HANDLE PubKeyHandle,
unsigned char* lpData,
unsigned long DataLength,
unsigned char* lpEncryptedData,
unsigned long* lpEncryptedDataLength
);
</source>

<b>Description</b>

To encrypt data with RSA public key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
<tr>
<td>lpData [in]</td>
<td>plaintext</td>
</tr>
<tr>
<td>lpDataLength [in]</td>
<td>length of plaintext</td>
</tr>
<tr>
<td>lpEncryptedData [out]</td>
<td>ciphertext</td>
</tr>
<tr>
<td>EncryptedDataLength [out]</td>
<td>length of ciphertext</td>
</tr>
</table>

<b>Notes:</b>

DataLength can be <code>RSA_DATA_LEN_1024_BIT</code> or <code>SA_DATA_LEN_2048_BIT</code>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Usage Note</b>

The handle of public key should be retrieved with <code>UT_RSAGetPubKeyByPriKey</code> 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.

<b>Sample</b>

<source lang="C">
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
);
</source>

== UT_RSAPriKeyDecrypt ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_RSAPriKeyDecrypt(
UT_HANDLE utHandle,
KEY_HANDLE PriKeyHandle,
unsigned char* lpEncryptedData,
unsigned long EncryptedDataLength,
unsigned char* lpData,
unsigned long* lpDataLength
);
</source>

<b>Description</b>

To decrypt data with RSA private key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
<tr>
<td>lpEncryptedData [in]</td>
<td>ciphertext</td>
</tr>
<tr>
<td>EncryptedDataLength [in]</td>
<td>length of ciphertext</td>
</tr>
<tr>
<td>lpData [out]</td>
<td>plaintext</td>
</tr>
<tr>
<td>lpDataLength [out]</td>
<td>length of plaintext</td>
</tr>
</table>

<b>Notes:</b>

DataLength can be <code>RSA_DATA_LEN_1024_BIT</code> or <code>SA_DATA_LEN_2048_BIT</code>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Usage Note</b>

The handle of private key should be retrieved with <code>RSAGetPriKeyByPubKey</code> 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.

<b>Sample</b>

<source lang="C">
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
);
</source>

== UT_RSAPriKeyEncrypt ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_RSAPriKeyEncrypt(
UT_HANDLE utHandle,
KEY_HANDLE PriKeyHandle,
unsigned char* lpData,
unsigned long DataLength,
unsigned char* lpEncryptedData,
unsigned long* lpEncryptedDataLength
);
</source>

<b>Description</b>

To encrypt data with RSA private key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
<tr>
<td>lpData [in]</td>
<td>plaintext</td>
</tr>
<tr>
<td>lpDataLength [in]</td>
<td>length of plaintext</td>
</tr>
<tr>
<td>lpEncryptedData [out]</td>
<td>ciphertext</td>
</tr>
<tr>
<td>EncryptedDataLength [out]</td>
<td>length of ciphertext</td>
</tr>
</table>

<b>Notes:</b>

DataLength can be <code>RSA_DATA_LEN_1024_BIT</code> or <code>SA_DATA_LEN_2048_BIT</code>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Usage Note</b>

The handle of private key should be retrieved with <code>UT_RSAGetPriKeyByPubKey</code> 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.

<b>Sample</b>

<source lang="C">
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
);
</source>

== UT_RSAPubKeyDecrypt ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_RSAPubKeyDecrypt(
UT_HANDLE utHandle,
KEY_HANDLE PubKeyHandle,
unsigned char* lpEncryptedData,
unsigned long EncryptedDataLength,
unsigned char* lpData,
unsigned long* lpDataLength
);
</source>

<b>Description</b>

To decrypt data with RSA public key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
<tr>
<td>lpEncryptedData [in]</td>
<td>ciphertext</td>
</tr>
<tr>
<td>EncryptedDataLength [in]</td>
<td>length of ciphertext</td>
</tr>
<tr>
<td>lpData [out]</td>
<td>plaintext</td>
</tr>
<tr>
<td>lpDataLength [out]</td>
<td>length of plaintext</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Usage Note</b>

The handle of public key should be retrieved with <code>UT_RSAGetPubKeyByPriKey</code> 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.

<b>Sample</b>

<source lang="C">
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
);
</source>

== UT_RSAGetKeyPairCount ==

<b>Prototype</b>

<code>UT_RV UT_API UT_RSAGetKeyPairCount(UT_HANDLE utHandle, unsigned long* lpKeyCount);</code>

<b>Description</b>

To count RSA keys.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyCount [out]</td>
<td>the number of key pairs</td>
</tr>
</table>

<b>Notes</b>

The maximum number of RSA key pairs is 16.

<b>Returned value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned long KeyCount;
ret = UT_RSAGetKeyPairCount(utHandle, &KeyCount);
</source>

== UT_RSAGetFirstKeyPairHandle ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_RSAGetFirstKeyPairHandle(
UT_HANDLE utHandle,
KEY_HANDLE_PTR lpPubKeyHandle,
KEY_HANDLE_PTR lpPriKeyHandle
);
</source>

<b>Description</b>

To get the handles of the first RSA key pair.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpPubKeyHandle [out]</td>
<td>public key handle</td>
</tr>
<tr>
<td>lpPriKeyHandle [out]</td>
<td>private key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
</table>

<b>Sample</b>

See also the sample of <code>UT_RSAGetNextKeyPairHandle</code>

== UT_RSAGetNextKeyPairHandle ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_RSAGetNextKeyPairHandle(
UT_HANDLE utHandle,
KEY_HANDLE_PTR lpPubKeyHandle,
KEY_HANDLE_PTR lpPriKeyHandle
);
</source>

<b>Description</b>

To get the handles of the next RSA key pair.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpPubKeyHandle [out]</td>
<td>public key handle</td>
</tr>
<tr>
<td>lpPriKeyHandle [out]</td>
<td>private key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
<tr>
<td>UT_OPERATE_INVALID</td>
<td>Invalid operation</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE PubKeyHandle;
KEY_HANDLE PriKeyHandle;
ret = UT_RSAGetFirstKeyPairHandle(utHandle, &PubKeyHandle, &PriKeyHandle);
ret = UT_RSAGetNextKeyPairHandle(utHandle, &PubKeyHandle, &PriKeyHandle);
</source>

== UT_RSAPubKeyImport ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_RSAPubKeyImport(
UT_HANDLE utHandle,
UT_RSA* lpRsaKey,
KEY_HANDLE PriKeyHandle,
KEY_HANDLE_PTR lpPubKeyHandle
);
</source>

<b>Description</b>

To import RSA public key to UniToken device.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>PriKeyHandle [in]</td>
<td>private key handle</td>
</tr>
<tr>
<td>lpPubKeyHandle [out]</td>
<td>public key handle</td>
</tr>
</table>

<b>Notes</b>

PriKeyHandle can be the existing private key handle or <code>RSA_IMPORT_NEW</code>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
<tr>
<td>UT_KEY_EXIST</td>
<td>Key already exists</td>
</tr>
<tr>
<td>UT_KEY_FULL</td>
<td>No more keys can be generated</td>
</tr>
</table>

<b>Usage Note</b>

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 <code>UT_KEY_HANDLE_INVALID</code> If PriKeyHandle is <code>RSA_IMPORT_NEW</code> 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 <code>UT_KEY_FULL</code>

<b>Sample</b>

See the sample of <code>UT_RSAPriKeyImport</code>

== UT_RSAPriKeyImport ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_RSAPriKeyImport(
UT_HANDLE utHandle,
UT_RSA* lpRsaKey,
KEY_HANDLE PubKeyHandle,
KEY_HANDLE_PTR lpPriKeyHandle
);
</source>

<b>Description</b>

To import RSA private key to UniToken device.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>PubKeyHandle [in]</td>
<td>public key handle</td>
</tr>
<tr>
<td>lpPriKeyHandle [out]</td>
<td>private key handle</td>
</tr>
</table>

<b>Notes:</b>

PubKeyHandle can be the existing public key handle or <code>RSA_IMPORT_NEW</code>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
<tr>
<td>UT_KEY_EXIST</td>
<td>Key already exists</td>
</tr>
<tr>
<td>UT_KEY_FULL</td>
<td>No more keys can be generated</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
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
);
</source>

== UT_RSAPubKeyExport ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_RSAPubKeyExport(
UT_HANDLE utHandle,
KEY_HANDLE PubKeyHandle,
unsigned long* lpModulusBits,
UT_RSA* lpRsaKey
);
</source>

<b>Description</b>

To export RSA public key from UniToken device.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>PubKeyHandle [in]</td>
<td>public key handle</td>
</tr>
<tr>
<td>lpModulusBits [out]</td>
<td>modulus length</td>
</tr>
<tr>
<td>lpRsaKey [out]</td>
<td>RSA public key structure</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
<tr>
<td>UT_KEY_EXIST</td>
<td>Key already exists</td>
</tr>
<tr>
<td>UT_KEY_FULL</td>
<td>No more keys can be generated</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
UT_RSA RsaKey;
KEY_HANDLE PubKeyHandle;
unsigned long ModulusBits;
ret = UT_RSAPubKeyExport(utHandle, PubKeyHandle, &ModulusBits, &RsaKey);
</source>

== UT_RSAGetPubKeyHandle ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_RSAGetPubKeyHandle(
UT_HANDLE utHandle,
KEY_HANDLE PriKeyHandle,
KEY_HANDLE_PTR lpPubKeyHandle
);
</source>

<b>Description</b>

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

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>PriKeyHandle [in]</td>
<td>private key handle</td>
</tr>
<tr>
<td>lpPubKeyHandle [out]</td>
<td>the corresponding public key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE PubKeyHandle;
KEY_HANDLE PriKeyHandle;
ret = UT_RSAGetPubKeyHandle(utHandle, PriKeyHandle, &PubKeyHandle);
</source>

== UT_RSAGetPriKeyHandle ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_RSAGetPriKeyHandle(
UT_HANDLE utHandle,
KEY_HANDLE PubKeyHandle,
KEY_HANDLE_PTR lpPriKeyHandle
);
</source>

<b>Description</b>

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

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>PubKeyHandle [in]</td>
<td>public key handle</td>
</tr>
<tr>
<td>lpPriKeyHandle [out]</td>
<td>the corresponding private key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE PubKeyHandle;
KEY_HANDLE PriKeyHandle;
ret = UT_RSAGetPriKeyHandle(utHandle, PubKeyHandle, &PriKeyHandle);
</source>

== UT_RSAGetKeyPairModulus ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_RSAGetKeyPairModulus(
UT_HANDLE utHandle,
KEY_HANDLE PubKeyHandle,
unsigned long* lpModulusBits
);
</source>

<b>Description</b>

To get RSA key pair modulus.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>PubKeyHandle [in]</td>
<td>public key handle</td>
</tr>
<tr>
<td>lpModulusBits [out]</td>
<td>modulus length</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE PubKeyHandle;
unsigned long ModulusBits;
ret = UT_RSAGetKeyPairModulus(utHandle, PubKeyHandle, &ModulusBits);
</source>

== UT_RSADeleteKeyPair ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_RSADeleteKeyPair(
UT_HANDLE utHandle,
KEY_HANDLE PubKeyHandle,
KEY_HANDLE PriKeyHandle
);
</source>

<b>Description</b>

To delete the RSA key pair.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>PubKeyHandle [in]</td>
<td>public key handle</td>
</tr>
<tr>
<td>PriKeyHandle [in]</td>
<td>private key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Usage Note</b>

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

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE PubKeyHandle;
KEY_HANDLE PriKeyHandle;
ret = UT_RSADeleteKeyPair(utHandle, PubKeyHandle, PriKeyHandle);
</source>

== UT_MD5HMACGenerateKey ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_MD5HMACGenerateKey(
UT_HANDLE utHandle,
unsigned long KeyLength,
KEY_HANDLE_PTR lpKeyHandle
);
</source>

<b>Description</b>

To generate HMAC-MD5 key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyLength [in]</td>
<td>key length</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Notes:</b>

The length of key is <= 128 bytes

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_FULL</td>
<td>No more keys can be generated</td>
</tr>
</table>

<b>Usage Note</b>

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 <code>UT_KEY_FULL</code>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_MD5HMACGenerateKey(utHandle, 128, &KeyHandle);
</source>

== UT_MD5HMAC ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_MD5HMAC(
UT_HANDLE utHandle,
KEY_HANDLE KeyHandle,
unsigned char* lpData,
unsigned long DataLength,
unsigned char* lpDigest
);
</source>

<b>Description</b>

To run HMAC-MD5 algorithm.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
<tr>
<td>lpData [in]</td>
<td>data to be digested</td>
</tr>
<tr>
<td>DataLength [in]</td>
<td>data length</td>
</tr>
<tr>
<td>lpDigest [out]</td>
<td>digested data</td>
</tr>
</table>

<b>Notes:</b>

DataLength is 1~128 bytes. lpDigest is 16 bytes

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
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);
</source>

== UT_MD5 ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_MD5(
UT_HANDLE utHandle,
unsigned char* lpData,
unsigned long DataLength,
unsigned char* lpDigest
);
</source>

<b>Description</b>

To run MD5 algorithm.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpData [in]</td>
<td>data to be digested</td>
</tr>
<tr>
<td>DataLength [in]</td>
<td>data length</td>
</tr>
<tr>
<td>lpDigest [out]</td>
<td>digested data</td>
</tr>
</table>

<b>Notes</b>

DataLength is 1~128 bytes. lpDigest is 16 bytes

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned char Data[128];
unsigned char Digest[16];
ret = UT_MD5(utHandle, Data, 128, Digest);
</source>

== UT_MD5GetKeyCount ==

<b>Prototype</b>

<code>UT_RV UT_API UT_MD5GetKeyCount(UT_HANDLE utHandle, unsigned long* lpKeyCount);</code>

<b>Description</b>

To count HMAC-MD5 keys.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyCount [out]</td>
<td>the number of keys</td>
</tr>
</table>

<b>Notes:</b>

The maximum number of MD5 keys is 8.

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned long KeyCount;
ret = UT_MD5GetKeyCount(utHandle, &KeyCount);
</source>

== UT_MD5GetKeyLen ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_MD5GetKeyLen(
UT_HANDLE utHandle,
KEY_HANDLE KeyHandle,
unsigned long* lpKeyLength
);
</source>

<b>Description</b>

To get the length of HMAC-MD5 key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
<tr>
<td>lpKeyLength [out]</td>
<td>key length</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
unsigned long KeyLength;
ret = UT_MD5GetKeyLen(utHandle, KeyHandle, &KeyLength);
</source>

== UT_MD5GetFirstKeyHandle ==

<b>Prototype</b>

<code>UT_RV UT_API UT_MD5GetFirstKeyHandle(UT_HANDLE utHandle, KEY_HANDLE_PTR lpKeyHandle);</code>

<b>Description</b>

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

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
</table>

<b>Sample</b>

See the samples of <code>UT_MD5GetNextKeyHandle</code>

== UT_MD5GetNextKeyHandle ==

<b>Prototype</b>

<code>UT_RV UT_API UT_MD5GetNextKeyHandle(UT_HANDLE utHandle, KEY_HANDLE_PTR lpKeyHandle);</code>

<b>Description</b>

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

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
<tr>
<td>UT_OPERATE_INVALID</td>
<td>Invalid operation</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_MD5GetFirstKeyHandle(utHandle, &KeyHandle);
ret = UT_MD5GetNextKeyHandle(utHandle, &KeyHandle);
</source>

== UT_MD5DeleteKey ==

<b>Prototype</b>

<code>UT_RV UT_API UT_MD5DeleteKey(UT_HANDLE utHandle, KEY_HANDLE KeyHandle);</code>

<b>Description</b>

To delete HMAC-MD5 key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_MD5DeleteKey(utHandle, KeyHandle);
</source>

== UT_MD5ImportKey ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_MD5ImportKey(
UT_HANDLE utHandle,
unsigned char* lpKey,
unsigned long KeyLength,
KEY_HANDLE_PTR lpKeyHandle
);
</source>

<b>Description</b>

To import HMAC-MD5 key to UniToken device.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyLength [in]</td>
<td>key length</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Notes:</b>

KeyLength is 1~128 bytes.

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_FULL</td>
<td>No more keys can be generated</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
unsigned char Key[128];
ret = UT_MD5ImportKey(utHandle, Key, 128, &KeyHandle);
</source>

== UT_SHA1HMACGenerateKey ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_SHA1HMACGenerateKey(
UT_HANDLE utHandle,
unsigned long KeyLength,
KEY_HANDLE_PTR lpKeyHandle
);
</source>

<b>Description</b>

To generate HMAC-SHA1 key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyLength [in]</td>
<td>key length</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Notes:</b>

The length of key is <=128 bytes.

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_FULL</td>
<td>No more keys can be generated</td>
</tr>
</table>

<b>Usage Note</b>

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 <code>UT_KEY_FULL</code>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_SHA1HMACGenerateKey(utHandle, 128, &KeyHandle);
</source>

== UT_SHA1HMAC ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_SHA1HMAC(
UT_HANDLE utHandle,
KEY_HANDLE KeyHandle,
unsigned char* lpData,
unsigned long DataLength,
unsigned char* lpDigest
);
</source>

<b>Description</b>

To run HMAC-SHA1 algorithm.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
<tr>
<td>lpData [in]</td>
<td>data to be digested</td>
</tr>
<tr>
<td>DataLength [in]</td>
<td>data length</td>
</tr>
<tr>
<td>lpDigest [out]</td>
<td>digested data</td>
</tr>
</table>

<b>Notes:</b>

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

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
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);
</source>

== UT_SHA1 ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_SHA1(
UT_HANDLE utHandle,
unsigned char* lpData,
unsigned long DataLength,
unsigned char* lpDigest
);
</source>

<b>Description</b>

To run SHA1 algorithm.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpData [in]</td>
<td>data to be digested</td>
</tr>
<tr>
<td>DataLength [in]</td>
<td>data length</td>
</tr>
<tr>
<td>lpDigest [out]</td>
<td>digested data</td>
</tr>
</table>

<b>Notes:</b>

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

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned char Data[128];
unsigned char Digest[20];
ret = UT_SHA1(utHandle, Data, 128, Digest);
</source>

== UT_SHA1GetKeyCount ==

<b>Prototype</b>

<code>UT_RV UT_API UT_SHA1GetKeyCount(UT_HANDLE utHandle, unsigned long* lpKeyCount);</code>

<b>Description</b>

To count HMAC-SHA1 keys

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyCount [out]</td>
<td>the number of keys</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned long KeyCount;
ret = UT_SHA1GetKeyCount(utHandle, &KeyCount);
</source>

== UT_SHA1GetKeyLen ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_SHA1GetKeyLen(
UT_HANDLE utHandle,
KEY_HANDLE KeyHandle,
unsigned long* lpKeyLength
);
</source>

<b>Description</b>

To get the length of HMAC-SHA1 key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
<tr>
<td>lpKeyLength [out]</td>
<td>key length</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
unsigned long KeyLength;
ret = UT_SHA1GetKeyLen(utHandle, KeyHandle, &KeyLength);
</source>

== UT_SHA1GetFirstKeyHandle ==

<b>Prototype</b>

<code>UT_RV UT_API UT_SHA1GetFirstKeyHandle(UT_HANDLE utHandle, KEY_HANDLE_PTR lpKeyHandle);</code>

<b>Description</b>

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

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
</table>

<b>Sample</b>

See also the sample of <code>UT_SHA1GetNextKeyHandle</code>

== UT_SHA1GetNextKeyHandle ==

<b>Prototype</b>

<code>UT_RV UT_API UT_SHA1GetNextKeyHandle(UT_HANDLE utHandle, KEY_HANDLE_PTR lpKeyHandle);</code>

<b>Description</b>

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

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
<tr>
<td>UT_OPERATE_INVALID</td>
<td>Invalid operation</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_SHA1GetFirstKeyHandle(utHandle, &KeyHandle);
ret = UT_SHA1GetNextKeyHandle(utHandle, &KeyHandle);
</source>

== UT_SHA1DeleteKey ==

<b>Prototype</b>

<code>UT_RV UT_API UT_SHA1DeleteKey(UT_HANDLE utHandle, KEY_HANDLE KeyHandle);</code>

<b>Description</b>

To delete HMAC-SHA1 key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_SHA1DeleteKey(utHandle, KeyHandle);
</source>

== UT_SHA1ImportKey ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_SHA1ImportKey(
UT_HANDLE utHandle,
unsigned char* lpKey,
unsigned long KeyLength,
KEY_HANDLE_PTR lpKeyHandle
);
</source>

<b>Description</b>

To import HMAC-SHA1 key to UniToken device.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKey [in]</td>
<td>SHA1 key</td>
</tr>
<tr>
<td>KeyLength [in]</td>
<td>key length</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Notes:</b>

KeyLength is 1~128 bytes.

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_FULL</td>
<td>No more keys can be generated</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
unsigned char Key[128];
ret = UT_SHA1ImportKey(utHandle, Key, 128, &KeyHandle);
</source>

== UT_FS_GetSpace ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_FS_GetSpace(
UT_HANDLE utHandle,
unsigned long* UsedSpace,
unsigned long* FreeSpace
);
</source>

<b>Description</b>

To get the size of the free memory.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UsedSize [out]</td>
<td>size of used memory</td>
</tr>
<tr>
<td>FreeSize [out]</td>
<td>size of free memory</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned long UsedSpace;
unsigned long FreeSpace;
ret = UT_FS_GetSpace(utHandle, &UsedSpace, &FreeSpace);
</source>

== UT_FS_GetFileCount ==

<b>Prototype</b>

<code>UT_RV UT_API UT_FS_GetFileCount(UT_HANDLE utHandle, unsigned long* lpFileCount);</code>

<b>Description</b>

To get the number of files.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpFileCount [out]</td>
<td>the number of files</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_FS_NO_FILE</td>
<td>No file found</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned long FileCount;
ret = UT_FS_GetFileCount(utHandle, &FileCount);
</source>

== UT_FS_GetFirstFileName ==

<b>Prototype</b>

<code>UT_RV UT_API UT_FS_GetFirstFileName(UT_HANDLE utHandle, char* lpszFileName);</code>

<b>Description</b>

To get the name of the first file.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpszFileName [out]</td>
<td>filename (string, 16 bytes)</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_FS_NO_FILE</td>
<td>No file found</td>
</tr>
</table>

<b>Sample</b>

See also the sample of <code>UT_GetNextFileName</code>

== UT_FS_GetNextFileName ==

<b>Prototype</b>

<code>UT_RV UT_API UT_FS_GetNextFileName(UT_HANDLE utHandle, char* lpszFileName);</code>

<b>Description</b>
To get the name of the next file.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpszFileName [out]</td>
<td>filename (string, 16 bytes)</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_FS_LIST_END</td>
<td>End of fire list</td>
</tr>
<tr>
<td>UT_OPERATE_INVALID</td>
<td>Invalid operation</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
char FileName[17];
ret = UT_FS_GetFirstFileName(utHandle, FileName);
ret = UT_FS_GetNextFileName(utHandle, FileName);
</source>

== UT_FS_GetFileSize ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_FS_GetFileSize(
UT_HANDLE utHandle,
char* lpszFileName,
unsigned long* lpFileSize
);
</source>

<b>Description</b>

To get the file size.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpszFileName [in]</td>
<td>filename (string, 16 bytes)</td>
</tr>
<tr>
<td>lpFileSize [out]</td>
<td>size of file</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_FS_NAME_LEN_RANGE</td>
<td>Filename too long</td>
</tr>
<tr>
<td>UT_FS_NO_FILE</td>
<td>No file found</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
char FileName[17];
unsigned long FileSize;
ret = UT_FS_GetFileSize(utHandle, FileName, &FileSize);
</source>

== UT_FS_GetFilePermission ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_FS_GetFilePermission(
UT_HANDLE utHandle,
char* lpszFileName,
unsigned char* lpFilePermission
);
</source>

<b>Description</b>

To get the file permission of the specified file.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpszFileName [in]</td>
<td>filename (string, 16 bytes)</td>
</tr>
<tr>
<td>lpFilePermission [out]</td>
<td>file permission</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_FS_NAME_LEN_RANGE</td>
<td>Filename too long</td>
</tr>
<tr>
<td>UT_FS_NO_FILE</td>
<td>No file found</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
char FileName[17];
unsigned char FilePermission;
ret = UT_FS_GetFilePermission(utHandle, FileName, &FilePermission);
</source>

== UT_FS_CreatFile ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_FS_CreateFile(
UT_HANDLE utHandle,
char* lpszFileName,
unsigned long FileSize,
unsigned char FilePermission
);
</source>

<b>Description</b>

To create a file.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpszFileName [in]</td>
<td>filename (string, 16 bytes)</td>
</tr>
<tr>
<td>FileSize [in]</td>
<td>size of file</td>
</tr>
<tr>
<td>FilePermission [in]</td>
<td>file permission</td>
</tr>
</table>

<b>Notes:</b>

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

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_FS_NAME_LEN_RANGE</td>
<td>Filename too long</td>
</tr>
<tr>
<td>UT_FS_FILE_EXIST</td>
<td>The file already exists</td>
</tr>
</table>

<b>Usage Note</b>
File permission types:
# FILE_PERMISSION_GUEST: With GUEST and higher permissions, reading the file is allowed; With USER and higher permissions, writing file is allowed.
# FILE_PERMISSION_USER: With USER and higher permissions, reading and writing file are allowed.
# FILE_PERMISSION_ADMIN: Only ADMIN is allowed to read and write the file.

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
char FileName[17];
ret = UT_FS_CreateFile(utHandle, FileName, 200, FILE_PERMISSION_GUEST);
</source>

== UT_FS_DeleteFile ==

<b>Prototype</b>

<code>UT_RV UT_API UT_FS_DeleteFile(UT_HANDLE utHandle, char* lpszFileName);</code>

<b>Description</b>

To delete a file.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpszFileName [in]</td>
<td>filename (string, 16 bytes)</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_FS_NAME_LEN_RANGE</td>
<td>Filename too long</td>
</tr>
<tr>
<td>UT_FS_NO_FILE</td>
<td>No file found</td>
</tr>
</table>

<b>Usage Note</b>

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.

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
char FileName[17];
ret = UT_FS_DeleteFile(utHandle, FileName);
</source>

== UT_FS_OpenFile ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_FS_OpenFile(
UT_HANDLE utHandle,
char* lpszFileName,
void* lpReserve
);
</source>

<b>Description</b>

To open a file.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpszFileName [in]</td>
<td>filename (string, 16 bytes)</td>
</tr>
<tr>
<td>lpReserve<td>
<td>reserved for further usage</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_FS_NAME_LEN_RANGE</td>
<td>Filename too long</td>
</tr>
<tr>
<td>UT_FS_NO_FILE</td>
<td>No file found</td>
</tr>
</table>

<b>Usage Note</b>

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.

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
char FileName[17];
ret = UT_FS_OpenFile(utHandle, FileName, NULL);
</source>

== UT_FS_WriteFile ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_FS_WriteFile(
UT_HANDLE utHandle,
unsigned long Offset,
unsigned long Length,
unsigned char* Buffer,
void* lpReserve
);
</source>

<b>Description</b>

To write or modify a file.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>Offset [in]</td>
<td>start position for writing</td>
</tr>
<tr>
<td>Length [in]</td>
<td>length of data</td>
</tr>
<tr>
<td>Buffer [in]</td>
<td>data to write</td>
</tr>
<tr>
<td>lpReserve</td>
<td>reserved for further usage</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_FS_OFFSET_INVALID</td>
<td>Invalid start point for specified file</td>
</tr>
<tr>
<td>UT_FS_NO_OPEN</td>
<td>Cannot open file</td>
</tr>
<tr>
<td>UT_FS_NOSPACE</td>
<td>No room in file system</td>
</tr>
<tr>
<td>UT_FS_NO_FILE</td>
<td>No file found</td>
</tr>
</table>

<b>Usage Note</b>

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.

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned long Offset;
unsigned char Buffer[200];
ret = UT_FS_WriteFile(utHandle, 0, 200, Buffer, NULL);
</source>

== UT_FS_ReadFile ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_FS_ReadFile(
UT_HANDLE utHandle,
unsigned long Offset,
unsigned long Length,
unsigned char* Buffer,
void* lpReserve
);
</source>

<b>Description</b>

To read a file.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>Offset [in]</td>
<td>start position for writing</td>
</tr>
<tr>
<td>Length [in]</td>
<td>length of data</td>
</tr>
<tr>
<td>Buffer [in]</td>
<td>data to write</td>
</tr>
<tr>
<td>lpReserve</td>
<td>reserved for further usage</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_FS_OFFSET_INVALID</td>
<td>Invalid start point for specified file</td>
</tr>
<tr>
<td>UT_FS_NO_OPEN</td>
<td>Cannot open file</td>
</tr>
<tr>
<td>UT_FS_DATA_LEN_RANGE</td>
<td>Out of range of data length<td>
</tr>
<tr>
<td>UT_FS_NO_FILE</td>
<td>No file found</td>
</tr>
</table>

<b>Usage Note</b>

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.

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned long Offset;
unsigned char Buffer[200];
ret = UT_FS_ReadFile(utHandle, 0, 200, Buffer, NULL);
</source>

== UT_FS_CloseFile ==

<b>Prototype</b>

<code>UT_RV UT_API UT_FS_CloseFile(UT_HANDLE utHandle, void* lpReserve);</code>

<b>Description</b>

To close a file.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpReserve</td>
<td>reserved for further usage</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_FS_NO_OPEN</td>
<td>Cannot open file</td>
</tr>
</table>

<b>Usage Note</b>

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.

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
ret = UT_FS_CloseFile(utHandle, NULL);
</source>

UniToken API Reference

2016-08-23T05:33:36Z

Bao:

[[category:UniToken_API]]

== UT_GetLibraryVersion ==
<b>API Prototype</b>

<source lang="C">unsigned long UT_API UT_GetLibraryVersion()</source>

<b>Description</b>

To get the version of the present library.

<b>Parameters</b>

n/a

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>Library version</td>
<td>the version of the current library</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
unsigned long ulLibraryVersion;
ulLibraryVersion = UT_GetLibraryVersion();
</source>

== UT_Initialize ==
<b>API Prototype</b>

<source lang="C">UT_RV UT_API UT_Initialize()</source>

<b>Description</b>

To initialize the UniToken. This should be called before any other function, with the exception <source lang="C">UT_GetLibraryVersion</source>

<b>Parameters</b>

n/a

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_ALREADY_INITIALIZE</td>
<td>Library already initialized</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
ret = UT_Initialize();
</source>

== UT_Finalize ==

<b>API Prototype</b>

<source lang="C">UT_RV UT_API UT_Finalize()</source>

<b>Description</b>

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

<b>Parameters</b>

n/a

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
ret = UT_Finalize();
</source>

== UT_GetTokenList ==

<b>API Prototype</b>

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

<b>Description</b>

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

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>lpSlotID</td>
<td>[out] slot ID list</td>
</tr>
<tr>
<td>lpTokenCount</td>
<td>
* [in] size of buffer (0~32 bytes)
* [out]number of token
</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
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);
</source>

== UT_OpenDevice ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_OpenDevice(
UT_SLOT_ID SlotID,
UT_HANDLE* lputHandle
);
</source>

<b>Description</b>

To open the device in the specified slot.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>SlotID</td>
<td>[in] the specified slot</td>
</tr>
<tr>
<td>lputHandle</td>
<td>[out] device handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_SLOT_ID_INVALUD</td>
<td>Invalid slot ID</td>
</tr>
</table>

<b>Usage Note</b>

SlotID should be retrieved from <source lang="C">UT_GetTokenList</source> instead manually entered. Therefore, this function cannot be called before <code>UT_GetTokenList</code>

<b>Sample</b>

See the sample of <source lang="C">UT_GetTokenList</source>

== UT_CloseDevice ==

<b>Prototype</b>

<source lang="C">UT_RV UT_API UT_CloseDevice(UT_HANDLE utHandle);</source>

<b>Description</b>

To close the specified device.

<b>Parameters</b>

n/a

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
</table>

<b>Sample</b>

See also the sample of <source lang="C">UT_GetTokenList</source>

== UT_GetHandle ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_GetHandle(
UT_SLOT_ID SlotID,
UT_HANDLE* lputHandle
);
</source>

<b>Description</b>

To get device handle by Slot ID.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>SlotID [in]</td>
<td>the specified slot</td>
</tr>
<tr>
<td>lputHandle [out]</td>
<td>device handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
</table>

<b>Sample</b>

See the sample of <source lang="C">UT_GetTokenList</source>

== UT_GetSlotID ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_GetSlotID(
UT_HANDLE utHandle,
UT_SLOT_ID* lpSlotID
);
</source>

<b>Description</b>

To get Slot ID by device handle.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>the specified handle</td>
</tr>
<tr>
<td>lpSlotID [out]</td>
<td>Slot ID</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALIDM</td>
<td>Invalid token handle</td>
</tr>
</table>

<b>Sample</b>

See the sample of <source lang="C">UT_GetTokenList</source>

== UT_GetSlotStatus ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_GetSlotStatus(
UT_STATUS* lpStatus,
UT_SLOT_ID* lpSlotID
);
</source>

<b>Description</b>

To get the status of Slot.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>lpStatus [out]</td>
<td>the current status of slot</td>
</tr>
<tr>
<td>lpSlotID [out]</td>
<td>Slot ID</td>
</tr>
</table>

<b>Notes:</b>

lpStatus can be:

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

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
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
}
}
</source>

== UT_GetTokenType ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_GetTokenType(
UT_HANDLE utHandle,
char* lpszTokenType
);
</source>

<b>Description</b>

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

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpszTokenType [out]</td>
<td>UniToken type (string, 32 bytes)</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
char TokenType[33] = {0};
ret = UT_GetTokenType(utHandle, (char *)TokenType);
</source>

== UT_GetFirmwareVersion ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_GetFirmwareVersion(
UT_HANDLE utHandle,
unsigned long* lpVersion
);
</source>

<b>Description</b>

To get the version of firmware.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpVersion [out]</td>
<td>firmware version</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned long Version;
ret = UT_GetFirmwareVersion(utHandle, &Version);
</source>

== UT_Logoff ==

<b>Prototype</b>

<source lang="C">UT_RV UT_API UT_Logoff(UT_HANDLE utHandle);</source>

<b>Description</b>

To log off the specified Token.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
</table>

<b>Sample</b>

See the sample of <source lang="C">UT_Logon</source>

== UT_Logon ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_Logon(
UT_HANDLE utHandle,
unsigned long UserLevel,
unsigned char* lpszPin
);
</source>

<b>Description</b>

To logon the specified token.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>UserLevel [in]</td>
<td>levels of permission</td>
</tr>
<tr>
<td>lpszPin [in]</td>
<td>the corresponding password with certain permission level</td>
</tr>
</table>

<b>Note:</b>

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

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_PIN_ERROR</td>
<td>Wrong password</td>
</tr>
<tr>
<td>UT_USER_FULL</td>
<td>No more sessions allowed</td>
</tr>
<tr>
<td>UT_USER_LOCKED</td>
<td>Token locked</td>
</tr>
</table>

<b>Usage Note</b>

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.

<b>Sample</b>

<source lang="C">
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);
</source>

== UT_GetCurrentUserLevel ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_GetCurrentUserLevel(
UT_HANDLE utHandle,
unsigned long* lpUserLevel
);
</source>

<b>Description</b>

To get the current permission level.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpUserLevel [out]</td>
<td>Permission level</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
</table>

<b>Sample</b>

See the sample of UT_Logon.

== UT_ChangePin ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_ChangePin(
UT_HANDLE utHandle,
unsigned char UserLevel,
unsigned long ChangeMode,
unsigned char* OldPin,
unsigned char* NewPin
);
</source>

<b>Description</b>

To change the PIN.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>UserLevel [in]</td>
<td>permission level</td>
</tr>
<tr>
<td>ChangeMode [in]</td>
<td>mode to change to</td>
</tr>
<tr>
<td>OldPIN [in]</td>
<td>old PIN</td>
</tr>
<tr>
<td>NewPin [in]</td>
<td>new PIN</td>
</tr>
</table>

<b>Notes:</b>

Change Mode can be <source lang="C">UT_CHANGE_PIN_MODE_BYSELF</source> or <code>UT_CHANGE_PIN_MODE_ADMIN_CHANGE_USER</code>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NOT_ALLOWED</td>
<td>Operation not allowed</td>
</tr>
</table>

<b>Usage Note</b>

Two ways of changing password:

# 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 <source lang="C">UT_CHANGE_PIN_MODE_BYSELF</source>
# Admin resets user password. Log on as ADMIN and type in new password of USER. Here, the mode of changing PIN is <source lang="C">UT_CHANGE_PIN_MODE_ADMIN_CHANGE_USER</source> In this case, OldPin is not required.

<b>Sample</b>

<source lang="C">
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);
</source>

== UT_GetID ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_GetID(
UT_HANDLE utHandle,
char* lpszId
);
</source>

<b>Description</b>

To get the token ID of specified device.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpszId [out]</td>
<td>UniToken ID (string, 32 bytes)</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
</table>

<b>Sample</b>

See the sample of <source lang="C">UT_SetID</source>

== UT_SetID ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_SetID(
UT_HANDLE utHandle,
char* lpszId
);
</source>

<b>Description</b>

To set the token ID of the specified device

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpszId [out]</td>
<td>UniToken ID (string, 32 bytes)</td>
</tr>
</table>

<b>Returned value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
char Id[33] = "UniTokenPRO";
unsigned long UserLevel;
ret = UT_SetID(utHandle, Id);
ret = UT_GetID(utHandle, Id);
</source>

== UT_GetHID ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_GetHID(
UT_HANDLE utHandle,
unsigned long* lpHid
);
</source>

<b>Description</b>

To get the Hardware ID of the specified device

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpHid [out]</td>
<td>Hardware ID</td>
</tr>
</table>

<b>Returned value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned long Hid;
ret = UT_GetHID(utHandle, &Hid);
</source>

== UT_GetSoftID ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_GetSoftID(
UT_HANDLE utHandle,
unsigned long* lpSoftID
);
</source>

<b>Description</b>

To get the Software ID of the specified device

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpSoftID [out]</td>
<td>Software ID</td>
</tr>
</table>

<b>Returned value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
</table>

<b>Sample</b>

See also the sample of <source lang="C">UT_SetSoftID</source>

== UT_SetSoftID ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_SetSoftID(
UT_HANDLE utHandle,
unsigned long SoftID
);
</source>

<b>Description</b>

To set the Software ID of the specified device.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpSoftID [out]</td>
<td>Software ID</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned long SoftID = 0;
ret = UT_GetSoftID(utHandle, &SoftID);
ret = UT_SetSoftID(utHandle, SoftID);
</source>

== UT_LED ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_LED(
UT_HANDLE utHandle,
unsigned char On
);
</source>

<b>Description</b>

To turn on/off LED.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>On [in]</td>
<td>the status of the LED</td>
</tr>
</table>

<b>Notes:</b>

The parameter On can be <source lang="C">LED_ON</source> or <code>LED_OFF</code>

<b>Returned value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
ret = UT_LED(utHandle, LED_ON);
</source>

== UT_SetAttemptCount ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_SetAttemptCount(
UT_HANDLE utHandle,
unsigned long MaxAttempt
);
</source>

<b>Description</b>

To set the maximum times of PIN attempt

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>MaxAttempt [in]</td>
<td>maximum attempt times</td>
</tr>
</table>

<b>Notes:</b>

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.

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
</table>

<b>Usage Note</b>

This function is used for unlocking the token.

<b>Sample</b>

See the sample of <source lang="C">UT_GetAttemptCount</source>

== UT_GetAttemptCount ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_GetAttemptCount(
UT_HANDLE utHandle,
unsigned long* lpUserAttempt,
unsigned long* lpAdminAttempt
);
</source>

<b>Description</b>

To count the number of failed login attempts.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpUserAttempt [out]</td>
<td>User PIN attempt times</td>
</tr>
<tr>
<td>lpAdminAttempt [out]</td>
<td>Admin PIN attempt times</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned long UserAttempt;
unsigned long AdminAttempt;
ret = UT_SetAttemptCount(utHandle, 15);
ret = UT_GetAttemptCount(utHandle, &UserAttempt, &AdminAttempt);
</source>

== UT_Format ==

<b>Prototype</b>

<source lang="C">UT_RV UT_API UT_Format(UT_HANDLE utHandle);</source>

<b>Description</b>

To format a UniToken.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
</table>

<b>Usage Note:</b>
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.

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
ret = UT_Format(utHandle);
</source>

== UT_Rand ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_Rand(
UT_HANDLE utHandle,
unsigned long Length,
unsigned char* lpOut,
void* lpReserve
);
</source>

<b>Description</b>

To generate random numbers.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>Length [in]</td>
<td>length of random number (in bytes)</td>
</tr>
<tr>
<td>lpOut [out]</td>
<td>random number</td>
</tr>
<tr>
<td>lpReserve</td>
<td>reserved for future use</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned char OutRand[8];
ret = UT_Rand(utHandle, 8, OutRand, NULL);
</source>

== UT_DESGenerateKey ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_DESGenerateKey(
UT_HANDLE utHandle,
KEY_HANDLE_PTR lpKeyHandle
);
</source>

<b>Description</b>

To generate a DES key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Note:</b>

The length of generated DES key is 8 bytes.

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_FULL</td>
<td>no more keys can be generated</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_DESGenerateKey(utHandle, &KeyHandle);
</source>

== UT_DESEncrypt ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_DESEncryptZ(
UT_HANDLE utHandle,
KEY_HANDLE KeyHandle,
unsigned char* lpData,
unsigned long DataLength,
unsigned char* lpEncryptedData,
unsigned long* lpEncryptedDataLength
);
</source>

<b>Description</b>

To encrypt data with DES.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
<tr>
<td>lpData [in]</td>
<td>plaintext</td>
</tr>
<tr>
<td>DataLength [in]</td>
<td>length of plaintext in bytes</td>
</tr>
<tr>
<td>lpEncryptedData [out]</td>
<td>ciphertext</td>
</tr>
<tr>
<td>lpEncryptedDataLength [out]</td>
<td>length of ciphertext</td>
</tr>
</table>

<b>Notes:</b>

DateLength is <source lang="C">DES_DATA_LEN_8_BYTE</source>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
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
);
</source>

== UT_DESDecrypt ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_DESDecrypt(
UT_HANDLE utHandle,
KEY_HANDLE KeyHandle,
unsigned char* lpEncryptedData,
unsigned long EncryptedDataLength,
unsigned char* lpData,
unsigned long* lpDataLength
);
</source>

<b>Description</b>

To decrypt data with DES.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
<tr>
<td>lpEncryptedData [in]</td>
<td>ciphertext</td>
</tr>
<tr>
<td>EncryptedDataLength [in]</td>
<td>length of ciphertext in bytes</td>
</tr>
<tr>
<td>lpData [out]</td>
<td>plaintext</td>
</tr>
<tr>
<td>lpDataLength [out]</td>
<td>length of plaintext</td>
</tr>
</table>

<b>Notes:</b>

EncryptedDataLength is <source lang="C">DES_DATA_LEN_8_BYTE</source>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
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
);
</source>

== UT_DESImportKey ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_DESImportKey(
UT_HANDLE utHandle,
unsigned char* lpKey,
KEY_HANDLE_PTR lpKeyHandle
);
</source>

<b>Description</b>

To import a DES key to UniToken device.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKey [in]</td>
<td>DES key</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_FULL</td>
<td>No more keys can be generated</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
unsigned char Key[DES_KEY_LEN_8_BYTE];
ret = UT_DESImportKey(utHandle, Key, &KeyHandle);
</source>

== UT_DESDeleteKey ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_DESDeleteKey(
UT_HANDLE utHandle,
KEY_HANDLE KeyHandle
);
</source>

<b>Description</b>

To delete a DES key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_DESDeleteKey(utHandle, KeyHandle);
</source>

== UT_DESGetKeyCount ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_DESGetKeyCount(
UT_HANDLE utHandle,
unsigned long* lpKeyCount
);
</source>

<b>Description</b>

To count DES keys.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyCount [out]</td>
<td>the number of keys</td>
</tr>
</table>

<b>Notes:</b>

The maximum number of DES keys is 16.

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned long KeyCount;
ret = UT_DESGetKeyCount(utHandle, &KeyCount);
</source>

== UT_DESGetFirstKeyHandle ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_DESGetFirstKeyHandle(
UT_HANDLE utHandle,
KEY_HANDLE_PTR lpKeyHandle
);
</source>

<b>Description</b>

To get the handle of the first DES key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
</table>

<b>Sample</b>

See also the sample of <source lang="C">UT_DESGetNextKeyHandle</source>

== UT_DESGetNextKeyHandle ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_DESGetNextKeyHandle(
UT_HANDLE utHandle,
KEY_HANDLE_PTR lpKeyHandle
);
</source>

<b>Description</b>

To get the handle of the next DES key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
<tr>
<td>UT_OPERATE_INVALID</td>
<td>Invalid operation</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_DESGetFirstKeyHandle(utHandle, &KeyHandle);
ret = UT_DESGetNextKeyHandle(utHandle, &KeyHandle);
</source>

== UT_DES3GenerateKey ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_DES3GenerateKey(
UT_HANDLE utHandle,
KEY_HANDLE_PTR lpKeyHandle
);
</source>

<b>Description</b>

To generate a 3DES key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Note:</b>

The length of generated 3DES key is 24 bytes.

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_FULL</td>
<td>no more keys can be generated</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_DES3GenerateKey(utHandle, &KeyHandle);
</source>

== UT_DES3Encrypt ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_DES3Encrypt(
UT_HANDLE utHandle,
KEY_HANDLE KeyHandle,
unsigned char* lpData,
unsigned long DataLength,
unsigned char* lpEncryptedData,
unsigned long* lpEncryptedDataLength
);
</source>

<b>Description</b>

To encrypt data with 3DES.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
<tr>
<td>lpData [in]</td>
<td>plaintext</td>
</tr>
<tr>
<td>DataLength [in]</td>
<td>length of plaintext</td>
</tr>
<tr>
<td>lpEncryptedData [out]</td>
<td>ciphertext</td>
</tr>
<tr>
<td>lpEncryptedDataLength [out]</td>
<td>length of ciphertext</td>
</tr>
</table>

<b>Notes:</b>

DateLength is <source lang="C">DES_DATA_LEN_8_BYTE</source>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
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
);
</source>

== UT_DES3Decrypt ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_DES3Decrypt(
UT_HANDLE utHandle,
KEY_HANDLE KeyHandle,
unsigned char* lpEncryptedData,
unsigned long EncryptedDataLength,
unsigned char* lpData,
unsigned long* lpDataLength
);
</source>

<b>Description</b>

To decrypt data with 3DES.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
<tr>
<td>lpEncryptedData [in]</td>
<td>ciphertext</td>
</tr>
<tr>
<td>EncryptedDataLength [in]</td>
<td>length of ciphertext</td>
</tr>
<tr>
<td>lpData [out]</td>
<td>plaintext</td>
</tr>
<tr>
<td>lpDataLength [out]</td>
<td>length of plaintext</td>
</tr>
</table>

<b>Notes:</b>

EncryptedDataLength is <source lang="C">DES_DATA_LEN_8_BYTE</source>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
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
);
</source>

== UT_DES3ImportKey ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_DES3ImportKey(
UT_HANDLE utHandle,
unsigned char* lpKey,
KEY_HANDLE_PTR lpKeyHandle
);
</source>

<b>Description</b>

To import 3DES keys to UniToken device.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKey [in]</td>
<td>3DES key</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_FULL</td>
<td>No more keys can be generated</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
unsigned char Key[DES3_KEY_LEN_24_BYTE];
ret = UT_DES3ImportKey(utHandle, Key, &KeyHandle);
</source>

== UT_DES3DeleteKey ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_DES3DeleteKey(
UT_HANDLE utHandle,
KEY_HANDLE KeyHandle
);
</source>

<b>Description</b>

To delete a 3DES key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_DES3DeleteKey(utHandle, KeyHandle);
</source>

== UT_DES3GetKeyCount ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_DES3GetKeyCount(
UT_HANDLE utHandle,
unsigned long* lpKeyCount
);
</source>

<b>Description</b>

To count 3DES keys.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyCount [out]</td>
<td>the number of keys</td>
</tr>
</table>

<b>Notes:</b>

The maximum number of 3DES keys is 16.

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned long KeyCount;
ret = UT_DES3GetKeyCount(utHandle, &KeyCount);
</source>

== UT_DES3GetFirstKeyHandle ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_DES3GetFirstKeyHandle(
UT_HANDLE utHandle,
KEY_HANDLE_PTR lpKeyHandle
);
</source>

<b>Description</b>

To get the handle of the first 3DES key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
</table>

<b>Sample</b>

See also the samples of <source lang="C">UT_DES3GetNextKeyHandle</source>

== UT_DES3GetNextKeyHandle ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_DES3GetNextKeyHandle(
UT_HANDLE utHandle,
KEY_HANDLE_PTR lpKeyHandle
);
</source>

<b>Description</b>

To get the handle of the next 3DES key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
<tr>
<td>UT_OPERATE_INVALID</td>
<td>Invalid operation</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_DES3GetFirstKeyHandle(utHandle, &KeyHandle);
ret = UT_DES3GetNextKeyHandle(utHandle, &KeyHandle);
</source>

== UT_AESGenerateKey ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_AESGenerateKey(
UT_HANDLE utHandle,
unsigned long KeyLength,
KEY_HANDLE_PTR lpKeyHandle
);
</source>

<b>Description</b>

To generate an AES key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyLength [in]</td>
<td>key length</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Notes:</b>

KeyLength can be <source lang="C">AES_KEY_LEN_128_BIT</source> or <code>AES_KEY_LEN_192_BIT</code>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_FULL</td>
<td>No more keys can be generated</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_AESGenerateKey(utHandle, AES_KEY_LEN_128_BIT, &KeyHandle);
</source>

== UT_AESEncrypt ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_AESEncrypt(
UT_HANDLE utHandle,
KEY_HANDLE KeyHandle,
unsigned char* lpData,
unsigned long DataLength,
unsigned char* lpEncryptedData,
unsigned long* lpEncryptedDataLength
);
</source>

<b>Description</b>

To encrypt data with AES.

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
<tr>
<td>lpData [in]</td>
<td>plaintext</td>
</tr>
<tr>
<td>DataLength [in]</td>
<td>length of plaintext</td>
</tr>
<tr>
<td>lpEncryptedData [out]</td>
<td>ciphertext</td>
</tr>
<tr>
<td>lpEncryptedDataLength [out]</td>
<td>length of ciphertext</td>
</tr>
</table>

<b>Notes:</b>

DateLength is <source lang="C">AES_DATA_LEN_16_BYTE</source>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
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
);
</source>

== UT_AESDecrypt ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_AESDecrypt(
HANDLE utHandle,
KEY_HANDLE KeyHandle,
unsigned char* lpEncryptedData,
unsigned long EncryptedDataLength,
unsigned char* lpData,
unsigned long* lpDataLength
);
</source>

<b>Description</b>

To decrypt data with AES.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
<tr>
<td>lpEncryptedData [in]</td>
<td>ciphertext</td>
</tr>
<tr>
<td>EncryptedDataLength [in]</td>
<td>length of ciphertext</td>
</tr>
<tr>
<td>lpData [out]</td>
<td>plaintext</td>
</tr>
<tr>
<td>lpDataLength [out]</td>
<td>length of plaintext</td>
</tr>
</table>

<b>Notes:</b>

DateLength is <source lang="C">AES_DATA_LEN_16_BYTE</source>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
unsigned char Data[AES_DATA_LEN_16_BYTE];
unsigned char EncryptedData[AES_DATA_LEN_16_BYTE];
unsigned long DataLength;
ret = UT_AESDecrypt(handle,
KeyHandle,
EncryptedData,
AES_DATA_LEN_16_BYTE,
Data,
&DataLength
);
</source>

== UT_AESImportKey ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_AESImportKey(
HANDLE utHandle,
unsigned char* lpKey,
unsigned long KeyLength,
KEY_HANDLE_PTR lpKeyHandle
);
</source>

<b>Description</b>

To import AES key to UniToken device.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyLength [in]</td>
<td>key length</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Notes:</b>

KeyLength can be <source lang="C">AES_KEY_LEN_128_BIT</source> or <code>AES_KEY_LEN_192_BIT</code>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_FULL</td>
<td>No more keys can be generated</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
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);
</source>

== UT_AESDeleteKey ==

<b>Prototype</b>

<source lang="C">UT_RV UT_API UT_AESDeleteKey(UT_HANDLE utHandle, KEY_HANDLE KeyHandle);</source>

<b>Description</b>

To delete an AES key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_AESDeleteKey(utHandle, KeyHandle);
</source>

== UT_AESGetKeyCount ==

<b>Prototype</b>

<source lang="C">UT_RV UT_API UT_AESGetKeyCount(UT_HANDLE utHandle, unsigned long* lpKeyCount);</source>

<b>Description</b>

To count AES keys.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyCount [out]</td>
<td>the number of keys</td>
</tr>
</table>

<b>Notes:</b>

The maximum number of 3DES keys is 32.

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned long KeyCount;
ret = UT_AESGetKeyCount(utHandle, &KeyCount);
</source>

== UT_AESGetKeyLen ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_AESGetKeyLen(
UT_HANDLE utHandle,
KEY_HANDLE KeyHandle,
unsigned long* lpKeyLength
);
</source>

<b>Description</b>

To get the length of AES key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
<tr>
<td>lpKeyLength [out]</td>
<td>key length</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
unsigned long KeyLength;
ret = UT_AESGetKeyLen(utHandle, KeyHandle, &KeyLength);
</source>

== UT_AESGetFirstKeyHandle ==

<b>Prototype</b>

<source lang="C">UT_RV UT_API UT_AESGetFirstKeyHandle(UT_HANDLE utHandle, KEY_HANDLE_PTR lpKeyHandle);</source>

<b>Description</b>

To get the handle of the first AES key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
</table>

<b>Sample</b>

See also the sample of <source lang="C">UT_AESGetNextKeyHandle</source>

== UT_AESGetNextKeyHandle ==

<b>Prototype</b>

<source lang="C">UT_RV UT_API UT_AESGetNextKeyHandle(UT_HANDLE utHandle, KEY_HANDLE_PTR lpKeyHandle);</source>

<b>Description</b>

To get the handle of the next AES key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
<tr>
<td>UT_OPERATE_INVALID</td>
<td>Invalid operation</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_AESGetFirstKeyHandle(utHandle, &KeyHandle);
ret = UT_AESGetNextKeyHandle(utHandle, &KeyHandle);
</source>

== UT_RSAGenerateKeyPair ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_RSAGenerateKeyPair(
UT_HANDLE utHandle,
unsigned long ModulusBits,
unsigned long PubExp,
KEY_HANDLE_PTR lpPubKeyHandle,
KEY_HANDLE_PTR lpPriKeyHandle
);
</source>

<b>Description</b>

To generate RSA key pair.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>ModulusBits [in]</td>
<td>modulus length</td>
</tr>
<tr>
<td>PubExp [in]</td>
<td>public exponent</td>
</tr>
<tr>
<td>lpPubKeyHandle [out]</td>
<td>public key handle</td>
</tr>
<tr>
<td>lpPriKeyHandle [out]</td>
<td>private key handle</td>
</tr>
</table>

<b>Notes:</b>

# UniToken device can store as many as 16 RSA key pairs
# ModulusBits can be <source lang="C">RSA_MODULUS_LEN_1024_BIT</source> or <code>RSA_MODULUS_LEN_2048_BIT</code>
# PubExp is <source lang="C">RSA_PUBEXP_LEN_65537_BIT</source>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_FULL</td>
<td>No more keys can be generated</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
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
);
</source>

== UT_RSAPubKeyEncrypt ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_RSAPubKeyEncrypt(
UT_HANDLE utHandle,
KEY_HANDLE PubKeyHandle,
unsigned char* lpData,
unsigned long DataLength,
unsigned char* lpEncryptedData,
unsigned long* lpEncryptedDataLength
);
</source>

<b>Description</b>

To encrypt data with RSA public key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
<tr>
<td>lpData [in]</td>
<td>plaintext</td>
</tr>
<tr>
<td>lpDataLength [in]</td>
<td>length of plaintext</td>
</tr>
<tr>
<td>lpEncryptedData [out]</td>
<td>ciphertext</td>
</tr>
<tr>
<td>EncryptedDataLength [out]</td>
<td>length of ciphertext</td>
</tr>
</table>

<b>Notes:</b>

DataLength can be <source lang="C">RSA_DATA_LEN_1024_BIT</source> or <code>SA_DATA_LEN_2048_BIT</code>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Usage Note</b>

The handle of public key should be retrieved with <source lang="C">UT_RSAGetPubKeyByPriKey</source> 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.

<b>Sample</b>

<source lang="C">
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
);
</source>

== UT_RSAPriKeyDecrypt ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_RSAPriKeyDecrypt(
UT_HANDLE utHandle,
KEY_HANDLE PriKeyHandle,
unsigned char* lpEncryptedData,
unsigned long EncryptedDataLength,
unsigned char* lpData,
unsigned long* lpDataLength
);
</source>

<b>Description</b>

To decrypt data with RSA private key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
<tr>
<td>lpEncryptedData [in]</td>
<td>ciphertext</td>
</tr>
<tr>
<td>EncryptedDataLength [in]</td>
<td>length of ciphertext</td>
</tr>
<tr>
<td>lpData [out]</td>
<td>plaintext</td>
</tr>
<tr>
<td>lpDataLength [out]</td>
<td>length of plaintext</td>
</tr>
</table>

<b>Notes:</b>

DataLength can be <source lang="C">RSA_DATA_LEN_1024_BIT</source> or <code>SA_DATA_LEN_2048_BIT</code>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Usage Note</b>

The handle of private key should be retrieved with <source lang="C">RSAGetPriKeyByPubKey</source> 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.

<b>Sample</b>

<source lang="C">
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
);
</source>

== UT_RSAPriKeyEncrypt ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_RSAPriKeyEncrypt(
UT_HANDLE utHandle,
KEY_HANDLE PriKeyHandle,
unsigned char* lpData,
unsigned long DataLength,
unsigned char* lpEncryptedData,
unsigned long* lpEncryptedDataLength
);
</source>

<b>Description</b>

To encrypt data with RSA private key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
<tr>
<td>lpData [in]</td>
<td>plaintext</td>
</tr>
<tr>
<td>lpDataLength [in]</td>
<td>length of plaintext</td>
</tr>
<tr>
<td>lpEncryptedData [out]</td>
<td>ciphertext</td>
</tr>
<tr>
<td>EncryptedDataLength [out]</td>
<td>length of ciphertext</td>
</tr>
</table>

<b>Notes:</b>

DataLength can be <source lang="C">RSA_DATA_LEN_1024_BIT</source> or <code>SA_DATA_LEN_2048_BIT</code>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Usage Note</b>

The handle of private key should be retrieved with <source lang="C">UT_RSAGetPriKeyByPubKey</source> 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.

<b>Sample</b>

<source lang="C">
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
);
</source>

== UT_RSAPubKeyDecrypt ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_RSAPubKeyDecrypt(
UT_HANDLE utHandle,
KEY_HANDLE PubKeyHandle,
unsigned char* lpEncryptedData,
unsigned long EncryptedDataLength,
unsigned char* lpData,
unsigned long* lpDataLength
);
</source>

<b>Description</b>

To decrypt data with RSA public key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
<tr>
<td>lpEncryptedData [in]</td>
<td>ciphertext</td>
</tr>
<tr>
<td>EncryptedDataLength [in]</td>
<td>length of ciphertext</td>
</tr>
<tr>
<td>lpData [out]</td>
<td>plaintext</td>
</tr>
<tr>
<td>lpDataLength [out]</td>
<td>length of plaintext</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Usage Note</b>

The handle of public key should be retrieved with <source lang="C">UT_RSAGetPubKeyByPriKey</source> 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.

<b>Sample</b>

<source lang="C">
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
);
</source>

== UT_RSAGetKeyPairCount ==

<b>Prototype</b>

<source lang="C">UT_RV UT_API UT_RSAGetKeyPairCount(UT_HANDLE utHandle, unsigned long* lpKeyCount);</source>

<b>Description</b>

To count RSA keys.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyCount [out]</td>
<td>the number of key pairs</td>
</tr>
</table>

<b>Notes</b>

The maximum number of RSA key pairs is 16.

<b>Returned value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned long KeyCount;
ret = UT_RSAGetKeyPairCount(utHandle, &KeyCount);
</source>

== UT_RSAGetFirstKeyPairHandle ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_RSAGetFirstKeyPairHandle(
UT_HANDLE utHandle,
KEY_HANDLE_PTR lpPubKeyHandle,
KEY_HANDLE_PTR lpPriKeyHandle
);
</source>

<b>Description</b>

To get the handles of the first RSA key pair.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpPubKeyHandle [out]</td>
<td>public key handle</td>
</tr>
<tr>
<td>lpPriKeyHandle [out]</td>
<td>private key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
</table>

<b>Sample</b>

See also the sample of <source lang="C">UT_RSAGetNextKeyPairHandle</source>

== UT_RSAGetNextKeyPairHandle ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_RSAGetNextKeyPairHandle(
UT_HANDLE utHandle,
KEY_HANDLE_PTR lpPubKeyHandle,
KEY_HANDLE_PTR lpPriKeyHandle
);
</source>

<b>Description</b>

To get the handles of the next RSA key pair.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpPubKeyHandle [out]</td>
<td>public key handle</td>
</tr>
<tr>
<td>lpPriKeyHandle [out]</td>
<td>private key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
<tr>
<td>UT_OPERATE_INVALID</td>
<td>Invalid operation</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE PubKeyHandle;
KEY_HANDLE PriKeyHandle;
ret = UT_RSAGetFirstKeyPairHandle(utHandle, &PubKeyHandle, &PriKeyHandle);
ret = UT_RSAGetNextKeyPairHandle(utHandle, &PubKeyHandle, &PriKeyHandle);
</source>

== UT_RSAPubKeyImport ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_RSAPubKeyImport(
UT_HANDLE utHandle,
UT_RSA* lpRsaKey,
KEY_HANDLE PriKeyHandle,
KEY_HANDLE_PTR lpPubKeyHandle
);
</source>

<b>Description</b>

To import RSA public key to UniToken device.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>PriKeyHandle [in]</td>
<td>private key handle</td>
</tr>
<tr>
<td>lpPubKeyHandle [out]</td>
<td>public key handle</td>
</tr>
</table>

<b>Notes</b>

PriKeyHandle can be the existing private key handle or <source lang="C">RSA_IMPORT_NEW</source>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
<tr>
<td>UT_KEY_EXIST</td>
<td>Key already exists</td>
</tr>
<tr>
<td>UT_KEY_FULL</td>
<td>No more keys can be generated</td>
</tr>
</table>

<b>Usage Note</b>

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 <source lang="C">UT_KEY_HANDLE_INVALID</source> If PriKeyHandle is <code>RSA_IMPORT_NEW</code> 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 <code>UT_KEY_FULL</code>

<b>Sample</b>

See the sample of <source lang="C">UT_RSAPriKeyImport</source>

== UT_RSAPriKeyImport ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_RSAPriKeyImport(
UT_HANDLE utHandle,
UT_RSA* lpRsaKey,
KEY_HANDLE PubKeyHandle,
KEY_HANDLE_PTR lpPriKeyHandle
);
</source>

<b>Description</b>

To import RSA private key to UniToken device.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>PubKeyHandle [in]</td>
<td>public key handle</td>
</tr>
<tr>
<td>lpPriKeyHandle [out]</td>
<td>private key handle</td>
</tr>
</table>

<b>Notes:</b>

PubKeyHandle can be the existing public key handle or <source lang="C">RSA_IMPORT_NEW</source>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
<tr>
<td>UT_KEY_EXIST</td>
<td>Key already exists</td>
</tr>
<tr>
<td>UT_KEY_FULL</td>
<td>No more keys can be generated</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
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
);
</source>

== UT_RSAPubKeyExport ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_RSAPubKeyExport(
UT_HANDLE utHandle,
KEY_HANDLE PubKeyHandle,
unsigned long* lpModulusBits,
UT_RSA* lpRsaKey
);
</source>

<b>Description</b>

To export RSA public key from UniToken device.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>PubKeyHandle [in]</td>
<td>public key handle</td>
</tr>
<tr>
<td>lpModulusBits [out]</td>
<td>modulus length</td>
</tr>
<tr>
<td>lpRsaKey [out]</td>
<td>RSA public key structure</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
<tr>
<td>UT_KEY_EXIST</td>
<td>Key already exists</td>
</tr>
<tr>
<td>UT_KEY_FULL</td>
<td>No more keys can be generated</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
UT_RSA RsaKey;
KEY_HANDLE PubKeyHandle;
unsigned long ModulusBits;
ret = UT_RSAPubKeyExport(utHandle, PubKeyHandle, &ModulusBits, &RsaKey);
</source>

== UT_RSAGetPubKeyHandle ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_RSAGetPubKeyHandle(
UT_HANDLE utHandle,
KEY_HANDLE PriKeyHandle,
KEY_HANDLE_PTR lpPubKeyHandle
);
</source>

<b>Description</b>

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

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>PriKeyHandle [in]</td>
<td>private key handle</td>
</tr>
<tr>
<td>lpPubKeyHandle [out]</td>
<td>the corresponding public key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE PubKeyHandle;
KEY_HANDLE PriKeyHandle;
ret = UT_RSAGetPubKeyHandle(utHandle, PriKeyHandle, &PubKeyHandle);
</source>

== UT_RSAGetPriKeyHandle ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_RSAGetPriKeyHandle(
UT_HANDLE utHandle,
KEY_HANDLE PubKeyHandle,
KEY_HANDLE_PTR lpPriKeyHandle
);
</source>

<b>Description</b>

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

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>PubKeyHandle [in]</td>
<td>public key handle</td>
</tr>
<tr>
<td>lpPriKeyHandle [out]</td>
<td>the corresponding private key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE PubKeyHandle;
KEY_HANDLE PriKeyHandle;
ret = UT_RSAGetPriKeyHandle(utHandle, PubKeyHandle, &PriKeyHandle);
</source>

== UT_RSAGetKeyPairModulus ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_RSAGetKeyPairModulus(
UT_HANDLE utHandle,
KEY_HANDLE PubKeyHandle,
unsigned long* lpModulusBits
);
</source>

<b>Description</b>

To get RSA key pair modulus.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>PubKeyHandle [in]</td>
<td>public key handle</td>
</tr>
<tr>
<td>lpModulusBits [out]</td>
<td>modulus length</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE PubKeyHandle;
unsigned long ModulusBits;
ret = UT_RSAGetKeyPairModulus(utHandle, PubKeyHandle, &ModulusBits);
</source>

== UT_RSADeleteKeyPair ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_RSADeleteKeyPair(
UT_HANDLE utHandle,
KEY_HANDLE PubKeyHandle,
KEY_HANDLE PriKeyHandle
);
</source>

<b>Description</b>

To delete the RSA key pair.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>PubKeyHandle [in]</td>
<td>public key handle</td>
</tr>
<tr>
<td>PriKeyHandle [in]</td>
<td>private key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Usage Note</b>

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

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE PubKeyHandle;
KEY_HANDLE PriKeyHandle;
ret = UT_RSADeleteKeyPair(utHandle, PubKeyHandle, PriKeyHandle);
</source>

== UT_MD5HMACGenerateKey ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_MD5HMACGenerateKey(
UT_HANDLE utHandle,
unsigned long KeyLength,
KEY_HANDLE_PTR lpKeyHandle
);
</source>

<b>Description</b>

To generate HMAC-MD5 key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyLength [in]</td>
<td>key length</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Notes:</b>

The length of key is <= 128 bytes

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_FULL</td>
<td>No more keys can be generated</td>
</tr>
</table>

<b>Usage Note</b>

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 <source lang="C">UT_KEY_FULL</source>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_MD5HMACGenerateKey(utHandle, 128, &KeyHandle);
</source>

== UT_MD5HMAC ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_MD5HMAC(
UT_HANDLE utHandle,
KEY_HANDLE KeyHandle,
unsigned char* lpData,
unsigned long DataLength,
unsigned char* lpDigest
);
</source>

<b>Description</b>

To run HMAC-MD5 algorithm.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
<tr>
<td>lpData [in]</td>
<td>data to be digested</td>
</tr>
<tr>
<td>DataLength [in]</td>
<td>data length</td>
</tr>
<tr>
<td>lpDigest [out]</td>
<td>digested data</td>
</tr>
</table>

<b>Notes:</b>

DataLength is 1~128 bytes. lpDigest is 16 bytes

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
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);
</source>

== UT_MD5 ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_MD5(
UT_HANDLE utHandle,
unsigned char* lpData,
unsigned long DataLength,
unsigned char* lpDigest
);
</source>

<b>Description</b>

To run MD5 algorithm.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpData [in]</td>
<td>data to be digested</td>
</tr>
<tr>
<td>DataLength [in]</td>
<td>data length</td>
</tr>
<tr>
<td>lpDigest [out]</td>
<td>digested data</td>
</tr>
</table>

<b>Notes</b>

DataLength is 1~128 bytes. lpDigest is 16 bytes

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned char Data[128];
unsigned char Digest[16];
ret = UT_MD5(utHandle, Data, 128, Digest);
</source>

== UT_MD5GetKeyCount ==

<b>Prototype</b>

<source lang="C">UT_RV UT_API UT_MD5GetKeyCount(UT_HANDLE utHandle, unsigned long* lpKeyCount);</source>

<b>Description</b>

To count HMAC-MD5 keys.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyCount [out]</td>
<td>the number of keys</td>
</tr>
</table>

<b>Notes:</b>

The maximum number of MD5 keys is 8.

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned long KeyCount;
ret = UT_MD5GetKeyCount(utHandle, &KeyCount);
</source>

== UT_MD5GetKeyLen ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_MD5GetKeyLen(
UT_HANDLE utHandle,
KEY_HANDLE KeyHandle,
unsigned long* lpKeyLength
);
</source>

<b>Description</b>

To get the length of HMAC-MD5 key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
<tr>
<td>lpKeyLength [out]</td>
<td>key length</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
unsigned long KeyLength;
ret = UT_MD5GetKeyLen(utHandle, KeyHandle, &KeyLength);
</source>

== UT_MD5GetFirstKeyHandle ==

<b>Prototype</b>

<source lang="C">UT_RV UT_API UT_MD5GetFirstKeyHandle(UT_HANDLE utHandle, KEY_HANDLE_PTR lpKeyHandle);</source>

<b>Description</b>

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

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
</table>

<b>Sample</b>

See the samples of <source lang="C">UT_MD5GetNextKeyHandle</source>

== UT_MD5GetNextKeyHandle ==

<b>Prototype</b>

<source lang="C">UT_RV UT_API UT_MD5GetNextKeyHandle(UT_HANDLE utHandle, KEY_HANDLE_PTR lpKeyHandle);</source>

<b>Description</b>

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

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
<tr>
<td>UT_OPERATE_INVALID</td>
<td>Invalid operation</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_MD5GetFirstKeyHandle(utHandle, &KeyHandle);
ret = UT_MD5GetNextKeyHandle(utHandle, &KeyHandle);
</source>

== UT_MD5DeleteKey ==

<b>Prototype</b>

<source lang="C">UT_RV UT_API UT_MD5DeleteKey(UT_HANDLE utHandle, KEY_HANDLE KeyHandle);</source>

<b>Description</b>

To delete HMAC-MD5 key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_MD5DeleteKey(utHandle, KeyHandle);
</source>

== UT_MD5ImportKey ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_MD5ImportKey(
UT_HANDLE utHandle,
unsigned char* lpKey,
unsigned long KeyLength,
KEY_HANDLE_PTR lpKeyHandle
);
</source>

<b>Description</b>

To import HMAC-MD5 key to UniToken device.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyLength [in]</td>
<td>key length</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Notes:</b>

KeyLength is 1~128 bytes.

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_FULL</td>
<td>No more keys can be generated</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
unsigned char Key[128];
ret = UT_MD5ImportKey(utHandle, Key, 128, &KeyHandle);
</source>

== UT_SHA1HMACGenerateKey ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_SHA1HMACGenerateKey(
UT_HANDLE utHandle,
unsigned long KeyLength,
KEY_HANDLE_PTR lpKeyHandle
);
</source>

<b>Description</b>

To generate HMAC-SHA1 key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyLength [in]</td>
<td>key length</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Notes:</b>

The length of key is <=128 bytes.

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_FULL</td>
<td>No more keys can be generated</td>
</tr>
</table>

<b>Usage Note</b>

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 <source lang="C">UT_KEY_FULL</source>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_SHA1HMACGenerateKey(utHandle, 128, &KeyHandle);
</source>

== UT_SHA1HMAC ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_SHA1HMAC(
UT_HANDLE utHandle,
KEY_HANDLE KeyHandle,
unsigned char* lpData,
unsigned long DataLength,
unsigned char* lpDigest
);
</source>

<b>Description</b>

To run HMAC-SHA1 algorithm.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
<tr>
<td>lpData [in]</td>
<td>data to be digested</td>
</tr>
<tr>
<td>DataLength [in]</td>
<td>data length</td>
</tr>
<tr>
<td>lpDigest [out]</td>
<td>digested data</td>
</tr>
</table>

<b>Notes:</b>

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

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
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);
</source>

== UT_SHA1 ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_SHA1(
UT_HANDLE utHandle,
unsigned char* lpData,
unsigned long DataLength,
unsigned char* lpDigest
);
</source>

<b>Description</b>

To run SHA1 algorithm.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpData [in]</td>
<td>data to be digested</td>
</tr>
<tr>
<td>DataLength [in]</td>
<td>data length</td>
</tr>
<tr>
<td>lpDigest [out]</td>
<td>digested data</td>
</tr>
</table>

<b>Notes:</b>

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

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned char Data[128];
unsigned char Digest[20];
ret = UT_SHA1(utHandle, Data, 128, Digest);
</source>

== UT_SHA1GetKeyCount ==

<b>Prototype</b>

<source lang="C">UT_RV UT_API UT_SHA1GetKeyCount(UT_HANDLE utHandle, unsigned long* lpKeyCount);</source>

<b>Description</b>

To count HMAC-SHA1 keys

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyCount [out]</td>
<td>the number of keys</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned long KeyCount;
ret = UT_SHA1GetKeyCount(utHandle, &KeyCount);
</source>

== UT_SHA1GetKeyLen ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_SHA1GetKeyLen(
UT_HANDLE utHandle,
KEY_HANDLE KeyHandle,
unsigned long* lpKeyLength
);
</source>

<b>Description</b>

To get the length of HMAC-SHA1 key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
<tr>
<td>lpKeyLength [out]</td>
<td>key length</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
unsigned long KeyLength;
ret = UT_SHA1GetKeyLen(utHandle, KeyHandle, &KeyLength);
</source>

== UT_SHA1GetFirstKeyHandle ==

<b>Prototype</b>

<source lang="C">UT_RV UT_API UT_SHA1GetFirstKeyHandle(UT_HANDLE utHandle, KEY_HANDLE_PTR lpKeyHandle);</source>

<b>Description</b>

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

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
</table>

<b>Sample</b>

See also the sample of <source lang="C">UT_SHA1GetNextKeyHandle</source>

== UT_SHA1GetNextKeyHandle ==

<b>Prototype</b>

<source lang="C">UT_RV UT_API UT_SHA1GetNextKeyHandle(UT_HANDLE utHandle, KEY_HANDLE_PTR lpKeyHandle);</source>

<b>Description</b>

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

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_KEY</td>
<td>No key found</td>
</tr>
<tr>
<td>UT_OPERATE_INVALID</td>
<td>Invalid operation</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_SHA1GetFirstKeyHandle(utHandle, &KeyHandle);
ret = UT_SHA1GetNextKeyHandle(utHandle, &KeyHandle);
</source>

== UT_SHA1DeleteKey ==

<b>Prototype</b>

<source lang="C">UT_RV UT_API UT_SHA1DeleteKey(UT_HANDLE utHandle, KEY_HANDLE KeyHandle);</source>

<b>Description</b>

To delete HMAC-SHA1 key.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>KeyHandle [in]</td>
<td>key handle</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_HANDLE_INVALID</td>
<td>Invalid key handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
ret = UT_SHA1DeleteKey(utHandle, KeyHandle);
</source>

== UT_SHA1ImportKey ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_SHA1ImportKey(
UT_HANDLE utHandle,
unsigned char* lpKey,
unsigned long KeyLength,
KEY_HANDLE_PTR lpKeyHandle
);
</source>

<b>Description</b>

To import HMAC-SHA1 key to UniToken device.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpKey [in]</td>
<td>SHA1 key</td>
</tr>
<tr>
<td>KeyLength [in]</td>
<td>key length</td>
</tr>
<tr>
<td>lpKeyHandle [out]</td>
<td>key handle</td>
</tr>
</table>

<b>Notes:</b>

KeyLength is 1~128 bytes.

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_KEY_FULL</td>
<td>No more keys can be generated</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
KEY_HANDLE KeyHandle;
unsigned char Key[128];
ret = UT_SHA1ImportKey(utHandle, Key, 128, &KeyHandle);
</source>

== UT_FS_GetSpace ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_FS_GetSpace(
UT_HANDLE utHandle,
unsigned long* UsedSpace,
unsigned long* FreeSpace
);
</source>

<b>Description</b>

To get the size of the free memory.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UsedSize [out]</td>
<td>size of used memory</td>
</tr>
<tr>
<td>FreeSize [out]</td>
<td>size of free memory</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned long UsedSpace;
unsigned long FreeSpace;
ret = UT_FS_GetSpace(utHandle, &UsedSpace, &FreeSpace);
</source>

== UT_FS_GetFileCount ==

<b>Prototype</b>

<source lang="C">UT_RV UT_API UT_FS_GetFileCount(UT_HANDLE utHandle, unsigned long* lpFileCount);</source>

<b>Description</b>

To get the number of files.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpFileCount [out]</td>
<td>the number of files</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_FS_NO_FILE</td>
<td>No file found</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned long FileCount;
ret = UT_FS_GetFileCount(utHandle, &FileCount);
</source>

== UT_FS_GetFirstFileName ==

<b>Prototype</b>

<source lang="C">UT_RV UT_API UT_FS_GetFirstFileName(UT_HANDLE utHandle, char* lpszFileName);</source>

<b>Description</b>

To get the name of the first file.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpszFileName [out]</td>
<td>filename (string, 16 bytes)</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_FS_NO_FILE</td>
<td>No file found</td>
</tr>
</table>

<b>Sample</b>

See also the sample of <source lang="C">UT_GetNextFileName</source>

== UT_FS_GetNextFileName ==

<b>Prototype</b>

<source lang="C">UT_RV UT_API UT_FS_GetNextFileName(UT_HANDLE utHandle, char* lpszFileName);</source>

<b>Description</b>
To get the name of the next file.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpszFileName [out]</td>
<td>filename (string, 16 bytes)</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_FS_LIST_END</td>
<td>End of fire list</td>
</tr>
<tr>
<td>UT_OPERATE_INVALID</td>
<td>Invalid operation</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
char FileName[17];
ret = UT_FS_GetFirstFileName(utHandle, FileName);
ret = UT_FS_GetNextFileName(utHandle, FileName);
</source>

== UT_FS_GetFileSize ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_FS_GetFileSize(
UT_HANDLE utHandle,
char* lpszFileName,
unsigned long* lpFileSize
);
</source>

<b>Description</b>

To get the file size.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpszFileName [in]</td>
<td>filename (string, 16 bytes)</td>
</tr>
<tr>
<td>lpFileSize [out]</td>
<td>size of file</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_FS_NAME_LEN_RANGE</td>
<td>Filename too long</td>
</tr>
<tr>
<td>UT_FS_NO_FILE</td>
<td>No file found</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
char FileName[17];
unsigned long FileSize;
ret = UT_FS_GetFileSize(utHandle, FileName, &FileSize);
</source>

== UT_FS_GetFilePermission ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_FS_GetFilePermission(
UT_HANDLE utHandle,
char* lpszFileName,
unsigned char* lpFilePermission
);
</source>

<b>Description</b>

To get the file permission of the specified file.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpszFileName [in]</td>
<td>filename (string, 16 bytes)</td>
</tr>
<tr>
<td>lpFilePermission [out]</td>
<td>file permission</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_FS_NAME_LEN_RANGE</td>
<td>Filename too long</td>
</tr>
<tr>
<td>UT_FS_NO_FILE</td>
<td>No file found</td>
</tr>
</table>

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
char FileName[17];
unsigned char FilePermission;
ret = UT_FS_GetFilePermission(utHandle, FileName, &FilePermission);
</source>

== UT_FS_CreatFile ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_FS_CreateFile(
UT_HANDLE utHandle,
char* lpszFileName,
unsigned long FileSize,
unsigned char FilePermission
);
</source>

<b>Description</b>

To create a file.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpszFileName [in]</td>
<td>filename (string, 16 bytes)</td>
</tr>
<tr>
<td>FileSize [in]</td>
<td>size of file</td>
</tr>
<tr>
<td>FilePermission [in]</td>
<td>file permission</td>
</tr>
</table>

<b>Notes:</b>

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

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_FS_NAME_LEN_RANGE</td>
<td>Filename too long</td>
</tr>
<tr>
<td>UT_FS_FILE_EXIST</td>
<td>The file already exists</td>
</tr>
</table>

<b>Usage Note</b>
File permission types:
# FILE_PERMISSION_GUEST: With GUEST and higher permissions, reading the file is allowed; With USER and higher permissions, writing file is allowed.
# FILE_PERMISSION_USER: With USER and higher permissions, reading and writing file are allowed.
# FILE_PERMISSION_ADMIN: Only ADMIN is allowed to read and write the file.

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
char FileName[17];
ret = UT_FS_CreateFile(utHandle, FileName, 200, FILE_PERMISSION_GUEST);
</source>

== UT_FS_DeleteFile ==

<b>Prototype</b>

<source lang="C">UT_RV UT_API UT_FS_DeleteFile(UT_HANDLE utHandle, char* lpszFileName);</source>

<b>Description</b>

To delete a file.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpszFileName [in]</td>
<td>filename (string, 16 bytes)</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_FS_NAME_LEN_RANGE</td>
<td>Filename too long</td>
</tr>
<tr>
<td>UT_FS_NO_FILE</td>
<td>No file found</td>
</tr>
</table>

<b>Usage Note</b>

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.

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
char FileName[17];
ret = UT_FS_DeleteFile(utHandle, FileName);
</source>

== UT_FS_OpenFile ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_FS_OpenFile(
UT_HANDLE utHandle,
char* lpszFileName,
void* lpReserve
);
</source>

<b>Description</b>

To open a file.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpszFileName [in]</td>
<td>filename (string, 16 bytes)</td>
</tr>
<tr>
<td>lpReserve<td>
<td>reserved for further usage</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_FS_NAME_LEN_RANGE</td>
<td>Filename too long</td>
</tr>
<tr>
<td>UT_FS_NO_FILE</td>
<td>No file found</td>
</tr>
</table>

<b>Usage Note</b>

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.

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
char FileName[17];
ret = UT_FS_OpenFile(utHandle, FileName, NULL);
</source>

== UT_FS_WriteFile ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_FS_WriteFile(
UT_HANDLE utHandle,
unsigned long Offset,
unsigned long Length,
unsigned char* Buffer,
void* lpReserve
);
</source>

<b>Description</b>

To write or modify a file.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>Offset [in]</td>
<td>start position for writing</td>
</tr>
<tr>
<td>Length [in]</td>
<td>length of data</td>
</tr>
<tr>
<td>Buffer [in]</td>
<td>data to write</td>
</tr>
<tr>
<td>lpReserve</td>
<td>reserved for further usage</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_FS_OFFSET_INVALID</td>
<td>Invalid start point for specified file</td>
</tr>
<tr>
<td>UT_FS_NO_OPEN</td>
<td>Cannot open file</td>
</tr>
<tr>
<td>UT_FS_NOSPACE</td>
<td>No room in file system</td>
</tr>
<tr>
<td>UT_FS_NO_FILE</td>
<td>No file found</td>
</tr>
</table>

<b>Usage Note</b>

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.

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned long Offset;
unsigned char Buffer[200];
ret = UT_FS_WriteFile(utHandle, 0, 200, Buffer, NULL);
</source>

== UT_FS_ReadFile ==

<b>Prototype</b>

<source lang="C">
UT_RV UT_API UT_FS_ReadFile(
UT_HANDLE utHandle,
unsigned long Offset,
unsigned long Length,
unsigned char* Buffer,
void* lpReserve
);
</source>

<b>Description</b>

To read a file.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>Offset [in]</td>
<td>start position for writing</td>
</tr>
<tr>
<td>Length [in]</td>
<td>length of data</td>
</tr>
<tr>
<td>Buffer [in]</td>
<td>data to write</td>
</tr>
<tr>
<td>lpReserve</td>
<td>reserved for further usage</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_ARGUMENTS_BAD</td>
<td>Invalid argument</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_FS_OFFSET_INVALID</td>
<td>Invalid start point for specified file</td>
</tr>
<tr>
<td>UT_FS_NO_OPEN</td>
<td>Cannot open file</td>
</tr>
<tr>
<td>UT_FS_DATA_LEN_RANGE</td>
<td>Out of range of data length<td>
</tr>
<tr>
<td>UT_FS_NO_FILE</td>
<td>No file found</td>
</tr>
</table>

<b>Usage Note</b>

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.

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
unsigned long Offset;
unsigned char Buffer[200];
ret = UT_FS_ReadFile(utHandle, 0, 200, Buffer, NULL);
</source>

== UT_FS_CloseFile ==

<b>Prototype</b>

<source lang="C">UT_RV UT_API UT_FS_CloseFile(UT_HANDLE utHandle, void* lpReserve);</source>

<b>Description</b>

To close a file.

<b>Parameters</b>

<table class="wikitable">
<tr>
<th>PARAMETERS</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>utHandle [in]</td>
<td>device handle</td>
</tr>
<tr>
<td>lpReserve</td>
<td>reserved for further usage</td>
</tr>
</table>

<b>Returned Value</b>

<table class="wikitable">
<tr>
<th>RETURNED VALUE</th>
<th>DESCRIPTION</th>
</tr>
<tr>
<td>UT_OK</td>
<td>Successful operation</td>
</tr>
<tr>
<td>UT_NOT_INITIALIZE</td>
<td>Library not initialized</td>
</tr>
<tr>
<td>UT_TOKEN_HANDLE_INVALID</td>
<td>Invalid token handle</td>
</tr>
<tr>
<td>UT_NO_PERMISSION</td>
<td>No permission</td>
</tr>
<tr>
<td>UT_FS_NO_OPEN</td>
<td>Cannot open file</td>
</tr>
</table>

<b>Usage Note</b>

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.

<b>Sample</b>

<source lang="C">
UT_RV ret;
UT_HANDLE utHandle;
ret = UT_FS_CloseFile(utHandle, NULL);
</source>

UniToken API Reference

2016-08-23T05:30:49Z

Bao: Major rework of tables, everything

UniKey Console Tool

2016-08-23T00:22:32Z

Bao:

[[category:UniKey Manuals]]
==<b>UniKey Console</b>==

<b>User Guide</b>

<b><i>Version 8.3</i></b>

<table class="wikitable">
<tr>
<td style="background-color: red;"><b style="color: #fff;">Version</b></td>
<td>1.0</td>
<td>1.1</td>
<td>1.2</td>
<td>1.3</td>
<td>2.0</td>
<td>2.1</td>
<td>2.2</td>
<td>3.0</td>
<td>4.0</td>
<td>5.0</td>
<td>6.0</td>
<td>7.0</td>
<td>7.1</td>
<td>7.3</td>
<td>8.0</td>
<td>8.1</td>
<td>8.2</td>
<td>8.3</td>
</tr>
<tr>
<td style="background-color: red;"><b style="color: #fff;">Date</b></td>
<td>2006.1</td>
<td>2006.8</td>
<td>2006.10</td>
<td>2006.12</td>
<td>2007.2</td>
<td>2007.4</td>
<td>2007.8</td>
<td>2008.5</td>
<td>2008.8</td>
<td>2009.3</td>
<td>2010.4</td>
<td>2010.6</td>
<td>2010.8</td>
<td>2010.9</td>
<td>2012.3</td>
<td>2012.4</td>
<td>2016.5</td>
<td>2016.7</td>
</tr>
</table>

==Introduction==
UniKey Console is a powerful tool to help software vendors manage their software development, license software and track their software sales performance. It can be integrated into your ERP, CRM and financial system seamlessly.
The UniKey Console is designed to follow the waterfall software development procedure, which helps software vendors manage their different products along its whole lifecycle. The feature based license management method is an innovative way to protect your software away from intruders and to license efficiently.

To administrate all software, check the sales history and gather information to prepare for the following software development, UniKey Console employs a database to record information. It supports almost all database techniques available in todays market, such as SQL, MySQL, and Oracle.
Additionally, this Console supports multiple users logging in to the system. Different operators in different roles can logon and operate the Console utility within their personal level of permission. For example, employees from a product department can login to the Console system, and submit product orders, but they cannot see any other information about the sales department.

<div style="page-break-before:always"></div>
==Deployment==
This section will introduce how to deploy the UniKey Console on your system. The Console has two parts, the front is a GUI which is green software and does not need any installation. Users simply copy the folder to their computer. The next step is to install a database and create tables. In the SDK we provide instructional pictures, follow the pictures to finish the MySQL installation. If no version of MySQL Server is included in the SDK, you can download the latest version from: https://dev.mysql.com/downloads/mysql/. After installing the database, click on Start, and open the MySQL Command Line Client. Log in to the database by entering your password.

[[File:MySQL console.png|left|500px|alt=MySQL command line client]]

<table class="wikitable" align="left" style="width: 100px;">
<tr>
<td align="center"><i>Device mode does not support multiple users and will not keep operation records on the database</i></td>
</tr>
</table>

<div style="clear:both;"></div>
To create the required tables, input <code>"source file directory"\createconsoletables.sql</code> (if that does not work try the command: <code>source "source file directory"\createconsoletables.sql</code>) and press enter. After the database has been successfully built, open the console GUI by double clicking on the Console icon (you may need to re-open the Console application to register any changes to the database).

==UniKey Console Working Mode==
The UniKey Console provides two different modes for users, Manage Mode and Device Mode. The Manage Mode is mainly used to manage the whole lifecycle of your software, and allows multiple operators to logon the system to implement their operations with their own levels of permission. Device mode provides a quick way to configure parameters or generate an update file for a UniKey device.

==Manage Mode==
The UniKey Console Manage Mode closely follows the software lifecycle, from the beginning of software design to the end of software development. At the design stage, software designers will separate the software into different blocks according to their functions. We highly recommend medium to large software vendors use Manage Mode to manage and license your software.

===Login===
This system supports remote login. Users can set up the servers IP via the GUI, and log in to the server remotely to finish their operation. To start using the Console, double click on the UniKey Console. The login interface will pop up.

[[File:console login.png|500px|alt=UniKey Console login page]]

Input the user name and password to log in to the system.
* If this is the first time you are logging in to the system, the user name is administrator, and password is admin.
* The administrator should log in to the system and change their password first, and then he/she can create other accounts for different operators.
* If you try to log in to a server remotely, click on Network Setting and in the pop-up window, input the server IP address and port number.

===Product===
The product panel provides a series of interfaces for product related operations, including creating license features and generating product license strategies by combining one or more license features together.

====Feature Setting====
Feature setting is the most basic element to form a license for a product. For example, if the software requires a license based on expiration time, a time module shall be selected and the expiration time shall be set. This will form a license feature. If more license strategies are going to be used, more license features can be created.

[[File:feature setting console.png|500px|alt=UniKey Console feature setting]]

Click on Add to add a license feature in the pop-up window.

[[File:add license feature.png|500px|alt=UniKey Console add license feature]]

As you can see from the above picture, lots of license features can be used to build up a single product license, such as license module, memory, arithmetic, SID, max connections, partition information, etc.

====License Module====
This feature limits access to the software based on rules. When the correct UniKey is connected, the software bound to the UniKey is activated.

[[File:license module.png|thumb|left|500px|alt=UniKey Console add license feature perpetual|License Module is the most widely used feature on all UniKey devices]]

<div style="clear:both;"></div>
There are two ways to use the License Module. The first is to bind a module to the software, once the module is enabled, the software will start working. The second is to set the execute count, so every time when the software is started the count will decrement until the value reaches 0.

<b>A non-zero number must be set to enable the License Module. This number will not be changed unless Exe Count Mode has been selected.</b>

====Memory====
UniKey has 4KB of memory which allows developers to store any information, such as a software abstract, version information, buyers or developers information, etc.

[[File:console memory.png|500px|alt=UniKey Console writing into memory]]

In the feature setting:
* Input the encoding in the left column.
* Input the start address, which refers to the start point where the content will be stored.
* Input the length, which refers the length of content that will be stored in memory.

====Arithmetic ====
To protect your software safely, it is a good idea to write a block of code inside the UniKey device itself, therefore without the device, the software cannot run. The arithmetic option is designed for this purpose.

[[File:console arithmetic.png|thumb|left|500px|alt=UniKey Console arithmetic feature|For the syntax and how to write an equation, please refer to the UniKey manual in the arithmetic section]]

<div style="clear:both;"></div>
In the feature setting:
* Input your custom arithmetic.
* Input the start address, to set the start point of the arithmetic.
* Input the length, so that the arithmetic will end at the start address plus the length.

====SID Range====
SID is another important property in UniKey that can provide effective license management and software protection. Developers can use this feature to set it so that only one key or several keys can launch a specific copy of software.

[[File:console SID range.png|500px|alt=UniKey Console software ID generation rules]]

<b>Feature setting</b> - In the SID generation mode, which will generate a rule for how UniKey SID codes are created, there are 4 different methods of generation:
* All the same: all SID burned to UniKey devices will be the same.
* Increment: the SID value of every UniKey device will add 1 from the initial value when burning.
* Decrement: the SID value of every UniKey device will decrease by 1
* Time/date: the SID value will be the produced from the current time/date
The initial value gives a starting SID value/position/number.

====Update Tag====
The update tag is mainly used to update related issues. It can be used to record the number of times the software has been updated, or protect an update file from being used by other UniKey devices with a different update tag.

[[File:console update tag.png|500px|alt=UniKey Console update tag]]

====Max Connections====
Some software may employ a floating license strategy, where people on the network will share a license. The maximum number of connections can restrict the total number of users who share a license simultaneously on a local network.

[[File:console max connections.png|500px|alt=UniKey Console number of max connections]]

====Seed====
For every UniKey device, the password cannot be customized, but developers can generate their own passwords by themselves. Passwords can be generated by entering a seed value in the seed setting, and when a license is produced, the password of the device will be changed to the value calculated by the UniKey system based on this seed value.

[[File:console seed.png|500px|alt=UniKey Console set seed]]

In the feature setting, input the seed value.
* Each UniKey dongle can only generate a new password TWICE! After this it cannot generate anymore passwords.
* When generating a new password, the dongle is formatted.
* <b>To reset the password for a 3rd time, the UniKey dongle must be sent back to SecuTech</b>

====Partition information====
Each UniKey Drive device has four partitions:
* Virtual CD-ROM emulation drive
* Public partition
* Password protected partition
* Hidden partition
This page is used by customers to set the space for each partition on the UniKey Drive device.

[[File:console partition information.png|500px|alt=UniKey Drive partition information]]

====Files in hidden partition====
UniKey Drive has a unique hidden partition which allows users to store files. Each file stored on the hidden partition is invisible and inaccessible to end users. Vendors could integrate UniKey Drive APIs with their software and then that software will be able to access the files stored on the UniKey Drives hidden partition.

[[File:console hidden partition files.png|500px|alt=UniKey Drive hidden partition files]]

The files stored on the hidden partition should have the filename as an 8.3 format, for example, 12345678.123

====Product setting====
Product setting is used to combine the basic license elements and features together to form a product license strategy, to help meet the different requirements of customers, businesses, and sales strategies. For each software package, decision makers can set several license strategies by selecting different license features which have been set in Feature setting, maximizing their market share and revenue. For some special requirements, a customized license can even be quickly generated.

[[File:console product setting.png|500px|alt=UniKey Console product setting]]

The above picture shows the Product setting panel, and to add a license for a product click on the Add button.

After clicking on Add, this window is displayed

[[File:console add product.png|thumb|left|500px|alt=UniKey Console add new product|The configuration will affect this product, and will not change previous Feature settings]]

<div style="clear:both;"></div>
Input the product name; a comment can be added in the comment box, and please select the correct device type(s). In the Feature setting section, you can reset the update tag, max connections, seed, and SID generation mode by checking the respective item boxes. This provides a quick interface to modify the license settings. From the Feature list choose the preferred features from the list and click on > to move them to the products desired features on the right. These features will combine together to form a product license.

[[File:console product setting added.png|thumb|left|500px|alt=UniKey Console list product ID, name and any comments|Once an order has been placed on a product, this product will not be deleted]]

<div style="clear:both;"></div>
Based on the current product, you can create a new license quickly by using the Customize function; you can then input a new name and reset values or add more features to create another license. This allows you to easily create another product with a new name and unique product ID that may share features with other products. A product can be changed by selecting the product and clicking on Edit, or can be deleted by clicking Delete.

<div style="page-break-before:always"></div>
===Sales===
The sale function will help vendors to manage their customers and orders. It contains two configurations: Customer Management and Order Setting.

====Customer Management====
Customer Management will record all information about customers and their order history. If a customer wants to place an order, then this customer must be added to the customer list. Click the button Add to execute the corresponding operation.

====Order Setting====
Order setting contains order related operations, such as place an order, update a product, append a new order to an existing order, edit, delete, submit and check status.

[[File:console order management.png|500px|alt=UniKey Console order management]]

===Production===
Production is mainly used for the production department, once an order has been submitted, the order will be passed to the production department, x and this order will be listed. The producer shall produce the order.

[[File:console product management.png|500px|alt=UniKey Console production management]]

Click on Production, and follow the instruction to finish the production procedure.

[[File:console production progress.png|300px|alt=progress bar for production]]

If there is an error or problem in the order, the producer shall decline the order by clicking on decline, and then the order will be sent back to sales.

===Management===
Administrators shall use the Management tab to add, edit and delete users, including user name, password, and assign permission levels.

[[File:console user management.png|500px|alt=UniKey Console user management]]

==Device Mode==
Device Mode provides you a direct way to configure all parameters for your UniKey device locally or to generate a remote update file. It is suitable for altering UniKey hardware operations and property configurations directly.

[[File:console device setting.png|500px|alt=UniKey Console device mode login screen]]

When you click on Check status, the status of the device connected to the local computer will be displayed in the message box. By entering the correct password, and then clicking on User logon or Vendor logon, you can log in to the device as a user or vendor to perform operations within your level of permission.

===Configure===
Click on Configure on the left side of the control panel, all configuration options will be displayed in the dropdown menu:
* General information
* Memory
* Algorithm
* License and Time Module <em>(Time Module is not available for UniKey Drive)</em>
* New password <em>(Available in General information when logged in as a vendor)</em>
* Encrypt/Decrypt
* Random number <em>(not available for UniKey Drive)</em>
* Format <em>(Under the Initialization tab for UniKey Drive)</em>
* Network

[[File:console device configure.png|500px|alt=UniKey Console configure tab]]

You can configure any properties according to your own desired licensing strategies. By clicking on the corresponding options, you can enter your required parameters.

===General information===

[[File:console device general information.png|500px|alt=UniKey Console general information (SID and Update Tag)]]

<b>The HID is a fixed serial number, and cannot be changed.</b>

In menu, the UniKey devices SID and Update Tag connected to your computer will show in the message box. You can change the SID and Update Tag value, by entering value in the respective input box and then clicking Write.

<div style="clear:both;"></div>
===Memory===

[[File:console device memory.png|500px|alt=UniKey Console device memory details]]

In Memory, you can read, edit, and delete content stored in the UniKeys memory. By clicking on Read, you can read content from the UniKeys memory, and by clicking on Write, you can write all content edited by you into the UniKeys memory. To facilitate your editing, UniKey Console provides a load from file function. By clicking on Load from file, you can load content stored in a file to Console, and then write it to memory by clicking on Write. Alternatively, you can save the data which is read from the UniKeys memory to a file by clicking on Save to file.

===Algorithm===

[[File:console device algorithm.png|500px|UniKey Console write and run algorithms]]

UniKey Algorithm is a very powerful method to protect your software, as this block of code is stored directly in UniKey, independent in memory from where software code is stored. Without the right permissions, this block of code cannot be written to or read by anyone. An algorithm can be typed into the Input algorithm field. You can input more than one statement in your algorithm and each statement is separated by comma.

Input the start address to set the starting point for your algorithm, and input a length to set the end point. The end point address will be the start address plus length. Select a calculation mode, and then click on Write to write your configurations into the UniKey. If you want to run your algorithm for a test, you can initialize the variable, A, B, C, D, seed/module (depending on the selected calculation mode), and start address, and then click on Run. The result from A, B, C, and D will be displayed directly.

<div style="page-break-before:always"></div>
===License Module===

[[File:console device module.png|500px|alt=UniKey Console module settings]]

License Module allows you to enable/disable specified modules and set the number of execution times. In the list on the right side of the console, you can see a list and module status. Click on the white triangle to check each corresponding modules parameters and status.

[[File:Console device module options.png|thumb|left|500px|alt=UniKey Console greater module details|To enable a module, a positive number must be entered]]

<div style="clear:both;"></div>
Click on Check to view the information and status of a device and click on Write to write your configurations.

You can enable/disable the auto-decrement function by toggling the check box next to Auto-decrement. To check the information in all modules, you can click on the Check All button; you can also set all modules by clicking on Write All to write all settings to device.

<div style="page-break-before:always"></div>
===Time Module (UniKey Time Only)===

[[File:UniKey Console Time Module tab.PNG|500px|alt=UniKey Console time module selections]]

The UniKey Time has 16 time modules to work with, and you can bind any time module with your whole software, or bind just a single piece of functionality, helping to achieve a time-based licensing strategy. Clicking on Read Time reads the current time from the dongle, and the time can be set by inputting the time in the Dongle Clock field (DD-MM-YYYY format) and pressing Write Time; otherwise you can synchronize your dongle's clock with your system time by pressing Write system time to device. Clicking on the white triangle icon to the right of any time module allows you to set the details for an individual time module.

====Set Start Time====

[[File:UniKey Console Time Module 0 start time.PNG|500px|alt=time module duration mode (days, hours)]]

You can utilize the current devices time or system time by clicking on Use device time or Use system time respectively. UniKey provides two different methods; expiration and duration, for you to select from (the default being duration). Inputting Duration Time indicates how long the user can use the software after it the given Start Time.

====Set Expiration Time====

[[File:UniKey Console Time Module expiration method.PNG|500px|alt=time module expiration time (YYYY-MM-HH-MM)]]

If a module will never be used, you can click on Write, but if the module has been set before, then to reset the module, you must either erase the module first or check the Re-write option box. You can set more than one module at once by selecting Write All to set your modules in-batch; make sure to click Check All afterwards to check the status of all modules. Clicking on Erase All removes all settings stored each time module, please note that all modules will be initialized, so be careful when using the feature.

===New Password===

[[File:UniKey Console New Password tab.PNG|500px|alt=enter a seed value to generate four new passwords]]

UniKey does not allow users to defined passwords by themselves. The only way to change passwords is by using the password generation mechanism embedded in the UniKey Console. Please input a seed (numbers only) and click on New Password, all new passwords will be displayed in the New Password output boxes and will be recorded into the UniKey Console folder. <b>The passwords of a UniKey dongle can only be changed twice, after which they cannot be changed again.</b>

===Encrypt/Decrypt===

[[File:console device encrypt and decrypt.png|500px|alt=UniKey Console encrypt or decrypt text]]

Each UniKey dongle has an encrypt/decrypt function, and can store 3 keys inside each device. In the encrypt/decrypt option, you can choose the encrypt/decrypt operation, generate keys and check output.
From the Select Operation drop-down menu, you can choose a specific operation. For example, choosing generate key, you can choose the key you want to use and click on Run to generate a secret key for your UniKey.

Encryt/Decrypt: to check the encrypt/decrypt result, you can choose your desired operation from the Select Operation drop-down menu. Select the key, choose the encoding, input your content (the length must be an integer multiple of 16) in the input box and then click Run, you can then see the result in the output box. To reverse the operation, you can click on < between the input and output boxes, choose the opposite operation, and then click on Run to check the result from the output box.
UniKey also provides an MD5 algorithm, for you to perform checksums. You can perform the MD5 calculation by following the same procedure.

===Random Number===

[[File:UniKey Console Random Number tab.PNG|500px|alt=enter a seed to generate four distinct randomly generated numbers]]

UniKey Console provides its own random number generator. By just entering a seed (numbers only) value and clicking Run you are provided with four random numbers in Result; the numbers generated are cryptographically random.

<div style="page-break-before:always"></div>
===Network===

[[File:console device network.png|500px|alt=UniKey Console network settings]]

This option allows you to configure your UniKey device (PRO, Time, and Drive) in a network environment. In the first line, you can set the maximum number of users who can connect to the server simultaneously.

====Client setting====
* Server IP is the servers IP address in the network. This address will guide clients to find the server in the network.
* Server port is the port to build communications between client and server.
* Time-out defines the maximum waiting period. If the client sends a request to the server, but the server does not send a response back in the set time, then the client is denied access.
* The default time-out period is 5 seconds.

<table class="wikitable" align="left" style="width: 100px;">
<tr>
<td align="center"><i>You can use this to control the behavior of the NetUniKey Client</i></td>
</tr>
</table>
The access mode box shows how NetUniKey Clients access the NetUniKey Server. If you set it to access by IP, NetUniKey Server accepts only ONE client per IP. If this value is set to access by process, the NetUniKey client from the same process can only be accepted once. If it is set to access by thread, NetUniKey can be accepted in any thread. Access by shared IP means all requests from a single IP will be counted as 1. To facilitate setting other devices with the same configuration, you can save your configuration information into a file, or to update a device remotely, you can generate an update file.

Working mode specifies how the UniKey Client will operate. If this value is set to local only, the NetUniKey Client will only work with a UniKey dongle attached to a local USB port.
If this value is local->network, the UniKey Client will check for a local UniKey dongle attached to a USB port first, if this fails, it will try to search for the UniKey dongle attached to the UniKey server in the network.
If you set it to network only, the NetUniKey Client will only work with the UniKey dongle attached to the UniKey server. When this value is set to network->local, the NetUniKey client will try to connect with the UniKey dongle attached to UniKey server first, and if it fails, it will try to load a local UniKey attached to a USB port.

Search mode sets how UniKey clients will try to find a UniKey dongle on the network. Local only is used for connecting to the server by using the server IP set in the configuration file. If it is set to local->broadcast, the UniKey client will try to use the information in the configuration file first, if this fails, the UniKey clients will broadcast to the local network to find the UniKey.
If set to broadcast->local, the UniKey clients will broadcast to the network first, and will try to connect to the UniKey specified in NetUniKey configuration file when they cannot find any UniKey via the broadcast. You can save this configuration file by clicking on Save, or read the previous client settings file by clicking on Read.

<div style="clear:both;"></div>

<div style="page-break-before:always"></div>
====Server setting====

[[File:console device network server.png|thumb|left|500px|alt=UniKey Console server settings|The default port is 5680]]

<div style="clear:both;"></div>
In this panel, you can enter the server IP, desired server port, and timeout. Enable/Disable the black and white IP list. To add an IP address to the list, click on the corresponding Add button, in the pop-up window, enter the start and end IP addresses. Or you can move an IP from the black list to white list by clicking on the >/< buttons.
* If the white list is enabled, only IP addresses in this list can access the server. If the list is empty, then no clients can access the server.
* The black list always has the highest priority. When the server starts, it will always check the black list first. If an IP appears in both the black and white list, the IP will be blocked.

===File System===
<b><em>Please note that this section is only for the UniKey Drive Console.</em></b>

File System allows you to manage the hidden and secure partition of the UniKey Drive dongle.

[[File:drive console file system.png|500px|alt=UniKey Drive Console file system initial window]]

====Entering the Hidden Partition====

[[File:drive console hidden partition.png|thumb|none|500px|alt=UniKey Drive Console hidden partition login screen|The default passwords to enter the hidden partition are 12345678]]

To enter the hidden partition, please input all four passwords to the UniKey Drive file system, then press OK. All the data stored on both the hidden and secure partitions are encrypted using a 128-bit encryption algorithm.

[[File:unikey drive hidden partition filesystem.png|500px|alt=UniKey Drive Console hidden partition filesystem]]

====Entering the Secure Partition====

[[File:drive console secure partition login screen.png|thumb|none|500px|alt=UniKey Drive Console secure partition login screen|The default password to enter the secure partition is 123456]]

The secure partition is also known as the password-protected partition; customers can access it by providing the correct password.

===Initialization===
<b><em>Please note that this section is only for the UniKey Drive Console.</em></b>

The Initialization tab for the UniKey Drive contains two parts; format and partition device memory.

[[File:drive console initialization.png|500px|alt=UniKey Drive Console Initialization tab]]

====Format====

[[File:UniKey Drive Initialization Format.png|500px|alt=UniKey Drive Console Initialization Format tab]]

By using the Format function, customers can format the UniKey Drive's 4KB memory, SID, license modules, algorithms and update tags.

====Partition====
To partition the UniKey Drive, you need to input all four passwords to log in to the Drive's filesystem. Pressing Default Password loads the default passwords automatically for you.

[[File:drive console initialization partition.png|thumb|none|500px|alt=UniKey Drive Console Initialization Partition tab|The four default passwords are 12345678]]

Device capacity is the UniKey Drive's total memory; UniKey Drives are available in 2, 4, 8, 16, and 32GB variants. An image file (ISO) is used for UniKey Drive's virtual CD-ROM partition; a user can burn their own ISO files to the Drive's virtual CD-ROM. A vendor can modify the capacity of the hidden, normal, and secure partition. Vendors need to create a password for the secure partition, so that end users are able to open the password-protected partition.

===Generate===

[[File:console generate unikey update.png|500px|alt=UniKey Console read update file]]

====Generate UniKey File====
UniKey file is used by the UniKey Burner tool, when a customer wants to burn the dongles in a batch by using the same configurations and settings, this file will be loaded into the UniKey Burner tool. Pressing the Read button will load the information stored on the .uky file to the Console tool. The Generate button will create the .uky file with the dongles information/settings from the Console tool.

===Generate Update File===

[[File:console generate update file.png|500px|alt=UniKey Console generate update file]]

The Update File is used by the UniKey Drive Remote Updater; it does the same thing as the UniKey Remote Update Generator does.

The Properties to be bound box will allow the customer to bind specific HID, SID, License Modules and Update Tags to the generated .upt2 file. After binding with a specific value, the .upt2 file will check if the values stored inside of the UniKey Drive dongle are the same or not. If they are not the same, the .upt2 file will not update the UniKey Drive.

The Property to be written box allows the customer to use the .upt2 file for updating the settings and configurations of the target UniKey Drive.
File password will allow the customer to set an independent password for the generated .upt2 file, and then when the end user updates their UniKey Drive by using the corresponding .upt2 file, they will need to input this password in order to access/use the .upt2 file.

UniKey Console Tool

2016-08-23T00:21:57Z

Bao:

[[category:UniKey Manuals]]
==<b>UniKey Console</b>==

<b>User Guide</b>

<b><i>Version 8.3</i></b>

<table class="wikitable">
<tr>
<td style="background-color: red;"><b style="color: #fff;">Version</b></td>
<td>1.0</td>
<td>1.1</td>
<td>1.2</td>
<td>1.3</td>
<td>2.0</td>
<td>2.1</td>
<td>2.2</td>
<td>3.0</td>
<td>4.0</td>
<td>5.0</td>
<td>6.0</td>
<td>7.0</td>
<td>7.1</td>
<td>7.3</td>
<td>8.0</td>
<td>8.1</td>
<td>8.2</td>
<td>8.3</td>
</tr>
<tr>
<td style="background-color: red;"><b style="color: #fff;">Date</b></td>
<td>2006.1</td>
<td>2006.8</td>
<td>2006.10</td>
<td>2006.12</td>
<td>2007.2</td>
<td>2007.4</td>
<td>2007.8</td>
<td>2008.5</td>
<td>2008.8</td>
<td>2009.3</td>
<td>2010.4</td>
<td>2010.6</td>
<td>2010.8</td>
<td>2010.9</td>
<td>2012.3</td>
<td>2012.4</td>
<td>2016.5</td>
<td>2016.7</td>
</tr>
</table>

==Introduction==
UniKey Console is a powerful tool to help software vendors manage their software development, license software and track their software sales performance. It can be integrated into your ERP, CRM and financial system seamlessly.
The UniKey Console is designed to follow the waterfall software development procedure, which helps software vendors manage their different products along its whole lifecycle. The feature based license management method is an innovative way to protect your software away from intruders and to license efficiently.

To administrate all software, check the sales history and gather information to prepare for the following software development, UniKey Console employs a database to record information. It supports almost all database techniques available in todays market, such as SQL, MySQL, and Oracle.
Additionally, this Console supports multiple users logging in to the system. Different operators in different roles can logon and operate the Console utility within their personal level of permission. For example, employees from a product department can login to the Console system, and submit product orders, but they cannot see any other information about the sales department.

<div style="page-break-before:always"></div>
==Deployment==
This section will introduce how to deploy the UniKey Console on your system. The Console has two parts, the front is a GUI which is green software and does not need any installation. Users simply copy the folder to their computer. The next step is to install a database and create tables. In the SDK we provide instructional pictures, follow the pictures to finish the MySQL installation. If no version of MySQL Server is included in the SDK, you can download the latest version from: https://dev.mysql.com/downloads/mysql/. After installing the database, click on Start, and open the MySQL Command Line Client. Log in to the database by entering your password.

[[File:MySQL console.png|left|500px|alt=MySQL command line client]]

<table class="wikitable" align="left" style="width: 100px;">
<tr>
<td align="center"><i>Device mode does not support multiple users and will not keep operation records on the database</i></td>
</tr>
</table>

<div style="clear:both;"></div>
To create the required tables, input <code>"source file directory"\createconsoletables.sql</code> (if that does not work try the command: <code>source "source file directory"\createconsoletables.sql</code>) and press enter. After the database has been successfully built, open the console GUI by double clicking on the Console icon (you may need to re-open the Console application to register any changes to the database).

==UniKey Console Working Mode==
The UniKey Console provides two different modes for users, Manage Mode and Device Mode. The Manage Mode is mainly used to manage the whole lifecycle of your software, and allows multiple operators to logon the system to implement their operations with their own levels of permission. Device mode provides a quick way to configure parameters or generate an update file for a UniKey device.

==Manage Mode==
The UniKey Console Manage Mode closely follows the software lifecycle, from the beginning of software design to the end of software development. At the design stage, software designers will separate the software into different blocks according to their functions. We highly recommend medium to large software vendors use Manage Mode to manage and license your software.

===Login===
This system supports remote login. Users can set up the servers IP via the GUI, and log in to the server remotely to finish their operation. To start using the Console, double click on the UniKey Console. The login interface will pop up.

[[File:console login.png|500px|alt=UniKey Console login page]]

Input the user name and password to log in to the system.
* If this is the first time you are logging in to the system, the user name is administrator, and password is admin.
* The administrator should log in to the system and change their password first, and then he/she can create other accounts for different operators.
* If you try to log in to a server remotely, click on Network Setting and in the pop-up window, input the server IP address and port number.

===Product===
The product panel provides a series of interfaces for product related operations, including creating license features and generating product license strategies by combining one or more license features together.

====Feature Setting====
Feature setting is the most basic element to form a license for a product. For example, if the software requires a license based on expiration time, a time module shall be selected and the expiration time shall be set. This will form a license feature. If more license strategies are going to be used, more license features can be created.

[[File:feature setting console.png|500px|alt=UniKey Console feature setting]]

Click on Add to add a license feature in the pop-up window.

[[File:add license feature.png|500px|alt=UniKey Console add license feature]]

As you can see from the above picture, lots of license features can be used to build up a single product license, such as license module, memory, arithmetic, SID, max connections, partition information, etc.

====License Module====
This feature limits access to the software based on rules. When the correct UniKey is connected, the software bound to the UniKey is activated.

[[File:license module.png|thumb|left|500px|alt=UniKey Console add license feature perpetual|License Module is the most widely used feature on all UniKey devices]]

<div style="clear:both;"></div>
There are two ways to use the License Module. The first is to bind a module to the software, once the module is enabled, the software will start working. The second is to set the execute count, so every time when the software is started the count will decrement until the value reaches 0.

<b>A non-zero number must be set to enable the License Module. This number will not be changed unless Exe Count Mode has been selected.</b>

====Memory====
UniKey has 4KB of memory which allows developers to store any information, such as a software abstract, version information, buyers or developers information, etc.

[[File:console memory.png|500px|alt=UniKey Console writing into memory]]

In the feature setting:
* Input the encoding in the left column.
* Input the start address, which refers to the start point where the content will be stored.
* Input the length, which refers the length of content that will be stored in memory.

====Arithmetic ====
To protect your software safely, it is a good idea to write a block of code inside the UniKey device itself, therefore without the device, the software cannot run. The arithmetic option is designed for this purpose.

[[File:console arithmetic.png|thumb|left|500px|alt=UniKey Console arithmetic feature|For the syntax and how to write an equation, please refer to the UniKey manual in the arithmetic section]]

<div style="clear:both;"></div>
In the feature setting:
* Input your custom arithmetic.
* Input the start address, to set the start point of the arithmetic.
* Input the length, so that the arithmetic will end at the start address plus the length.

====SID Range====
SID is another important property in UniKey that can provide effective license management and software protection. Developers can use this feature to set it so that only one key or several keys can launch a specific copy of software.

[[File:console SID range.png|500px|alt=UniKey Console software ID generation rules]]

<b>Feature setting</b> - In the SID generation mode, which will generate a rule for how UniKey SID codes are created, there are 4 different methods of generation:
* All the same: all SID burned to UniKey devices will be the same.
* Increment: the SID value of every UniKey device will add 1 from the initial value when burning.
* Decrement: the SID value of every UniKey device will decrease by 1
* Time/date: the SID value will be the produced from the current time/date
The initial value gives a starting SID value/position/number.

====Update Tag====
The update tag is mainly used to update related issues. It can be used to record the number of times the software has been updated, or protect an update file from being used by other UniKey devices with a different update tag.

[[File:console update tag.png|500px|alt=UniKey Console update tag]]

====Max Connections====
Some software may employ a floating license strategy, where people on the network will share a license. The maximum number of connections can restrict the total number of users who share a license simultaneously on a local network.

[[File:console max connections.png|500px|alt=UniKey Console number of max connections]]

====Seed====
For every UniKey device, the password cannot be customized, but developers can generate their own passwords by themselves. Passwords can be generated by entering a seed value in the seed setting, and when a license is produced, the password of the device will be changed to the value calculated by the UniKey system based on this seed value.

[[File:console seed.png|500px|alt=UniKey Console set seed]]

In the feature setting, input the seed value.
* Each UniKey dongle can only generate a new password TWICE! After this it cannot generate anymore passwords.
* When generating a new password, the dongle is formatted.
* <b>To reset the password for a 3rd time, the UniKey dongle must be sent back to SecuTech</b>

====Partition information====
Each UniKey Drive device has four partitions:
* Virtual CD-ROM emulation drive
* Public partition
* Password protected partition
* Hidden partition
This page is used by customers to set the space for each partition on the UniKey Drive device.

[[File:console partition information.png|500px|alt=UniKey Drive partition information]]

====Files in hidden partition====
UniKey Drive has a unique hidden partition which allows users to store files. Each file stored on the hidden partition is invisible and inaccessible to end users. Vendors could integrate UniKey Drive APIs with their software and then that software will be able to access the files stored on the UniKey Drives hidden partition.

[[File:console hidden partition files.png|500px|alt=UniKey Drive hidden partition files]]

The files stored on the hidden partition should have the filename as an 8.3 format, for example, 12345678.123

====Product setting====
Product setting is used to combine the basic license elements and features together to form a product license strategy, to help meet the different requirements of customers, businesses, and sales strategies. For each software package, decision makers can set several license strategies by selecting different license features which have been set in Feature setting, maximizing their market share and revenue. For some special requirements, a customized license can even be quickly generated.

[[File:console product setting.png|500px|alt=UniKey Console product setting]]

The above picture shows the Product setting panel, and to add a license for a product click on the Add button.

After clicking on Add, this window is displayed

[[File:console add product.png|thumb|left|500px|alt=UniKey Console add new product|The configuration will affect this product, and will not change previous Feature settings]]

<div style="clear:both;"></div>
Input the product name; a comment can be added in the comment box, and please select the correct device type(s). In the Feature setting section, you can reset the update tag, max connections, seed, and SID generation mode by checking the respective item boxes. This provides a quick interface to modify the license settings. From the Feature list choose the preferred features from the list and click on > to move them to the products desired features on the right. These features will combine together to form a product license.

[[File:console product setting added.png|thumb|left|500px|alt=UniKey Console list product ID, name and any comments|Once an order has been placed on a product, this product will not be deleted]]

<div style="clear:both;"></div>
Based on the current product, you can create a new license quickly by using the Customize function; you can then input a new name and reset values or add more features to create another license. This allows you to easily create another product with a new name and unique product ID that may share features with other products. A product can be changed by selecting the product and clicking on Edit, or can be deleted by clicking Delete.

<div style="page-break-before:always"></div>
===Sales===
The sale function will help vendors to manage their customers and orders. It contains two configurations: Customer Management and Order Setting.

====Customer Management====
Customer Management will record all information about customers and their order history. If a customer wants to place an order, then this customer must be added to the customer list. Click the button Add to execute the corresponding operation.

====Order Setting====
Order setting contains order related operations, such as place an order, update a product, append a new order to an existing order, edit, delete, submit and check status.

[[File:console order management.png|500px|alt=UniKey Console order management]]

===Production===
Production is mainly used for the production department, once an order has been submitted, the order will be passed to the production department, x and this order will be listed. The producer shall produce the order.

[[File:console product management.png|500px|alt=UniKey Console production management]]

Click on Production, and follow the instruction to finish the production procedure.

[[File:console production progress.png|300px|alt=progress bar for production]]

If there is an error or problem in the order, the producer shall decline the order by clicking on decline, and then the order will be sent back to sales.

===Management===
Administrators shall use the Management tab to add, edit and delete users, including user name, password, and assign permission levels.

[[File:console user management.png|500px|alt=UniKey Console user management]]

==Device Mode==
Device Mode provides you a direct way to configure all parameters for your UniKey device locally or to generate a remote update file. It is suitable for altering UniKey hardware operations and property configurations directly.

[[File:console device setting.png|500px|alt=UniKey Console device mode login screen]]

When you click on Check status, the status of the device connected to the local computer will be displayed in the message box. By entering the correct password, and then clicking on User logon or Vendor logon, you can log in to the device as a user or vendor to perform operations within your level of permission.

===Configure===
Click on Configure on the left side of the control panel, all configuration options will be displayed in the dropdown menu:
* General information
* Memory
* Algorithm
* License and Time Module <em>(Time Module is not available for UniKey Drive)</em>
* New password <em>(Available in General information when logged in as a vendor)</em>
* Encrypt/Decrypt
* Random number <em>(not available for UniKey Drive)</em>
* Format <em>(Under the Initialization tab for UniKey Drive)</em>
* Network

[[File:console device configure.png|500px|alt=UniKey Console configure tab]]

You can configure any properties according to your own desired licensing strategies. By clicking on the corresponding options, you can enter your required parameters.

===General information===

[[File:console device general information.png|500px|alt=UniKey Console general information (SID and Update Tag)]]

<b>The HID is a fixed serial number, and cannot be changed.</b>

In menu, the UniKey devices SID and Update Tag connected to your computer will show in the message box. You can change the SID and Update Tag value, by entering value in the respective input box and then clicking Write.

<div style="clear:both;"></div>
===Memory===

[[File:console device memory.png|500px|alt=UniKey Console device memory details]]

In Memory, you can read, edit, and delete content stored in the UniKeys memory. By clicking on Read, you can read content from the UniKeys memory, and by clicking on Write, you can write all content edited by you into the UniKeys memory. To facilitate your editing, UniKey Console provides a load from file function. By clicking on Load from file, you can load content stored in a file to Console, and then write it to memory by clicking on Write. Alternatively, you can save the data which is read from the UniKeys memory to a file by clicking on Save to file.

===Algorithm===

[[File:console device algorithm.png|500px|UniKey Console write and run algorithms]]

UniKey Algorithm is a very powerful method to protect your software, as this block of code is stored directly in UniKey, independent in memory from where software code is stored. Without the right permissions, this block of code cannot be written to or read by anyone. An algorithm can be typed into the Input algorithm field. You can input more than one statement in your algorithm and each statement is separated by comma.

Input the start address to set the starting point for your algorithm, and input a length to set the end point. The end point address will be the start address plus length. Select a calculation mode, and then click on Write to write your configurations into the UniKey. If you want to run your algorithm for a test, you can initialize the variable, A, B, C, D, seed/module (depending on the selected calculation mode), and start address, and then click on Run. The result from A, B, C, and D will be displayed directly.

<div style="page-break-before:always"></div>
===License Module===

[[File:console device module.png|500px|alt=UniKey Console module settings]]

License Module allows you to enable/disable specified modules and set the number of execution times. In the list on the right side of the console, you can see a list and module status. Click on the white triangle to check each corresponding modules parameters and status.

[[File:Console device module options.png|thumb|left|500px|alt=UniKey Console greater module details|To enable a module, a positive number must be entered]]

<div style="clear:both;"></div>
Click on Check to view the information and status of a device and click on Write to write your configurations.

You can enable/disable the auto-decrement function by toggling the check box next to Auto-decrement. To check the information in all modules, you can click on the Check All button; you can also set all modules by clicking on Write All to write all settings to device.

===Time Module (UniKey Time Only)===

[[File:UniKey Console Time Module tab.PNG|500px|alt=UniKey Console time module selections]]

The UniKey Time has 16 time modules to work with, and you can bind any time module with your whole software, or bind just a single piece of functionality, helping to achieve a time-based licensing strategy. Clicking on Read Time reads the current time from the dongle, and the time can be set by inputting the time in the Dongle Clock field (DD-MM-YYYY format) and pressing Write Time; otherwise you can synchronize your dongle's clock with your system time by pressing Write system time to device. Clicking on the white triangle icon to the right of any time module allows you to set the details for an individual time module.

====Set Start Time====

[[File:UniKey Console Time Module 0 start time.PNG|500px|alt=time module duration mode (days, hours)]]

You can utilize the current devices time or system time by clicking on Use device time or Use system time respectively. UniKey provides two different methods; expiration and duration, for you to select from (the default being duration). Inputting Duration Time indicates how long the user can use the software after it the given Start Time.

====Set Expiration Time====

[[File:UniKey Console Time Module expiration method.PNG|500px|alt=time module expiration time (YYYY-MM-HH-MM)]]

If a module will never be used, you can click on Write, but if the module has been set before, then to reset the module, you must either erase the module first or check the Re-write option box. You can set more than one module at once by selecting Write All to set your modules in-batch; make sure to click Check All afterwards to check the status of all modules. Clicking on Erase All removes all settings stored each time module, please note that all modules will be initialized, so be careful when using the feature.

===New Password===

[[File:UniKey Console New Password tab.PNG|500px|alt=enter a seed value to generate four new passwords]]

UniKey does not allow users to defined passwords by themselves. The only way to change passwords is by using the password generation mechanism embedded in the UniKey Console. Please input a seed (numbers only) and click on New Password, all new passwords will be displayed in the New Password output boxes and will be recorded into the UniKey Console folder. <b>The passwords of a UniKey dongle can only be changed twice, after which they cannot be changed again.</b>

===Encrypt/Decrypt===

[[File:console device encrypt and decrypt.png|500px|alt=UniKey Console encrypt or decrypt text]]

Each UniKey dongle has an encrypt/decrypt function, and can store 3 keys inside each device. In the encrypt/decrypt option, you can choose the encrypt/decrypt operation, generate keys and check output.
From the Select Operation drop-down menu, you can choose a specific operation. For example, choosing generate key, you can choose the key you want to use and click on Run to generate a secret key for your UniKey.

Encryt/Decrypt: to check the encrypt/decrypt result, you can choose your desired operation from the Select Operation drop-down menu. Select the key, choose the encoding, input your content (the length must be an integer multiple of 16) in the input box and then click Run, you can then see the result in the output box. To reverse the operation, you can click on < between the input and output boxes, choose the opposite operation, and then click on Run to check the result from the output box.
UniKey also provides an MD5 algorithm, for you to perform checksums. You can perform the MD5 calculation by following the same procedure.

===Random Number===

[[File:UniKey Console Random Number tab.PNG|500px|alt=enter a seed to generate four distinct randomly generated numbers]]

UniKey Console provides its own random number generator. By just entering a seed (numbers only) value and clicking Run you are provided with four random numbers in Result; the numbers generated are cryptographically random.

<div style="page-break-before:always"></div>
===Network===

[[File:console device network.png|500px|alt=UniKey Console network settings]]

This option allows you to configure your UniKey device (PRO, Time, and Drive) in a network environment. In the first line, you can set the maximum number of users who can connect to the server simultaneously.

====Client setting====
* Server IP is the servers IP address in the network. This address will guide clients to find the server in the network.
* Server port is the port to build communications between client and server.
* Time-out defines the maximum waiting period. If the client sends a request to the server, but the server does not send a response back in the set time, then the client is denied access.
* The default time-out period is 5 seconds.

<table class="wikitable" align="left" style="width: 100px;">
<tr>
<td align="center"><i>You can use this to control the behavior of the NetUniKey Client</i></td>
</tr>
</table>
The access mode box shows how NetUniKey Clients access the NetUniKey Server. If you set it to access by IP, NetUniKey Server accepts only ONE client per IP. If this value is set to access by process, the NetUniKey client from the same process can only be accepted once. If it is set to access by thread, NetUniKey can be accepted in any thread. Access by shared IP means all requests from a single IP will be counted as 1. To facilitate setting other devices with the same configuration, you can save your configuration information into a file, or to update a device remotely, you can generate an update file.

Working mode specifies how the UniKey Client will operate. If this value is set to local only, the NetUniKey Client will only work with a UniKey dongle attached to a local USB port.
If this value is local->network, the UniKey Client will check for a local UniKey dongle attached to a USB port first, if this fails, it will try to search for the UniKey dongle attached to the UniKey server in the network.
If you set it to network only, the NetUniKey Client will only work with the UniKey dongle attached to the UniKey server. When this value is set to network->local, the NetUniKey client will try to connect with the UniKey dongle attached to UniKey server first, and if it fails, it will try to load a local UniKey attached to a USB port.

Search mode sets how UniKey clients will try to find a UniKey dongle on the network. Local only is used for connecting to the server by using the server IP set in the configuration file. If it is set to local->broadcast, the UniKey client will try to use the information in the configuration file first, if this fails, the UniKey clients will broadcast to the local network to find the UniKey.
If set to broadcast->local, the UniKey clients will broadcast to the network first, and will try to connect to the UniKey specified in NetUniKey configuration file when they cannot find any UniKey via the broadcast. You can save this configuration file by clicking on Save, or read the previous client settings file by clicking on Read.

<div style="clear:both;"></div>

<div style="page-break-before:always"></div>
====Server setting====

[[File:console device network server.png|thumb|left|500px|alt=UniKey Console server settings|The default port is 5680]]

<div style="clear:both;"></div>
In this panel, you can enter the server IP, desired server port, and timeout. Enable/Disable the black and white IP list. To add an IP address to the list, click on the corresponding Add button, in the pop-up window, enter the start and end IP addresses. Or you can move an IP from the black list to white list by clicking on the >/< buttons.
* If the white list is enabled, only IP addresses in this list can access the server. If the list is empty, then no clients can access the server.
* The black list always has the highest priority. When the server starts, it will always check the black list first. If an IP appears in both the black and white list, the IP will be blocked.

===File System===
<b><em>Please note that this section is only for the UniKey Drive Console.</em></b>

File System allows you to manage the hidden and secure partition of the UniKey Drive dongle.

[[File:drive console file system.png|500px|alt=UniKey Drive Console file system initial window]]

====Entering the Hidden Partition====

[[File:drive console hidden partition.png|thumb|none|500px|alt=UniKey Drive Console hidden partition login screen|The default passwords to enter the hidden partition are 12345678]]

To enter the hidden partition, please input all four passwords to the UniKey Drive file system, then press OK. All the data stored on both the hidden and secure partitions are encrypted using a 128-bit encryption algorithm.

[[File:unikey drive hidden partition filesystem.png|500px|alt=UniKey Drive Console hidden partition filesystem]]

====Entering the Secure Partition====

[[File:drive console secure partition login screen.png|thumb|none|500px|alt=UniKey Drive Console secure partition login screen|The default password to enter the secure partition is 123456]]

The secure partition is also known as the password-protected partition; customers can access it by providing the correct password.

===Initialization===
<b><em>Please note that this section is only for the UniKey Drive Console.</em></b>

The Initialization tab for the UniKey Drive contains two parts; format and partition device memory.

[[File:drive console initialization.png|500px|alt=UniKey Drive Console Initialization tab]]

====Format====

[[File:UniKey Drive Initialization Format.png|500px|alt=UniKey Drive Console Initialization Format tab]]

By using the Format function, customers can format the UniKey Drive's 4KB memory, SID, license modules, algorithms and update tags.

====Partition====
To partition the UniKey Drive, you need to input all four passwords to log in to the Drive's filesystem. Pressing Default Password loads the default passwords automatically for you.

[[File:drive console initialization partition.png|thumb|none|500px|alt=UniKey Drive Console Initialization Partition tab|The four default passwords are 12345678]]

Device capacity is the UniKey Drive's total memory; UniKey Drives are available in 2, 4, 8, 16, and 32GB variants. An image file (ISO) is used for UniKey Drive's virtual CD-ROM partition; a user can burn their own ISO files to the Drive's virtual CD-ROM. A vendor can modify the capacity of the hidden, normal, and secure partition. Vendors need to create a password for the secure partition, so that end users are able to open the password-protected partition.

===Generate===

[[File:console generate unikey update.png|500px|alt=UniKey Console read update file]]

====Generate UniKey File====
UniKey file is used by the UniKey Burner tool, when a customer wants to burn the dongles in a batch by using the same configurations and settings, this file will be loaded into the UniKey Burner tool. Pressing the Read button will load the information stored on the .uky file to the Console tool. The Generate button will create the .uky file with the dongles information/settings from the Console tool.

===Generate Update File===

[[File:console generate update file.png|500px|alt=UniKey Console generate update file]]

The Update File is used by the UniKey Drive Remote Updater; it does the same thing as the UniKey Remote Update Generator does.

The Properties to be bound box will allow the customer to bind specific HID, SID, License Modules and Update Tags to the generated .upt2 file. After binding with a specific value, the .upt2 file will check if the values stored inside of the UniKey Drive dongle are the same or not. If they are not the same, the .upt2 file will not update the UniKey Drive.

The Property to be written box allows the customer to use the .upt2 file for updating the settings and configurations of the target UniKey Drive.
File password will allow the customer to set an independent password for the generated .upt2 file, and then when the end user updates their UniKey Drive by using the corresponding .upt2 file, they will need to input this password in order to access/use the .upt2 file.

UniKey Console Tool

2016-08-23T00:20:41Z

Bao:

[[category:UniKey Manuals]]
==<b>UniKey Console</b>==

<b>User Guide</b>

<b><i>Version 8.3</i></b>

<table class="wikitable">
<tr>
<td style="background-color: red;"><b style="color: #fff;">Version</b></td>
<td>1.0</td>
<td>1.1</td>
<td>1.2</td>
<td>1.3</td>
<td>2.0</td>
<td>2.1</td>
<td>2.2</td>
<td>3.0</td>
<td>4.0</td>
<td>5.0</td>
<td>6.0</td>
<td>7.0</td>
<td>7.1</td>
<td>7.3</td>
<td>8.0</td>
<td>8.1</td>
<td>8.2</td>
<td>8.3</td>
</tr>
<tr>
<td style="background-color: red;"><b style="color: #fff;">Date</b></td>
<td>2006.1</td>
<td>2006.8</td>
<td>2006.10</td>
<td>2006.12</td>
<td>2007.2</td>
<td>2007.4</td>
<td>2007.8</td>
<td>2008.5</td>
<td>2008.8</td>
<td>2009.3</td>
<td>2010.4</td>
<td>2010.6</td>
<td>2010.8</td>
<td>2010.9</td>
<td>2012.3</td>
<td>2012.4</td>
<td>2016.5</td>
<td>2016.7</td>
</tr>
</table>

==Introduction==
UniKey Console is a powerful tool to help software vendors manage their software development, license software and track their software sales performance. It can be integrated into your ERP, CRM and financial system seamlessly.
The UniKey Console is designed to follow the waterfall software development procedure, which helps software vendors manage their different products along its whole lifecycle. The feature based license management method is an innovative way to protect your software away from intruders and to license efficiently.

To administrate all software, check the sales history and gather information to prepare for the following software development, UniKey Console employs a database to record information. It supports almost all database techniques available in todays market, such as SQL, MySQL, and Oracle.
Additionally, this Console supports multiple users logging in to the system. Different operators in different roles can logon and operate the Console utility within their personal level of permission. For example, employees from a product department can login to the Console system, and submit product orders, but they cannot see any other information about the sales department.

<div style="page-break-before:always"></div>
==Deployment==
This section will introduce how to deploy the UniKey Console on your system. The Console has two parts, the front is a GUI which is green software and does not need any installation. Users simply copy the folder to their computer. The next step is to install a database and create tables. In the SDK we provide instructional pictures, follow the pictures to finish the MySQL installation. If no version of MySQL Server is included in the SDK, you can download the latest version from: https://dev.mysql.com/downloads/mysql/. After installing the database, click on Start, and open the MySQL Command Line Client. Log in to the database by entering your password.

[[File:MySQL console.png|left|500px|alt=MySQL command line client]]

<table class="wikitable" align="left" style="width: 100px;">
<tr>
<td align="center"><i>Device mode does not support multiple users and will not keep operation records on the database</i></td>
</tr>
</table>

<div style="clear:both;"></div>
To create the required tables, input <code>"source file directory"\createconsoletables.sql</code> (if that does not work try the command: <code>source "source file directory"\createconsoletables.sql</code>) and press enter. After the database has been successfully built, open the console GUI by double clicking on the Console icon (you may need to re-open the Console application to register any changes to the database).

==UniKey Console Working Mode==
The UniKey Console provides two different modes for users, Manage Mode and Device Mode. The Manage Mode is mainly used to manage the whole lifecycle of your software, and allows multiple operators to logon the system to implement their operations with their own levels of permission. Device mode provides a quick way to configure parameters or generate an update file for a UniKey device.

==Manage Mode==
The UniKey Console Manage Mode closely follows the software lifecycle, from the beginning of software design to the end of software development. At the design stage, software designers will separate the software into different blocks according to their functions. We highly recommend medium to large software vendors use Manage Mode to manage and license your software.

===Login===
This system supports remote login. Users can set up the servers IP via the GUI, and log in to the server remotely to finish their operation. To start using the Console, double click on the UniKey Console. The login interface will pop up.

[[File:console login.png|500px|alt=UniKey Console login page]]

Input the user name and password to log in to the system.
* If this is the first time you are logging in to the system, the user name is administrator, and password is admin.
* The administrator should log in to the system and change their password first, and then he/she can create other accounts for different operators.
* If you try to log in to a server remotely, click on Network Setting and in the pop-up window, input the server IP address and port number.

===Product===
The product panel provides a series of interfaces for product related operations, including creating license features and generating product license strategies by combining one or more license features together.

====Feature Setting====
Feature setting is the most basic element to form a license for a product. For example, if the software requires a license based on expiration time, a time module shall be selected and the expiration time shall be set. This will form a license feature. If more license strategies are going to be used, more license features can be created.

[[File:feature setting console.png|500px|alt=UniKey Console feature setting]]

Click on Add to add a license feature in the pop-up window.

[[File:add license feature.png|500px|alt=UniKey Console add license feature]]

As you can see from the above picture, lots of license features can be used to build up a single product license, such as license module, memory, arithmetic, SID, max connections, partition information, etc.

====License Module====
This feature limits access to the software based on rules. When the correct UniKey is connected, the software bound to the UniKey is activated.

[[File:license module.png|thumb|left|500px|alt=UniKey Console add license feature perpetual|License Module is the most widely used feature on all UniKey devices]]

<div style="clear:both;"></div>
There are two ways to use the License Module. The first is to bind a module to the software, once the module is enabled, the software will start working. The second is to set the execute count, so every time when the software is started the count will decrement until the value reaches 0.

<b>A non-zero number must be set to enable the License Module. This number will not be changed unless Exe Count Mode has been selected.</b>

====Memory====
UniKey has 4KB of memory which allows developers to store any information, such as a software abstract, version information, buyers or developers information, etc.

[[File:console memory.png|500px|alt=UniKey Console writing into memory]]

In the feature setting:
* Input the encoding in the left column.
* Input the start address, which refers to the start point where the content will be stored.
* Input the length, which refers the length of content that will be stored in memory.

====Arithmetic ====
To protect your software safely, it is a good idea to write a block of code inside the UniKey device itself, therefore without the device, the software cannot run. The arithmetic option is designed for this purpose.

[[File:console arithmetic.png|thumb|left|500px|alt=UniKey Console arithmetic feature|For the syntax and how to write an equation, please refer to the UniKey manual in the arithmetic section]]

<div style="clear:both;"></div>
In the feature setting:
* Input your custom arithmetic.
* Input the start address, to set the start point of the arithmetic.
* Input the length, so that the arithmetic will end at the start address plus the length.

====SID Range====
SID is another important property in UniKey that can provide effective license management and software protection. Developers can use this feature to set it so that only one key or several keys can launch a specific copy of software.

[[File:console SID range.png|500px|alt=UniKey Console software ID generation rules]]

<b>Feature setting</b> - In the SID generation mode, which will generate a rule for how UniKey SID codes are created, there are 4 different methods of generation:
* All the same: all SID burned to UniKey devices will be the same.
* Increment: the SID value of every UniKey device will add 1 from the initial value when burning.
* Decrement: the SID value of every UniKey device will decrease by 1
* Time/date: the SID value will be the produced from the current time/date
The initial value gives a starting SID value/position/number.

====Update Tag====
The update tag is mainly used to update related issues. It can be used to record the number of times the software has been updated, or protect an update file from being used by other UniKey devices with a different update tag.

[[File:console update tag.png|500px|alt=UniKey Console update tag]]

====Max Connections====
Some software may employ a floating license strategy, where people on the network will share a license. The maximum number of connections can restrict the total number of users who share a license simultaneously on a local network.

[[File:console max connections.png|500px|alt=UniKey Console number of max connections]]

====Seed====
For every UniKey device, the password cannot be customized, but developers can generate their own passwords by themselves. Passwords can be generated by entering a seed value in the seed setting, and when a license is produced, the password of the device will be changed to the value calculated by the UniKey system based on this seed value.

[[File:console seed.png|500px|alt=UniKey Console set seed]]

In the feature setting, input the seed value.
* Each UniKey dongle can only generate a new password TWICE! After this it cannot generate anymore passwords.
* When generating a new password, the dongle is formatted.
* <b>To reset the password for a 3rd time, the UniKey dongle must be sent back to SecuTech</b>

====Partition information====
Each UniKey Drive device has four partitions:
* Virtual CD-ROM emulation drive
* Public partition
* Password protected partition
* Hidden partition
This page is used by customers to set the space for each partition on the UniKey Drive device.

[[File:console partition information.png|500px|alt=UniKey Drive partition information]]

====Files in hidden partition====
UniKey Drive has a unique hidden partition which allows users to store files. Each file stored on the hidden partition is invisible and inaccessible to end users. Vendors could integrate UniKey Drive APIs with their software and then that software will be able to access the files stored on the UniKey Drives hidden partition.

[[File:console hidden partition files.png|500px|alt=UniKey Drive hidden partition files]]

The files stored on the hidden partition should have the filename as an 8.3 format, for example, 12345678.123

====Product setting====
Product setting is used to combine the basic license elements and features together to form a product license strategy, to help meet the different requirements of customers, businesses, and sales strategies. For each software package, decision makers can set several license strategies by selecting different license features which have been set in Feature setting, maximizing their market share and revenue. For some special requirements, a customized license can even be quickly generated.

[[File:console product setting.png|500px|alt=UniKey Console product setting]]

The above picture shows the Product setting panel, and to add a license for a product click on the Add button.

After clicking on Add, this window is displayed

[[File:console add product.png|thumb|left|500px|alt=UniKey Console add new product|The configuration will affect this product, and will not change previous Feature settings]]

<div style="clear:both;"></div>
Input the product name; a comment can be added in the comment box, and please select the correct device type(s). In the Feature setting section, you can reset the update tag, max connections, seed, and SID generation mode by checking the respective item boxes. This provides a quick interface to modify the license settings. From the Feature list choose the preferred features from the list and click on > to move them to the products desired features on the right. These features will combine together to form a product license.

[[File:console product setting added.png|thumb|left|500px|alt=UniKey Console list product ID, name and any comments|Once an order has been placed on a product, this product will not be deleted]]

<div style="clear:both;"></div>
Based on the current product, you can create a new license quickly by using the Customize function; you can then input a new name and reset values or add more features to create another license. This allows you to easily create another product with a new name and unique product ID that may share features with other products. A product can be changed by selecting the product and clicking on Edit, or can be deleted by clicking Delete.

<div style="page-break-before:always"></div>
===Sales===
The sale function will help vendors to manage their customers and orders. It contains two configurations: Customer Management and Order Setting.

====Customer Management====
Customer Management will record all information about customers and their order history. If a customer wants to place an order, then this customer must be added to the customer list. Click the button Add to execute the corresponding operation.

====Order Setting====
Order setting contains order related operations, such as place an order, update a product, append a new order to an existing order, edit, delete, submit and check status.

[[File:console order management.png|500px|alt=UniKey Console order management]]

===Production===
Production is mainly used for the production department, once an order has been submitted, the order will be passed to the production department, x and this order will be listed. The producer shall produce the order.

[[File:console product management.png|500px|alt=UniKey Console production management]]

Click on Production, and follow the instruction to finish the production procedure.

[[File:console production progress.png|300px|alt=progress bar for production]]

If there is an error or problem in the order, the producer shall decline the order by clicking on decline, and then the order will be sent back to sales.

===Management===
Administrators shall use the Management tab to add, edit and delete users, including user name, password, and assign permission levels.

[[File:console user management.png|500px|alt=UniKey Console user management]]

==Device Mode==
Device Mode provides you a direct way to configure all parameters for your UniKey device locally or to generate a remote update file. It is suitable for altering UniKey hardware operations and property configurations directly.

[[File:console device setting.png|500px|alt=UniKey Console device mode login screen]]

When you click on Check status, the status of the device connected to the local computer will be displayed in the message box. By entering the correct password, and then clicking on User logon or Vendor logon, you can log in to the device as a user or vendor to perform operations within your level of permission.

===Configure===
Click on Configure on the left side of the control panel, all configuration options will be displayed in the dropdown menu:
* General information
* Memory
* Algorithm
* License and Time Module <em>(Time Module is not available for UniKey Drive)</em>
* New password <em>(Available in General information when logged in as a vendor)</em>
* Encrypt/Decrypt
* Random number <em>(not available for UniKey Drive)</em>
* Format <em>(Under the Initialization tab for UniKey Drive)</em>
* Network

[[File:console device configure.png|500px|alt=UniKey Console configure tab]]

You can configure any properties according to your own desired licensing strategies. By clicking on the corresponding options, you can enter your required parameters.

===General information===

[[File:console device general information.png|500px|alt=UniKey Console general information (SID and Update Tag)]]

<b>The HID is a fixed serial number, and cannot be changed.</b>

In menu, the UniKey devices SID and Update Tag connected to your computer will show in the message box. You can change the SID and Update Tag value, by entering value in the respective input box and then clicking Write.

<div style="clear:both;"></div>
===Memory===

[[File:console device memory.png|500px|alt=UniKey Console device memory details]]

In Memory, you can read, edit, and delete content stored in the UniKeys memory. By clicking on Read, you can read content from the UniKeys memory, and by clicking on Write, you can write all content edited by you into the UniKeys memory. To facilitate your editing, UniKey Console provides a load from file function. By clicking on Load from file, you can load content stored in a file to Console, and then write it to memory by clicking on Write. Alternatively, you can save the data which is read from the UniKeys memory to a file by clicking on Save to file.

===Algorithm===

[[File:console device algorithm.png|500px|UniKey Console write and run algorithms]]

UniKey Algorithm is a very powerful method to protect your software, as this block of code is stored directly in UniKey, independent in memory from where software code is stored. Without the right permissions, this block of code cannot be written to or read by anyone. An algorithm can be typed into the Input algorithm field. You can input more than one statement in your algorithm and each statement is separated by comma.

Input the start address to set the starting point for your algorithm, and input a length to set the end point. The end point address will be the start address plus length. Select a calculation mode, and then click on Write to write your configurations into the UniKey. If you want to run your algorithm for a test, you can initialize the variable, A, B, C, D, seed/module (depending on the selected calculation mode), and start address, and then click on Run. The result from A, B, C, and D will be displayed directly.

===License Module===

[[File:console device module.png|500px|alt=UniKey Console module settings]]

License Module allows you to enable/disable specified modules and set the number of execution times. In the list on the right side of the console, you can see a list and module status. Click on the white triangle to check each corresponding modules parameters and status.

[[File:Console device module options.png|thumb|left|500px|alt=UniKey Console greater module details|To enable a module, a positive number must be entered]]

<div style="clear:both;"></div>
Click on Check to view the information and status of a device and click on Write to write your configurations.

You can enable/disable the auto-decrement function by toggling the check box next to Auto-decrement. To check the information in all modules, you can click on the Check All button; you can also set all modules by clicking on Write All to write all settings to device.

===Time Module (UniKey Time Only)===

[[File:UniKey Console Time Module tab.PNG|500px|alt=UniKey Console time module selections]]

The UniKey Time has 16 time modules to work with, and you can bind any time module with your whole software, or bind just a single piece of functionality, helping to achieve a time-based licensing strategy. Clicking on Read Time reads the current time from the dongle, and the time can be set by inputting the time in the Dongle Clock field (DD-MM-YYYY format) and pressing Write Time; otherwise you can synchronize your dongle's clock with your system time by pressing Write system time to device. Clicking on the white triangle icon to the right of any time module allows you to set the details for an individual time module.

====Set Start Time====

[[File:UniKey Console Time Module 0 start time.PNG|500px|alt=time module duration mode (days, hours)]]

You can utilize the current devices time or system time by clicking on Use device time or Use system time respectively. UniKey provides two different methods; expiration and duration, for you to select from (the default being duration). Inputting Duration Time indicates how long the user can use the software after it the given Start Time.

====Set Expiration Time====

[[File:UniKey Console Time Module expiration method.PNG|500px|alt=time module expiration time (YYYY-MM-HH-MM)]]

If a module will never be used, you can click on Write, but if the module has been set before, then to reset the module, you must either erase the module first or check the Re-write option box. You can set more than one module at once by selecting Write All to set your modules in-batch; make sure to click Check All afterwards to check the status of all modules. Clicking on Erase All removes all settings stored each time module, please note that all modules will be initialized, so be careful when using the feature.

===New Password===

[[File:UniKey Console New Password tab.PNG|500px|alt=enter a seed value to generate four new passwords]]

UniKey does not allow users to defined passwords by themselves. The only way to change passwords is by using the password generation mechanism embedded in the UniKey Console. Please input a seed (numbers only) and click on New Password, all new passwords will be displayed in the New Password output boxes and will be recorded into the UniKey Console folder. <b>The passwords of a UniKey dongle can only be changed twice, after which they cannot be changed again.</b>

===Encrypt/Decrypt===

[[File:console device encrypt and decrypt.png|500px|alt=UniKey Console encrypt or decrypt text]]

Each UniKey dongle has an encrypt/decrypt function, and can store 3 keys inside each device. In the encrypt/decrypt option, you can choose the encrypt/decrypt operation, generate keys and check output.
From the Select Operation drop-down menu, you can choose a specific operation. For example, choosing generate key, you can choose the key you want to use and click on Run to generate a secret key for your UniKey.

Encryt/Decrypt: to check the encrypt/decrypt result, you can choose your desired operation from the Select Operation drop-down menu. Select the key, choose the encoding, input your content (the length must be an integer multiple of 16) in the input box and then click Run, you can then see the result in the output box. To reverse the operation, you can click on < between the input and output boxes, choose the opposite operation, and then click on Run to check the result from the output box.
UniKey also provides an MD5 algorithm, for you to perform checksums. You can perform the MD5 calculation by following the same procedure.

===Random Number===

[[File:UniKey Console Random Number tab.PNG|500px|alt=enter a seed to generate four distinct randomly generated numbers]]

UniKey Console provides its own random number generator. By just entering a seed (numbers only) value and clicking Run you are provided with four random numbers in Result; the numbers generated are cryptographically random.

<div style="page-break-before:always"></div>
===Network===

[[File:console device network.png|500px|alt=UniKey Console network settings]]

This option allows you to configure your UniKey device (PRO, Time, and Drive) in a network environment. In the first line, you can set the maximum number of users who can connect to the server simultaneously.

====Client setting====
* Server IP is the servers IP address in the network. This address will guide clients to find the server in the network.
* Server port is the port to build communications between client and server.
* Time-out defines the maximum waiting period. If the client sends a request to the server, but the server does not send a response back in the set time, then the client is denied access.
* The default time-out period is 5 seconds.

<table class="wikitable" align="left" style="width: 100px;">
<tr>
<td align="center"><i>You can use this to control the behavior of the NetUniKey Client</i></td>
</tr>
</table>
The access mode box shows how NetUniKey Clients access the NetUniKey Server. If you set it to access by IP, NetUniKey Server accepts only ONE client per IP. If this value is set to access by process, the NetUniKey client from the same process can only be accepted once. If it is set to access by thread, NetUniKey can be accepted in any thread. Access by shared IP means all requests from a single IP will be counted as 1. To facilitate setting other devices with the same configuration, you can save your configuration information into a file, or to update a device remotely, you can generate an update file.

Working mode specifies how the UniKey Client will operate. If this value is set to local only, the NetUniKey Client will only work with a UniKey dongle attached to a local USB port.
If this value is local->network, the UniKey Client will check for a local UniKey dongle attached to a USB port first, if this fails, it will try to search for the UniKey dongle attached to the UniKey server in the network.
If you set it to network only, the NetUniKey Client will only work with the UniKey dongle attached to the UniKey server. When this value is set to network->local, the NetUniKey client will try to connect with the UniKey dongle attached to UniKey server first, and if it fails, it will try to load a local UniKey attached to a USB port.

Search mode sets how UniKey clients will try to find a UniKey dongle on the network. Local only is used for connecting to the server by using the server IP set in the configuration file. If it is set to local->broadcast, the UniKey client will try to use the information in the configuration file first, if this fails, the UniKey clients will broadcast to the local network to find the UniKey.
If set to broadcast->local, the UniKey clients will broadcast to the network first, and will try to connect to the UniKey specified in NetUniKey configuration file when they cannot find any UniKey via the broadcast. You can save this configuration file by clicking on Save, or read the previous client settings file by clicking on Read.

<div style="clear:both;"></div>

<div style="page-break-before:always"></div>
====Server setting====

[[File:console device network server.png|thumb|left|500px|alt=UniKey Console server settings|The default port is 5680]]

<div style="clear:both;"></div>
In this panel, you can enter the server IP, desired server port, and timeout. Enable/Disable the black and white IP list. To add an IP address to the list, click on the corresponding Add button, in the pop-up window, enter the start and end IP addresses. Or you can move an IP from the black list to white list by clicking on the >/< buttons.
* If the white list is enabled, only IP addresses in this list can access the server. If the list is empty, then no clients can access the server.
* The black list always has the highest priority. When the server starts, it will always check the black list first. If an IP appears in both the black and white list, the IP will be blocked.

===File System===
<b><em>Please note that this section is only for the UniKey Drive Console.</em></b>

File System allows you to manage the hidden and secure partition of the UniKey Drive dongle.

[[File:drive console file system.png|500px|alt=UniKey Drive Console file system initial window]]

====Entering the Hidden Partition====

[[File:drive console hidden partition.png|thumb|none|500px|alt=UniKey Drive Console hidden partition login screen|The default passwords to enter the hidden partition are 12345678]]

To enter the hidden partition, please input all four passwords to the UniKey Drive file system, then press OK. All the data stored on both the hidden and secure partitions are encrypted using a 128-bit encryption algorithm.

[[File:unikey drive hidden partition filesystem.png|500px|alt=UniKey Drive Console hidden partition filesystem]]

====Entering the Secure Partition====

[[File:drive console secure partition login screen.png|thumb|none|500px|alt=UniKey Drive Console secure partition login screen|The default password to enter the secure partition is 123456]]

The secure partition is also known as the password-protected partition; customers can access it by providing the correct password.

===Initialization===
<b><em>Please note that this section is only for the UniKey Drive Console.</em></b>

The Initialization tab for the UniKey Drive contains two parts; format and partition device memory.

[[File:drive console initialization.png|500px|alt=UniKey Drive Console Initialization tab]]

====Format====

[[File:UniKey Drive Initialization Format.png|500px|alt=UniKey Drive Console Initialization Format tab]]

By using the Format function, customers can format the UniKey Drive's 4KB memory, SID, license modules, algorithms and update tags.

====Partition====
To partition the UniKey Drive, you need to input all four passwords to log in to the Drive's filesystem. Pressing Default Password loads the default passwords automatically for you.

[[File:drive console initialization partition.png|thumb|none|500px|alt=UniKey Drive Console Initialization Partition tab|The four default passwords are 12345678]]

Device capacity is the UniKey Drive's total memory; UniKey Drives are available in 2, 4, 8, 16, and 32GB variants. An image file (ISO) is used for UniKey Drive's virtual CD-ROM partition; a user can burn their own ISO files to the Drive's virtual CD-ROM. A vendor can modify the capacity of the hidden, normal, and secure partition. Vendors need to create a password for the secure partition, so that end users are able to open the password-protected partition.

===Generate===

[[File:console generate unikey update.png|500px|alt=UniKey Console read update file]]

====Generate UniKey File====
UniKey file is used by the UniKey Burner tool, when a customer wants to burn the dongles in a batch by using the same configurations and settings, this file will be loaded into the UniKey Burner tool. Pressing the Read button will load the information stored on the .uky file to the Console tool. The Generate button will create the .uky file with the dongles information/settings from the Console tool.

===Generate Update File===

[[File:console generate update file.png|500px|alt=UniKey Console generate update file]]

The Update File is used by the UniKey Drive Remote Updater; it does the same thing as the UniKey Remote Update Generator does.

The Properties to be bound box will allow the customer to bind specific HID, SID, License Modules and Update Tags to the generated .upt2 file. After binding with a specific value, the .upt2 file will check if the values stored inside of the UniKey Drive dongle are the same or not. If they are not the same, the .upt2 file will not update the UniKey Drive.

The Property to be written box allows the customer to use the .upt2 file for updating the settings and configurations of the target UniKey Drive.
File password will allow the customer to set an independent password for the generated .upt2 file, and then when the end user updates their UniKey Drive by using the corresponding .upt2 file, they will need to input this password in order to access/use the .upt2 file.

UniKey Console Tool

2016-08-23T00:18:10Z

Bao: /* Device Mode */ Added Time Module, New Password and Random Number

[[category:UniKey Manuals]]
==<b>UniKey Console</b>==

<b>User Guide</b>

<b><i>Version 8.3</i></b>

<table class="wikitable">
<tr>
<td style="background-color: red;"><b style="color: #fff;">Version</b></td>
<td>1.0</td>
<td>1.1</td>
<td>1.2</td>
<td>1.3</td>
<td>2.0</td>
<td>2.1</td>
<td>2.2</td>
<td>3.0</td>
<td>4.0</td>
<td>5.0</td>
<td>6.0</td>
<td>7.0</td>
<td>7.1</td>
<td>7.3</td>
<td>8.0</td>
<td>8.1</td>
<td>8.2</td>
<td>8.3</td>
</tr>
<tr>
<td style="background-color: red;"><b style="color: #fff;">Date</b></td>
<td>2006.1</td>
<td>2006.8</td>
<td>2006.10</td>
<td>2006.12</td>
<td>2007.2</td>
<td>2007.4</td>
<td>2007.8</td>
<td>2008.5</td>
<td>2008.8</td>
<td>2009.3</td>
<td>2010.4</td>
<td>2010.6</td>
<td>2010.8</td>
<td>2010.9</td>
<td>2012.3</td>
<td>2012.4</td>
<td>2016.5</td>
<td>2016.7</td>
</tr>
</table>

==Introduction==
UniKey Console is a powerful tool to help software vendors manage their software development, license software and track their software sales performance. It can be integrated into your ERP, CRM and financial system seamlessly.
The UniKey Console is designed to follow the waterfall software development procedure, which helps software vendors manage their different products along its whole lifecycle. The feature based license management method is an innovative way to protect your software away from intruders and to license efficiently.

To administrate all software, check the sales history and gather information to prepare for the following software development, UniKey Console employs a database to record information. It supports almost all database techniques available in todays market, such as SQL, MySQL, and Oracle.
Additionally, this Console supports multiple users logging in to the system. Different operators in different roles can logon and operate the Console utility within their personal level of permission. For example, employees from a product department can login to the Console system, and submit product orders, but they cannot see any other information about the sales department.

<div style="page-break-before:always"></div>
==Deployment==
This section will introduce how to deploy the UniKey Console on your system. The Console has two parts, the front is a GUI which is green software and does not need any installation. Users simply copy the folder to their computer. The next step is to install a database and create tables. In the SDK we provide instructional pictures, follow the pictures to finish the MySQL installation. If no version of MySQL Server is included in the SDK, you can download the latest version from: https://dev.mysql.com/downloads/mysql/. After installing the database, click on Start, and open the MySQL Command Line Client. Log in to the database by entering your password.

[[File:MySQL console.png|left|500px|alt=MySQL command line client]]

<table class="wikitable" align="left" style="width: 100px;">
<tr>
<td align="center"><i>Device mode does not support multiple users and will not keep operation records on the database</i></td>
</tr>
</table>

<div style="clear:both;"></div>
To create the required tables, input <code>"source file directory"\createconsoletables.sql</code> (if that does not work try the command: <code>source "source file directory"\createconsoletables.sql</code>) and press enter. After the database has been successfully built, open the console GUI by double clicking on the Console icon (you may need to re-open the Console application to register any changes to the database).

==UniKey Console Working Mode==
The UniKey Console provides two different modes for users, Manage Mode and Device Mode. The Manage Mode is mainly used to manage the whole lifecycle of your software, and allows multiple operators to logon the system to implement their operations with their own levels of permission. Device mode provides a quick way to configure parameters or generate an update file for a UniKey device.

==Manage Mode==
The UniKey Console Manage Mode closely follows the software lifecycle, from the beginning of software design to the end of software development. At the design stage, software designers will separate the software into different blocks according to their functions. We highly recommend medium to large software vendors use Manage Mode to manage and license your software.

===Login===
This system supports remote login. Users can set up the servers IP via the GUI, and log in to the server remotely to finish their operation. To start using the Console, double click on the UniKey Console. The login interface will pop up.

[[File:console login.png|500px|alt=UniKey Console login page]]

Input the user name and password to log in to the system.
* If this is the first time you are logging in to the system, the user name is administrator, and password is admin.
* The administrator should log in to the system and change their password first, and then he/she can create other accounts for different operators.
* If you try to log in to a server remotely, click on Network Setting and in the pop-up window, input the server IP address and port number.

===Product===
The product panel provides a series of interfaces for product related operations, including creating license features and generating product license strategies by combining one or more license features together.

====Feature Setting====
Feature setting is the most basic element to form a license for a product. For example, if the software requires a license based on expiration time, a time module shall be selected and the expiration time shall be set. This will form a license feature. If more license strategies are going to be used, more license features can be created.

[[File:feature setting console.png|500px|alt=UniKey Console feature setting]]

Click on Add to add a license feature in the pop-up window.

[[File:add license feature.png|500px|alt=UniKey Console add license feature]]

As you can see from the above picture, lots of license features can be used to build up a single product license, such as license module, memory, arithmetic, SID, max connections, partition information, etc.

====License Module====
This feature limits access to the software based on rules. When the correct UniKey is connected, the software bound to the UniKey is activated.

[[File:license module.png|thumb|left|500px|alt=UniKey Console add license feature perpetual|License Module is the most widely used feature on all UniKey devices]]

<div style="clear:both;"></div>
There are two ways to use the License Module. The first is to bind a module to the software, once the module is enabled, the software will start working. The second is to set the execute count, so every time when the software is started the count will decrement until the value reaches 0.

<b>A non-zero number must be set to enable the License Module. This number will not be changed unless Exe Count Mode has been selected.</b>

====Memory====
UniKey has 4KB of memory which allows developers to store any information, such as a software abstract, version information, buyers or developers information, etc.

[[File:console memory.png|500px|alt=UniKey Console writing into memory]]

In the feature setting:
* Input the encoding in the left column.
* Input the start address, which refers to the start point where the content will be stored.
* Input the length, which refers the length of content that will be stored in memory.

====Arithmetic ====
To protect your software safely, it is a good idea to write a block of code inside the UniKey device itself, therefore without the device, the software cannot run. The arithmetic option is designed for this purpose.

[[File:console arithmetic.png|thumb|left|500px|alt=UniKey Console arithmetic feature|For the syntax and how to write an equation, please refer to the UniKey manual in the arithmetic section]]

<div style="clear:both;"></div>
In the feature setting:
* Input your custom arithmetic.
* Input the start address, to set the start point of the arithmetic.
* Input the length, so that the arithmetic will end at the start address plus the length.

====SID Range====
SID is another important property in UniKey that can provide effective license management and software protection. Developers can use this feature to set it so that only one key or several keys can launch a specific copy of software.

[[File:console SID range.png|500px|alt=UniKey Console software ID generation rules]]

<b>Feature setting</b> - In the SID generation mode, which will generate a rule for how UniKey SID codes are created, there are 4 different methods of generation:
* All the same: all SID burned to UniKey devices will be the same.
* Increment: the SID value of every UniKey device will add 1 from the initial value when burning.
* Decrement: the SID value of every UniKey device will decrease by 1
* Time/date: the SID value will be the produced from the current time/date
The initial value gives a starting SID value/position/number.

====Update Tag====
The update tag is mainly used to update related issues. It can be used to record the number of times the software has been updated, or protect an update file from being used by other UniKey devices with a different update tag.

[[File:console update tag.png|500px|alt=UniKey Console update tag]]

====Max Connections====
Some software may employ a floating license strategy, where people on the network will share a license. The maximum number of connections can restrict the total number of users who share a license simultaneously on a local network.

[[File:console max connections.png|500px|alt=UniKey Console number of max connections]]

====Seed====
For every UniKey device, the password cannot be customized, but developers can generate their own passwords by themselves. Passwords can be generated by entering a seed value in the seed setting, and when a license is produced, the password of the device will be changed to the value calculated by the UniKey system based on this seed value.

[[File:console seed.png|500px|alt=UniKey Console set seed]]

In the feature setting, input the seed value.
* Each UniKey dongle can only generate a new password TWICE! After this it cannot generate anymore passwords.
* When generating a new password, the dongle is formatted.
* <b>To reset the password for a 3rd time, the UniKey dongle must be sent back to SecuTech</b>

====Partition information====
Each UniKey Drive device has four partitions:
* Virtual CD-ROM emulation drive
* Public partition
* Password protected partition
* Hidden partition
This page is used by customers to set the space for each partition on the UniKey Drive device.

[[File:console partition information.png|500px|alt=UniKey Drive partition information]]

====Files in hidden partition====
UniKey Drive has a unique hidden partition which allows users to store files. Each file stored on the hidden partition is invisible and inaccessible to end users. Vendors could integrate UniKey Drive APIs with their software and then that software will be able to access the files stored on the UniKey Drives hidden partition.

[[File:console hidden partition files.png|500px|alt=UniKey Drive hidden partition files]]

The files stored on the hidden partition should have the filename as an 8.3 format, for example, 12345678.123

====Product setting====
Product setting is used to combine the basic license elements and features together to form a product license strategy, to help meet the different requirements of customers, businesses, and sales strategies. For each software package, decision makers can set several license strategies by selecting different license features which have been set in Feature setting, maximizing their market share and revenue. For some special requirements, a customized license can even be quickly generated.

[[File:console product setting.png|500px|alt=UniKey Console product setting]]

The above picture shows the Product setting panel, and to add a license for a product click on the Add button.

After clicking on Add, this window is displayed

[[File:console add product.png|thumb|left|500px|alt=UniKey Console add new product|The configuration will affect this product, and will not change previous Feature settings]]

<div style="clear:both;"></div>
Input the product name; a comment can be added in the comment box, and please select the correct device type(s). In the Feature setting section, you can reset the update tag, max connections, seed, and SID generation mode by checking the respective item boxes. This provides a quick interface to modify the license settings. From the Feature list choose the preferred features from the list and click on > to move them to the products desired features on the right. These features will combine together to form a product license.

[[File:console product setting added.png|thumb|left|500px|alt=UniKey Console list product ID, name and any comments|Once an order has been placed on a product, this product will not be deleted]]

<div style="clear:both;"></div>
Based on the current product, you can create a new license quickly by using the Customize function; you can then input a new name and reset values or add more features to create another license. This allows you to easily create another product with a new name and unique product ID that may share features with other products. A product can be changed by selecting the product and clicking on Edit, or can be deleted by clicking Delete.

<div style="page-break-before:always"></div>
===Sales===
The sale function will help vendors to manage their customers and orders. It contains two configurations: Customer Management and Order Setting.

====Customer Management====
Customer Management will record all information about customers and their order history. If a customer wants to place an order, then this customer must be added to the customer list. Click the button Add to execute the corresponding operation.

====Order Setting====
Order setting contains order related operations, such as place an order, update a product, append a new order to an existing order, edit, delete, submit and check status.

[[File:console order management.png|500px|alt=UniKey Console order management]]

===Production===
Production is mainly used for the production department, once an order has been submitted, the order will be passed to the production department, x and this order will be listed. The producer shall produce the order.

[[File:console product management.png|500px|alt=UniKey Console production management]]

Click on Production, and follow the instruction to finish the production procedure.

[[File:console production progress.png|300px|alt=progress bar for production]]

If there is an error or problem in the order, the producer shall decline the order by clicking on decline, and then the order will be sent back to sales.

===Management===
Administrators shall use the Management tab to add, edit and delete users, including user name, password, and assign permission levels.

[[File:console user management.png|500px|alt=UniKey Console user management]]

==Device Mode==
Device Mode provides you a direct way to configure all parameters for your UniKey device locally or to generate a remote update file. It is suitable for altering UniKey hardware operations and property configurations directly.

[[File:console device setting.png|500px|alt=UniKey Console device mode login screen]]

When you click on Check status, the status of the device connected to the local computer will be displayed in the message box. By entering the correct password, and then clicking on User logon or Vendor logon, you can log in to the device as a user or vendor to perform operations within your level of permission.

===Configure===
Click on Configure on the left side of the control panel, all configuration options will be displayed in the dropdown menu:
* General information
* Memory
* Algorithm
* License and Time Module <em>(Time Module is not available for UniKey Drive)</em>
* New password <em>(Available in General information when logged in as a vendor)</em>
* Encrypt/Decrypt
* Random number <em>(not available for UniKey Drive)</em>
* Format <em>(Under the Initialization tab for UniKey Drive)</em>
* Network

[[File:console device configure.png|500px|alt=UniKey Console configure tab]]

You can configure any properties according to your own desired licensing strategies. By clicking on the corresponding options, you can enter your required parameters.

===General information===

[[File:console device general information.png|500px|alt=UniKey Console general information (SID and Update Tag)]]

<b>The HID is a fixed serial number, and cannot be changed.</b>

In menu, the UniKey devices SID and Update Tag connected to your computer will show in the message box. You can change the SID and Update Tag value, by entering value in the respective input box and then clicking Write.

<div style="clear:both;"></div>
===Memory===

[[File:console device memory.png|500px|alt=UniKey Console device memory details]]

In Memory, you can read, edit, and delete content stored in the UniKeys memory. By clicking on Read, you can read content from the UniKeys memory, and by clicking on Write, you can write all content edited by you into the UniKeys memory. To facilitate your editing, UniKey Console provides a load from file function. By clicking on Load from file, you can load content stored in a file to Console, and then write it to memory by clicking on Write. Alternatively, you can save the data which is read from the UniKeys memory to a file by clicking on Save to file.

===Algorithm===

[[File:console device algorithm.png|500px|UniKey Console write and run algorithms]]

UniKey Algorithm is a very powerful method to protect your software, as this block of code is stored directly in UniKey, independent in memory from where software code is stored. Without the right permissions, this block of code cannot be written to or read by anyone. An algorithm can be typed into the Input algorithm field. You can input more than one statement in your algorithm and each statement is separated by comma.

Input the start address to set the starting point for your algorithm, and input a length to set the end point. The end point address will be the start address plus length. Select a calculation mode, and then click on Write to write your configurations into the UniKey. If you want to run your algorithm for a test, you can initialize the variable, A, B, C, D, seed/module (depending on the selected calculation mode), and start address, and then click on Run. The result from A, B, C, and D will be displayed directly.

===License Module===

[[File:console device module.png|500px|alt=UniKey Console module settings]]

License Module allows you to enable/disable specified modules and set the number of execution times. In the list on the right side of the console, you can see a list and module status. Click on the white triangle to check each corresponding modules parameters and status.

[[File:Console device module options.png|thumb|left|500px|alt=UniKey Console greater module details|To enable a module, a positive number must be entered]]

<div style="clear:both;"></div>
Click on Check to view the information and status of a device and click on Write to write your configurations.

You can enable/disable the auto-decrement function by toggling the check box next to Auto-decrement. To check the information in all modules, you can click on the Check All button; you can also set all modules by clicking on Write All to write all settings to device.

===Time Module (UniKey Time Only)===

[[File:UniKey Console Time Module tab.PNG|500px|alt=UniKey Console time module selections]]

The UniKey Time has 16 time modules to work with, and you can bind any time module with your whole software, or bind just a single piece of functionality, helping to achieve a time-based licensing strategy. Clicking on Read Time reads the current time from the dongle, and the time can be set by inputting the time in the Dongle Clock field (DD-MM-YYYY format) and pressing Write Time; otherwise you can synchronize your dongle's clock with your system time by pressing Write system time to device. Clicking on the white triangle icon to the right of any time module allows you to set the details for an individual time module.

====Set Start Time====

[[File:UniKey Console Time Module 0 start time.PNG|500px|alt=time module duration mode (days, hours)]]

You can utilize the current devices time or system time by clicking on Use device time or Use system time respectively. UniKey provides two different methods; expiration and duration, for you to select from (the default being duration). Inputting Duration Time indicates how long the user can use the software after it the given Start Time.

====Set Expiration Time====

[[File:UniKey Console Time Module expiration method.PNG|500px|alt=time module expiration time (YYYY-MM-HH-MM)]]

If a module will never be used, you can click on Write, but if the module has been set before, then to reset the module, you must either erase the module first or check the Re-write option box. You can set more than one module at once by selecting Write All to set your modules in-batch; make sure to click Check All afterwards to check the status of all modules. Clicking on Erase All removes all settings stored each time module, please note that all modules will be initialized, so be careful when using the feature.

===New Password===

[[File:UniKey Console New Password tab.PNG|500px|alt=enter a seed value to generate four new passwords]]

UniKey does not allow users to defined passwords by themselves. The only way to change passwords is by using the password generation mechanism embedded in the UniKey Console. Please input a seed (numbers only) and click on New Password, all new passwords will be displayed in the New Password output boxes and will be recorded into the UniKey Console folder. <b>The passwords of a UniKey dongle can only be changed twice, after which they cannot be changed again.</b>

===Encrypt/Decrypt===

[[File:console device encrypt and decrypt.png|500px|alt=UniKey Console encrypt or decrypt text]]

Each UniKey dongle has an encrypt/decrypt function, and can store 3 keys inside each device. In the encrypt/decrypt option, you can choose the encrypt/decrypt operation, generate keys and check output.
From the Select Operation drop-down menu, you can choose a specific operation. For example, choosing generate key, you can choose the key you want to use and click on Run to generate a secret key for your UniKey.

Encryt/Decrypt: to check the encrypt/decrypt result, you can choose your desired operation from the Select Operation drop-down menu. Select the key, choose the encoding, input your content (the length must be an integer multiple of 16) in the input box and then click Run, you can then see the result in the output box. To reverse the operation, you can click on < between the input and output boxes, choose the opposite operation, and then click on Run to check the result from the output box.
UniKey also provides an MD5 algorithm, for you to perform checksums. You can perform the MD5 calculation by following the same procedure.

===Random Number===

[[File:UniKey Console Random Number tab.PNG|500px|alt=enter a seed to generate four distinct randomly generated numbers]]

UniKey Console provides its own random number generator. By just entering a seed (numbers only) value and clicking Run you are provided with four random numbers in Result; the numbers generated are cryptographically random.

===Network===

[[File:console device network.png|500px|alt=UniKey Console network settings]]

This option allows you to configure your UniKey device (PRO, Time, and Drive) in a network environment. In the first line, you can set the maximum number of users who can connect to the server simultaneously.

====Client setting====
* Server IP is the servers IP address in the network. This address will guide clients to find the server in the network.
* Server port is the port to build communications between client and server.
* Time-out defines the maximum waiting period. If the client sends a request to the server, but the server does not send a response back in the set time, then the client is denied access.
* The default time-out period is 5 seconds.

<table class="wikitable" align="left" style="width: 100px;">
<tr>
<td align="center"><i>You can use this to control the behavior of the NetUniKey Client</i></td>
</tr>
</table>
The access mode box shows how NetUniKey Clients access the NetUniKey Server. If you set it to access by IP, NetUniKey Server accepts only ONE client per IP. If this value is set to access by process, the NetUniKey client from the same process can only be accepted once. If it is set to access by thread, NetUniKey can be accepted in any thread. Access by shared IP means all requests from a single IP will be counted as 1. To facilitate setting other devices with the same configuration, you can save your configuration information into a file, or to update a device remotely, you can generate an update file.

Working mode specifies how the UniKey Client will operate. If this value is set to local only, the NetUniKey Client will only work with a UniKey dongle attached to a local USB port.
If this value is local->network, the UniKey Client will check for a local UniKey dongle attached to a USB port first, if this fails, it will try to search for the UniKey dongle attached to the UniKey server in the network.
If you set it to network only, the NetUniKey Client will only work with the UniKey dongle attached to the UniKey server. When this value is set to network->local, the NetUniKey client will try to connect with the UniKey dongle attached to UniKey server first, and if it fails, it will try to load a local UniKey attached to a USB port.

Search mode sets how UniKey clients will try to find a UniKey dongle on the network. Local only is used for connecting to the server by using the server IP set in the configuration file. If it is set to local->broadcast, the UniKey client will try to use the information in the configuration file first, if this fails, the UniKey clients will broadcast to the local network to find the UniKey.
If set to broadcast->local, the UniKey clients will broadcast to the network first, and will try to connect to the UniKey specified in NetUniKey configuration file when they cannot find any UniKey via the broadcast. You can save this configuration file by clicking on Save, or read the previous client settings file by clicking on Read.

<div style="clear:both;"></div>

====Server setting====

[[File:console device network server.png|thumb|left|500px|alt=UniKey Console server settings|The default port is 5680]]

<div style="clear:both;"></div>
In this panel, you can enter the server IP, desired server port, and timeout. Enable/Disable the black and white IP list. To add an IP address to the list, click on the corresponding Add button, in the pop-up window, enter the start and end IP addresses. Or you can move an IP from the black list to white list by clicking on the >/< buttons.
* If the white list is enabled, only IP addresses in this list can access the server. If the list is empty, then no clients can access the server.
* The black list always has the highest priority. When the server starts, it will always check the black list first. If an IP appears in both the black and white list, the IP will be blocked.

===File System===
<b><em>Please note that this section is only for the UniKey Drive Console.</em></b>

File System allows you to manage the hidden and secure partition of the UniKey Drive dongle.

[[File:drive console file system.png|500px|alt=UniKey Drive Console file system initial window]]

====Entering the Hidden Partition====

[[File:drive console hidden partition.png|thumb|none|500px|alt=UniKey Drive Console hidden partition login screen|The default passwords to enter the hidden partition are 12345678]]

To enter the hidden partition, please input all four passwords to the UniKey Drive file system, then press OK. All the data stored on both the hidden and secure partitions are encrypted using a 128-bit encryption algorithm.

[[File:unikey drive hidden partition filesystem.png|500px|alt=UniKey Drive Console hidden partition filesystem]]

====Entering the Secure Partition====

[[File:drive console secure partition login screen.png|thumb|none|500px|alt=UniKey Drive Console secure partition login screen|The default password to enter the secure partition is 123456]]

The secure partition is also known as the password-protected partition; customers can access it by providing the correct password.

===Initialization===
<b><em>Please note that this section is only for the UniKey Drive Console.</em></b>

The Initialization tab for the UniKey Drive contains two parts; format and partition device memory.

[[File:drive console initialization.png|500px|alt=UniKey Drive Console Initialization tab]]

====Format====

[[File:UniKey Drive Initialization Format.png|500px|alt=UniKey Drive Console Initialization Format tab]]

By using the Format function, customers can format the UniKey Drive's 4KB memory, SID, license modules, algorithms and update tags.

====Partition====
To partition the UniKey Drive, you need to input all four passwords to log in to the Drive's filesystem. Pressing Default Password loads the default passwords automatically for you.

[[File:drive console initialization partition.png|thumb|none|500px|alt=UniKey Drive Console Initialization Partition tab|The four default passwords are 12345678]]

Device capacity is the UniKey Drive's total memory; UniKey Drives are available in 2, 4, 8, 16, and 32GB variants. An image file (ISO) is used for UniKey Drive's virtual CD-ROM partition; a user can burn their own ISO files to the Drive's virtual CD-ROM. A vendor can modify the capacity of the hidden, normal, and secure partition. Vendors need to create a password for the secure partition, so that end users are able to open the password-protected partition.

===Generate===

[[File:console generate unikey update.png|500px|alt=UniKey Console read update file]]

====Generate UniKey File====
UniKey file is used by the UniKey Burner tool, when a customer wants to burn the dongles in a batch by using the same configurations and settings, this file will be loaded into the UniKey Burner tool. Pressing the Read button will load the information stored on the .uky file to the Console tool. The Generate button will create the .uky file with the dongles information/settings from the Console tool.

===Generate Update File===

[[File:console generate update file.png|500px|alt=UniKey Console generate update file]]

The Update File is used by the UniKey Drive Remote Updater; it does the same thing as the UniKey Remote Update Generator does.

The Properties to be bound box will allow the customer to bind specific HID, SID, License Modules and Update Tags to the generated .upt2 file. After binding with a specific value, the .upt2 file will check if the values stored inside of the UniKey Drive dongle are the same or not. If they are not the same, the .upt2 file will not update the UniKey Drive.

The Property to be written box allows the customer to use the .upt2 file for updating the settings and configurations of the target UniKey Drive.
File password will allow the customer to set an independent password for the generated .upt2 file, and then when the end user updates their UniKey Drive by using the corresponding .upt2 file, they will need to input this password in order to access/use the .upt2 file.

File:UniKey Console Random Number tab.PNG

2016-08-23T00:16:00Z

Bao:

File:UniKey Console New Password tab.PNG

2016-08-23T00:15:13Z

Bao:

File:UniKey Console Time Module expiration method.PNG

2016-08-23T00:14:00Z

Bao:

File:UniKey Console Time Module 0 start time.PNG

2016-08-23T00:12:54Z

Bao:

File:UniKey Console Time Module tab.PNG

2016-08-23T00:11:37Z

Bao:

UniToken API Usage

2016-08-17T05:36:31Z

Bao:

[[category:UniToken_API]]

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

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

==Prototype Specification==

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

<code>typedef unsigned long UT_HANDLE;</code>

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

<code>typedef unsigned long KEY_HANDLE;</code>

KEY_HANDLE_PTR is the pointer of KEY_HANDLE.

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

<code>typedef unsigned long UT_RV;</code>

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

<code>typedef unsigned long UT_SLOT_ID;</code>

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

<code>typedef unsigned long UT_STATUS;</code>

We defined some values for this UniToken library version.

* define TOKEN_NO_EVENT 0
* define TOKEN_INSERT 1
* define TOKEN_REMOVE 2

==About Macro==

===Size===
* define UT_MAX_PIN_LEN 128
* define UT_MAX_ID_LEN 32
* define MAX_SLOT_NUMBER 32
* define FS_MEMORY (256*1024)

; Parameter Meaning
* UT_MAX_PIN_LEN the maximum password length
* UT_MAX_ID_LEN the maximum UniToken ID length
* MAX_SLOT_NUMBER the maximum volume of slot
* FS_MEMORY the maximum capacity of file system

===Password===
* define UT_DEFAULT_SO "admin"
* define UT_DEFAULT_USER "user"

; Parameter Meaning
* UT_DEFAULT_SO the admin default password of UniToken
* T_DEFAULT_USER the user default password of UniToken

===Slot Status===
* define TOKEN_NO_EVENT 0
* define TOKEN_INSERT 1
* define TOKEN_REMOVE 2

; Parameter Meaning
* TOKEN_NO_EVENT No slot status has changed
* TOKEN_INSERT A device is inserted in a slot
* TOKEN_REMOVE The device in the slot is removed

===User Level===
* define UT_USER_LEVEL_GUEST 0x0
* define UT_USER_LEVEL_USER 0x1
* define UT_USER_LEVEL_ADMIN 0x2

; Parameter Meaning
* UT_USER_LEVEL_GUEST GUEST Level
* UT_USER_LEVEL_USER USER Level
* UT_USER_LEVEL_ADMIN ADMIN ADMIN Level

===Modes of Changing Passwords===
* define UT_CHANGE_PIN_MODE_BYSELF 0x1
* define UT_CHANGE_PIN_MODE_ADMIN_CHANGE_USER 0x2

; Parameter Meaning
* UT_CHANGE_PIN_MODE_BYSELF Current user changes his password
* UT_CHANGE_PIN_MODE_ADMIN_CHANGE_USER Changing user password requires admin permission

===LED On-off===
* define LED_ON 1
* define LED_OFF 0

; Parameter Meaning
* LED_ON turn on LED
* LED_OFF turn off LED

===DES Key Length===
* define DES_KEY_LEN_8_BYTE 8
* define DES3_KEY_LEN_24_BYTE 24

; Parameter Meaning
* DES_KEY_LEN_8_BYTE DES key length
* DES3_KEY_LEN_24_BYTE DES3 key length

===DES Data Length===
* define DES_DATA_LEN_8_BYTE 8

; Parameter Meaning
* DES_DATA_LEN_8_BYTE BYTE DES en/decrypt data length

===AES Key Length===
* define AES_KEY_LEN_128_BIT 16
* define AES_KEY_LEN_192_BIT 24

; Parameter Meaning
* AES_KEY_LEN_128_BIT default key length
* AES_KEY_LEN_192_BIT maximum key length

===AES Data Length===
* define AES_DATA_LEN_16_BYTE 16

; Parameter Meaning
* AES_DATA_LEN_16_BYTE AES en/decrypt data length

===RSA Modulus Length===
* define RSA_MODULUS_LEN_1024_BIT 128
* define RSA_MODULUS_LEN_2048_BIT 256

; Parameter Meaning
* RSA_MODULUS_LEN_1024_BIT default modulus length
* RSA_MODULUS_LEN_2048_BIT Maximum modulus length

===RSA Public Exponent===
* define RSA_PUBEXP_LEN_65537_BIT 65537

; Parameter Meaning
* RSA_PUBEXP_LEN_65537_BIT RSA public exponent

===RSA Data Length===
* define RSA_DATA_LEN_1024_BIT 128
* define RSA_DATA_LEN_2048_BIT 256

; Parameter Meaning
* RSA_DATA_LEN_1024_BIT default data length
* RSA_DATA_LEN_2048_BIT maximum data length

===RSA Import New Key Pair===
* define RSA_IMPORT_NEW 0

; Parameter Meaning
* RSA_IMPORT_NEW newly imported key pair

===File Name Length===
* define UT_FILE_NAME_LENGTH 16

; Parameter Meaning
* UT_FILE_NAME_LENGTH file name maximum length not including string terminator

===File Permission===
* define FILE_PERMISSION_GUEST 0x0
* define FILE_PERMISSION_USER 0x1
* define FILE_PERMISSION_ADMIN 0x2

; Parameter Meaning
* FILE_PERMISSION_GUEST GUEST permission file
* FILE_PERMISSION_USER USER permission file
* FILE_PERMISSION_ADMIN ADMIN permission file

UniOTP Agent APIs

2016-08-17T04:49:55Z

Bao:

[[Category:UniOTP_API]]

== Chapter 1: C/C++ ==

=== Installation and usage ===

# Please copy the Securepass_auth.h header file and the radclt.lib library file into your project.
# Please perform authentication through the SecuAuth interface. For detailed instructions, please see the demo project.

'''How to integrate with the C++ environment'''

# Please add the RadiusClt1.h header file and radclt.lib library file to the project.
# When you need to perform authentication, instantiate the RadiusClt class.
# Use the initrad member function inside the RadiusClt class to initialize authentication information.
# Use the “parase” member function inside the RadiusClt class in order to set the username and OTP PIN for authentication. Use the “auth” member function inside the RadiusClt class to terminate the authentication process.

=== API ===

<source lang="C" collapse="true" first-line="2" highlight="[4,6]" title="title">
int secuauth(
char *phost,
char *pshare,
int nsharelen,
char *pszusername,
int nusernamelen,
char *pszpassword,
int npasswordlen,
int *pnchallenge,
int *pbvalidresponse,
char *presponse /* = NULL*/,
int nmaxbuflen /* = 0*/,
unsigned short uport /* = 1812*/,
int nwaittime /* = 3*/
);
</source>

'''Parameters'''

{| class="wikitable"
|-
! Parameters
! Description
|-
| Char *phost
| [IN] authentication server main address (IP address)
|-
| Char *pshare
| [IN] shared key used by authentication server and dynamic password token
|-
| Int nsharelen
| [IN] shared key length
|-
| char *pszusername
| [IN] The username waiting for authentication
|-
| int nusernamelen
| [IN] username length
|-
| char *pszpassword
| [IN] Password for this time (OTP[PIN] PIN is optional, but it is compulsory to choose a PIN for challenge/response type)
|-
| int npasswordlen
| [IN] password length
|-
| int *pnchallenge
| [OUT] The challenge code returned from the server. If the function return value is RD_ERROR_CHALLENGENEED, pnchallenge will be used as the challenge code
|-
| int *pbvalidresponse
| [OUT] whether Challenge information returned or not(please don’t try to set this parameter to NULL)
|-
| char *presponse
| [OUT] Buffer used for receiving challenge information. If the buffer length is smaller than the challenge information length, challenge information will not be returned. Challenge information length cannot exceed 256 bytes
|-
| int nmaxbuflen
| [IN] response buffer maximum size (byte)
|-
| unsigned short uport
| [IN] Authentication server port number, the default port for standard Radius is 1812
|-
| int nwaittime
| [IN] Maximum waiting time (second), if waiting time exceeds this value, the client will stop waiting for server response
|}

'''Return value'''

{| class="wikitable"
|-
! Return value
! Description
|-
| RD_ERROR_SUCCESS
| Authentication succeeded
|-
| RD_ERROR_CHALLENGENEED
| The function received successfully the challenge information returned from the server
|-
| RD_ERROR_INVALID_USERNAMERD_ERROR_INVALID
| Cannot use this username
|-
| RD_ERROR_INVALID_PWD
| Cannot use this password (wrong format, etc.)
|-
| RD_ERROR_INVALIDHOST
| Cannot use this authentication server (this error is also returned when the IP address field is empty)
|-
| RD_ERROR_INVALIDPCNAME
| Cannot read Computer name
|-
| RD_ERROR_GENRAFAILED
| Failed to generate authenticator request, an error might have occurred when requesting certification package
|-
| RD_ERROR_GENPWDFAILED
| Failed to encrypt the password submitted by the user, this error might have occurred when organizing the packets
|-
| RD_ERROR_CREATEPKTFAILED
| Failed to generate the authentication packets
|-
| RD_ERROR_CREATESOCKETFAILED
| Socket initialization failed
|-
| RD_ERROR_SENDDATAFAILED
| Failed to send packets
|-
| RD_ERROR_RECVDATAFAILED
| Failed to receive data
|-
| RD_ERROR_INVALIDPKT
| Data received are invalid
|-
| RD_ERROR_NORESPONSE
| The server doesn’t respond
|-
| RD_ERROR_AUTHFAILED
| Authentication failed (wrong password, etc)
|-
| RD_ERROR_GETCHALLENGEFAILED
| The server sent challenge information but an error occurred when receiving data
|-
| RD_ERROR_REMOTESOCKETCLOSED
| Server socket closed
|-
| RD_ERROR_INITSOCKFAILED
| Under Windows, error when executing WSAStartup function
|}

== Chapter 2: C# ==

=== Installation and usage ===

# Please add the UniOTP_Clt.dll dynamic library to your project.
# Instantiate the SecuRadClts_Client constructor class in your source code where you want to authenticate the user.
# Use the Authenticate method inside the SecuRadClts_Client class to perform the authentication

For further details about the source code, please see the sample folder. SecuRadClts_Client class performs Radius client functions. By calling the member class function interfaces below, you can perform standard Radius authentication.

=== API: SECURADCLTS_CLIENT() ===

'''Prototype'''

<source lang="C#" collapse="true" first-line="2" highlight="[4,6]" title="title">
SecuRadClts_Client (
string Server,
string SharedSecret,
string Username,
string Password,
int nport
);
</source>

'''Description'''

Class object instantiation, completes the initialization process

'''Parameters'''

{| class="wikitable"
|-
! Parameters
! Description
|-
| String Server
| Authentication server address
|-
| String SharedSecret
| Shared key
|-
| String Username
| Username for the authentication
|-
| String Password
| Password for the authentication
|-
| Int nport
| Authentication server port
|}

'''Return value '''

{| class="wikitable"
|-
! Return Value
! Description
|-
| 0
| Authentication Succeeded
|-
| 1
| Authentication request failed (impossible to connect to the server or wrong shared key)
|-
| 2
| authentication server response time out
|-
| 3
| returned packets are invalid (length shorter than the packet shortest length)
|-
| 4
| Authentication failed (password error)
|-
| 5
| Invalid packets (Identification code error)
|-
| 6
| packet length error
|-
| 7
| invalid challenge information
|-
| 8
| invalid packets
|-
| 100
| The server sent a challenge
|}

'''Properties'''

{| class="wikitable"
|-
! Property
! Type
! Meaning
! Performing method
|-
| Shared Secret
| String
| Shared Key
| Set get
|-
| UserName
| String
| Username waiting to be authenticated
| Set get
|-
| Password
| String
| Authentication password
| Set get
|-
| Server
| String
| Authentication server address
| Set get
|-
| Port
| String
| Authentication server port (Standard Radius authentication protocol users 1812 for authentication)
| Set get
|-
| UDPTimeout
| String
| Server longest waiting time
| Set get
|-
| pChallenge
| String
| Server Challenge message
| Set get
|}

== Chapter 3: Java ==

=== Installation and Usage ===

# Add the secuotp_jradiust.jar file inside your project.
# When you need to authenticate, Use RadientClient to create a client instance.
# Use “authenticate” to complete the authentication.

For further details about the source code, please see the sample folder.

=== API: RadiusCLIENT() ===

'''Prototype'''

<source lang="java" collapse="true" first-line="2" highlight="[4,6]" title="title">
RadiusClient (
String hostname,
String sharedSecret,
String username
);
</source>

'''Description'''

Create an object from the RadiusClient class

'''Parameters'''

{| class="wikitable"
|-
! Parameters
! Description
|-
| String hostname
| Authentication server address
|-
| String shareSecret
| Shared key
|-
| String username
| Username for user waiting to be authenticated
|}

'''Prototype 2'''

<source lang="java" collapse="true" first-line="2" highlight="[4,6]" title="title">
RadiusClient (
String hostname,
int authPort,
String sharedSecret,
String username
);
</source>

'''Parameters'''

{| class="wikitable"
|-
! Parameters
! Description
|-
| String hostname
| Authentication server address
|-
| int authPort
| Authentication service port (standard Radius authentication port is 1812)
|-
| String shareSecret
| Shared key
|-
| String username
| Username for user waiting to be authenticated
|}

'''Prototype 3'''

<source lang="java" collapse="true" first-line="2" highlight="[4,6]" title="title">
RadiusClient (
String hostname,
int authPort,
String sharedSecret,
String userName,
int sockTimeout
);
</source>

'''Description'''

Create an object from the RadiusClient class.

'''Parameters'''

{| class="wikitable"
|-
! Parameters
! Description
|-
| String hostname
| Authentication server address
|-
| int authPort
| Authentication service port (standard Radius authentication port is 1812)
|-
| String shareSecret
| Shared key
|-
| String username
| Username for user waiting to be authenticated
|-
| int sockTimeout
| Longest waiting time for the server response
|}

=== API: AUTHENTICATE() ===

'''Prototype'''

<source lang="java" collapse="true" first-line="2" highlight="[4,6]" title="title">
int authenticate (
String userPass
);
</source>

'''Description'''

Perform authentication

'''Parameters'''

{| class="wikitable"
|-
! Parameters
! Description
|-
| Sting userPass
| User authentication password for this time (OTP only or OTP + PIN)
|}

'''Return Value'''

{| class="wikitable"
|-
! Return Value
! Description
|-
| ACCESS_ACCEPT
| Authentication succeeded
|-
| ACCESS_REJECT
| Authentication failed
|-
| ACCESS_CHALLENGE
| The server sent challenge information
|}

=== API: GETCHALLENGEMESSAGE() ===

'''Prototype'''

<code>String getChallengeMessage();</code>

'''Description'''

When the authentication server sends a challenge, this function is used to retrieve the challenge information returned by the authentication service.

'''Parameters'''

N/A

'''Return value'''

N/A Challenge information returned by the server

'''Static data definition'''

{| class="wikitable"
|-
! Static data
! Value
! Meaning
|-
| ACCESS_ACCEPT
| 2
| Radius packet type, this packet shows that the authentication succeeded
|-
| ACCESS_REJECT
| 3
| Radius packet type, this packet shows that the authentication failed
|-
| ACCESS_CHALLENGE
| 11
| Radius packet type, this packet showsthat the authentication emitted a challenge
|}

== Chapter 4: PHP ==

=== Installation and Usage ===

# Copy the 2 files, radius.class.php and radius_config.php into the project directory.
# Change the radius_config.php file contents so that it matches your authentication server parameters.
# When you need to authenticate, create an instance of Radius class
# Use the AccessRequest member function to complete the authentication procedure.

For further details about the source code, please see the sample folder.

Class Radius is used for Radius on the client side, by using the following functions of the class, you can get the configuration data from the authentication server, the authentication information configuration data of the authentication user, user ID authentication, the server additional information, etc.

=== API: RADIUS() ===

'''Prototype:'''

<source lang="php" collapse="true" first-line="2" highlight="[4,6]" title="title">
Radius (
$ip_radius_server = '127.0.0.1',
$shared_secret = <i>, </i>
$udp_timeout = 5,
$authentication_port = 1812
);
</source>

'''Description'''

Function to create an object from Radius class. Call this function to instantiate Radius class and in the same time configure server address, shared key and longest waiting time for server response.

'''Parameters'''

{| class="wikitable"
|-
! Parameters
! Description
|-
| $ip_radius_server
| Authentication server address or server domain name, if empty, local computer will be chosen as default.
|-
| $shared_secret
| shared key, if empty, no shared key will be used
|-
| $udp_timeout
| Server response waiting time, if empty, time out will be 5
|-
| $authentication_port
| Authentication server port, if empty, the value will be 1812
|}

'''Return Value'''

N/A

=== API:ACCESSREQUEST() ===

'''Prototype'''

<source lang="php" collapse="true" first-line="2" highlight="[4,6]" title="title">
AccessRequest (
$username = <i>, </i>
$password = <i>, </i>
$udp_timeout = 0
);
</source>

'''Description'''

Perform user authentication

'''Parameters'''

{| class="wikitable"
|-
! Parameters
! Description
|-
| width="120" | $username
| Username for the user waiting to be authenticated
|-
| $password
| Authentication password for this time’s authentication, depending on the authentication method, this can either be OTP or OTP+PIN
|-
| $udp_timeout
| Longest server response waiting time. If you don’t set this parameter, the value will be the default value defined in the class when instantiating.
|}

'''Return value '''

{| class="wikitable"
|-
! Return Value
! Description
|-
| width="120" | ACCESS_ACCEPT
| Authentication succeeded
|-
| ACCESS_REJECT
| Authentication failed
|-
| ACCESS_CHALLENGE
| Challenge sent by the authentication server for this time’s authentication
|}

=== API: GETCHALLENGEMSG() ===

'''Prototype'''

<code>GetChallengeMsg();</code>

'''Description'''

When the AccessRequest function returns ACCESS_CHALLENGE, call this function to get the challenge code returned by the authentication server, which is used for the current ID authentication.

'''Parameters'''

N/A

'''Return Value'''

Challenge information returned by the authentication server for this time’s authentication

=== API:GETLASTERROR() ===

'''Prototype'''

<code>GetLastError();</code>

'''Description'''

Get information about last error

'''Parameters'''

N/A

'''Return Value'''

Character string, last abnormal error message

=== API:CLEARLASTERROR() ===

'''Prototype'''

<code>ClearLastError();</code>

'''Description'''

Clears error information

'''Parameters'''

N/A

'''Return Value'''

N/A

'''Static data definition'''

{| class="wikitable"
|-
! Static data
! Value
! Meaning
|-
| ACCESS_ACCEPT
| 2
| Radius packet type, this packet shows that the authentication succeeded
|-
| ACCESS_REJECT
| 3
| Radius packet type, this packet shows that the authentication failed
|-
| ACCESS_CHALLENGE
| 11
| Radius packet type, this packet shows that the authentication emitted a challenge
|}

UniOTP Business Solution

2016-08-17T04:02:30Z

Bao: /* UniOTP Dynamic password protection for each type of transaction */

[[Category:UniOTP_Integration_Solutions]]

== About This Guide ==

This document is intended for use by management. UniOTP dynamic password authentication system is a dynamic password authentication product designed by SecuTech Solution Inc. The company is committed to providing superior software protection and authentication experience for the user's personal data and intellectual property.

E-commerce requires that each party cooperates closely in order to provide to the consumer a safer environment and a more comfortable and appropriate consuming platform. It will become one of the most important business models in the future. But, while having brought convenience to people’s life, e-commerce also brings several hidden security risks. Attacks are becoming more sophisticated and diverse, and cases where a consumers’ profit has been infringed are rapidly increasing. Security is one of the most important obstacles to e-commerce development.

Financial industry refers to those enterprises operating specialized financial products, including banking, insurance, trusts, securities industry, leasing industry, mortgage industry etc. With the application of network technology in the financial industry, people can enjoy convenience brought by the computer network, such as online banking and online security trading. But with this convenience, user information security is facing more serious challenges. Various network attack technologies result in economic losses to customers. As the first user information security shield, if authentication is not strong enough, it can cause severe security problem and economic loss.

Authentication is the first step in assuring safety. This safety is directly related to the consumers’ personal benefits. Dynamic authentication is a technology that provides a strong authentication method to users and is considered to be a method that can solve today’s authentication related problems. The combination of dynamic password with e-commerce greatly raises the security level of electronic transactions, and better protects consumers’ benefits. Enterprise application refers to all kinds of information management systems which is applied by different enterprises, such as E-commerce, Enterprise resource planning (ERP), custom relationship management (CRM), etc. It will greatly improve enterprise management and manufacture efficiency by using enterprise applications to process cumbersome information.

Some of the information maintained by enterprise applications contains confidential information which may involve the core enterprises interests, so security of this information is very important. Enterprise information security can be achieved by building a defense system, including anti-virus, firewall network monitors and etc.

== Current Situation of Financial Transactions ==

=== Transaction mode ===

; OCT (Order confirmation transaction)
: When a customer goes to the counter and talks a teller to do their business directly, customers have to present their ID and bank card to tellers and provide password to complete authentication and do business.

; Dedicated terminal
: Customers use a dedicated terminal provided by a financial institutions (ATM and POS) to process their transactions. Customers need to present credential card (bank card), customer ID and customer password to start independent transactions.

; Online transaction
: Customers log in to financial institution websites to process business. In online transactions, customers normally provide an account name and password to complete the authentication process. After successfully logging on, customers can process their business online.

; Telephone transaction
: Customers can process their business through calling the financial institutions hotline. Customers need to provide user credentials and password to complete authentication.

=== Transaction security ===

A variety of transaction modes provide different trading experiences to customers along with different security risk.

; OCT security
: When customers provide their account number and passwords, there is a risk that criminals may peek at their passwords. After stealing the passwords, a criminal can log into customer accounts and perform illegal operations.

; Dedicated terminal security
: When a user inputs their account number and password, there is a risk that criminals may record their password. Because dedicated terminals are for public use without any special protection, it is easy for criminals to steal a users’ identification information.

; Online transaction security
: There is risk that online transaction user accounts and passwords are stolen by criminals, through listening, installing Trojans on a target computer, network hijacking, etc.

; Telephone transaction security
: There is risk that user accounts and passwords are stolen by recording and eavesdropping.

=== Common account security risks ===

; Plagiarism leak
: Attackers steal customer account information by eye, and fake a user's customer ID to operate that customer's account illegally. This kind of risk usually occurs when customers do their business in public.

; Install Trojans
: Attackers install Trojans on a target computer, and steal user accounts and passwords remotely. This security risk usually exists when users perform their business online by PC.

; Network sniffing
: Attackers extract a user’s confidential information through eavesdropping on the data transmission network.

; Replay attack
: Attackers simulate a user login, through sending authentication request data packages which were intercepted and recorded via network, to gain access to a user account.

; User password guess
: If a user's password is too simple, using characters such as date of birth, anniversary and name, attackers can obtain user passwords by guessing these details easily.

; Records leak
: If a password is too complicated and a user records it on paper, there is the risk of someone else seeing it.

; Brute force
: Attackers can obtain passwords by an enumerating method, and just attempting different combinations.

; Password sharing
: To remember various passwords for many different accounts, users will sometimes use the same password. If one password is stolen, criminals can try it on other accounts.

== Security Analysis ==

A general overview of the hidden security risks with e-commerce:

; Falsification
: Business related information is falsified as it is been transferred over a network.

; Information destruction
: Due to network devices or software malfunctioning, some data loss can happen.

; Identification
: A third party who uses weak methods of identification could be used to gain another party’s identity and achieve illegal operations.

; Information leaking
: Information of a transaction between two parties is read by a third party.

UniOTP's dynamic authentication system helps solve identification related risks. Below are common patterns of identification security risks:

* Consumer’s account name and password are stolen.
* The attacker installs a Trojan horse on a user’s computer to steal personal information such as bank account numbers.
* The attacker listens on the network, intercepts user information and gets the bank account number.
* For greater convenience, a consumer chooses an easy password such as their birth date, wedding anniversary, name, etc. making the password easy to guess for the attacker.
* The consumer stores password information in a certain place (file or notebook), that might lead to it being leaked.
* The attacker uses a brute force attack.
* The consumer uses the same password for different accounts.

== Dynamic Password Technology ==

=== Dynamic password overview ===

Dynamic passwords, also called one time passwords, are considered to be one method capable of solving existing authentication security problems. It is widely used for many situations and users such as Banks, Bourse, e-commerce. A dynamic password generation algorithm, user’s private key and dynamic elements constitute the 3 elements used to generate the dynamic password. When you authenticate yourself, besides your account name and your password, you have to provide the dynamic password to be able to pass the authentication process. Time based dynamic password generation creates a new unpredictable random password automatically every 60 seconds. This password can only be used once. Event based dynamic password generates a new unpredictable random password every time you press its button. This password can only be used once. Challenge response dynamic password uses a challenge code to generate a new unpredictable password. When the user requests authentication, the server will return a challenge code, this challenge code will be used to generate this time’s password.

=== Dynamic password characteristics ===

; Dynamic
: Depending on the dynamic factor changes, the password generated by dynamic password token will change. Every password generated is different from each other.

; Valid only one time
: Password generated by the dynamic password token can only be used one time, after that it will become invalid.

; Random
: Passwords are randomly generated, and cannot be predicted based on statistics.

; Easy to use
: Dynamic password is easy to use, no need for the user to remember the password, he only needs to read the password from the token at authentication time.

; Loss report
: As the user always keeps the token with him, he can notice the loss of the device immediately and report it as lost to the administrator who will disable the token, reducing risks caused by loss.

; Protection against Trojans/Network interception
: As the password is only valid one time, it is a way to protect oneself from peeking, Trojans, network interception.

; Protection against brute force attack
: The fact that the password is dynamic, and so, that it always changes every time is a good protection against a brute force attack (The attacker has less than 60 seconds to crack the password and use it before it becomes invalid or before the user himself uses it).

; Economic
: One token can be used for more than 3 years, thus saving on continual costs.

; Computer-independent
: The dynamic password Token has a LED display, you do not need to connect it to your computer through the USB port. In this case, it is very safe to use, as there is no connection with the computer as it doesn’t have the same security risks as USB based token products and certificate based products (In the case of USB products, there is still some risk of getting infected by Trojans).

=== Static password weak points ===

* In order to make a password easier to remember, users may often use birth date, phone number, etc. as a password. Hackers can use a dictionary attack in order to crack the password.
* If a password is used many times, hackers can calculate the password easily, by identifying the encrypted authentication information transmitted through network by using a interception and reply technique, causing critical information to be leaked.
* Because most current authentication information transmitted through a network is unencrypted, hackers can obtain important information about users through eavesdropping on the network data stream. They identify authentication information and intercept passwords from the network or telephone line.
* Hackers may even intercept a user’s password by using spies, social engineering or other methods.

=== Dynamic password usage procedure ===

* User requests connection to the web server
* Web server asks the user to authenticate
* User’s computer displays a login interface, asking user to input account name, password and dynamic password.
* User’s computer sends user authentication information to the web server
* Web server requests the Authentication Server to authenticate user’s identity.
* Authentication server returns authentication information to the web server.
* Web Server decides if the user can log in or not based on authentication results.

== UniOTP Dynamic Password Authentication ==

=== Overview ===

UniOTP dynamic password authentication system is a dynamic password product developed by SecuTech Solution Inc. UniOTP dynamic password authentication products can efficiently reduce losses caused by password leaks, and offer a powerful protection for user information and intellectual property. UniOTP dynamic password authentication system can be integrated with many kinds of systems, providing a dynamic password authentication service fitting any users’ needs. The enterprise server uses Agent SDK to perform the integration with UniOTP dynamic password authentication system and unify user authentication service. UniOTP dynamic password system open architecture and module-based structure provides convenience for UniOTP dynamic password system and enterprise server integration. UniOTP dynamic password authentication system robustness, flexibility, high availability and easy maintenance provide the best dynamic password authentication experience to the user.

=== Solution Description ===

E-commerce’s web structure mainly uses a server/browser setup. UniOTP dynamic password system provides two integration methods:

====First Solution====

Use Agent SDK (or Agent software) to perform integration of Web server and UniOTP dynamic password authentication systems, providing a unified authentication for the consumer. UniOTP’s dynamic password system open architecture, high stability and user-friendly interactivity provides the best dynamic password authentication and user experience possible.

[[Image:bussol img01.jpg|600px|Alt=user browser -> web server <-> UniOTP Agent <-> UniOTP Authentication server]]

; Authentication process
: After having integrated the dynamic password authentication as above, the consumer login process is the following:
:* The consumer uses their browser to display the login page
:* The consumer fills in their username, password, dynamic password and sends the login request
:* The web server authentication module receives the data submitted by the user and uses UniOTP Agent to send this data to the UniOTP authentication server.
:* UniOTP authentication server processes user authentication information to complete the authentication, and returns authentication results to UniOTP Agent.
:* UniOTP Agent returns the authentication results to the Web server authentication module.
:* The web server decides if the user can login or not depending on the authentication results sent by UniOTP Agent.
:* The consumer is able to log in, or receives a log in error message if the authentication failed.

====Second solution====
Use Server SDK to add dynamic password authentication function to the web server and perform integration of the Web Server System and UniOTP dynamic password authentication system. By using Server SDK integration to perform web application dynamic password authentication, you don’t need to rely on a UniOTP authentication server, but, compared to the previous method, this method requires the user to have strong development skills.

[[Image:bussol img02.jpg|500px|alt=user browser <-> web server <-> UniOTP Authentication server]]

; Authentication process
: Once you’ve integrated UniOTP dynamic password authentication according to the picture above, the authentication process is the following:
:* The consumer opens the login page in their browser.
:* The consumer fills in their username, password, dynamic password and sends the login request.
:* The Web server receives authentication information submitted by the user and calls UniOTP Authentication Module to complete user authentication.
:* The Web server decides to allow or deny consumer login depending on authentication results.
:* Consumer is allowed to log in, or receives an error message if authentication fails.

=== UniOTP Dynamic password protection for each type of transaction ===

{| class="wikitable"
|-
! Transaction method
! UniOTP protection
|-
| OTC transaction
| The main security risk of OTC transaction is from plagiarism. The UniOTP dynamic password authentication system uses one-time valid passwords. After the password is used, it is disabled. Therefore UniOTP system can protect user information security effectively.
|-
| Dedicated terminal transaction
| The one time validity of UniOTP dynamic password provides excellent anti-peek feature. No matter what means exploited by an attacker to steal user information, the information is no longer valid, therefore UniOTP dynamic password authentication system can eliminate risk from dedicated terminal transaction.
|-
| Online transaction
| Online transactions are easily attacked. With features of one-time validity, randomness and unpredictability, UniOTP dynamic password protects user information from Trojans, network sniffing and replay attacks.
|-
| Telephone transaction
| The one-time validity feature enables UniOTP to eliminate password leakage caused by stealing password via telephone transaction.
|}

=== UniOTP Dynamic password increases user authentication security ===

UniOTP dynamic passwords are only valid once and cannot be predicted by any statistical mean, the attacker cannot deduce what will be the next password from the previous ones, and moreover already used passwords will immediately be disabled after being used once. By using dynamic passwords, you can avoid potential safety problems which are caused by plagiarism, Trojans, network monitoring and password leakage by consumers.

=== UniOTP dynamic password authentication solution analysis ===

* UniOTP dynamic password authentication helps financial institutions provide customers with a secure authentication service, and satisfy customers who require higher account security.
* Easy integration and maintenance reduce costs.
* Better account protection helps to improve the reputation of financial institutions.
* Secure transaction environments will attract more customers.
* Reduce administrative cost caused by password theft.
* Easy to use, does not need require any software or connection to a computer by using an interface.
* Reduce user costs; every UniOTP can be used for 3-5 years.
* Improve account security and reduce customer economic risk.

=== UniOTP Dynamic password authentication benefits analysis ===

* UniOTP Dynamic authentication system helps financial organizations to strengthen its authentication method in order to satisfy consumer security needs.
* UniOTP dynamic password authentication system can be integrated simply and maintained easily, thus it reducing costs.
* UniOTP dynamic password authentication system assists e-business service providers to build a more secure platform for consumers and increase the credit and reputation of the e-business operator.
* UniOTP Dynamic password authentication protects consumer information from being stolen, and increases your users’ feeling of security.
* One token can be used from 3 to 5 years, reducing initial cost for the consumer.

== About UniOTP ==

UniOTP dynamic password authentication system is a dynamic password authentication product designed by SecuTech Solution Inc. The company is committed to providing superior software protection and authentication experience for the user's personal data and intellectual property. Financial sector activities require that each party cooperates closely in order to provide the consumer a safer commercial environment and a more comfortable and appropriate consumer platform.

UniOTP Business Solution

2016-08-17T03:57:28Z

Bao:

[[Category:UniOTP_Integration_Solutions]]

== About This Guide ==

This document is intended for use by management. UniOTP dynamic password authentication system is a dynamic password authentication product designed by SecuTech Solution Inc. The company is committed to providing superior software protection and authentication experience for the user's personal data and intellectual property.

E-commerce requires that each party cooperates closely in order to provide to the consumer a safer environment and a more comfortable and appropriate consuming platform. It will become one of the most important business models in the future. But, while having brought convenience to people’s life, e-commerce also brings several hidden security risks. Attacks are becoming more sophisticated and diverse, and cases where a consumers’ profit has been infringed are rapidly increasing. Security is one of the most important obstacles to e-commerce development.

Financial industry refers to those enterprises operating specialized financial products, including banking, insurance, trusts, securities industry, leasing industry, mortgage industry etc. With the application of network technology in the financial industry, people can enjoy convenience brought by the computer network, such as online banking and online security trading. But with this convenience, user information security is facing more serious challenges. Various network attack technologies result in economic losses to customers. As the first user information security shield, if authentication is not strong enough, it can cause severe security problem and economic loss.

Authentication is the first step in assuring safety. This safety is directly related to the consumers’ personal benefits. Dynamic authentication is a technology that provides a strong authentication method to users and is considered to be a method that can solve today’s authentication related problems. The combination of dynamic password with e-commerce greatly raises the security level of electronic transactions, and better protects consumers’ benefits. Enterprise application refers to all kinds of information management systems which is applied by different enterprises, such as E-commerce, Enterprise resource planning (ERP), custom relationship management (CRM), etc. It will greatly improve enterprise management and manufacture efficiency by using enterprise applications to process cumbersome information.

Some of the information maintained by enterprise applications contains confidential information which may involve the core enterprises interests, so security of this information is very important. Enterprise information security can be achieved by building a defense system, including anti-virus, firewall network monitors and etc.

== Current Situation of Financial Transactions ==

=== Transaction mode ===

; OCT (Order confirmation transaction)
: When a customer goes to the counter and talks a teller to do their business directly, customers have to present their ID and bank card to tellers and provide password to complete authentication and do business.

; Dedicated terminal
: Customers use a dedicated terminal provided by a financial institutions (ATM and POS) to process their transactions. Customers need to present credential card (bank card), customer ID and customer password to start independent transactions.

; Online transaction
: Customers log in to financial institution websites to process business. In online transactions, customers normally provide an account name and password to complete the authentication process. After successfully logging on, customers can process their business online.

; Telephone transaction
: Customers can process their business through calling the financial institutions hotline. Customers need to provide user credentials and password to complete authentication.

=== Transaction security ===

A variety of transaction modes provide different trading experiences to customers along with different security risk.

; OCT security
: When customers provide their account number and passwords, there is a risk that criminals may peek at their passwords. After stealing the passwords, a criminal can log into customer accounts and perform illegal operations.

; Dedicated terminal security
: When a user inputs their account number and password, there is a risk that criminals may record their password. Because dedicated terminals are for public use without any special protection, it is easy for criminals to steal a users’ identification information.

; Online transaction security
: There is risk that online transaction user accounts and passwords are stolen by criminals, through listening, installing Trojans on a target computer, network hijacking, etc.

; Telephone transaction security
: There is risk that user accounts and passwords are stolen by recording and eavesdropping.

=== Common account security risks ===

; Plagiarism leak
: Attackers steal customer account information by eye, and fake a user's customer ID to operate that customer's account illegally. This kind of risk usually occurs when customers do their business in public.

; Install Trojans
: Attackers install Trojans on a target computer, and steal user accounts and passwords remotely. This security risk usually exists when users perform their business online by PC.

; Network sniffing
: Attackers extract a user’s confidential information through eavesdropping on the data transmission network.

; Replay attack
: Attackers simulate a user login, through sending authentication request data packages which were intercepted and recorded via network, to gain access to a user account.

; User password guess
: If a user's password is too simple, using characters such as date of birth, anniversary and name, attackers can obtain user passwords by guessing these details easily.

; Records leak
: If a password is too complicated and a user records it on paper, there is the risk of someone else seeing it.

; Brute force
: Attackers can obtain passwords by an enumerating method, and just attempting different combinations.

; Password sharing
: To remember various passwords for many different accounts, users will sometimes use the same password. If one password is stolen, criminals can try it on other accounts.

== Security Analysis ==

A general overview of the hidden security risks with e-commerce:

; Falsification
: Business related information is falsified as it is been transferred over a network.

; Information destruction
: Due to network devices or software malfunctioning, some data loss can happen.

; Identification
: A third party who uses weak methods of identification could be used to gain another party’s identity and achieve illegal operations.

; Information leaking
: Information of a transaction between two parties is read by a third party.

UniOTP's dynamic authentication system helps solve identification related risks. Below are common patterns of identification security risks:

* Consumer’s account name and password are stolen.
* The attacker installs a Trojan horse on a user’s computer to steal personal information such as bank account numbers.
* The attacker listens on the network, intercepts user information and gets the bank account number.
* For greater convenience, a consumer chooses an easy password such as their birth date, wedding anniversary, name, etc. making the password easy to guess for the attacker.
* The consumer stores password information in a certain place (file or notebook), that might lead to it being leaked.
* The attacker uses a brute force attack.
* The consumer uses the same password for different accounts.

== Dynamic Password Technology ==

=== Dynamic password overview ===

Dynamic passwords, also called one time passwords, are considered to be one method capable of solving existing authentication security problems. It is widely used for many situations and users such as Banks, Bourse, e-commerce. A dynamic password generation algorithm, user’s private key and dynamic elements constitute the 3 elements used to generate the dynamic password. When you authenticate yourself, besides your account name and your password, you have to provide the dynamic password to be able to pass the authentication process. Time based dynamic password generation creates a new unpredictable random password automatically every 60 seconds. This password can only be used once. Event based dynamic password generates a new unpredictable random password every time you press its button. This password can only be used once. Challenge response dynamic password uses a challenge code to generate a new unpredictable password. When the user requests authentication, the server will return a challenge code, this challenge code will be used to generate this time’s password.

=== Dynamic password characteristics ===

; Dynamic
: Depending on the dynamic factor changes, the password generated by dynamic password token will change. Every password generated is different from each other.

; Valid only one time
: Password generated by the dynamic password token can only be used one time, after that it will become invalid.

; Random
: Passwords are randomly generated, and cannot be predicted based on statistics.

; Easy to use
: Dynamic password is easy to use, no need for the user to remember the password, he only needs to read the password from the token at authentication time.

; Loss report
: As the user always keeps the token with him, he can notice the loss of the device immediately and report it as lost to the administrator who will disable the token, reducing risks caused by loss.

; Protection against Trojans/Network interception
: As the password is only valid one time, it is a way to protect oneself from peeking, Trojans, network interception.

; Protection against brute force attack
: The fact that the password is dynamic, and so, that it always changes every time is a good protection against a brute force attack (The attacker has less than 60 seconds to crack the password and use it before it becomes invalid or before the user himself uses it).

; Economic
: One token can be used for more than 3 years, thus saving on continual costs.

; Computer-independent
: The dynamic password Token has a LED display, you do not need to connect it to your computer through the USB port. In this case, it is very safe to use, as there is no connection with the computer as it doesn’t have the same security risks as USB based token products and certificate based products (In the case of USB products, there is still some risk of getting infected by Trojans).

=== Static password weak points ===

* In order to make a password easier to remember, users may often use birth date, phone number, etc. as a password. Hackers can use a dictionary attack in order to crack the password.
* If a password is used many times, hackers can calculate the password easily, by identifying the encrypted authentication information transmitted through network by using a interception and reply technique, causing critical information to be leaked.
* Because most current authentication information transmitted through a network is unencrypted, hackers can obtain important information about users through eavesdropping on the network data stream. They identify authentication information and intercept passwords from the network or telephone line.
* Hackers may even intercept a user’s password by using spies, social engineering or other methods.

=== Dynamic password usage procedure ===

* User requests connection to the web server
* Web server asks the user to authenticate
* User’s computer displays a login interface, asking user to input account name, password and dynamic password.
* User’s computer sends user authentication information to the web server
* Web server requests the Authentication Server to authenticate user’s identity.
* Authentication server returns authentication information to the web server.
* Web Server decides if the user can log in or not based on authentication results.

== UniOTP Dynamic Password Authentication ==

=== Overview ===

UniOTP dynamic password authentication system is a dynamic password product developed by SecuTech Solution Inc. UniOTP dynamic password authentication products can efficiently reduce losses caused by password leaks, and offer a powerful protection for user information and intellectual property. UniOTP dynamic password authentication system can be integrated with many kinds of systems, providing a dynamic password authentication service fitting any users’ needs. The enterprise server uses Agent SDK to perform the integration with UniOTP dynamic password authentication system and unify user authentication service. UniOTP dynamic password system open architecture and module-based structure provides convenience for UniOTP dynamic password system and enterprise server integration. UniOTP dynamic password authentication system robustness, flexibility, high availability and easy maintenance provide the best dynamic password authentication experience to the user.

=== Solution Description ===

E-commerce’s web structure mainly uses a server/browser setup. UniOTP dynamic password system provides two integration methods:

====First Solution====

Use Agent SDK (or Agent software) to perform integration of Web server and UniOTP dynamic password authentication systems, providing a unified authentication for the consumer. UniOTP’s dynamic password system open architecture, high stability and user-friendly interactivity provides the best dynamic password authentication and user experience possible.

[[Image:bussol img01.jpg|600px|Alt=user browser -> web server <-> UniOTP Agent <-> UniOTP Authentication server]]

; Authentication process
: After having integrated the dynamic password authentication as above, the consumer login process is the following:
:* The consumer uses their browser to display the login page
:* The consumer fills in their username, password, dynamic password and sends the login request
:* The web server authentication module receives the data submitted by the user and uses UniOTP Agent to send this data to the UniOTP authentication server.
:* UniOTP authentication server processes user authentication information to complete the authentication, and returns authentication results to UniOTP Agent.
:* UniOTP Agent returns the authentication results to the Web server authentication module.
:* The web server decides if the user can login or not depending on the authentication results sent by UniOTP Agent.
:* The consumer is able to log in, or receives a log in error message if the authentication failed.

====Second solution====
Use Server SDK to add dynamic password authentication function to the web server and perform integration of the Web Server System and UniOTP dynamic password authentication system. By using Server SDK integration to perform web application dynamic password authentication, you don’t need to rely on a UniOTP authentication server, but, compared to the previous method, this method requires the user to have strong development skills.

[[Image:bussol img02.jpg|500px|alt=user browser <-> web server <-> UniOTP Authentication server]]

; Authentication process
: Once you’ve integrated UniOTP dynamic password authentication according to the picture above, the authentication process is the following:
:* The consumer opens the login page in their browser.
:* The consumer fills in their username, password, dynamic password and sends the login request.
:* The Web server receives authentication information submitted by the user and calls UniOTP Authentication Module to complete user authentication.
:* The Web server decides to allow or deny consumer login depending on authentication results.
:* Consumer is allowed to log in, or receives an error message if authentication fails.

=== UniOTP Dynamic password protection for each type of transaction ===

{| class="wikitable"
|-
| Transaction method
| UniOTP protection
|-
| OTC transaction
| The main security risk of OTC transaction is from plagiarism. The UniOTP dynamic password authentication system uses one-time valid passwords. After the password is used, it is disabled. Therefore UniOTP system can protect user information security effectively.
|-
| Dedicated terminal transaction
| The one time validity of UniOTP dynamic password provides excellent anti-peek feature. No matter what means exploited by an attacker to steal user information, the information is no longer valid, therefore UniOTP dynamic password authentication system can eliminate risk from dedicated terminal transaction.
|-
| Online transaction
| Online transactions are easily attacked. With features of one-time validity, randomness and unpredictability, UniOTP dynamic password protects user information from Trojans, network sniffing and replay attacks.
|-
| Telephone transaction
| The one-time validity feature enables UniOTP to eliminate password leakage caused by stealing password via telephone transaction.
|}

=== UniOTP Dynamic password increases user authentication security ===

UniOTP dynamic passwords are only valid once and cannot be predicted by any statistical mean, the attacker cannot deduce what will be the next password from the previous ones, and moreover already used passwords will immediately be disabled after being used once. By using dynamic passwords, you can avoid potential safety problems which are caused by plagiarism, Trojans, network monitoring and password leakage by consumers.

=== UniOTP dynamic password authentication solution analysis ===

* UniOTP dynamic password authentication helps financial institutions provide customers with a secure authentication service, and satisfy customers who require higher account security.
* Easy integration and maintenance reduce costs.
* Better account protection helps to improve the reputation of financial institutions.
* Secure transaction environments will attract more customers.
* Reduce administrative cost caused by password theft.
* Easy to use, does not need require any software or connection to a computer by using an interface.
* Reduce user costs; every UniOTP can be used for 3-5 years.
* Improve account security and reduce customer economic risk.

=== UniOTP Dynamic password authentication benefits analysis ===

* UniOTP Dynamic authentication system helps financial organizations to strengthen its authentication method in order to satisfy consumer security needs.
* UniOTP dynamic password authentication system can be integrated simply and maintained easily, thus it reducing costs.
* UniOTP dynamic password authentication system assists e-business service providers to build a more secure platform for consumers and increase the credit and reputation of the e-business operator.
* UniOTP Dynamic password authentication protects consumer information from being stolen, and increases your users’ feeling of security.
* One token can be used from 3 to 5 years, reducing initial cost for the consumer.

== About UniOTP ==

UniOTP dynamic password authentication system is a dynamic password authentication product designed by SecuTech Solution Inc. The company is committed to providing superior software protection and authentication experience for the user's personal data and intellectual property. Financial sector activities require that each party cooperates closely in order to provide the consumer a safer commercial environment and a more comfortable and appropriate consumer platform.

UniToken Console Tool

2016-08-17T02:18:58Z

Bao:

[[Category:UniToken_Tools]]

UniToken Console is used for the management of devices, including specifying user permissions and maintaining certificates and the file system.

== Device Management ==

=== Logon ===
To log onto the device:

# Select the corresponding UniToken from the UniToken icon in the device list.
# Input the corresponding PIN in PIN.
# Click Logon.

[[Image:unitokenconsole img01.jpg|500px|alt='logged on successfully' message]]

[[Image:unitokenconsole img02.jpg|500px|alt=UniToken Console device list]]

After successfully logging on, the current user will be granted corresponding permissions.

=== Logoff ===

To log off the device:

# Select the UniToken in the device list.
# Click Logoff.

[[Image:unitokenconsole img03.jpg|500px|alt=admin permissions reverting to guest permissions after log off]]

Once logged off, the Console will revert back to Guest permissions. When the UniToken device is initially connected to the computer, the device automatically defaults to the "Guest" permission. If an incorrect User PIN is entered over 15 times in succession (this number, known as the Maximal Attempt Times, by default 15, but may be changed by the administrator), the UniToken device will automatically lock itself to prevent any further login attempts as a security measure, regardless if the correct PIN is entered afterwards. The administrator must log in to unlock the UniToken device.

== User Management ==

Information about the UniToken device, such as UniToken ID, number of stored files, Current Permission, Used and Remaining Space, can be found under the User tab, as shown below. Functions that can be performed under the User tab depend on the permissions of the current user, and include Edit UniToken ID, Reset User PIN, Unlock, Edit SID and Change Admin PIN.

[[Image:unitokenconsole img04.jpg|500px|alt=UniToken Console user management tab]]

=== Edit UniToken ID (Admin, User) ===

The UniToken ID is the label assigned to the UniToken device to facilitate quick and easy identification of the token. To modify the UniToken ID:

# Enter a UniToken ID (maximum 32 characters).
# Click OK.

[[Image:unitokenconsole img05.jpg|500px|alt=inputting a new UniToken ID]]

=== Reset User PIN (Admin) ===

Under Reset User PIN, the Admin can reset the User PIN. To reset the PIN:

# Enter a new User PIN under New PIN.
# Re-enter the new User PIN under Verify PIN.
# Click OK.

[[Image:unitokenconsole img06.jpg|500px|alt=resetting a user PIN]]

=== Unlock (Admin) ===

If the maximum number of incorrect login attempts has been reached and, as a result, the UniToken device has locked itself, the Administrator must unlock the UniToken device to continue using the UniToken. To do so, the Administrator must log in, navigate to Unlock found under User, and complete the following steps:

# Enter a new User PIN user under New User PIN.
# Re-enter the new User PIN under Verify User PIN.
# Set the maximum number of incorrect PIN login attempts, between 0 and 15, under Pin attempts limit (0 - 15).
# Click OK.

[[Image:unitokenconsole img07.jpg|500px|alt=unlocking the admin account]]

=== Edit SID (Admin, User) ===

Software ID (SID) is a modifiable 32-bit unsigned integer that can be used a secondary form of identification for UniToken devices. The SID can be set to identify devices either through a software product’s individual serial number, or any unique or shared number to identify a batch of tokens which share some common feature(s).

To change the SID:

# Enter the new SID.
# Click OK.

[[Image:unitokenconsole img08.jpg|500px|alt=inputting a new SID between 0 and 4,294,967,295]]

=== Change Admin PIN (Admin) ===

Logged in as the admin, to change the admin PIN:

# Enter the old Admin PIN under Old PIN.
# Enter the new Admin PIN under New PIN.
# Re-enter the new Admin PIN under Verify PIN.
# Click OK.

=== Change User PIN (User) ===

When logged into the UniToken device under the User permissions, the User has access to: Edit UniToken ID, and Change User PIN.

[[Image:unitokenconsole img10.jpg|500px|alt=changing user PIN]]

=== Disconnection ===

If the UniToken device is removed from the computer at any point in time, the console will display a warning message to reconnect the UniToken device.

[[Image:unitokenconsole img11.jpg|500px|alt='please insert UniToken' message]]

== File System Management ==

UniToken provides a secure file system for the storage of digital credentials and files using the three-level permission system. Under the File tab, a list of the files stored on the device can be viewed, including their respective number, name, size and file permission, as well as the ability to delete files and view the remaining space.

[[Image:unitokenconsole img12.jpg|500px|alt=UniToken Console file system tab]]

=== Create a file ===

When creating a file, the filename, file size and file permission of the file to be created are required.

[[Image:unitokenconsole img13.jpg|500px|alt=filename; file size; file permissiosn (guest r/w, user r/w, admin r/w)]]

=== Delete a file ===

To delete a file:

# Select the file from the File List under the File tab that you wish to delete.
# Click Delete.

[[Image:unitokenconsole img14.jpg|500px|alt=displaying current file list]]

A pop-up message will appear if the file was deleted successfully.

[[Image:unitokenconsole img15.jpg|500px|alt='file deleted successfully' message]]

=== Format ===

Formatting the UniToken device resets the UniToken’s ID, User PIN, and Certifictate Container, located under Format as shown below. Notably, when formatting the token, the option to either enable or disable the Certificate Container is available. If the Certificate Container is created, Users can import and use certificates on the device. Without the Certificate Container, Users will not be able to do so. '''Note: Formatting the UniToken device irreversibly deletes all data on the device! Ensure formatting the UniToken device is required before continuing!'''

[[Image:unitokenconsole img16.jpg|500px|alt=UniToken Console format tab]]

== Certificate Management ==

In the Certificate tab, a summary of certificates on the token can be viewed. Functions available to Users include viewing and importing certificates.

[[Image:unitokenconsole img17.jpg|500px|alt=UniToken Console certificate tab]]

=== View ===

To view a specific digital certificate:

# Select a certificate from the list under the Certificate tab.
# Click View.

A window will appear displaying all related information of the selected certificate.

[[Image:unitokenconsole img18.jpg|500px|alt=certificate: issued; issuer; validity; signature algorithm; serial number; public key; version]]

=== Import ===

To import a digital certificate:

# Click Import.
# Browse to the directory of the certificate.
# With the chosen certificate selected, click Open.
# Input a password for the imported certificate.
# Click OK.

[[Image:unitokenconsole img19.jpg|500px|alt='please input certificate password' message]]

After importing the certificate, the certificate will appear in the list of stored digital certificates on the token.

UniOTP VPN Solution

2016-08-17T01:47:48Z

Bao:

[[Category:UniOTP_Integration_Solutions]]

== Note ==

The following steps apply to Windows Server 2003 and Windows XP where relevant. For recent versions of Windows, the steps below may differ slightly.

== About This Guide ==



VPN (Virtual Private Network) refers to a computer and firewall with VPN capability that can establish a secure tunnel between the server and a client over the Internet. In the tunnel initiator (server), the user's private data is encapsulated and encrypted and then transmitted through the Internet; on the receiver side (client), the received data is unpacked and decrypted. VPN services are installed with Windows 2000/2003. This manual is based on the installed VPN service, named "Routing and Remote Access". This service can be found from <code>Start Menu - All Programs - Administrative Tools - Services</code>

== Routing and Remote Access Configuration ==

From <code>Start Menu - All Programs - Administrative Tools - [Routing and Remote Access]</code> open the Routing and Remote Access control panel. Right-Click on Routing and Remote Access on the left-side of the panel, then select Add server to add a VPN server.

[[Image:vpnsol img01.jpg|500px|alt=routing and remote access main window]]

Right click on the newly-added server and select Configure and Enable Routing and Remote Access. If the Windows Firewall/Internet Connection Sharing (ICS) service is enabled, the Routing and Remote Access service cannot be turned on, and an ICS service warning message will appear. Configure the ICS service to allow the above operation, then redo the above steps. After Routing and Remote Access is enabled, the following configuration wizard will appear. In the Routing and Remote Access Server Setup Wizard window, under the Configuration step, select Remote access (dial-up or VPN) then click Next.

[[Image:vpnsol img02.jpg|500px|alt=choose remote access (dial-up or VPN)]]

On the Remote Access step, select VPN then click Next.

[[Image:vpnsol img03.jpg|500px|alt=choose VPN then next]]

Click Finish after completing the remainder of the wizard to complete the VPN installation.

== Configuring the VPN Server with UniOTP ==

After successfully setting up and configuring the VPN Server, open <code>Start Menu - All Programs - Administrative Tools</code> and open the Routing and Remote Access control panel.

[[Image:vpnsol img06.jpg|500px|alt=routing and remot access control panel]]

In the Routing and Remote Access window, right-click on the respective server from the directory list and select Properties.

[[Image:vpnsol img07.jpg|500px|alt=selecting properties option]]

In the Properties window, select the Security tab, and under Authentication provider, select RADIUS Authentication from the drop-down menu.

[[Image:vpnsol img08.jpg|500px|alt=RADIUS authentication selection]]

Click on Configure to configure the RADIUS Authentication server. In the configuration panel, click on Add to add a Radius authentication server.

[[Image:vpnsol img09.jpg|500px|alt=adding a RADIUS authentication server]]

Under the Add RADIUS Server window, fill in the UniOTP authentication server name and server details. Afterwards, click on Change next to Secret to change the RADIUS communication shared key.

[[Image:vpnsol img10.jpg|500px|alt=server name; secret; time-out (s); initial score; port]]

In the Change Secret window, configure the communication shared key, then click OK.

[[Image:vpnsol img11.jpg|500px|alt=changing secret value]]

The RADIUS Authentication window should now a indicate a Radius server has been added. Click on OK to save the authentication server configuration.

[[Image:vpnsol img12.jpg|500px|alt=added server 192.168.1.225 with initial score 30]]

Returning to the Properties window, click on Authentication Methods.

[[Image:vpnsol img13.jpg|500px|alt=certificate properties tab]]

In the Authentication Methods window, check the check-boxes: Extensible authentication protocol (EAP); Encrypted authentication (CHAP); and Unencrypted password (PAP). ''Please Note: Authentication methods Microsoft encrypted authentication version 2 (MS-CHAP v2); Microsoft encrypted authentication (MS-CHAP); and Shiva Password Authentication Protocol (SPAP) are not supported.'' Click on OK to apply settings and exit the window.

[[Image:vpnsol img14.jpg|500px|alt=authentication methods window]]

To apply configuration changes, restart the VPN server by right-clicking the server, selecting All Tasks, Restart.

[[Image:vpnsol img15.jpg|500px|alt=restarting the VPN server]]

== Add VPN Client ==

Open the Network Connections control panel found in the Control Panel.

[[Image:Vpnsol img16.jpg|500px|alt=network connections control panel]]

On the left-hand side, under Network Tasks, click on Create a new connection.

[[Image:Vpnsol img17.jpg|500px|alt='connect to the network at my workplace' option]]

A New Connection Wizard window will appear. On the Network Connection Type step, select Connect to the network at my workplace, then click Next.

[[Image:Vpnsol img18.jpg|500px|alt='virtual private network connection' option]]

On the Network Connection step, select Virtual Private Network connection, then click Next.

[[Image:Vpnsol img19.jpg|500px|alt=enter host name or IP address]]

On the VPN Server Selection step, enter the host name or IP address of the VPN to connect to, then click Next. If you wish, you can choose to Add a shortcut to this connection to my desktop on the final step, then click Finish to complete the wizard.

[[Image:Vpnsol img21.jpg|500px|adding a desktop shortcut option]]

When attempting to connect to the VPN server, a connection window similar to the window below will appear.

[[Image:Vpnsol img22.jpg|500px|alt=VPN connection window]]


If you have added a VPN access user, and bound this user to a dynamic token, you can use that dynamic password and PIN (if OTP+PIN authentication method has been selected) to connect to the VPN. When following this manual, a Guest account has been added to VPN Server and to the UniOTP dynamic password authentication system, therefore Guest and OTP + PIN (for Guest account the authentication method is OTP + PIN) need to be filled into this window. Please Click Connect.

[[Image:Vpnsol img23.jpg|500px|alt=VPN connection window with details entered]]

The following error may happen:

[[Image:Vpnsol img24.jpg|500px|alt='local computer does not support required encryption' message]]

To solve this error, please click Properties.

[[Image:Vpnsol img25.jpg|500px|alt=properties is located at the bottom of the connection window]]

Deselect Require data encryption, click on OK, and click Connect to start the connection again.

[[Image:Vpnsol img26.jpg|500px|alt='require data encryption (disconnect if none)' option in security]]

After connecting to the VPN server successfully, on the lower-right corner of the screen, the following information will appear indicating that the configuration of VPN with UniOTP authentication has been completed successfully.

[[Image:Vpnsol img27.jpg|300px|alt='user is now connected' pop-up]]

== Appendix ==

===Common errors upon VPN clients connecting to the server===

{| class="wikitable"
|-
| '''Error Code'''
| '''Reason'''
|-
| 800
| Unable to establish VPN connection. The VPN server may be un-reachable, or security parameters may not be configured properly for this connection
|-
| 619
| In most cases, it is caused by the NAT-T function, used for clients to connect to the Internet, has been turned off, or a VPN that does not support NAT-T in GRE and PPTP protocol. To solve this problem, you can turn on the gateway’s NAT-T. If this error happens frequently, please change the gateway equipment.
|-
| 721
| In most cases, this problem is caused by the client system. If users are using Windows XP SP2, this problem may happen, and you can solve it through modifying the registry entry: <code>HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Class\{4D36E972-E325-11CE-BFC1-08002bE10318}\<000x></code> <000x> is the network adapter of the Satellite WAN port (PPTP) driver. In this key, create a new DWORD value, name ValidataAddress with value 0. If the configuration of the PPP protocol on the server is not correct, it will cause this problem as well.

|-
| 718
| Wrong user name or password when connecting, or authentication service error occurs on authentication server.
|-
| 734
| Normally caused by VPN configuration problems, such as PPP configuration, unsupported or poorly supported MPPE.
|}

UniOTP Management System

2016-08-17T01:11:08Z

Bao: /* Search Log */

[[Category:UniOTP_Tools]]

== Introduction ==

The UniOTP Management System is a web-based management system. Administration and maintenance operations concerning dynamic password system configuration such as user information, token information, operator information and log information can be performed with this system. The system employs different levels of privileges for compartmentalization of information and tasks.

== Operator Login ==

On the login page of the UniOTP Management System, input the Operator ID in the OperatorID field and enter the corresponding password in the Password field. Click Submit to log in. The default Operator ID for the Super Operator is "1000000001" with the corresponding default password "123456", both without quotation marks.

[[Image:uniotpmgs img01.jpg|350px|alt=UniOTP Management login screen]]

If Operator login was successful, the administration interface will be accessible on the main page, otherwise an error message will appear if the login credentials are incorrect. From the administration interface, actions to perform can be chosen from the menu on the left or from the shortcut icons in the main panel.

[[Image:uniotpmgs img02.jpg|500px|alt=UniOtp Management system main window]]

== Logout ==

To log out of the system, click Exit System located at the top-right corner of the window, as shown in the screenshot above. For security purposes, please always use this method to log out of the system.

[[Image:uniotpmgs img03.jpg|500px|alt=UniOTP Management logged out of system]]

== Change Password ==

From the administration interface, click on Change Password from either under the Operator Management menu on the left or the Change Password shortcut on the main panel.

[[Image:uniotpmgs img04.jpg|500px|alt=UniOTP Management changing passwords icon]]

In the Change Password interface, input the current password in the Old Password field, and enter the new password in both the New Password and Confirm fields, enter the new password. Click Submit to apply changes.

[[Image:uniotpmgs img05.jpg|500px|alt=UniOTP Management change password screen]]

A message will appear indicating if the password change was successful or unsuccessful.

== Search User ==

From the administration interface, click on User Search from either under the User Management menu on the left or the User Search shortcut on the main panel.

[[Image:uniotpmgs img08.jpg|500px|alt=UniOTP Management user search icon]]

Users can be searched by either User ID or Username. Fill either field then click Search.

[[Image:uniotpmgs img09.jpg|500px|alt=UniOTP Management user search screen]]

For example, if searching User ID "US20110127002", without quotation marks.

[[Image:uniotpmgs img10.jpg|500px|alt=searching user ID US20110127002]]

If you enter "t" in the Username field, you will see information about all users whose username contains the character 't', you can choose the user you want to manage, modify or delete.

[[Image:uniotpmgs img11.jpg|500px|alt=selecting a user to modify]]

== Add a User ==

From the administration interface, click on Add User from either under the User Management menu on the left or the User Search shortcut on the main panel.

[[Image:uniotpmgs img12.jpg|500px|alt=UniOTP Management add user icon]]

In the Add User interface, fill in the corresponding fields: username (unique) in Username; user ID (unique) in UserID; contact number in Tel; the serial ID of the corresponding UniOTP device for the user in Serial; email address in Email; the user PIN; and authentication method (OTP+PIN, generated one-time password with the user PIN, is recommended for maximum security). Either username or user ID can be used interchangeably when authenticating.

[[Image:uniotpmgs img13.jpg|500px|alt=UniOTP Management adding user window]]

If an invalid token serial number is entered, the error message below will appear.

[[Image:uniotpmgs img14.jpg|500px|alt='invalid token' message]]

After inputting valid user information, click Submit.

[[Image:uniotpmgs img15.jpg|500px|alt=user fields filled]]

The notification below will appear if the user has been added successfully.

[[Image:uniotpmgs img16.jpg|500px|alt='user xxx added successfully' message]]

== Change User State ==

From the administration interface, click on Add User from either under the User Management menu on the left or the User Search shortcut on the main panel.

[[Image:uniotpmgs img17.jpg|500px|alt=UniOTP Management change user state icon]]

Under the Change User State interface, functions such as flagging a token as lost/stolen, unflagging lost/stolen tokens and permanently removing tokens can be performed. Functions are performed on users based on the user's User ID.

[[Image:uniotpmgs img18.jpg|500px|alt=UniOTP Management changing user state window]]

== Resynchronize Token ==

Under certain circumstances, a token may desynchronize with the server. In this case, the token must be resynchronized with the server to be able to authenticate with it. This can be done from the Token Reparation interface. From the administration interface, click on Token Reparation from either under the User Management menu on the left or the Token Reparation shortcut on the main panel.

[[Image:uniotpmgs img19.jpg|500px|alt=UniOTP Management token repair icon]]

To resynchronize the token, the User ID of the user whom the token is assigned under and the token itself is needed. Input the User ID in UserID. Afterwards, generate a one-time password from the token device, then input the generated OTP in First OTP. Generate a second OTP immediately after the previously generated OTP, and input the generated OTP in Second OTP. Two consecutive one-time passwords are needed in order for the the server and the token to be synchronized. When done, click Submit.

[[Image:uniotpmgs img20.jpg|500px|alt=UniOTP Management token repair window]]

The message below will appear if synchronization is successful.

[[Image:uniotpmgs img21.jpg|500px|alt='token repair successful' message]]

If the two generated one-time passwords are not consecutive with one another, or if the generated OTPs exceeds a certain generation range, synchronization will fail, and an error message similar to the one below will appear.

[[Image:uniotpmgs img22.jpg|500px|alt='token repair failed' message]]

== Add Operator ==

Under the Add Operator interface, new operators can be added into the system. The user to be added should not be one with a higher privilege level than the operator privilege level, otherwise the operation will be denied. From the administration interface, click on Add Operator from either under the Operator Management menu on the left or the Add Operator shortcut on the main panel.

[[Image:uniotpmgs img23.jpg|500px|alt=UniOTP Management add operator icon]]

In the Add Operator interface, input the Name, Password and Confirm password, and select the privilege level in the Level list, then click Submit.

[[Image:uniotpmgs img24.jpg|500px|alt=UniOTP Management add operator window]]

If the operation is successful, the following message will be returned. The Operator ID of newly added operator will be displayed.

[[Image:uniotpmgs img25.jpg|500px|alt='operator added successfully, operator ID is: ...' message]]

If the privileges of the new user is higher than the operator's, or that of the current user, the following error message will appear.

[[Image:uniotpmgs img26.jpg|500px|alt='insufficient rights to add new operator' message]]

== Delete Operator ==

The Delete Operator interface provides removal of an operator from the database. An operator can only be deleted if the privilege level of the current user is higher than the privilege level of the operator to be deleted. From the administration interface, click on Delete Operator from either under the Operator Management menu on the left or the Delete Operator shortcut on the main panel.

[[Image:uniotpmgs img27.jpg|500px|alt=UniOTP Management delete operator icon]]

In the Delete Operator interface, operators can be removed in one of two methods: An individual operator account can be deleted by Operator ID; multiple operator accounts can be deleted by a range of Operator IDs, specifying the starting Operator ID under BeginID and last Operator ID range under EndID. All operators in this specified range, inclusive, will be deleted. Input the corresponding data into either forms, then click Submit or Execute.

[[Image:uniotpmgs img28.jpg|500px|alt=UniOTP Management delete operator window]]

If the current user does not possess sufficient privileges to delete the specified or affected operator, the following error message will be returned.

[[Image:uniotpmgs img29.jpg|500px|alt='insufficient rights to delete this operator' message]]

If deletion was successful, the following message will be displayed.

[[Image:uniotpmgs img30.jpg|500px|alt='operation succeeded' message]]

== Search Operator ==

Under the Operator Search interface, information concerning operator accounts can be searched and viewed. Only operator accounts whose privilege level is less than the current user can be searched. From the administration interface, click on Operator Search from either under the Operator Management menu on the left or the Operator Search shortcut on the main panel.

[[Image:uniotpmgs img31.jpg|500px|alt=UniOTP Management operator search icon]]

In the Operator Information Search interface, operators can be searched in one of two methods: An individual operator account can be searched by Operator ID; multiple operator accounts can be searched by a range of Operator IDs, specifying the start Operator ID under BeginID and end Operator ID range under EndID, and, in addition, by name. All found operators in this specified range, inclusive, will be returned. Input the corresponding data into either form, then click Submit or Execute.

[[Image:uniotpmgs img32.jpg|500px|alt=UniOTP Management operator information search window]]

To illustrate, if "1000000001", without quotation marks, as the Operator ID was entered under OperatorID then submitted, information about the operator account whose Operator ID is 1000000001 will be returned. However, as 1000000001 is, by default, the Super Operator ID, only the Super Operator has sufficient privileges to view the specified search criteria, and hence is the only operator who can perform and view this search. Returned operators can be deleted by clicking the icon to the right of the operator in the returned list. Deletion of operators adhere to the requirements in the subsection above, in that operators can only be deleted if the privilege level of the current user is higher the the privilege level of the operator to be deleted. Searching by Operator ID will yield a results page similar to the screenshot below.

[[Image:uniotpmgs img33.jpg|500px|alt=operator ID; password; operator index; operator name; domain]]

Searching operators in a specific range will yield a results page similar to the screenshot below.

[[Image:uniotpmgs img34.jpg|500px|alt=multiple operators listed in search results]]

== Batch Import Token/User==

The Token/User Batch Import interface allows the service provider to import multiple tokens in the database. It also can import many users bound to a token at once inside the database. Refer to the picture below to enter the corresponding interface.

[[Image:uniotpmgs img35.jpg|500px|alt=UniOTP Management token import icon]]

In order to import Token files, you need to provide decryption keys for those files, there is no decryption key function for user import. The extension for token files and user information files is .unif.

[[Image:uniotpmgs img36.png|500px|alt=UniOTP Management token/user import window]]

If there is an error with the secret key or if the file is corrupted, the following message will be displayed.

[[Image:uniotpmgs img37.png|500px|alt='bad file' message]]

The token file part will successfully prompt an error for the token, there is no line in front of the failure of the token serial number corresponding to the record, you can export the information to the service provider to determine the cause of the error (duplicate imports should be excluded due to errors)

[[Image:uniotpmgs img38.png|500px|alt='please send information to provider' message]]

If the token import succeeds, a message will be displayed specifying the number of token imported

[[Image:uniotpmgs img39.png|500px|alt='1 line affected' message; one line per token]]

In the case user import has failed, the following error message, containing the details about the concerned users, will be displayed.

[[Image:uniotpmgs img40.png|500px|alt=SQL user details; invalid token error being displayed]]

== Search Log ==

The log search function provides an interface for searching and viewing logs from the UniOTP Management System, including regular operation and user authentication logs. From the administration interface, click on Log Search from either under the Database Management menu on the left or the Log Search shortcut on the main panel.

[[Image:uniotpmgs img41.png|500px|alt=UniOTP Management search log icon]]

In the Log Search interface, various search criteria is provided to narrow search of logs. Under LogDomain, Syslog refers to system task logs, and Commonlog refers to user authentication logs. Under Search Mode, logs can be optionally filtered by specific operators by selecting Specific Operator, otherwise all logs from all operators will be returned with All. In the QueryMode field you can choose logs for a specific operator, once you have specified an operator, the logs information displayed are only for the specified operator (If you specify username, the
authentication logs information for this user only will be displayed).

Under OperatorID, an Operator ID or username must be entered if Specific Operator was selected in Search Mode. All logs for the specified operator will be returned. Under Begin Date and End Date, logs can be filtered between two time periods. Set the two fields of logs from Begin Date to End Date to return, in order of year, month, day and hour. After specifying search criteria, click Submit.

[[Image:uniotpmgs img42.png|500px|alt=UniOTP Management search log window]]

Logs that correlate with specified criteria will be returned, similar to the screen below.

[[Image:uniotpmgs img43.png|500px|alt=log search results]]

If no results matching the requested search criteria has been found, the following screen will appear.

[[Image:uniotpmgs img44.png|500px|alt='no related info' message]]

== Export Log ==

Exports logs to a text file. From the administration interface, click on Export Log from either under the Database Management menu on the left or the Export Log shortcut on the main panel.

[[Image:uniotpmgs img45.png|500px|alt=UniOTP Management export log icon]]

Under LogDomain, Syslog refers to system task logs, and Commonlog refers to user authentication logs. Under Begin Date and End Date, logs can be filtered between two time periods. Set the two fields of logs from Begin Date to End Date to return, in order of year, month, day and hour. Under Compress, select the type of compression to compress the exported file. After specifying criteria, click Submit to backup the selected logs.

[[Image:uniotpmgs img46.png|500px|alt=|alt=UniOTP Management export log window]]

== Clear Logs ==

All specified logs can be deleted from the Export Log interface. From the administration interface, click on Empty log records from under the Database Management menu on the left.

[[Image:uniotpmgs img47.png|500px|alt=UniOTP Management empty log records sidebar selection]]

In the Empty log records interface, two categories of logs can be cleared. Syslog refers to system task logs, and Commonlog refers to user authentication logs.

[[Image:uniotpmgs img48.png|500px|alt=UniOTP Management empty log records window]]

Click Execute to clear selected logs. If deletion of logs was successful, the following message will be displayed.

[[Image:uniotpmgs img49.png|500px|alt='operation succeeded' message]]

== Backup Database ==

The database backup feature is used to restore all needed information.

[[Image:uniotpmgs img50.png|500px|alt=UniOTP Management backup database sidebar selection]]

In Backup Mode choose the backup mode. You can choose to backup the whole database, including the table structure and the data contained inside (You can specify which data you want to backup in the Log Backup field). You can also choose to backup only the table structure. In this case, the data contained inside the database will not be backed up.

[[Image:uniotpmgs img51.png|500px|alt=UniOTP Management backup database window]]

== Statistics ==

From the Statistics interface, You can see temporal and spatial repartition, make statistics, analyze about authentication strength, repartition and operation repartition.

[[Image:uniotpmgs img52.png|500px|alt=UniOTP Management statistics icon]]

In the Statistics interface, two types of analysis can be performed. In Load Analysis, two you can perform load statistics. In Operation statistics, you can perform operation statistics. You can choose a scale for these two parts (Year or month). In the Display Mode field, you can choose the display method, there are three kinds: histograms, line charts, and pie charts.

[[Image:uniotpmgs img53.png|500px|alt=UniOTP Management statistics window]]

The picture below shows the histogram of operation type analysis.

[[Image:uniotpmgs img54.png|500px|alt=histogram of empty log with one authentication]]

== System Information ==

Click the home icon in the left menu to show system information and the system configuration page, this page displays system information and the current settings list.

[[Image:uniotpmgs img55.png|500px|alt=UniOTP Management system information sidebar icon]]

== System configuration ==

Using the system configuration page you can change system settings. Click Config Database to configure the database.

[[Image:uniotpmgs img56.png|500px|alt=UniOTP Management systems configuration sidebar icon]]

Once you’ve entered the database settings page, you can change database settings such as database host, database name, port, login username, login password. You can also test the connection to the database, after you have submitted these changes, a new configuration file will be created.

[[Image:uniotpmgs img57.png|500px|alt=UniOTP Management change database configuration window]]

UniOTP Management System

2016-08-17T01:10:26Z

Bao:

[[Category:UniOTP_Tools]]

== Introduction ==

The UniOTP Management System is a web-based management system. Administration and maintenance operations concerning dynamic password system configuration such as user information, token information, operator information and log information can be performed with this system. The system employs different levels of privileges for compartmentalization of information and tasks.

== Operator Login ==

On the login page of the UniOTP Management System, input the Operator ID in the OperatorID field and enter the corresponding password in the Password field. Click Submit to log in. The default Operator ID for the Super Operator is "1000000001" with the corresponding default password "123456", both without quotation marks.

[[Image:uniotpmgs img01.jpg|350px|alt=UniOTP Management login screen]]

If Operator login was successful, the administration interface will be accessible on the main page, otherwise an error message will appear if the login credentials are incorrect. From the administration interface, actions to perform can be chosen from the menu on the left or from the shortcut icons in the main panel.

[[Image:uniotpmgs img02.jpg|500px|alt=UniOtp Management system main window]]

== Logout ==

To log out of the system, click Exit System located at the top-right corner of the window, as shown in the screenshot above. For security purposes, please always use this method to log out of the system.

[[Image:uniotpmgs img03.jpg|500px|alt=UniOTP Management logged out of system]]

== Change Password ==

From the administration interface, click on Change Password from either under the Operator Management menu on the left or the Change Password shortcut on the main panel.

[[Image:uniotpmgs img04.jpg|500px|alt=UniOTP Management changing passwords icon]]

In the Change Password interface, input the current password in the Old Password field, and enter the new password in both the New Password and Confirm fields, enter the new password. Click Submit to apply changes.

[[Image:uniotpmgs img05.jpg|500px|alt=UniOTP Management change password screen]]

A message will appear indicating if the password change was successful or unsuccessful.

== Search User ==

From the administration interface, click on User Search from either under the User Management menu on the left or the User Search shortcut on the main panel.

[[Image:uniotpmgs img08.jpg|500px|alt=UniOTP Management user search icon]]

Users can be searched by either User ID or Username. Fill either field then click Search.

[[Image:uniotpmgs img09.jpg|500px|alt=UniOTP Management user search screen]]

For example, if searching User ID "US20110127002", without quotation marks.

[[Image:uniotpmgs img10.jpg|500px|alt=searching user ID US20110127002]]

If you enter "t" in the Username field, you will see information about all users whose username contains the character 't', you can choose the user you want to manage, modify or delete.

[[Image:uniotpmgs img11.jpg|500px|alt=selecting a user to modify]]

== Add a User ==

From the administration interface, click on Add User from either under the User Management menu on the left or the User Search shortcut on the main panel.

[[Image:uniotpmgs img12.jpg|500px|alt=UniOTP Management add user icon]]

In the Add User interface, fill in the corresponding fields: username (unique) in Username; user ID (unique) in UserID; contact number in Tel; the serial ID of the corresponding UniOTP device for the user in Serial; email address in Email; the user PIN; and authentication method (OTP+PIN, generated one-time password with the user PIN, is recommended for maximum security). Either username or user ID can be used interchangeably when authenticating.

[[Image:uniotpmgs img13.jpg|500px|alt=UniOTP Management adding user window]]

If an invalid token serial number is entered, the error message below will appear.

[[Image:uniotpmgs img14.jpg|500px|alt='invalid token' message]]

After inputting valid user information, click Submit.

[[Image:uniotpmgs img15.jpg|500px|alt=user fields filled]]

The notification below will appear if the user has been added successfully.

[[Image:uniotpmgs img16.jpg|500px|alt='user xxx added successfully' message]]

== Change User State ==

From the administration interface, click on Add User from either under the User Management menu on the left or the User Search shortcut on the main panel.

[[Image:uniotpmgs img17.jpg|500px|alt=UniOTP Management change user state icon]]

Under the Change User State interface, functions such as flagging a token as lost/stolen, unflagging lost/stolen tokens and permanently removing tokens can be performed. Functions are performed on users based on the user's User ID.

[[Image:uniotpmgs img18.jpg|500px|alt=UniOTP Management changing user state window]]

== Resynchronize Token ==

Under certain circumstances, a token may desynchronize with the server. In this case, the token must be resynchronized with the server to be able to authenticate with it. This can be done from the Token Reparation interface. From the administration interface, click on Token Reparation from either under the User Management menu on the left or the Token Reparation shortcut on the main panel.

[[Image:uniotpmgs img19.jpg|500px|alt=UniOTP Management token repair icon]]

To resynchronize the token, the User ID of the user whom the token is assigned under and the token itself is needed. Input the User ID in UserID. Afterwards, generate a one-time password from the token device, then input the generated OTP in First OTP. Generate a second OTP immediately after the previously generated OTP, and input the generated OTP in Second OTP. Two consecutive one-time passwords are needed in order for the the server and the token to be synchronized. When done, click Submit.

[[Image:uniotpmgs img20.jpg|500px|alt=UniOTP Management token repair window]]

The message below will appear if synchronization is successful.

[[Image:uniotpmgs img21.jpg|500px|alt='token repair successful' message]]

If the two generated one-time passwords are not consecutive with one another, or if the generated OTPs exceeds a certain generation range, synchronization will fail, and an error message similar to the one below will appear.

[[Image:uniotpmgs img22.jpg|500px|alt='token repair failed' message]]

== Add Operator ==

Under the Add Operator interface, new operators can be added into the system. The user to be added should not be one with a higher privilege level than the operator privilege level, otherwise the operation will be denied. From the administration interface, click on Add Operator from either under the Operator Management menu on the left or the Add Operator shortcut on the main panel.

[[Image:uniotpmgs img23.jpg|500px|alt=UniOTP Management add operator icon]]

In the Add Operator interface, input the Name, Password and Confirm password, and select the privilege level in the Level list, then click Submit.

[[Image:uniotpmgs img24.jpg|500px|alt=UniOTP Management add operator window]]

If the operation is successful, the following message will be returned. The Operator ID of newly added operator will be displayed.

[[Image:uniotpmgs img25.jpg|500px|alt='operator added successfully, operator ID is: ...' message]]

If the privileges of the new user is higher than the operator's, or that of the current user, the following error message will appear.

[[Image:uniotpmgs img26.jpg|500px|alt='insufficient rights to add new operator' message]]

== Delete Operator ==

The Delete Operator interface provides removal of an operator from the database. An operator can only be deleted if the privilege level of the current user is higher than the privilege level of the operator to be deleted. From the administration interface, click on Delete Operator from either under the Operator Management menu on the left or the Delete Operator shortcut on the main panel.

[[Image:uniotpmgs img27.jpg|500px|alt=UniOTP Management delete operator icon]]

In the Delete Operator interface, operators can be removed in one of two methods: An individual operator account can be deleted by Operator ID; multiple operator accounts can be deleted by a range of Operator IDs, specifying the starting Operator ID under BeginID and last Operator ID range under EndID. All operators in this specified range, inclusive, will be deleted. Input the corresponding data into either forms, then click Submit or Execute.

[[Image:uniotpmgs img28.jpg|500px|alt=UniOTP Management delete operator window]]

If the current user does not possess sufficient privileges to delete the specified or affected operator, the following error message will be returned.

[[Image:uniotpmgs img29.jpg|500px|alt='insufficient rights to delete this operator' message]]

If deletion was successful, the following message will be displayed.

[[Image:uniotpmgs img30.jpg|500px|alt='operation succeeded' message]]

== Search Operator ==

Under the Operator Search interface, information concerning operator accounts can be searched and viewed. Only operator accounts whose privilege level is less than the current user can be searched. From the administration interface, click on Operator Search from either under the Operator Management menu on the left or the Operator Search shortcut on the main panel.

[[Image:uniotpmgs img31.jpg|500px|alt=UniOTP Management operator search icon]]

In the Operator Information Search interface, operators can be searched in one of two methods: An individual operator account can be searched by Operator ID; multiple operator accounts can be searched by a range of Operator IDs, specifying the start Operator ID under BeginID and end Operator ID range under EndID, and, in addition, by name. All found operators in this specified range, inclusive, will be returned. Input the corresponding data into either form, then click Submit or Execute.

[[Image:uniotpmgs img32.jpg|500px|alt=UniOTP Management operator information search window]]

To illustrate, if "1000000001", without quotation marks, as the Operator ID was entered under OperatorID then submitted, information about the operator account whose Operator ID is 1000000001 will be returned. However, as 1000000001 is, by default, the Super Operator ID, only the Super Operator has sufficient privileges to view the specified search criteria, and hence is the only operator who can perform and view this search. Returned operators can be deleted by clicking the icon to the right of the operator in the returned list. Deletion of operators adhere to the requirements in the subsection above, in that operators can only be deleted if the privilege level of the current user is higher the the privilege level of the operator to be deleted. Searching by Operator ID will yield a results page similar to the screenshot below.

[[Image:uniotpmgs img33.jpg|500px|alt=operator ID; password; operator index; operator name; domain]]

Searching operators in a specific range will yield a results page similar to the screenshot below.

[[Image:uniotpmgs img34.jpg|500px|alt=multiple operators listed in search results]]

== Batch Import Token/User==

The Token/User Batch Import interface allows the service provider to import multiple tokens in the database. It also can import many users bound to a token at once inside the database. Refer to the picture below to enter the corresponding interface.

[[Image:uniotpmgs img35.jpg|500px|alt=UniOTP Management token import icon]]

In order to import Token files, you need to provide decryption keys for those files, there is no decryption key function for user import. The extension for token files and user information files is .unif.

[[Image:uniotpmgs img36.png|500px|alt=UniOTP Management token/user import window]]

If there is an error with the secret key or if the file is corrupted, the following message will be displayed.

[[Image:uniotpmgs img37.png|500px|alt='bad file' message]]

The token file part will successfully prompt an error for the token, there is no line in front of the failure of the token serial number corresponding to the record, you can export the information to the service provider to determine the cause of the error (duplicate imports should be excluded due to errors)

[[Image:uniotpmgs img38.png|500px|alt='please send information to provider' message]]

If the token import succeeds, a message will be displayed specifying the number of token imported

[[Image:uniotpmgs img39.png|500px|alt='1 line affected' message; one line per token]]

In the case user import has failed, the following error message, containing the details about the concerned users, will be displayed.

[[Image:uniotpmgs img40.png|500px|alt=SQL user details; invalid token error being displayed]]

== Search Log ==

The log search function provides an interface for searching and viewing logs from the UniOTP Management System, including regular operation and user authentication logs. From the administration interface, click on Log Search from either under the Database Management menu on the left or the Log Search shortcut on the main panel.

[[Image:uniotpmgs img41.png|500px|alt=UniOTP Management search log icon]]

In the Log Search interface, various search criteria is provided to narrow search of logs. Under LogDomain, Syslog refers to system task logs, and Commonlog refers to user authentication logs. Under Search Mode, logs can be optionally filtered by specific operators by selecting Specific Operator, otherwise all logs from all operators will be returned with All. In the QueryMode field you can choose logs for a specific operator, once you have specified an operator, the logs information displayed are only for the specified operator (If you specify username, the
authentication logs information for this user only will be displayed.) Under OperatorID, an Operator ID or username must be entered if Specific Operator was selected in Search Mode. All logs for the specified operator will be returned. Under Begin Date and End Date, logs can be filtered between two time periods. Set the two fields of logs from Begin Date to End Date to return, in order of year, month, day and hour. After specifying search criteria, click Submit.

[[Image:uniotpmgs img42.png|500px|alt=UniOTP Management search log window]]

Logs that correlate with specified criteria will be returned, similar to the screen below.

[[Image:uniotpmgs img43.png|500px|alt=log search results]]

If no results matching the requested search criteria has been found, the following screen will appear.

[[Image:uniotpmgs img44.png|500px|alt='no related info' message]]

== Export Log ==

Exports logs to a text file. From the administration interface, click on Export Log from either under the Database Management menu on the left or the Export Log shortcut on the main panel.

[[Image:uniotpmgs img45.png|500px|alt=UniOTP Management export log icon]]

Under LogDomain, Syslog refers to system task logs, and Commonlog refers to user authentication logs. Under Begin Date and End Date, logs can be filtered between two time periods. Set the two fields of logs from Begin Date to End Date to return, in order of year, month, day and hour. Under Compress, select the type of compression to compress the exported file. After specifying criteria, click Submit to backup the selected logs.

[[Image:uniotpmgs img46.png|500px|alt=|alt=UniOTP Management export log window]]

== Clear Logs ==

All specified logs can be deleted from the Export Log interface. From the administration interface, click on Empty log records from under the Database Management menu on the left.

[[Image:uniotpmgs img47.png|500px|alt=UniOTP Management empty log records sidebar selection]]

In the Empty log records interface, two categories of logs can be cleared. Syslog refers to system task logs, and Commonlog refers to user authentication logs.

[[Image:uniotpmgs img48.png|500px|alt=UniOTP Management empty log records window]]

Click Execute to clear selected logs. If deletion of logs was successful, the following message will be displayed.

[[Image:uniotpmgs img49.png|500px|alt='operation succeeded' message]]

== Backup Database ==

The database backup feature is used to restore all needed information.

[[Image:uniotpmgs img50.png|500px|alt=UniOTP Management backup database sidebar selection]]

In Backup Mode choose the backup mode. You can choose to backup the whole database, including the table structure and the data contained inside (You can specify which data you want to backup in the Log Backup field). You can also choose to backup only the table structure. In this case, the data contained inside the database will not be backed up.

[[Image:uniotpmgs img51.png|500px|alt=UniOTP Management backup database window]]

== Statistics ==

From the Statistics interface, You can see temporal and spatial repartition, make statistics, analyze about authentication strength, repartition and operation repartition.

[[Image:uniotpmgs img52.png|500px|alt=UniOTP Management statistics icon]]

In the Statistics interface, two types of analysis can be performed. In Load Analysis, two you can perform load statistics. In Operation statistics, you can perform operation statistics. You can choose a scale for these two parts (Year or month). In the Display Mode field, you can choose the display method, there are three kinds: histograms, line charts, and pie charts.

[[Image:uniotpmgs img53.png|500px|alt=UniOTP Management statistics window]]

The picture below shows the histogram of operation type analysis.

[[Image:uniotpmgs img54.png|500px|alt=histogram of empty log with one authentication]]

== System Information ==

Click the home icon in the left menu to show system information and the system configuration page, this page displays system information and the current settings list.

[[Image:uniotpmgs img55.png|500px|alt=UniOTP Management system information sidebar icon]]

== System configuration ==

Using the system configuration page you can change system settings. Click Config Database to configure the database.

[[Image:uniotpmgs img56.png|500px|alt=UniOTP Management systems configuration sidebar icon]]

Once you’ve entered the database settings page, you can change database settings such as database host, database name, port, login username, login password. You can also test the connection to the database, after you have submitted these changes, a new configuration file will be created.

[[Image:uniotpmgs img57.png|500px|alt=UniOTP Management change database configuration window]]

UniOTP Server Control Tool

2016-08-16T05:37:19Z

Bao:

[[Category:UniOTP_Tools]]

== About this tool ==

UniOTP Server Control is a desktop tool used to configure and manage UniOTP
authentication service. By using this tool, you can check and control the status of UniOTP authentication service, and check and reconfigure the configuration information of the UniOTP authentication service.

== Launch the tool ==

* Double click on UniOTPSCRControl desktop shortcut to launch the service control program.
* Launch the service control program through <code>Start Menu - Programs - UniOTPSCRControl</code>

== Function Introduction ==

=== Service status control ===

After the program is started, the interface of the service status will appear.

* '''ServiceName''': name of service
* '''DisplayName''': the display name of service
* '''Description''': the description information of the service
* '''Executeable File Path''': the absolute path of the executable program corresponding to the service
* '''StartType''': the start type of the service. It can be set to automatic, manual and disable
* '''Service Status''': the service current status

After the service configuration has been changed, the Apply button will become available, click on Apply to apply the new configuration. Click on Start or Stop to start and stop the service

[[Image:uniotpservercontrol img01.jpg|370px|alt=OTPServer control settings]]

=== Database configuration ===

Click on the Settings tab to get into more service configuration interfaces, such as the database configuration interface, as displayed in the following picture.

* '''DSN''': information is used to configure the data source
* '''Database Source Name''': select the suitable database source
* '''Description''': description of the database source
* '''DataBase Type''': the type of database

Connection Parameters is used to configure the database link parameters.
* '''User''': the username used to connect to the database
* '''Password''': the database login password corresponding to the user

After configuring all parameters, click on Test Connection button to test the connection.

[[Image:uniotpservercontrol img02.jpg|370px|alt=OTPServer database configuration panel]]

Note: If running the server on a 64-bit machine, use <code>C:\Windows\SysWOW64\odbcad32.exe</code> and a 32-bit connector. If all the information is valid, the connection has succeeded, as shown in the following picture.

[[Image:uniotpservercontrol img03.jpg|370px|alt=successful connection to server]]

If the information is incorrect, the connection will fail, as shown in the following picture.

[[Image:uniotpservercontrol img04.jpg|370px|alt=connection to database failed]]

=== Authentication service configuration ===

Click on the Server Setting tab to switch to service configuration interface, as displayed in the following picture. The Server Information column contains configuration information about service network and performance.

* '''Port (Radius Server)''': the port number of the authentication service, following the Radius authentication protocol. The default port is 1812.
* '''Request Interval''': the period of time between requests
* '''Max idle time''': the maximum idle time of the certified thread
* '''Max Threads Num''': the maximum number of worker threads.

[[Image:uniotpservercontrol img05.jpg|370px|alt=OTPServer authentication service configuration panel]]

=== Login and authentication parameters configuration ===

Select the Options tab to access the login and authentication parameters configuration.

In the Authentication Option column, we have.
* '''Authentication Wnd''': authentication window, the default value is 30 (for safety reasons the window should not be set to big)
* '''Key Length''': the length of user secret keys (please change this value carefully)
* '''Max Failed-Try''': the maximum number of failure attempts

In the Log Options column, we have.
* '''Log Mode''': log mode (store the log in log file or database)
* '''Log Condition''': the condition of log generation
* '''Log File Size''': the maximum log file size when you choose to store a log in log file

[[Image:uniotpservercontrol img06.jpg|370px|alt=OTPServer login and authentication configuration panel]]

=== The configuration of the shared secret key for the authentication service and clients ===

Click on the Share tab to enter shared secret key configuration interface. In this panel, configure the shared secret key of the authentication client (application server), and enable and disable each status.

[[Image:uniotpservercontrol img07.jpg|370px|alt=OTPServer client and blacklist]]

In the Client List, the IP address shows the current authorized authentication clients, and shared Key displays the shared secret key for the service and this authentication client. Click on Add button to add a new authentication client. And enter a new client IP address and shared key. Afterwards add a new authentication client, click on Apply to save and apply these new changes.

[[Image:uniotpservercontrol img08.jpg|370px|alt=add client to client list]]

Click on Delete button to delete an authentication client. After clicking on delete, the selected client will be deleted. During the delete operation, a confirmation dialogue will pop up (after confirming the delete operation, the client configuration file will be deleted).

[[Image:uniotpservercontrol img09.jpg|370px|alt='delete client ADDRESS?' message]]

If no client is selected, the following message will appear.

[[Image:uniotpservercontrol img10.jpg|370px|alt='no client is selected' message]]

Click on the Edit button to modify the configuration of the selected client. The client's IP address will not be modified, and only the shared key can be changed. For example, if the client (IP address 127.0.0.1) is selected, after clicking on Edit, a dialogue window will pop up. Enter the new shared key in the dialogue window, and then the Apply button will become available. Click Apply to enable all the new configurations.

[[Image:uniotpservercontrol img11.jpg|370px|alt=edit client IP address and shared key]]

Click on Add Black button to add an authentication client to the blacklist. Clients in the blacklist will not request authentication, but the authentication system will save the relative shared key information, so the authentication function can be recovered by removing the client from the blacklist. The blacklist, the IP address displays all the authentication clients' IP address' added into the blacklist, and shared key displays the shared key for the client and the authentication service. Clicking Delete to delete an authentication client from the blacklist. After the user confirms the delete operation, the client will be permanently deleted from the system. Click Remove to remove the client from the blacklist, to recover the authentication. After executing the remove operation, click Apply to apply changes. After clicking on Apply, the following dialogue will appear.

[[Image:uniotpservercontrol img12.jpg|370px|alt='update configuration successful' message]]

=== Email parameters configuration ===

Click on the Mail tab to enter Email configuration interface. This panel contains configurations about the Email server.

[[Image:uniotpservercontrol img13.jpg|370px|alt=OPTServer email configuration panel]]

Use Email Service select box to decide whether to use the email reminder function. After using the email reminder function, the SMTP server must be configured.

* '''SMTP Server''': the SMTP server name or IP address
* '''SMTP Port''': SMTP server Port (the default port is 25)
* '''Mail Subject''': the mail subject sent by the system
* '''Email From''': the email address displays in email recipients
* '''SMTP Server authentication''': select if the email server needs authentication
* '''User Name''': the username used for SMTP authentication.
* '''Password''': the password corresponding to the username.

After finishing the configuration , click Apply to apply configurations.

== Exit the tool ==

The tool will not exit by clicking on the close button in the interface. The tool will just be minimized to the tray. Right click on the icon in the tray, and click on Exit to close the program, as shown in the following picture.

[[Image:uniotpservercontrol img14.jpg|370px|alt=clicking exit on the tray icon to close the program]]

UniToken Monitor Tool

2016-08-16T03:19:42Z

Bao:

[[Category:UniToken_Tools]]

The UniToken Monitor utility offers a variety of functions, including the ability to view details on imported certificates, register or unregister certificates, change PINs and check the status of registrations. Upon running, UniToken Monitor will appear in the taskbar’s notification area and continue to run in the background. To open the UniToken interface, double-click the icon and the Monitor interface will appear.

== UniToken Information ==

In the UniToken Information tab, specifics of the UniToken device, such as Type, Name, Current Permission, Firmware Version, Free Memory and Total Memory, can be viewed.

[[Image:unitokenmonitor img01.jpg|370px|alt=UniToken Monitor tool UniToken Information tab]]

== Admin Tool ==

The Admin Tool tab provides numerous functions available to the Administrator for operation and maintenance.

[[Image:unitokenmonitor img02.jpg|370px|alt=UniToken Monitor tool Admin Tool tab]]

=== Change Admin PIN ===

To change the Admin PIN:

# Click on Change Admin PIN.
# Enter the old Admin PIN under Old PIN.
# Enter the new Admin PIN under New PIN.
# Re-enter the new Admin PIN under Verify PIN.
# Click OK.

[[Image:unitokenmonitor img03.jpg|370px|alt=change Admin PIN window]]

=== Format ===

To format the UniToken device:

# Click on Format.
# To confirm the format of the UniToken device, click OK.

[[Image:unitokenmonitor img04.jpg|370px|alt='are you sure you want to format this device' message]]

=== Set Token Name ===

To set the name of the token:

# Click on Set Token Name.
# Enter the name of the UniToken device.
# Click OK.

[[Image:unitokenmonitor img05.jpg|370px|alt=type in token name]]

=== Reset User PIN ===

To reset the User PIN:

# Click Reset User PIN.
# Enter a new User PIN under New PIN.
# Re-enter the new User PIN under Verify PIN.
# Click OK.

[[Image:unitokenmonitor img06.jpg|370px|alt=reset user PIN window]]

=== Unlock UniToken ===

To unlock the UniToken:

# Click on Unlock UniToken.
# Set the maximum number of incorrect PIN login attempts, between 0 and 15.
# Click "OK".

[[Image:unitokenmonitor img07.jpg|370px|alt=unlock a UniToken]]

== User Tools ==

This tab provides an interface to perform all the operations by User.

[[Image:unitokenmonitor img08.jpg|370px|alt=UniToken Monitor User Tool tab]]
[[Image:unitokenmonitor img09.jpg|370px|alt='user logged in successfully' message]]

=== Change User PIN ===

[[Image:unitokenmonitor img10.jpg|370px|alt=change user PIN]]

=== Import Certificate ===

[[Image:unitokenmonitor img11.jpg|370px|alt='type in password for private key' message]]

=== Certificate Management ===

[[Image:unitokenmonitor img12.jpg|370px|alt=displaying certificate details]]

=== View Certificate Information ===

[[Image:unitokenmonitor img13.jpg|370px|alt=viewing more detailed information about the certificate]]

=== Register/Unregister Certificate ===

[[Image:unitokenmonitor img14.jpg|370px|alt='please select a certificate' message]]
[[Image:unitokenmonitor img15.jpg|370px|alt='certificate unregistered successfully' message]]

=== Set Reminder Date ===

[[Image:unitokenmonitor img16.jpg|370px|alt=set reminder date in days]]

UniOTP PAM Agent

2016-08-16T02:25:46Z

Bao:

[[category:UniOTP_Tools]]



This document details how to install and configure the UniOTP PAM Authentication Agent in the Red Hat Enterprise Linux 5 operating system, and how to use UniOTP's authentication system as an additional factor in user authentication.

'''Environment ''': Operating System: Red Hat Enterprise 5

'''Important''': Please note that currently there is no ability to safely test if a user account bound with UniOTP authenticates successfully on Linux after installation and configuration. Backup all important data and proceed diligently.

== Installation ==

=== Extract pam_secu.tar.gz ===

Navigate to the directory where the setup package "pam_secu.tar.gz" is located. In the example screenshot below, the setup package is located in <code>/tmp/Desktop</code> Type "cd" to navigate to folder, and "tar zxvf" to extract the setup package, as shown below.

[[Image:uniotppam img01.jpg|alt=command line cd and tar command]]

Using the "tar" command, the extracted files will be extracted to the same directory as the archive file "pam_secure.tar.gz".

[[Image:uniotppam img02.jpg|alt=extraction output]]

=== Install the PAM Authentication Agent ===

To be able to install the PAM Agent, you must be logged in as root. Once logged in as root, in the directory of the extracted file, input "./install" to install the PAM Agent.

[[Image:uniotppam img03.jpg|alt=running install]]

The below will appear.

[[Image:uniotppam img04.jpg|alt=install output]]

After installation has completed, the system will prompt "Change configuration file now? [y/n]". If you want to change the configuration file now, input y and press enter, otherwise, input n and press enter. Here, input n and press enter, we can change the configuration file later. The following information will be display. Please make sure the configuration file has been configured correctly, before restarting your computer, otherwise it may cause log in failures next time.

[[Image:uniotppam img05.jpg|alt=installation finished output]]

=== Verify PAM Agent Installation ===

You can check if the PAM agent has been installed successfully, by the following method.

1. Go to <code>/lib/security</code> to check the pam_secu.so file.

[[Image:uniotppam img06.jpg|alt=security file directory]]

2. Go to <code>/user/lib</code> to check the libuniotp_agent_c.so file.

[[Image:uniotppam img07.jpg|alt=lib file directory]]

3. Go to <code>/etc</code> to check the secu_pam_agent.conf file.

[[Image:uniotppam img08.jpg|alt=etc file directory]]

If all these files can be found in the corresponding directory, the PAM Agent has been installed successfully, and the next step is to configure the PAM Agent.

== PAM Agent Configuration ==

=== Configure secu_pam_agent.conf ===

This file contains settings about the system account, mapping of the dynamic password name for the system account, authentication server IP address shared key and authentication server port. For more details, please read the introduction in secu_pam_agent.conf.

[[Image:uniotppam img09.jpg|alt=opening secu_pam_agent.conf with vi]]

The following file will be opened. Add a system user and other corresponding parameters as shown in the picture below.

[[Image:uniotppam img10.jpg|alt=uniotp_account=newtest authserver=192.168.1.225 share=hello port=1812 maxwait=3]]

* [user name]: a valid system account name (example: [root])
* uniotp_account: the mapping account name of dynamic password for [user name]
* authserver: authentication server IP address
* share: shared secret key (obtained from authentication service administrator)
* port: authentication server connection port
* maxwait: the maximum time waiting for authentication server response

=== Configure the PAM Authentication Agent ===

The PAM authentication agent configuration is adding the OTP Server PAM authentication agent program to the authentication module service, which is in <code>/etc/pam.d</code>

[[Image:uniotppam img11.jpg|alt=cd /etc/pam.d]]

=== Configure Command Line Login Authentication ===

Open the login file in directory <code>/etc/pam.d</code> and add "auth required pam_secu.so" in the row.

[[Image:uniotppam img12.jpg|alt=vi /etc/pam.d/login]]

[[Image:uniotppam img13.jpg|alt=auth required /lib/security/pam_secu.so]]

Save and quit. Now you have finished all PAM agent configurations for command line login authentication. There are five control-flag keywords: required, requisite, sufficient, optional and include.

* '''required:''' this indicates that the success of the module is required for the module-type facility to succeed. Failure of this module will not be apparent to the user until all of the remaining modules (of the same module-type) have been executed.
* '''requisite:''' like required, however, in the case that such a module returns a failure, control is directly returned to the application. The return value is that associated with the first required or requisite module to fail. Note, this flag can be used to protect against the possibility of a user getting the opportunity to enter a password over an unsafe medium. It is conceivable that such behavior might inform an attacker of valid accounts on a system. This possibility should be weighed against the not insignificant concerns of exposing a sensitive password in a hostile environment.
* '''sufficient:''' the success of this module is deemed `sufficient' to satisfy the Linux-PAM library that this module-type has succeeded in its purpose. In the event that no previous required module has failed, no more `stacked' modules of this type are invoked. (Note, in this case subsequent required modules are not invoked.). A failure of this module is not deemed as fatal to satisfying the application that this module-type has succeeded.
* '''optional:''' as its name suggests, this control-flag marks the module as not being critical to the success or failure of the user's application for service. In general, Linux-PAM ignores such a module when determining if the module stack will succeed or fail. However, in the absence of any definite successes or failures of previous or subsequent stacked modules this module will determine the nature of the response to the application. One example of this latter case, is when the other modules return something like PAM_IGNORE.
* '''include:''' this tells PAM to include all lines of given type from the configuration file specified as an argument to this control. The whole idea is to create few "systemwide" pam configs and include parts of them in application pam configs. pam_secu.so support debug function. If you input debug following pam_secu.so the debug information will be added to the system log file (like: auth sufficient pam_secu.so debug). And you can specify the configuration file by using conf –directory (like: <code>auth sufficient pam_secu.so conf –/etc/secu_pam_agent.conf</code> the agent will find configuration file from the specified directory, instead of the default one).

=== Configure Desktop Login Authentication ===

Open the PAM configuration file for gdm in directory <code>/etc/pam.d</code> and add "auth required pam_secu.so" in the first row.

[[Image:uniotppam img14.jpg|alt=vi /etc/pam.d/gdm_]]

[[Image:uniotppam img15.jpg|alt=auth required pam_secu.so]]

Save and quit. Now you have finished all PAM agent configurations for desktop login authentication. Please make sure the configuration file has been configured correctly, before restarting your computer, otherwise it may cause login failures on next boot.

=== Configure Remote Terminal Login Authentication ===

Open the sshd file in directory <code>/etc/pam.d</code> and add "auth sufficient pam_secu.so sshd" in the row.

[[Image:uniotppam img16.jpg|alt=vi sshd]]

[[Image:uniotppam img17.jpg|alt=auth sufficient pam_secu.so sshd]]

For remote login authentication configuration, you can only use sufficient. Save and quit. Now you have finished all PAM agent configurations for remote terminal login authentication.

== Testing PAM Authentication Agent ==

=== Testing Command Line Authentication ===

Input user name [root] and press enter. Now the system will ask for OTP[PIN]. Just input the dynamic password generated by your OTP device and your PIN following OTP in this line and press enter. In the next Password line, input your static password and press enter. You will login as root, if you see [root@localhost ~]#.

[[Image:uniotppam img18.jpg|370px|alt=command line authentication logging in as root]]

=== Testing Desktop Login Authentication ===

After configuring the gdm file, you can login the system by using the GUI, input the user name when the following login interface appear.

[[Image:uniotppam img19.jpg|370px|alt=Red Hat login screen, username: root]]

Input user name [root], and then the password interface will appear.

[[Image:uniotppam img20.jpg|370px|alt=Red Hat login screen, OTP[PIN]: enter]]

Please Input OTP and PIN, and then press enter. If you can log in to the system, you have successfully configured the PAM agent for desktop login authentication.

=== Testing Remote Login Authentication ===

We use SecureCRT as the remote login tool. After UniOTP protection is enabled for remote login authentication. You must input OTP+PIN in the password field to log in to the host computer, and click on OK.

[[Image:uniotppam img21.jpg|370px|alt=enter secure shell password]]

Once logged in successfully, the following picture is displayed:

[[Image:uniotppam img22.jpg|370px|alt=SecureCRT main window]]

UniOTP Credential Provider Agent

2016-08-16T01:12:05Z

Bao:

[[Category:UniOTP_Tools]]

This document details how to install and use the UniOTP Windows Logon Agent, intended for end users who want to use UniOTP authentication to log onto their system. The UniOTP Windows Logon Agent is used to integrate the UniOTP dynamic password authentication system with Windows. There are two versions of the UniOTP Windows Agent: GINA (Windows 2000, XP); and Credential Provider (Windows Vista, 7, Windows Server 2008). Both use two different Windows logon architecture models. This document covers the installation and usage of the Credential Provider agent.

Note: UniOTP MGS Win Logon currently does not work with Windows 7 Home Premium and Pro.

== Installation ==

==== Preparation ====

Before implementing the UniOTP Windows Logon Agent, please verify the following requirements:
* The UniOTP authentication server is already configured and running.
* The administrator has and is already using an active account for the agent on the server
* The aforementioned account has been bound to the UniOTP device used.

==== UniOTP Windows Logon Agent Installation ====

1. Once the UniOTP Windows Distributable Package has been downloaded and installed, find the installation file setup.exe inside the package and double-click it to launch the installation process.

2. Click on Next in the InstallShield Wizard welcome screen.

[[Image:uniotpcp img01.jpg|500px|alt=installation wizard initial screen]]

3. Input your User Name and Company Name and click on Next.

[[Image:uniotpcp img02.jpg|500px|alt=inputting user and company name]]

4. Select Complete and click on Next.

[[Image:uniotpcp img03.jpg|500px|alt=selecting installation type]]

5. Click on Install to begin the installation of the PKI package. After verifying the InstallShield Wizard has completed successfully then click Finish. Once the installation completed, the User Management Tool UniOTPManager will open automatically.

[[Image:uniotpcp img04.jpg|500px|alt=UniOTPManager main window]]

6. '''Important:''' It is strongly advised that a user account is added for this machine at this point. A new user account must be created before exiting this tool. If a functioning user account is not configured and added on the computer, users will '''not''' be able to log into the machine. '''Uninstall the UniOTP Windows Logon Agent immediately if any unresolvable errors appear in the following steps.'''

[[Image:uniotpcp img05.jpg|500px|alt='it is dangerous if you do not add a UniOTP account for this computer' message]]

7. In the UniOTPManager window, click Add to add a UniOTP account to be authenticated with on the computer.

[[Image:uniotpcp img06.jpg|500px|alt=adding new account]]

8. Under the Add Account window, in the fields:
* Account, input a valid UniOTP account name;
* Auth Server, input the IP address of the UniOTP authentication server;
* Port, input the service port of the above server (default is 1812);
* Share, input the shared key (used by the UniOTP authentication server);
* and Max Wait Time, input the number of seconds the computer should wait for the server response.

9. After the account has been added, and any other additional modifications made, click Apply. The Apply button must be clicked to submit and apply user information.

[[Image:uniotpcp img07.jpg|500px|alt=UniOTPManager new account and authentication server added]]

10. The dialog box below will appear if updating account information was successful.

[[Image:uniotpcp img08.jpg|250px|alt='update account information successfully' message]]

11. After successfully installing the UniOTP Windows Authentication Agent and adding a new user, performing a two-factor user logon can be done to ensure all processes are functioning correctly. Choose a user in the account list then click Test to perform an authentication test.

[[Image:uniotpcp img09.jpg|500px|alt=authentication test on a user account]]

12. Input the OTP password generated from the corresponding OTP device (If the authentication method is set to OTP+PIN, input the PIN directly after the OTP password in the same field), then click OK. If the password entered is correct, the following dialog will be displayed.

[[Image:uniotpcp img10.jpg|250px|alt='authenticated successfully' message]]

If the password entered is incorrect, the following dialog will instead be displayed.

[[Image:uniotpcp img11.jpg|250px|alt='authentication failed' message]]

13. A popup message indicating the result of the UniOTP authentication test will appear. If unsuccessful, refer to the displayed message to solve the error. '''Do not log off, switch user, lock, shutdown, reboot, or otherwise interact with Windows user credentials until successfully completing the authentication test. If an encountered error cannot be resolved, please uninstall the UniOTP Windows Logon Agent immediately.''' Failure to do so will result in the user being unable to log back into Windows. It is recommended to uninstall the UniOTP Windows Logon Agent until the error, if present, has been identified and rectified.

14. After verifying the two-factor authentication test has completed successful, the user account is now secured with UniOTP authentication. All user accounts identified with UniOTP require the corresponding OTP to successfully authenticate with the user account. To add additional users, repeat the above steps from step 7.

== Usage ==

[[Image:uniotpcp img12.jpg|750px|alt=Windows user select screen]]

1. In the Windows login screen, select a user to log into with.

[[Image:uniotpcp img13.jpg|750px|alt=Windows user login screen]]

2. In the password field, input the Windows password for the user account to log onto Windows.

3. In the UniOTP Account drop-down list, select the corresponding UniOTP account. In the OTP[PIN] password field, input the generated one-time password (if the authentication method is set to OTP+PIN, by default, input your dynamic password followed by your PIN immediately afterwards in the field. Refer to your administrator as to how OTP+PIN authentication is set up).

4. Press Enter or click the arrow button to authenticate.

If the OTP[PIN] password entered is incorrect, the following error will appear.

[[Image:uniotpcp img14.jpg|750px|alt='error code 13' message]]

If the OTP[PIN] entered is correct, but the Windows user account password is incorrect, the following error message will appear.

[[Image:uniotpcp img15.jpg|750px|alt='incorrect password or username' message]]

If authentication was successful, the Windows user account is secured with UniOTP dynamic password authentication.

== Important Remarks ==

# After installing the UniOTP Windows Authentication Agent, if none of the UniOTP user accounts pass the authentication test, uninstall the UniOTP Windows Authentication Agent '''without delay''', otherwise no user account on the computer will be able to log in.
# If authentication has failed numerous times in succession (, more than five consecutive attempts, refer to the administrator to inspect configuration settings), wait ten minutes before attempting to authenticate again. If authentication is still unsuccessful, refer to the administrator to repair your device.
# Do not modify or delete the "%SYSTEMROOT%\secuagt_cp.conf" file as this is the configuration file for the UniOTP Windows Authentication Agent. Deletion or modification of this file may result in a locked operating system.

Mobile UniOTP Solution

2016-08-16T00:56:31Z

Bao:

[[Category:UniOTP_Integration_Solutions]]
[[Category:UniOTP Mobile Solution]]

== Mobile UniOTP First Launch and Configuration ==

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" |
* This is the screen shown the first time the Mobile UniOTP application is lauched.
* At this step, you must set the password needed to access the application.
* Fill in the fields Password and Confirm Password and tap the Confirm button.
* The next time the application is launched, this password will be requested.
* If you forgot this password, delete and reinstall the application on your device.
* If this is the case, you will need to resynchronize your One Time Password application with the server.
| [[Image:mobotp img01.jpg|270px|alt=Mobile UniOTP login screen]]
|-
| width="50" | '''2'''
| width="400" |
* After setting the application password, you will be redirected automatically to the main screen.
* From the main screen, tap Synchronize at the bottom of the screen to access to the synchronization interface.
| [[Image:mobotp img02.jpg|270px|alt='password set successfully' message]]
|-
| width="50" | '''3'''
| width="400" |
* Select the type of One Time Password from the synchronization interface. You can choose among Event-Based, Time-Based and Challenge/Response.
* Depending on the type of OTP chosen, information needed for synchronization is different. For reasons of security, Mobile UniOTP operates independently from use of network communication. Hence, please communicate to your administrator the information displayed on the screen.
* If you decide to use Mobile UniOTP with OTP MGS, you will need a token file. Please send your synchronization information to [mailto:support@esecutech.com support@esecutech.com] to receive the token file corresponding to your device within 24 hours.
* If you decide to use UniOTP API (included in UniOTP SDK), the information displayed here can be used directly.
| [[Image:mobotp img03.jpg|270px|alt=UniOTP synchronization information]]
|-
| width="50" | '''4'''
| width="400" |
* Once information has been communicated to your administrator, tap Synchronize to apply changes.
* If returning to the main screen without synchronizing, synchronization information will not be saved and the application will not be able to generate correct One Time Passwords. Be sure to tap Synchronize before returning to the main screen.
* A message will be displayed if the synchronization succeeded.
* Every time you open the Synchronization interface, new synchronization information is generated but is only saved if the Synchronize button tapped.
| [[Image:mobotp img04.jpg|270px|alt=synchronized successfully]]
|-
| width="50" | '''5'''
| width="400" |
* Once back to the main screen, tap the icon corresponding to your type of generated OTP to access to the OTP generation interface.
| [[Image:mobotp img05.jpg|270px|alt=OTP generation interface]]
|}

== Event-Based OTP Generation==

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" |
* Each time the Event-Based OTP generation interface is accessed, a new password is automatically generated.
* The Generate button can be tapped to generate a new password.
* ''Note: If you switch back and forth between the main screen and OTP generation screen, or if you generate a new OTP excessively in a short period of time, the OTP application may become desynchronized and would need to be synchronized again.''
| [[Image:mobotp img06.jpg|270px|alt=OTP 699391 being displayed]]
|}

== Time-Based OTP Generation ==

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" |
* In the time-based OTP generation interface, a new password is generated every 60 seconds. Users cannot force the generation of a new password. For every time-based password generated, if 60 seconds have not lapsed, the password will remain the same, and thus only every 60 seconds a new password generated.
* ''Note: If the device time desynchronizes from the server time more than permitted, the device may become desynchronized. Please take note of this, and make sure to not change the time of your device after you have synchronized it with the server.''
| [[Image:mobotp img07.jpg|270px|alt=displaying time-based OTP]]
|}

== Challenge/Response Password Generation ==

{| class="wikitable"
|-
| width="50" | '''1'''
| width="400" |
* In order to generate a OTP using the Challenge and Response system, inputting a challenge code received from the server is required. Authentication will be determined by the correct response generated from the given challenge.

'''Example of Use:'''
* After a user has logged onto a website, the server will display a challenge code to the user, requesting the user to input the corresponding OTP generated from this code. The user inputs the challenge code in the Challenge/Response interface to generate a OTP. This generated response is used to authenticate to the server and, hence, only the correct response can be used to successfully authenticate.
| [[Image:mobotp img08.jpg|270px|alt=Enter challenge received and display current OTP]]
|}

== Other Settings ==

From the Settings screen, you can perform the operations listed below.
* Change the password for accessing the application.
* Display the S/N (Serial Number).
* Display the device time.

[[Image:mobotp img09.jpg|270px|alt=settings screen]]
[[Image:mobotp img10.jpg|270px|alt=change password screen]]

UniOTP GINA Agent

2016-08-16T00:32:49Z

Bao:

[[Category:UniOTP_Tools]]

This document details how to install and use the UniOTP Windows Logon Agent, intended for end users who want to use UniOTP authentication to log onto their system. The UniOTP Windows Logon Agent is used to integrate the UniOTP dynamic password authentication system with Windows. There are two versions of the UniOTP Windows Agent: GINA (Windows 2000, XP); and Credential Provider (Windows Vista, 7, Windows Server 2008). Both use two different Windows login architecture models. This document covers the installation and usage of the GINA agent.

== Installation ==

==== Preparation ====

Before implementing the UniOTP Windows Logon Agent, please verify the following requirements:
* The UniOTP authentication server is already configured and running.
* The administrator has and is already using an active account for the agent on the server
* The aforementioned account has been bound to the UniOTP device used.

==== UniOTP Windows Logon Agent implementation ====

1. Once the UniOTP Windows Distributable Package has been downloaded, locate and execute the installation file "setup.exe" to launch the installation process.

[[Image:GINA img01.jpg|370px|alt=locating setup executable]]

2. Click on Next in the InstallShield Wizard welcome screen.

[[Image:GINA img02.jpg|370px|alt=Install Wizard screen]]

3. Input your User Name and Company Name and click on Next.

[[Image:GINA img03.jpg|370px|alt=input user and company name]]

4. Select Complete and click on Next.

[[Image:GINA img04.jpg|370px|alt=finished WinLogon installation]]

Now that you have finished UniOTP WinLogon Agent installation, you now need to add a UniOTP account. If you try to close this tool without adding an account, you will get the following error message.

[[Image:GINA img05.jpg|370px|alt=error message for not adding an account]]

5. Click the Add button in order to add an account for this computer.

[[Image:GINA img06.jpg|370px|alt=adding new user account]]

Type in a valid UniOTP account name and the dynamic password displayed by UniOTP at this time (If you chose OTP+PIN as your authentication method, you need to input the static PIN just after the dynamic password in this same field). Check that the server address and port are correct and click on OK. If for a certain reason, you failed to add the account, the following message will appear:

[[Image:GINA img07.jpg|370px|alt=failure message]]

If the account was added successfully, you will get the following message (In order to enable the account, don’t forget to click on the Apply button).

[[Image:GINA img08.jpg|370px|alt=success message]]

6. When you finish adding a UniOTP user for this computer, restart the computer and enjoy the dynamic password authentication experience provided by UniOTP.

==== UniOTP Dynamic Password Authentication Experience ====

Once the installation has been completed, restart the computer and try to log on.

1. After restarting, the first thing we see is the usual login screen.

[[Image:GINA img09.jpg|370px|alt=user login window]]

2. After entering username, password and Windows authentication, we also need to provide UniOTP authentication.

[[Image:GINA img10.jpg|370px]]

3. Let’s fill in the username and dynamic password (depending on your settings OTP or OTP+PIN) for the account added in UniOTP management tool and you’ll be able to access the operating system. If username is wrong, you’ll get the following message. If the password is wrong, you’ll be redirected to the Windows Login screen.

[[Image:GINA img11.jpg|370px]]

In safe mode, as the computer uses the local backup of user data to perform the user dynamic authentication, and often the data stored locally is not synchronized with the server, the dynamic password authentication will take a very long time in safe mode. We don’t recommend using safe mode when UniOTP authentication is installed on the computer. The picture below is the UniOTP dynamic password authentication screenshot in safe mode.

[[Image:GINA img12.jpg|370px]]

[[Image:GINA img13.jpg|370px]]

== Important points ==

# When you finish installing UniOTP Windows Authentication Agent, if you cannot pass the authentication test, uninstall the software immediately to avoid being unable to log onto the operating system and the inconvenience brought with it.
# If failing to authenticate consecutively, please wait 10 minutes before attempting to authenticate again, if you still cannot authenticate, you need to ask an administrator to repair your device.
# In safe mode, UniOTP Authentication usually takes a very long time.

UniOTP GINA Agent

2016-08-16T00:32:25Z

Bao:

[[Category:UniOTP_Tools]]

This document details how to install and use the UniOTP Windows Logon Agent, intended for end users who want to use UniOTP authentication to log onto their system. The UniOTP Windows Logon Agent is used to integrate the UniOTP dynamic password authentication system with Windows. There are two versions of the UniOTP Windows Agent: GINA (Windows 2000, XP); and Credential Provider (Windows Vista, 7, Windows Server 2008). Both use two different Windows login architecture models. This document covers the installation and usage of the GINA agent.

== Installation ==

==== Preparation ====

Before implementing the UniOTP Windows Logon Agent, please verify the following requirements:
* The UniOTP authentication server is already configured and running.
* The administrator has and is already using an active account for the agent on the server
* The aforementioned account has been bound to the UniOTP device used.

==== UniOTP Windows Logon Agent implementation ====

1. Once the UniOTP Windows Distributable Package has been downloaded, locate and execute the installation file "setup.exe" to launch the installation process.

[[Image:GINA img01.jpg|370px|alt=locating setup executable]]

2. Click on Next in the InstallShield Wizard welcome screen.

[[Image:GINA img02.jpg|370px|alt=Install Wizard screen]]

3. Input your User Name and Company Name and click on Next.

[[Image:GINA img03.jpg|370px|alt=input user and company name]]

4. Select Complete and click on Next.

[[Image:GINA img04.jpg|370px|alt=finished WinLogon installation]]

Now that you have finished UniOTP WinLogon Agent installation, you now need to add a UniOTP account. If you try to close this tool without adding an account, you will get the following error message.

[[Image:GINA img05.jpg|370px|alt=error message for not adding an account]]

5. Click the Add button in order to add an account for this computer.

[[Image:GINA img06.jpg|370px|alt=adding new user account]]

Type in a valid UniOTP account name and the dynamic password displayed by UniOTP at this time (If you chose OTP+PIN as your authentication method, you need to input the static PIN just after the dynamic password in this same field). Check that the server address and port are correct and click on OK. If for a certain reason, you failed to add the account, the following message will appear:

[[Image:GINA img07.jpg|370px|alt=failure message]]

If the account was added successfully, you will get the following message (In order to enable the account, don’t forget to click on the Apply button).

[[Image:GINA img08.jpg|370px|alt=success message]]

6. When you finish adding a UniOTP user for this computer, restart the computer and enjoy the dynamic password authentication experience provided by UniOTP.

==== UniOTP Dynamic Password Authentication Experience ====

Once the installation has been completed, restart the computer and try to log on.

1. After restarting, the first thing we see is the usual login screen.

[[Image:GINA img09.jpg|370px|alt=user login window]]

2. After entering username, password and Windows authentication, we also need to provide UniOTP authentication.

[[Image:GINA img10.jpg|370px]]

3. Let’s fill in the username and dynamic password (depending on your settings OTP or OTP+PIN) for the account added in UniOTP management tool and you’ll be able to access the operating system. If username is wrong, you’ll get the following message. If the password is wrong, you’ll be redirected to the Windows Login screen.

[[Image:GINA img11.jpg|370px]]

In safe mode, as the computer uses the local backup of user data to perform the user dynamic authentication, and often the data stored locally is not synchronized with the server, the dynamic password authentication will take a very long time in safe mode. We don’t recommend using safe mode when UniOTP authentication is installed on the computer. The picture below is the UniOTP dynamic password authentication screenshot in safe mode.

[[Image:GINA img12.jpg|370px]]

[[Image:GINA img13.jpg|370px]]

== Important points ==

1. When you finish installing UniOTP Windows Authentication Agent, if you cannot pass the authentication test, uninstall the software immediately to avoid being unable to log onto the operating system and the inconvenience brought with it.
2. If failing to authenticate consecutively, please wait 10 minutes before attempting to authenticate again, if you still cannot authenticate, you need to ask an administrator to repair your device.
3. In safe mode, UniOTP Authentication usually takes a very long time.

UniToken WebAuthentication Init Tool

2016-08-16T00:15:16Z

Bao:

[[Category:UniToken_Tools]]

== About This Guide ==

UniToken Init is a graphical user interface (GUI) tool that assists software developers to configure UniToken parameters for web use.

== UniToken Init ==

Note: Please select the appropriate UniToken Init application according to your server-side scripting language. At present, UniToken supports ASP, ASP.NET and PHP. Launching the UniToken Init application, will bring up the window below.

[[Image:unitokeninit img01.jpg|370px|alt=UniToken Init login window]]

* Enter the User ID in UserID (less than 16 characters).
* Check the Auto check-box to automatically generate credentials, otherwise define the credentials in Credential.
* Enter the User PIN used by users to log onto the UniToken Pro token in UserPIN, or check the Default check-box for the factory default User PIN "user", without quotation marks.
* Enter the URL of the server in Server URL.

The UniToken Init tool can also be used to change a User's PIN. To do so, check the Change User PIN check-box, and enter the new user PIN twice to confirm. Click the Burn button to begin applying changes to the UniToken.

[[Image:unitokeninit img02.jpg|270px|alt='succesfully burned the UniToken' message]]

You have burnt your UniToken successfully if you see the above pop-up window. An insert SQL command will be added into the ImportSql.sql file which is in the same folder where UniToken Init tool is located. Open this file with a text editor, and you can add new records into the SQL database used to store user information. For more information, please refer to the Video Tutorial Guides.

UniToken WebAuthentication Daemon Tool

2016-08-16T00:10:23Z

Bao:

[[Category:UniToken_Tools]]

The UniToken Daemon tool is a GUI application run on the users' computer, and provides functions including logging onto the token, modifying settings and resetting user passwords. This tool is distributed together with UniToken PRO to users.

== Launching the UniToken Daemon Tool ==

After launching the UniToken Daemon tool, the User Logon window below will appear.

[[Image:unitokendaemon img01.jpg|370px|alt=UniToken Daemon Tool login window]]

Enter the User PIN to log onto the device. '''Note:''' The User ID displayed in the above window is the UniToken ID. If logging onto the UniToken device was successful, an icon will appear in the notification area.

== Assign an Internet Browser for use by UniToken ==

In the System Settings tab, select the browser you would like to use, then click Apply.

[[Image:unitokendaemon img02.jpg|370px|alt=UniToken System Settings, choosing a browser]]

== Reset User PIN ==

In the Change PIN tab, input fields Old PIN, New PIN and Confirm respectively. Click Submit to reset the User PIN.

[[Image:unitokendaemon img03.jpg|370px|alt=UniToken Daemon changing PIN]]

If resetting the User's PIN was successful, this message will appear.

[[Image:unitokendaemon img04.jpg|250px|alt='new password successfully set']]

UniToken FAQ

2016-08-16T00:03:46Z

Bao:

[[category:UniToken FAQ]]
== General ==

=== What is UniToken? ===

UniToken is a USB two-factor authentication token. UniToken utilizes PKI technology, and can be employed for user authentication for [[:Category:UniKey_Application_Solutions|a variety of applications]].

=== What is UniToken's three level password system? ===

To log onto a UniToken device, a PIN (Personal Identification Number; note that the PIN used is not restricted to solely numbers) is used for user management on the device. UniToken implements three separate levels of security, each using separate passwords for the different permission levels. Below is a list of the user permissions on UniToken, from lowest to highest:

* Without Login: Guest permissions
* User Login: User permissions ('user')
* Admin Login: Administrator permissions ('admin')

=== What is UniToken's secure file system? ===

The UniToken Secure File System allows the management of files to be utilized by the three-level permission system. Operations on files with certain restrictions require certain permissions. There are three different levels of file permissions:

* Guest: All users are able to read the file. Only Users and Admins can modify the file.
* User: Guests cannot read the file. Users and Admins can read and modify the file.
* Admin: Only Admins can read and write to the file.

<table class="wikitable">
<tr>
<td colspan="2" rowspan="2"></td>
<th colspan="3">User Actions</th>
</tr>
<tr>
<th>Guest</th>
<th>User</th>
<th>Admin</th>
</tr>
<tr>
<th rowspan="3">File Permission</th>
<th>Guest</th>
<td>Read</td>
<td>Read/Write</td>
<td>Read/Write</td>
</tr>
<tr>
<th>User</th>
<td>None</td>
<td>Read/Write</td>
<td>Read/Write</td>
</tr>
<tr>
<th>Admin</th>
<td>None</td>
<td>None</td>
<td>Read/Write</td>
</table>

=== What is UniToken's auto-lock feature? ===

UniToken's auto-lock feature automatically locks the device to prevent any further log in attempts as a security measure after an incorrect PIN has been entered in succession more than the "Maximal Attempt Times" number.

=== Can I use UniToken for smart card authentication? ===

Yes. Installing the PKI redistribution package allows you to perform Windows Smart Card Authentication with UniToken. Please see the appropriate documentation.

=== How many digital certificates can be stored in a single UniToken device? ===

Digital certificates are securely stored in what is known as a certificate container. Generally speaking, a single UniToken device can store up to two certificates in its certificate container.

=== What are the differences between the UniToken models? ===

Please see [http://www.esecutech.com/usb-authentication/unitoken-compare-features.html UniToken Compare Features].

=== How can I begin using UniToken? ===

Please see the [https://files.esecutech.com/marketing-materials/ProductsDoc/UniToken/UniToken_quickstart-130827EN.pdf UniToken Quick Start Guide].

=== What is the default Administrator and User PIN? ===

The factory default PIN for Administrator is "admin", and the default for User is "user".

=== Where can I receive resources or assistance? ===

Please see [[#Additional resources|Additional resources]].

== Hardware ==

=== What does "driverless" mean? ===

The UniToken authentication dongle is driverless, meaning UniToken requires no installation of drivers or additional software. Supported operating systems already possess the drivers needed by UniToken to operate and are automatically installed upon the first connection of the UniToken device, significantly reducing the problems associated with driver-dependent devices.

=== What steps does SecuTech take to ensure UniToken is environmentally sustainable? ===

SecuTech is committed to supplying products that are environmentally friendly. All parts and production processes of UniToken are lead-free and ROHS-compliant.

== Development ==

=== Which redistribution package should I use? ===

For full PKI application support, please install the developer’s package which provides support for PKCS#11 and MS-CAPI. For non-PKI application support, please install the end user’s package which enables UniToken API support.

=== What programming interfaces does UniToken support? ===

UniToken supports three sets of APIs: PKCS#11, MS-CAPI, and UniToken APIs.

=== What encryption algorithms does UniToken support? ===

UniToken supports RSA, 3DES, AES encryption algorithms and MD5 and SHA-1 hashing algorithms.

== Troubleshooting ==

=== What does the light on the UniToken dongle indicate? ===

The UniToken Status Indicator Light is the LED light on the UniToken device which displays the status of the device. If the LED light on the UniToken device is continually on, it is recognized by the computer and should be functioning correctly. If the LED light on the UniToken device is flashing, then the UniToken device has not been recognized by the computer. If this is the case, reconnect the UniToken device to the computer, otherwise contact SecuTech Technical Support at https://www.esecutech.com/support or [mailto:support@eSecuTech.com support@esecutech.com].

=== My UniToken device is locked. What should I do? ===

If the UniToken device has locked itself, only the Administrator can unlock the device. To do so, the Administrator must log in and unlock the device through the Unlock button, found under User.

== Additional resources ==

=== Where can I receive further assistance? ===

We, at SecuTech, are dedicated to providing high-quality technical support to our customers. If you have any questions, please feel free to contact us at https://www.esecutech.com/support or [mailto:support@eSecuTech.com support@esecutech.com].