UniOTP Server APIs

How to use C/C++

Preparation

1. 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.

2. 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.

3. Once you finish preparing the database, create an ODBC data source for this newly created database.(Use the database prepared in step 2).

4. 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

1. Add the Server SDK library files (dynamic or static library) and its header files (otp_corec32.h) to the project.

2. 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 )

3. Use API introduced later in this document to perform operations related to authentication.

SDK Operation procedure and Important points

Operation procedure
1. Use the API secuotp_initenv(char *pszConfpath) to initialize the SDK Settings information.

2. Use other interface to complete business related treatments.

3. 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
1. The function secuotp_initenv(char *pszConfpath) is used to initialize settings information, when using the SDK, you only need to call the function once.

2. Once you finish using UniOTP SDK, call the secuotp_cleanup() function to perform cleaning operations.

3. 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.

4. 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.

5. 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

int  secuotp_initenv(char *pszConfpath);

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

int secuotp_cleanup();

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

unsigned long secuotp_getlasterror(); 

Description

Get last error code

Parameters:

None

Return value:

Code of the last error that happened.

API:SECUOTP_AUTH()

Prototype

int secuotp_auth(char *pszUsername, char *pszPwd, unsigned int *pChallenge);

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

int secuotp_synchronize(char *pszUsername, char *pszOtp1, char *pszOtp2);

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

int secuotp_setuserpin(char *pszUsername, char *pszPin); 

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

int secuotp_resetpin(char *pszUsername, char *pszOldpin, char *pszNewpin);

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

int secuotp_setauthtype(char *pszUsername, int nAuthtype);

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

int secuotp_adduser(char *pszUsername, char *pszUserid,  char 
*pszContacttel, char *pszSerialnum, char *pszRemark, char *pszEmail, 
char *pszDomain, char *pszPin, char *pszPreusedate, int nAuthtype);

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

int secuotp_deleteuser(char *pszUsername);

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

int secuotp_setuserinvalid(char *pszUsername, int nvalid);

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

int secuotp_setuserlock(char *pszUsername, int nlock);

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

void secuotp_free(void **psbuf)

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

int secuotp_tokenimport(char *pszTokenfile, char *pszSecret, char 
**pstrErrinfo);

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

int secuotp_userimport(char *pszUserfile, char *pszSecret, char 
**pstrErrinfo); 

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

int secuotp_tokendelete(char *pszTokenserialnum);

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

int secuotp_makelog(int nLoglev, char *pszOperator,  int  nOptype,  
char *pszContent, char *pszSrvip);

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

int secuotp_rebind(const char *pszUsername, const char *pszNewserialnum);

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