OCRA Class

Properties   Methods   Events   Config Settings   Errors  

The OCRA class implements the OATH Challenge-Response Algorithm.

Syntax

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 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 class 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:

• ChallengeType
• ChallengeFormat
• ChallengeLength

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

• ChallengeType
• ChallengeFormat
• ChallengeLength
• ChallengeInput (required)
• HashAlgorithm
• Key

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:

• ChallengeFormat
• HashAlgorithm
• ResponseLength
• RequireCounter
• RequirePassword
• RequireTimeStamp
• PasswordHashAlgorithm
• RequireSessionInfo
• SessionInfoLength
• TimeStepSize
• TimeStepUnit

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:

• ChallengeFormat
• HashAlgorithm
• ResponseLength
• RequireCounter
• RequirePassword
• RequireTimeStamp
• PasswordHashAlgorithm
• RequireSessionInfo
• SessionInfoLength
• TimeStepSize
• TimeStepUnit

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:

• Challenge
• Counter
• HashAlgorithm
• Key
• OCRASuite
• Password
• ResponseLength
• CurrentTime
• SessionInfo
• TimeStepSize
• TimeStepUnit
• PasswordHashAlgorithm

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:

• ChallengeFormat
• HashAlgorithm
• ResponseLength
• RequireCounter
• RequirePassword
• RequireTimeStamp
• PasswordHashAlgorithm
• RequireSessionInfo
• SessionInfoLength
• TimeStepSize
• TimeStepUnit

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:

• Challenge
• Response
• Counter
• HashAlgorithm
• Key
• OCRASuite
• Password
• ResponseLength
• CurrentTime
• SessionInfo
• TimeStepSize
• TimeStepUnit
• PasswordHashAlgorithm

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.

Method List

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

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.

Config Settings

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

Challenge Property (OCRA Class)

The challenge value.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetChallenge(char* &lpChallenge, int &lenChallenge);
int SetChallenge(const char* lpChallenge, int lenChallenge);

Unicode (Windows)
INT GetChallenge(LPSTR &lpChallenge, INT &lenChallenge);
INT SetChallenge(LPCSTR lpChallenge, INT lenChallenge);

int ipworksauth_ocra_getchallenge(void* lpObj, char** lpChallenge, int* lenChallenge);
int ipworksauth_ocra_setchallenge(void* lpObj, const char* lpChallenge, int lenChallenge);

QByteArray GetChallenge();
int SetChallenge(QByteArray qbaChallenge);

Default Value

""

Remarks

This property is populated after calling CreateChallenge. The format is specified by the ChallengeFormat property and the length is defined by the ChallengeLength property.

This property must be specified before calling CalculateResponse or VerifyResponse.

Data Type

Binary String

ChallengeFormat Property (OCRA Class)

The format in which the challenge will be created.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetChallengeFormat();
int SetChallengeFormat(int iChallengeFormat);

Unicode (Windows)
INT GetChallengeFormat();
INT SetChallengeFormat(INT iChallengeFormat);

CF_ALPHANUMERIC(0), 
CF_NUMERIC(1), 
CF_HEX(2)

int ipworksauth_ocra_getchallengeformat(void* lpObj);
int ipworksauth_ocra_setchallengeformat(void* lpObj, int iChallengeFormat);

int GetChallengeFormat();
int SetChallengeFormat(int iChallengeFormat);

Default Value

0

Remarks

This setting specifies the format of the created challenge. This is applicable when calling CreateChallenge. Possible values are:

Data Type

Integer

ChallengeInput Property (OCRA Class)

The input for the signature challenge.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetChallengeInput(char* &lpChallengeInput, int &lenChallengeInput);
int SetChallengeInput(const char* lpChallengeInput, int lenChallengeInput);

Unicode (Windows)
INT GetChallengeInput(LPSTR &lpChallengeInput, INT &lenChallengeInput);
INT SetChallengeInput(LPCSTR lpChallengeInput, INT lenChallengeInput);

int ipworksauth_ocra_getchallengeinput(void* lpObj, char** lpChallengeInput, int* lenChallengeInput);
int ipworksauth_ocra_setchallengeinput(void* lpObj, const char* lpChallengeInput, int lenChallengeInput);

QByteArray GetChallengeInput();
int SetChallengeInput(QByteArray qbaChallengeInput);

Default Value

""

Remarks

This property specifies the data used when creating the signature challenge. This is only used when calling CreateChallenge when ChallengeType is set to Signature.

Data Type

Binary String

ChallengeLength Property (OCRA Class)

The challenge length.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetChallengeLength();
int SetChallengeLength(int iChallengeLength);

Unicode (Windows)
INT GetChallengeLength();
INT SetChallengeLength(INT iChallengeLength);

int ipworksauth_ocra_getchallengelength(void* lpObj);
int ipworksauth_ocra_setchallengelength(void* lpObj, int iChallengeLength);

int GetChallengeLength();
int SetChallengeLength(int iChallengeLength);

Default Value

8

Remarks

This setting specifies the length of the Challenge that is created when calling CreateChallenge. Valid values are from 4 to 64. The default value is 8.

Data Type

Integer

ChallengeType Property (OCRA Class)

The challenge type.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetChallengeType();
int SetChallengeType(int iChallengeType);

Unicode (Windows)
INT GetChallengeType();
INT SetChallengeType(INT iChallengeType);

CT_RANDOM(0), 
CT_SIGNATURE(1)

int ipworksauth_ocra_getchallengetype(void* lpObj);
int ipworksauth_ocra_setchallengetype(void* lpObj, int iChallengeType);

int GetChallengeType();
int SetChallengeType(int iChallengeType);

Default Value

0

Remarks

This property defines the type of challenge created. Possible values are:

When setting this property to 0 (ctRandom) and calling CreateChallenge the class will populate Challenge with a randomly generated value.

When setting this property to 1 (ctSignature) and calling CreateChallenge the class creates a Hash-based Message Authentication Code (HMAC) value using the data specified in ChallengeInput and then populate Challenge with the formatted result.

Data Type

Integer

Counter Property (OCRA Class)

The counter.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetCounter();
int SetCounter(int64 lCounter);

Unicode (Windows)
LONG64 GetCounter();
INT SetCounter(LONG64 lCounter);

int64 ipworksauth_ocra_getcounter(void* lpObj);
int ipworksauth_ocra_setcounter(void* lpObj, int64 lCounter);

qint64 GetCounter();
int SetCounter(qint64 lCounter);

Default Value

0

Remarks

This property specifies the counter.

If a counter is required this must be set before calling CalculateResponse and VerifyResponse. To determine if a counter is required assign OCRASuite to the OCRA suite and check the value of RequireCounter.

The counter value should begin at 0 be incremented until the maximum value is reached. After the maximum is reached the counter value should start again at 0.

Data Type

Long64

HashAlgorithm Property (OCRA Class)

The HMAC Hash Algorithm.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetHashAlgorithm();
int SetHashAlgorithm(int iHashAlgorithm);

Unicode (Windows)
INT GetHashAlgorithm();
INT SetHashAlgorithm(INT iHashAlgorithm);

HA_SHA1(0), 
HA_SHA256(1), 
HA_SHA512(2)

int ipworksauth_ocra_gethashalgorithm(void* lpObj);
int ipworksauth_ocra_sethashalgorithm(void* lpObj, int iHashAlgorithm);

int GetHashAlgorithm();
int SetHashAlgorithm(int iHashAlgorithm);

Default Value

0

Remarks

This property specifies the hash algorithm used by the class. Possible values are:

• 0 (SHA-1 - default)
• 1 (SHA-256)
• 2 (SHA-512)

Data Type

Integer

Key Property (OCRA Class)

The secret key.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetKey(char* &lpKey, int &lenKey);
int SetKey(const char* lpKey, int lenKey);

Unicode (Windows)
INT GetKey(LPSTR &lpKey, INT &lenKey);
INT SetKey(LPCSTR lpKey, INT lenKey);

int ipworksauth_ocra_getkey(void* lpObj, char** lpKey, int* lenKey);
int ipworksauth_ocra_setkey(void* lpObj, const char* lpKey, int lenKey);

QByteArray GetKey();
int SetKey(QByteArray qbaKey);

Default Value

""

Remarks

This property holds the secret key used when calling CalculateResponse and VerifyResponse.

This property is also used when calling CreateChallenge when ChallengeType is set to Signature.

An empty key is valid, however it is recommended to provide a key value.

Data Type

Binary String

OCRASuite Property (OCRA Class)

The OCRASuite defines parameters about the challenge and response.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetOCRASuite();
int SetOCRASuite(const char* lpszOCRASuite);

Unicode (Windows)
LPWSTR GetOCRASuite();
INT SetOCRASuite(LPCWSTR lpszOCRASuite);

char* ipworksauth_ocra_getocrasuite(void* lpObj);
int ipworksauth_ocra_setocrasuite(void* lpObj, const char* lpszOCRASuite);

QString GetOCRASuite();
int SetOCRASuite(QString qsOCRASuite);

Default Value

""

Remarks

This property holds the OCRASuite value which defines parameters about the challenge and response.

This property will be populated after calling CreateChallenge. This property must be set before calling CalculateResponse or VerifyResponse.

When calling CreateChallenge the following properties will be used to create the OCRASuite:

• ChallengeFormat
• HashAlgorithm
• ResponseLength
• RequireCounter
• RequirePassword
• RequireTimeStamp
• PasswordHashAlgorithm
• RequireSessionInfo
• SessionInfoLength
• TimeStepSize
• TimeStepUnit

When this property is set the value is parsed and the above properties are populated to reflect the requirements defined by the OCRASuite.

Data Type

String

Password Property (OCRA Class)

The password.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetPassword(char* &lpPassword, int &lenPassword);
int SetPassword(const char* lpPassword, int lenPassword);

Unicode (Windows)
INT GetPassword(LPSTR &lpPassword, INT &lenPassword);
INT SetPassword(LPCSTR lpPassword, INT lenPassword);

int ipworksauth_ocra_getpassword(void* lpObj, char** lpPassword, int* lenPassword);
int ipworksauth_ocra_setpassword(void* lpObj, const char* lpPassword, int lenPassword);

QByteArray GetPassword();
int SetPassword(QByteArray qbaPassword);

Default Value

""

Remarks

This property specifies the password.

If a password is required this must be set before calling CalculateResponse and VerifyResponse. To determine if a password is required assign OCRASuite to the OCRA suite and check the value of RequirePassword.

Data Type

Binary String

RequireCounter Property (OCRA Class)

Whether a Counter value is required to create the response.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetRequireCounter();
int SetRequireCounter(int bRequireCounter);

Unicode (Windows)
BOOL GetRequireCounter();
INT SetRequireCounter(BOOL bRequireCounter);

int ipworksauth_ocra_getrequirecounter(void* lpObj);
int ipworksauth_ocra_setrequirecounter(void* lpObj, int bRequireCounter);

bool GetRequireCounter();
int SetRequireCounter(bool bRequireCounter);

Default Value

FALSE

Remarks

This property specifies whether a Counter value is required to create the response.

This may be set before calling CreateChallenge, when the OCRASuite is generated.

When OCRASuite is assigned this value is updated to reflect the options specified in the OCRASuite

Data Type

Boolean

RequirePassword Property (OCRA Class)

Whether a Password is required to create the response.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetRequirePassword();
int SetRequirePassword(int bRequirePassword);

Unicode (Windows)
BOOL GetRequirePassword();
INT SetRequirePassword(BOOL bRequirePassword);

int ipworksauth_ocra_getrequirepassword(void* lpObj);
int ipworksauth_ocra_setrequirepassword(void* lpObj, int bRequirePassword);

bool GetRequirePassword();
int SetRequirePassword(bool bRequirePassword);

Default Value

FALSE

Remarks

This property specifies whether a Password is required to create the response.

This may be set before calling CreateChallenge, when the OCRASuite is generated.

When OCRASuite is assigned this value is updated to reflect the options specified in the OCRASuite

Data Type

Boolean

RequireTimeStamp Property (OCRA Class)

Whether a TimeStamp is required to create the response.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetRequireTimeStamp();
int SetRequireTimeStamp(int bRequireTimeStamp);

Unicode (Windows)
BOOL GetRequireTimeStamp();
INT SetRequireTimeStamp(BOOL bRequireTimeStamp);

int ipworksauth_ocra_getrequiretimestamp(void* lpObj);
int ipworksauth_ocra_setrequiretimestamp(void* lpObj, int bRequireTimeStamp);

bool GetRequireTimeStamp();
int SetRequireTimeStamp(bool bRequireTimeStamp);

Default Value

FALSE

Remarks

This property specifies whether a TimeStamp is required to create the response.

This may be set before calling CreateChallenge, when the OCRASuite is generated.

When OCRASuite is assigned this value is updated to reflect the options specified in the OCRASuite

The class will automatically use the current system time when calling CalculateResponse and VerifyResponse if this property is True. The CurrentTime setting may be set to specify the time instead of using the system time.

The following settings are also applicable when this value is True:

• TimeStepSize
• TimeStepUnit

Data Type

Boolean

Response Property (OCRA Class)

The OCRA response.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetResponse(char* &lpResponse, int &lenResponse);
int SetResponse(const char* lpResponse, int lenResponse);

Unicode (Windows)
INT GetResponse(LPSTR &lpResponse, INT &lenResponse);
INT SetResponse(LPCSTR lpResponse, INT lenResponse);

int ipworksauth_ocra_getresponse(void* lpObj, char** lpResponse, int* lenResponse);
int ipworksauth_ocra_setresponse(void* lpObj, const char* lpResponse, int lenResponse);

QByteArray GetResponse();
int SetResponse(QByteArray qbaResponse);

Default Value

""

Remarks

This property holds the challenge response.

This is populated after calling CalculateResponse. This must be set before calling VerifyResponse.

Data Type

Binary String

ResponseLength Property (OCRA Class)

Defines the length of the response.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetResponseLength();
int SetResponseLength(int iResponseLength);

Unicode (Windows)
INT GetResponseLength();
INT SetResponseLength(INT iResponseLength);

int ipworksauth_ocra_getresponselength(void* lpObj);
int ipworksauth_ocra_setresponselength(void* lpObj, int iResponseLength);

int GetResponseLength();
int SetResponseLength(int iResponseLength);

Default Value

6

Remarks

This property specifies the desired response length. Valid values are 4-10, and 0. Values 4-10 will result in a numeric value of that length. The value 0 indicates no truncation and the raw HMAC value is returned in the response

This may be set before calling CreateChallenge, when the OCRASuite is generated.

When OCRASuite is assigned this value is updated to reflect the options specified in the OCRASuite. When calling CalculateResponse the calculated Response will be a value with this length.

The default value is 6.

Data Type

Integer

CalculateResponse Method (OCRA Class)

This method calculates the response to the given challenge.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int CalculateResponse();

Unicode (Windows)
INT CalculateResponse();

int ipworksauth_ocra_calculateresponse(void* lpObj);

int CalculateResponse();

Remarks

This method 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:

• ChallengeFormat
• HashAlgorithm
• ResponseLength
• RequireCounter
• RequirePassword
• RequireTimeStamp
• PasswordHashAlgorithm
• RequireSessionInfo
• SessionInfoLength
• TimeStepSize
• TimeStepUnit

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:

• Challenge
• Counter
• HashAlgorithm
• Key
• OCRASuite
• Password
• ResponseLength
• CurrentTime
• SessionInfo
• TimeStepSize
• TimeStepUnit
• PasswordHashAlgorithm

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Config Method (OCRA Class)

Sets or retrieves a configuration setting.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* Config(const char* lpszConfigurationString);

Unicode (Windows)
LPWSTR Config(LPCWSTR lpszConfigurationString);

char* ipworksauth_ocra_config(void* lpObj, const char* lpszConfigurationString);

QString Config(const QString& qsConfigurationString);

Remarks

Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

CreateChallenge Method (OCRA Class)

Creates the challenge.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int CreateChallenge();

Unicode (Windows)
INT CreateChallenge();

int ipworksauth_ocra_createchallenge(void* lpObj);

int CreateChallenge();

Remarks

This 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:

• ChallengeType
• ChallengeFormat
• ChallengeLength

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

• ChallengeType
• ChallengeFormat
• ChallengeLength
• ChallengeInput (required)
• HashAlgorithm
• Key

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:

• ChallengeFormat
• HashAlgorithm
• ResponseLength
• RequireCounter
• RequirePassword
• RequireTimeStamp
• PasswordHashAlgorithm
• RequireSessionInfo
• SessionInfoLength
• TimeStepSize
• TimeStepUnit

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Reset Method (OCRA Class)

Reset the variables to default value.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Reset();

Unicode (Windows)
INT Reset();

int ipworksauth_ocra_reset(void* lpObj);

int Reset();

Remarks

This method will reset the variables to default value.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

VerifyResponse Method (OCRA Class)

This method verifies the response.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
bool VerifyResponse();

Unicode (Windows)
INT VerifyResponse();

bool ipworksauth_ocra_verifyresponse(void* lpObj);

bool VerifyResponse();

Remarks

This method 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:

• ChallengeFormat
• HashAlgorithm
• ResponseLength
• RequireCounter
• RequirePassword
• RequireTimeStamp
• PasswordHashAlgorithm
• RequireSessionInfo
• SessionInfoLength
• TimeStepSize
• TimeStepUnit

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:

• Challenge
• Response
• Counter
• HashAlgorithm
• Key
• OCRASuite
• Password
• ResponseLength
• CurrentTime
• SessionInfo
• TimeStepSize
• TimeStepUnit
• PasswordHashAlgorithm

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

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

Error Event (OCRA Class)

Fired when information is available about errors during data delivery.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireError(OCRAErrorEventParams *e);

typedef struct {
  int ErrorCode;
  const char *Description;
  int reserved;
} OCRAErrorEventParams;


Unicode (Windows)
virtual INT FireError(OCRAErrorEventParams *e);

typedef struct {
  INT ErrorCode;
  LPCWSTR Description;
  INT reserved;
} OCRAErrorEventParams;

#define EID_OCRA_ERROR 1

virtual INT IPWORKSAUTH_CALL FireError(INT &iErrorCode, LPSTR &lpszDescription);

class OCRAErrorEventParams {
public:
  int ErrorCode();

  const QString &Description();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Error(OCRAErrorEventParams *e);

// Or, subclass OCRA and override this emitter function.
virtual int FireError(OCRAErrorEventParams *e) {...}

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the class fails with an error.

The ErrorCode parameter contains an error code, and the Description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

Config Settings (OCRA Class)

OCRA Config Settings

Base Config Settings

Trappable Errors (OCRA Class)

Error Handling (C++)

Call the GetLastErrorCode() method to obtain the last called method's result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. Known error codes are listed below. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

OCRA Errors