UniOTP Agent APIs

Chapter 1: C/C++

Installation and usage

1. Please copy the Securepass_auth.h header file and the radclt.lib library file into your project.
2. Please perform authentication through the SecuAuth interface. For detailed instructions, please see the demo project.

How to integrate with the C++ environment

1. Please add the RadiusClt1.h header file and radclt.lib library file to the project.
2. When you need to perform authentication, instantiate the RadiusClt class.
3. Use the initrad member function inside the RadiusClt class to initialize authentication information.
4. 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

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*/
);

Parameters

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

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

1. Please add the UniOTP_Clt.dll dynamic library to your project.
2. Instantiate the SecuRadClts_Client constructor class in your source code where you want to authenticate the user.
3. 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

SecuRadClts_Client (
    string Server,
    string SharedSecret,
    string Username,
    string Password,
    int nport
);

Description

Class object instantiation, completes the initialization process

Parameters

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

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

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

1. Add the secuotp_jradiust.jar file inside your project.
2. When you need to authenticate, Use RadientClient to create a client instance.
3. Use “authenticate” to complete the authentication.

For further details about the source code, please see the sample folder.

API: RadiusCLIENT()

Prototype

RadiusClient (
    String hostname,
    String sharedSecret,
    String username
);

Description

Create an object from the RadiusClient class

Parameters

Parameters	Description
String hostname	Authentication server address
String shareSecret	Shared key
String username	Username for user waiting to be authenticated

Prototype 2

RadiusClient (
    String hostname,
    int authPort,
    String sharedSecret,
    String username
);

Parameters

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

RadiusClient (
    String hostname,
    int authPort,
    String sharedSecret,
    String userName,
    int sockTimeout
);

Description

Create an object from the RadiusClient class.

Parameters

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

int authenticate (
    String userPass
);

Description

Perform authentication

Parameters

Parameters	Description
Sting userPass	User authentication password for this time (OTP only or OTP + PIN)

Return Value

Return Value	Description
ACCESS_ACCEPT	Authentication succeeded
ACCESS_REJECT	Authentication failed
ACCESS_CHALLENGE	The server sent challenge information

API: GETCHALLENGEMESSAGE()

Prototype

String getChallengeMessage();

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

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

1. Copy the 2 files, radius.class.php and radius_config.php into the project directory.
2. Change the radius_config.php file contents so that it matches your authentication server parameters.
3. When you need to authenticate, create an instance of Radius class
4. 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:

Radius (
    $ip_radius_server = '127.0.0.1',
    $shared_secret = <i>, </i>
    $udp_timeout = 5,
    $authentication_port = 1812
);

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

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

AccessRequest (
    $username = <i>, </i>
    $password = <i>, </i>
    $udp_timeout = 0
);

Description

Perform user authentication

Parameters

Parameters	Description
$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

Return Value	Description
ACCESS_ACCEPT	Authentication succeeded
ACCESS_REJECT	Authentication failed
ACCESS_CHALLENGE	Challenge sent by the authentication server for this time’s authentication

API: GETCHALLENGEMSG()

Prototype

GetChallengeMsg();

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

GetLastError();

Description

Get information about last error

Parameters

N/A

Return Value

Character string, last abnormal error message

API:CLEARLASTERROR()

Prototype

ClearLastError();

Description

Clears error information

Parameters

N/A

Return Value

N/A

Static data definition

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