API C# class

The SAS authentication API is represented by a single C# class named BSIDAPI.

This class includes the following:

• A default constructor that loads its configuration information from a default registry location.
• An alternate constructor that allows the user to define an alternate location in the registry from which to load its configuration.

The API can be configured manually or through the Manager User Interface.

Constructors

The following constructor is used to read the registry key defined by the ConnectionInformation string.

BSIDAPI()
{
    // reads registry SOFTWARE\Thales\BSIDAPI
}

BSIDAPI(string ConnectionInformation)
{
    // reads registry key defined by ConnectionInformation
}

Methods

Authenticate method

All actions related to authentication make use of a single API call:

Authenticate
(
    string user,
    string org,
    string ipaddress,
    string passcode,
    ref string challenge,
    ref string state
);

Where:

• user — A string representing the user name of the individual who is authenticating.
• org — A string representing the organization to which the individual who is authenticating belongs. This should be passed as an empty string to represent the default organization.
• ipaddress — A string representing the IP address from which the authentication request originated. If this parameter is an empty string, the SAS will attempt to auto-detect it.
• passcode — A string representing the user's passcode, in one of the following formats:
  • [PIN+OTP] — For server-side PIN authentication
  • [OTP] — Token-side PIN or no PIN
  • [PIN] — When responding to a server-side change request for a user-changeable PIN
  • [StaticPassword] — User has a static password enabled or is responding to a static password change
  • [null] — Indicates that a challenge is required
• challenge — A string passed by reference that may be populated with a challenge, PIN change, or outer window authentication message.
• state — A string passed by reference that contains a state attribute. When returning a challenge, the same state must be passed back to the server.

The API call returns the following values:

VerifySignature method

This method verifies the token's signature for a given hash.

VerifySignature
(
    string SerialNumber,
    string Hash,
    string Signature
);

Where:

• SerialNumber — A string representing the token's serial number.
• Hash — A string representing the hash value for the signature verification.
• Signature — A string representing the signature to be verified for the given hash.

The method returns the following values:

CheckServerStatus method

This method monitors the operational status of the SAS authentication server.

CheckServerStatus
(
    // void
);

The method returns the following values:

getGridSureImageAsBase64 method

This method creates a Base64 encoded Bitmap (BMP) image based on the incoming challenge parameter.

getGridSureImageAsBase64
(
    string inChallenge,
    ref string outBase64EncodedBitmap,
    ref string outErrorMessage
);

Where:

• inChallenge — A string representing a GrID challenge returned from the Authenticate method of length 25, 36, 47, or 64.
• outBase64EncodedBitmap — An output string representing the Base64 encoded bitmap GrID image.
• outErrorMessage — An output string containing a detailed error message.

The method returns the following values:

getGridSureImage method

This method creates a Bitmap (BMP) image based on the incoming challenge parameter.

getGridSureImage
(
    string inChallenge,
    ref System.Drawing.Image outBitmap,
    ref string outErrorMessage
);

Where:

• inChallenge — A string representing a GrID challenge returned from the Authenticate method of length 25, 36, 47, or 64.
• outBitmap — An output string representing the Bitmap GrID image.
• outErrorMessage — An output string containing a detailed error message.

The method returns the following values:

SSL server certificate validation

SSL server certificate validation is enabled by default. To disable it, set the EnableSSLCertificateValidation registry value to 0 under HKEY_LOCAL_MACHINE\SOFTWARE\Thales\BSIDAPI. Set the value to 1 to enable it.

To define custom certificate validation logic, use the ServerCertificateValidationCallback property, as shown in the following sample:

ServicePointManager.ServerCertificateValidationCallback = {delegate function}

For more details, visit the following links:

• https://msdn.microsoft.com/en-us/library/ms144153%28v=vs.110%29.aspx
• https://msdn.microsoft.com/en-us/library/system.net.security.remotecertificatevalidationcallback%28v=vs.110%29.aspx