OCRA Bean

Properties Methods Events Configuration Settings Errors

The OCRA component implements the OATH Challenge-Response Algorithm.

Syntax

IPWorksAuth.Ocra

Remarks

The OCRA component provides a simple way to create challenges, calculate responses, and verify responses using the OATH Challenge-Response Algorithm.

The first step to using the component is creating the Challenge and generating the OCRASuite. This is done by calling the CreateChallenge method. After creating the Challenge and OCRASuite these values are sent to the other party.

When receiving a challenge and OCRASuite the component is use to calculate a response. Set OCRASuite, Challenge, and any other required properties and call CalculateResponse to calculate the Response. Send the Response back to the original party for verification.

After receiving the verification set Challenge, OCRASuite, and Response and call VerifyResponse. VerifyResponse returns True if the response is verified, False otherwise.

Creating the Challenge

The CreateChallenge method creates a Challenge. After calling this method the Challenge property will be populated with the created value.

When ChallengeType is set to ctRandom the following properties are applicable:

When ChallengeType is set to ctSignature the following properties are applicable:

In addition to creating the Challenge this method will also create the OCRASuite which defines parameters required by the other party to calculate a response. The following properties are applicable to OCRASuite creation:

Calculating the Response

CalculateResponse calculates Response to the given Challenge.

Before calling this method set OCRASuite to the suite obtained from the other party and set Challenge to the received challenge.

After setting OCRASuite the following properties are populated, which provide requirements for the response:

Inspect these properties to determine the requirements and provide any required values such as Counter or Password. Set Key to the key used during the HMAC computation. Set Challenge to the received challenge.

Call this method to calculate the response. After calling this method the Response property is populated. The response may then be transmitted to the other party for verification.

The following properties are applicable when calling this method:

Verifying the Response

VerifyResponse verifies the response and returns True or False depending on the result.

Before calling this method set OCRASuite, Challenge, and Response.

After setting OCRASuite the following properties are populated, which provide requirements for the response:

These properties may be inspected to determine the requirements. Provide any required values such as Counter or Password. Set Challenge to the original challenge that was issued. Set Response to the received response. Set Key to the key used during the HMAC computation.

Call this method to verify the response. The method will return True if the verification was successful, False otherwise.

The following properties are applicable when calling this method:

Random Challenge Example

//First create the challenge on machine A
Ocra ocra = new Ocra();
ocra.ChallengeType = OcraChallengeTypes.ctRandom;
ocra.ChallengeLength = 10;
ocra.ChallengeFormat = OcraChallengeFormats.cfNumeric;
ocra.CreateChallenge();

string challenge = ocra.Challenge; //Value like "3891592139"
string ocraSuite = ocra.OCRASuite; //Value "OCRA-1:HOTP-SHA1-6:QN10"
//Send Challenge and OCRASuite to Machine B

//Upon receiving the challenge on Machine B, calculate a response
ocra = new Ocra();
ocra.OCRASuite = ocraSuite; //Received from other party
ocra.Challenge = challenge; //Received from other party
ocra.Key = "shared secret key";
ocra.CalculateResponse();

string response = ocra.Response; //Value like "574464"
//Send Response back to Machine A

//Upon receiving the response on Machine A, verify it
ocra = new Ocra();
ocra.OCRASuite = ocraSuite; //Original OCRASuite saved before sending the original challenge
ocra.Challenge = challenge; //Original challenge that was sent
ocra.Response = response;   //Received from other party
ocra.Key = "shared secret key";

bool isValid = ocra.VerifyResponse(); //Returns True if verified

Signature Challenge Example

//First create the challenge on machine A
Ocra ocra = new Ocra();
ocra.ChallengeType = OcraChallengeTypes.ctSignature;
ocra.ChallengeInput = "test input";
ocra.Key = "signature key";
ocra.ChallengeFormat = OcraChallengeFormats.cfHex;
ocra.CreateChallenge();

string challenge = ocra.Challenge; //Value like "973131F0"
string ocraSuite = ocra.OCRASuite; //Value "OCRA-1:HOTP-SHA1-6:QH08"
//Send Challenge and OCRASuite to Machine B

//Upon receiving the challenge on Machine B, calculate a response
ocra = new Ocra();
ocra.OCRASuite = ocraSuite; //Received from other party
ocra.Challenge = challenge; //Received from other party
ocra.Key = "shared secret key";
ocra.CalculateResponse();

string response = ocra.Response; //Value like "574464"
//Send Response back to Machine A

//Upon receiving the response on Machine A, verify it
ocra = new Ocra();
ocra.OCRASuite = ocraSuite; //Original OCRASuite saved before sending the original challenge
ocra.Challenge = challenge; //Original challenge that was sent
ocra.Response = response;   //Received from other party
ocra.Key = "shared secret key";

bool isValid = ocra.VerifyResponse(); //Returns True if verified

Property List

The following is the full list of the properties of the bean with short descriptions. Click on the links for further details.


Challenge	The challenge value.
ChallengeFormat	The format in which the challenge will be created.
ChallengeInput	The input for the signature challenge.
ChallengeLength	The challenge length.
ChallengeType	The challenge type.
Counter	The counter.
HashAlgorithm	The HMAC Hash Algorithm.
Key	The secret key.
OCRASuite	The OCRASuite defines parameters about the challenge and response.
Password	The password.
RequireCounter	Whether a Counter value is required to create the response.
RequirePassword	Whether a Password is required to create the response.
RequireTimeStamp	Whether a TimeStamp is required to create the response.
Response	The OCRA response.
ResponseLength	Defines the length of the response.

Method List

The following is the full list of the methods of the bean with short descriptions. Click on the links for further details.


calculateResponse	This method calculates the response to the given challenge.
config	Sets or retrieves a configuration setting .
createChallenge	Creates the challenge.
reset	Reset the variables to default value.
verifyResponse	This method verifies the response.

Event List

The following is the full list of the events fired by the bean with short descriptions. Click on the links for further details.


Error	Information about errors during data delivery.

Configuration Settings

The following is a list of configuration settings for the bean with short descriptions. Click on the links for further details.


CounterHex	The counter value as a hexadecimal string.
PasswordHashAlgorithm	The password hash algorithm.
TimeStepSize	The time step.
TimeStepUnit	The time step unit.
CurrentTime	The current time in milliseconds.
RequireSessionInfo	Whether to use session information.
SessionInfoLength	The length of the session information.
SessionInfo	The session information.
CodePage	The system code page used for Unicode to Multibyte translations.