OCRA Class

Properties Methods Events Configuration Settings Errors

The OCRA class implements the OATH Challenge-Response Algorithm.

Syntax

class 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 class is creating the challenge and generating the ocra_suite. This is done by calling the create_challenge method. After creating the challenge and ocra_suite these values are sent to the other party.

When receiving a challenge and OCRASuite the class is use to calculate a response. Set ocra_suite, challenge, and any other required properties and call calculate_response to calculate the response. Send the response back to the original party for verification.

After receiving the verification set challenge, ocra_suite, and response and call verify_response. verify_response returns True if the response is verified, False otherwise.

Creating the Challenge

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

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

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

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

Calculating the Response

calculate_response calculates response to the given challenge.

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

After setting ocra_suite 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

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

Before calling this method set ocra_suite, challenge, and response.

After setting ocra_suite 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 class with short descriptions. Click on the links for further details.


challenge	The challenge value.
challenge_format	The format in which the challenge will be created.
challenge_input	The input for the signature challenge.
challenge_length	The challenge length.
challenge_type	The challenge type.
counter	The counter.
hash_algorithm	The HMAC Hash Algorithm.
key	The secret key.
ocra_suite	The OCRASuite defines parameters about the challenge and response.
password	The password.
require_counter	Whether a Counter value is required to create the response.
require_password	Whether a Password is required to create the response.
require_time_stamp	Whether a TimeStamp is required to create the response.
response	The OCRA response.
response_length	Defines the length of the response.

Method List

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


calculate_response	This method calculates the response to the given challenge.
config	Sets or retrieves a configuration setting.
create_challenge	Creates the challenge.
reset	Reset the variables to default value.
verify_response	This method verifies the response.

Event List

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


on_error	Information about errors during data delivery.

Configuration Settings

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


CounterHex	The counter value as a hexadecimal string.
CurrentTime	The current time in milliseconds.
PasswordHashAlgorithm	The password hash algorithm.
RequireSessionInfo	Whether to use session information.
SessionInfo	The session information.
SessionInfoLength	The length of the session information.
TimeStepSize	The time step.
TimeStepUnit	The time step unit.
BuildInfo	Information about the product's build.
CodePage	The system code page used for Unicode to Multibyte translations.
LicenseInfo	Information about the current license.
ProcessIdleEvents	Whether the class uses its internal event loop to process events when the main thread is idle.
SelectWaitMillis	The length of time in milliseconds the class will wait when DoEvents is called if there are no events to process.
UseInternalSecurityAPI	Tells the class whether or not to use the system security libraries or an internal implementation.