SwivelAuthClient Documentation

Overview

Class name: SwivelAuthClient

Namespace: swivelsecure.client

This class provides convenient access to the authentication service of a Swivel server. It is essentially a wrapper around the XML-based AgentXML API.

Typically, when using this class within an ASP.Net application, you can use the default constructor to create a new instance of this class. This will read settings from web.config, which should have been previously configured as described in the overview document.

Constructors

SwivelAuthClient()

Constructor which reads settings from web.config

SwivelAuthClient(SwivelSettings settings)

Constructor with pre-defined settings
settings: The settings for this client

Methods

bool Ping()

Tests basic PINsafe functionality. Doesn't check if the caller is a valid PINsafe Agent.
Returns True if PINsafe is available and working.

bool UserExists(string username)

Check whether a user exists or not.
username: The username to check
Returns True if the user exists in the Swivel database

string StartSession(string username)

Starts a new single channel session with the PINsafe server.
The returned session ID can subsequently be used to generate a TURing image within a limited time period.
Depending on the Swivel server settings, it is possible to request a TURing image for the user directly, without starting a session explicitly.
username: The username for the user.
Returns Session ID for the started session, or an empty string if an error occurred or the user does not exist.

bool Login(string username, string password, string OTC)

Perform an authentication with the Swivel server.
username: The username of the user.
password: The Swivel password of the user. This will typically be an empty string (not null), unless you have explicitly set a Swivel password.
OTC: The user's one-time code.
Returns True if authentication succeeded.

bool ChangePin(string username, string password, string newPassword, string OTC, string newOTC)

Perform a PIN or password change with the Swivel server.
username: The username of the user.
password: The current Swivel password of the user.
    This will typically be an empty string (not null), unless you have explicitly set a Swivel password.
newPassword: The new password. Empty string if the password is not required.
OTC: The user's one-time code, based on the current PIN.
    Note that this is the OTC according to the PINsafe protocol, NOT the PIN.
newOTC: The one-time code, based on the new PIN. This should use the same security string as the old one-time code.

string SendRequestXml(string xml)

Send an arbitrary AgentXML request to the Swivel server. This is provided to allow for future expansion.
Typically, you will not need to use this method directly.
xml: The XML request, according to the AgentXML protocol.
Returns The XML response from the server, or an empty string if an error occurred

Image GetImage(string sessionID, string username, out int status)

Request a TURing image from PINsafe.
The image can be requested using a previously-requested session ID or a username.
Using session ID is more secure, since session IDs can only be requested by valid Agents.
However, if image request by username is enabled in PINsafe, direct request by username is quicker, as only one request is required.
sessionID: A session ID previously requested from the Swivel server (can be null)
username: The username for which the image is to be generated (ignored if sessionID is not null or empty)
status: Returns the HTTP status code returned by the Swivel server
Returns A TURing image for the specified session ID or username as a System.Drawing.Image object.
Typically, this method must be called from a dedicated aspx file, which is specified as the src attribute of an img object.
The example client gives an example of this in Image.aspx and Image.aspx.cs.

Image GetMessage(string sessionID, string username, out int status)

Request an on-demand security string from PINsafe.
The message can be requested using a previously-requested session ID or a username.
Request by session ID is only valid if on-demand authentication is enabled in PINsafe.
In this case, the security string is only valid for a limited time. If on-demand delivery is enabled,
the security string is valid indefinitely, but must be requested by username.
Using session ID is more secure, since session IDs can only be requested by valid Agents.
However, if image request by username is enabled in PINsafe, direct request by username is quicker,
as only one request is required.
sessionID: A session ID previously requested from the Swivel server (can be null)
username: The username for which the image is to be generated (ignored if sessionID is not null or empty)
status: Returns the HTTP status code returned by the Swivel server
Returns An image with the word "CONFIRMED" (the message can be altered).
As for GetImage, this method is typically called from a dedicated aspx file.
An example of this is not given, but the GetImage example can easily be altered to use GetMessage.

Properties

Most of the properties here are read-only, and they simply return the value found in the loaded settings. Exceptions to this are noted.

bool SSL

True if HTTPS should be used to communicate with Swivel Server, false if HTTP should be used.
(Note that the naming is inconsistent with the corresponding SwivelSettings property).

string Server

The host name or IP address of the Swivel Server.

int Port

The port used by the Swivel Server.

string Context

The Swivel server context.

string Secret

The shared secret used when communicating with the Swivel Server.

bool AcceptSelfSigned

True if SSL certificate errors should be ignored when communicating with the Swivel Server.

bool AllowNonPINsafeUsers

True if usernames not recognised by Swivel server should be authenticated automatically.
If false, unknown users will be rejected.

string Address

The URL of the servlet used to access the Swivel server for AgentXML calls.
This is build on-the-fly from the settings, with "/AgentXML" appended.

string Error

The error message returned by the last request to the Swivel server. Can be set manually.

string[] Warnings

An array of warnings returned by the last request to the Swivel server.
Typically this indicates whether a PIN change is required soon.

string Request

The last XML request sent to the Swivel server.

string Response

The last XML response received from the Swivel server.