UniOTP Agent APIs

From SecuTech Wiki
Jump to: navigation, search


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