UniOTP Agent APIs

From SecuTech Wiki
Revision as of 17:23, 31 July 2012 by Joseph (talk | contribs)
Jump to navigationJump to 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
 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 shows
that 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



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