Defender 5.8 - Administrator Guide

Table 13. Properties
Property	Description
challengeMessage property	The prompt or message to be displayed to the user in response to the previous request.
sessionID property	The RADIUS session ID attribute.
timeout property	The number of seconds which the client program should wait for a response from the server.

Authenticate method

Submits a RADIUS request to the Defender Security Server and waits for a response. Typically, the Authenticate method would be invoked in a loop, whereby the current value of challengeMessage is displayed to the user, and the response from the user is supplied as the authData parameter on the next call to the Authenticate method. This would continue until the user chooses to cancel, or until the return code is not 1. If any request takes more than timeout seconds to complete, the method returns code -106.

C++ syntax
public : HRESULT Authenticate(BSTR userID, BSTR authData, LONG timeout, BSTR ipAddress, LONG port, BSTR sharedSecret, LONG* returnCode );

C# syntax
int Authenticate(string userID, string authData, int timeout, string ipAddress, int port, string sharedSecret);

Parameters

•

userID The username of the user to be authenticated. Maximum length is 255 characters.

•

authData The information which authenticates this user, such as a password or token response, typically entered by the user. You should set the value of this parameter in response to the current value of challengeMessage. Maximum length is 64 characters.

•

timeout The number of seconds before the request should be abandoned.

•

ipAddress The IP address of the Defender Security Server in “dotted decimal” format.

•

port The port number which the Defender Security Server is listening on for this client (Access Node).

•

sharedSecret This value is used to encrypt communications between the client program and the Defender Security Server. The value supplied here must match that defined in the Defender Access Node object for this client. See the Defender Installation and Administration Guide for further information on configuring Defender. Maximum length is 64 characters.

Return value

•

0 Authentication successful.

•

1 More information required to complete authentication.

•

2 Access denied.

•

-102 Unable to establish communications environment.

•

-103 API not supported on this platform.

•

-105 Unable to establish session with Defender Security Server.

•

-106 Unable to send request to Defender Security Server.

•

-107 Defender Security Server did not respond.

challengeMessage property

Displays the value of the challenge message to the user after each invocation of the Authenticate method.

C++ syntax
public : HRESULT get_challengeMessage(BSTR * bstrDefenderMessage);

C# syntax
public string challengeMessage { get; }

sessionID property

Holds the session attribute for the current session. Defender handles up to 255 concurrent sessions. This value is for information only and should not be set by the calling program.

C++ syntax
public : HRESULT get_sessionID(LONG * sessionID);

C# syntax
public int sessionID { get; }

timeout property

Holds the timeout value for the current session. This value is for information only and should not be set by the calling program. the timeout value is set using the timeout parameter on each call to the Authenticate method.

C++ syntax
public : HRESULT get_timeout(LONG timeoutValue);

C# syntax
public int timeout { get; }

IAuthenticator2 and IAuthenticator3 interfaces

Table 14. Properties
Property	Description
challengeMessageId property	The ID of the message to be displayed to the user in response to the previous request.
challengeMessageData property	Any variable data contained in the message to be displayed to the user in response to the previous request.

challengeMessageId property

Provides a numeric equivalent of the message to be displayed to the user after each invocation of the Authenticate method. This value could be used to lookup localized messages.

C++ syntax
public : HRESULT get_challengeMessageId(LONG * messageId);

C# syntax
public string challengeMessageId { get; }

challengeMessageData property

Provides any variable data contained in the message to be displayed to the user after each invocation of the Authenticate method.

C++ syntax
public : HRESULT get_challengeMessageData(BSTR * messageData);

C# syntax
public string challengeMessageData { get; }

IAuthenticator3 interface

Table 15. Methods
Method	Description
AddPayload method	Allows RADIUS payload attributes to be added to the authentication request.
GetGridData method	Gets the raw data used to construct the GrIDsure grid.
GetAuthenticationImage method	Returns the GrIDsure grid as a byte array containing a bitmap.
SetGridResetPIPAttribute method	Adds a RADIUS payload attributes to the authentication request indicating that the GrIDsure PIP should be reset.

Table 16. Properties
Property	Description
payload property	Gets an array of any RADIUS payload attributes returned in response to the previous request.
grIDsureMessage property	The GrIDsure specific message to be displayed to the user in response to the previous request.
grIDsureGridType property	The type of GrIDsure grid to be displayed.

AddPayload method

Allows RADIUS payload attributes to be added to the authentication request. Typically this method is used when the authenticating server or an intermediary requires additional information about the authenticating party.

The structure used to pass data to this function is defined below:

struct RADIUSPayloadAttribute

{

DWORD vendorId;

unsigned char type;

unsigned char length;

unsigned char data[253];

};

C++ syntax
public : HRESULT AddPayload(struct RADIUSPayloadAttribute *payload)

C# syntax
void AddPayload(ref RADIUSPayloadAttribute payload);

Parameters

payload Application specific payload data as a struct RADIUSPayloadAttribute.

Return value

Always returns S_OK.

GetGridData method

After an authentication request this method can be called to determine whether a user has a grid available and the state of that grid.

C++ syntax
public : HRESULT GetGridData(BSTR *grid, VARIANT_BOOL *isRegistrationGrid, VARIANT_BOOL *isGrIDsureOnly, VARIANT_BOOL *hasGrid);

C# syntax
bool GetGridData(out string grid, out bool isRegistrationGrid, out bool isGrIDsureOnly);

Parameters

•

grid A string containing the values for the grid.

•

isRegistrationGrid Returns TRUE if the user has not yet registered a PIP.

•

isGrIDsureOnly Returns TRUE if the user only has a GrIDsure token.

•

hasGrid Returns TRUE if a grid is available.

Return value

Always returns S_OK.

GetAuthenticationImage method

After an authentication request this function can be called to obtain a bitmap of the grid.

C++ syntax
public : HRESULT GetAuthenticationImage(VARIANT *imageData);

C# syntax
object GetAuthenticationImage();

Parameters

imageData A byte array containing a bitmap of the grid.

Return value

Returns S_OK if successful.

SetGridResetPIPAttribute method

Call this function before an authentication request to add a RADIUS payload attribute to inform the DSS that the user's GrIDsure PIP should be changed.

C++ syntax
public : HRESULT SetGridResetPIPAttribute(void);

C# syntax
void SetGridResetPIPAttribute();

After an authentication request this property will return an array of RADIUS payload attributes returned by the DSS. Each payload attribute will be returned as a struct RADIUSPayloadAttribute.

C++ syntax
public : HRESULT get_payload(SAFEARRAY(struct RADIUSPayloadAttribute) * payload);

C# syntax
public Array payload { get; }

grIDsureMessage property

After an authentication request this property will return the GrIDsure challenge.

C++ syntax
public : HRESULT get_grIDsureMessage(BSTR *message);

C# syntax
public string grIDsureMessage { get; }

grIDsureGridType property

After an authentication request this property will return the type of grid.

C++ syntax
public : HRESULT get_grIDsureGridType(LONG* gridType);

C# syntax
public int grIDsureGridType { get; }

Return value

•

0x00800000 The user has no grid.

•

0x01000000 The user has a registered grid.

•

0x02000000 The user has a grid but no PIP has been registered.

•

0x04000000 The user has a grid and the PIP has expired.

•

0x80000000 The user has a grid and they have expired the PIP.

IAuthInfo interface

Table 17. Properties
Property	Description
userIdType property	A value representing the type of user name expected for authentications through a Defender Access Node.
isUserDefenderAuthenticated property	Determines whether a user is to be Defender authenticated through a Defender Security Server and Defender Access Node.