OTPServer Class

Properties   Methods   Events   Config Settings   Errors  

The OTPServer class checks the validity of one-time passwords.

Syntax

OTPServer

Remarks

A One-Time Password (OTP) is a password that is valid for only one session or transaction. OTPs were designed to overcome the weaknesses of traditional static passwords such as vulnerability to replay attacks. The OTPServer class can check the validity of HMAC-Based One-Time Passwords (HOTP) and Time-Based One-Time Passwords (TOTP).

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.

BaseTime Property (OTPServer Class)

Specifies the TOTP client's base time.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetBaseTime();
int SetBaseTime(const char* lpszBaseTime);

Unicode (Windows)
LPWSTR GetBaseTime();
INT SetBaseTime(LPCWSTR lpszBaseTime);

char* secureblackbox_otpserver_getbasetime(void* lpObj);
int secureblackbox_otpserver_setbasetime(void* lpObj, const char* lpszBaseTime);

QString GetBaseTime();
int SetBaseTime(QString qsBaseTime);

Default Value

""

Remarks

Specifies the TOTP (Time-based OTP, RFC 6238) server's base time parameter.

Data Type

String

Delta Property (OTPServer Class)

Specifies the resynchronization limit.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetDelta();
int SetDelta(int iDelta);

Unicode (Windows)
INT GetDelta();
INT SetDelta(INT iDelta);

int secureblackbox_otpserver_getdelta(void* lpObj);
int secureblackbox_otpserver_setdelta(void* lpObj, int iDelta);

int GetDelta();
int SetDelta(int iDelta);

Default Value

0

Remarks

This property is used to overcome the asynchronicity between the one-time password (OTP) client and server. For HOTP servers (HMAC-based OTP, RFC 4226), Delta defines the maximum possible deviation of the client's counter value. For TOTP servers (Time-based OTP, RFC 6238), Delta contains the maximum number of time steps the client can be out of synch.

Data Type

Integer

FIPSMode Property (OTPServer Class)

Reserved.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetFIPSMode();
int SetFIPSMode(int bFIPSMode);

Unicode (Windows)
BOOL GetFIPSMode();
INT SetFIPSMode(BOOL bFIPSMode);

int secureblackbox_otpserver_getfipsmode(void* lpObj);
int secureblackbox_otpserver_setfipsmode(void* lpObj, int bFIPSMode);

bool GetFIPSMode();
int SetFIPSMode(bool bFIPSMode);

Default Value

FALSE

Remarks

This property is reserved for future use.

Data Type

Boolean

Users Property (OTPServer Class)

A database of users containing all the per-user password settings.

Syntax

• C++
• C
• Qt

SecureBlackboxList<SecureBlackboxUserAccount>* GetUsers();
int SetUsers(SecureBlackboxList<SecureBlackboxUserAccount>* val);

int secureblackbox_otpserver_getusercount(void* lpObj);
int secureblackbox_otpserver_setusercount(void* lpObj, int iUserCount);

int secureblackbox_otpserver_getuserassociateddata(void* lpObj, int userindex, char** lpUserAssociatedData, int* lenUserAssociatedData);
int secureblackbox_otpserver_setuserassociateddata(void* lpObj, int userindex, const char* lpUserAssociatedData, int lenUserAssociatedData);

char* secureblackbox_otpserver_getuserbasepath(void* lpObj, int userindex);
int secureblackbox_otpserver_setuserbasepath(void* lpObj, int userindex, const char* lpszUserBasePath);

int secureblackbox_otpserver_getusercertificate(void* lpObj, int userindex, char** lpUserCertificate, int* lenUserCertificate);
int secureblackbox_otpserver_setusercertificate(void* lpObj, int userindex, const char* lpUserCertificate, int lenUserCertificate);

char* secureblackbox_otpserver_getuserdata(void* lpObj, int userindex);
int secureblackbox_otpserver_setuserdata(void* lpObj, int userindex, const char* lpszUserData);

char* secureblackbox_otpserver_getuseremail(void* lpObj, int userindex);
int secureblackbox_otpserver_setuseremail(void* lpObj, int userindex, const char* lpszUserEmail);

int64 secureblackbox_otpserver_getuserhandle(void* lpObj, int userindex);
int secureblackbox_otpserver_setuserhandle(void* lpObj, int userindex, int64 lUserHandle);

char* secureblackbox_otpserver_getuserhashalgorithm(void* lpObj, int userindex);
int secureblackbox_otpserver_setuserhashalgorithm(void* lpObj, int userindex, const char* lpszUserHashAlgorithm);

int secureblackbox_otpserver_getuserincomingspeedlimit(void* lpObj, int userindex);
int secureblackbox_otpserver_setuserincomingspeedlimit(void* lpObj, int userindex, int iUserIncomingSpeedLimit);

int secureblackbox_otpserver_getuserotpalgorithm(void* lpObj, int userindex);
int secureblackbox_otpserver_setuserotpalgorithm(void* lpObj, int userindex, int iUserOtpAlgorithm);

int secureblackbox_otpserver_getuserotplen(void* lpObj, int userindex);
int secureblackbox_otpserver_setuserotplen(void* lpObj, int userindex, int iUserOTPLen);

int secureblackbox_otpserver_getuserotpvalue(void* lpObj, int userindex);
int secureblackbox_otpserver_setuserotpvalue(void* lpObj, int userindex, int iUserOtpValue);

int secureblackbox_otpserver_getuseroutgoingspeedlimit(void* lpObj, int userindex);
int secureblackbox_otpserver_setuseroutgoingspeedlimit(void* lpObj, int userindex, int iUserOutgoingSpeedLimit);

char* secureblackbox_otpserver_getuserpassword(void* lpObj, int userindex);
int secureblackbox_otpserver_setuserpassword(void* lpObj, int userindex, const char* lpszUserPassword);

int secureblackbox_otpserver_getusersharedsecret(void* lpObj, int userindex, char** lpUserSharedSecret, int* lenUserSharedSecret);
int secureblackbox_otpserver_setusersharedsecret(void* lpObj, int userindex, const char* lpUserSharedSecret, int lenUserSharedSecret);

int secureblackbox_otpserver_getusersshkey(void* lpObj, int userindex, char** lpUserSSHKey, int* lenUserSSHKey);
int secureblackbox_otpserver_setusersshkey(void* lpObj, int userindex, const char* lpUserSSHKey, int lenUserSSHKey);

char* secureblackbox_otpserver_getuserusername(void* lpObj, int userindex);
int secureblackbox_otpserver_setuserusername(void* lpObj, int userindex, const char* lpszUserUsername);

int GetUserCount();
int SetUserCount(int iUserCount);

QByteArray GetUserAssociatedData(int iUserIndex);
int SetUserAssociatedData(int iUserIndex, QByteArray qbaUserAssociatedData);

QString GetUserBasePath(int iUserIndex);
int SetUserBasePath(int iUserIndex, QString qsUserBasePath);

QByteArray GetUserCertificate(int iUserIndex);
int SetUserCertificate(int iUserIndex, QByteArray qbaUserCertificate);

QString GetUserData(int iUserIndex);
int SetUserData(int iUserIndex, QString qsUserData);

QString GetUserEmail(int iUserIndex);
int SetUserEmail(int iUserIndex, QString qsUserEmail);

qint64 GetUserHandle(int iUserIndex);
int SetUserHandle(int iUserIndex, qint64 lUserHandle);

QString GetUserHashAlgorithm(int iUserIndex);
int SetUserHashAlgorithm(int iUserIndex, QString qsUserHashAlgorithm);

int GetUserIncomingSpeedLimit(int iUserIndex);
int SetUserIncomingSpeedLimit(int iUserIndex, int iUserIncomingSpeedLimit);

int GetUserOtpAlgorithm(int iUserIndex);
int SetUserOtpAlgorithm(int iUserIndex, int iUserOtpAlgorithm);

int GetUserOTPLen(int iUserIndex);
int SetUserOTPLen(int iUserIndex, int iUserOTPLen);

int GetUserOtpValue(int iUserIndex);
int SetUserOtpValue(int iUserIndex, int iUserOtpValue);

int GetUserOutgoingSpeedLimit(int iUserIndex);
int SetUserOutgoingSpeedLimit(int iUserIndex, int iUserOutgoingSpeedLimit);

QString GetUserPassword(int iUserIndex);
int SetUserPassword(int iUserIndex, QString qsUserPassword);

QByteArray GetUserSharedSecret(int iUserIndex);
int SetUserSharedSecret(int iUserIndex, QByteArray qbaUserSharedSecret);

QByteArray GetUserSSHKey(int iUserIndex);
int SetUserSSHKey(int iUserIndex, QByteArray qbaUserSSHKey);

QString GetUserUsername(int iUserIndex);
int SetUserUsername(int iUserIndex, QString qsUserUsername);

Remarks

Use this property to provide a list of known users to the OTP server.

This property is not available at design time.

Data Type

SecureBlackboxUserAccount

Config Method (OTPServer 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* secureblackbox_otpserver_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.

DoAction Method (OTPServer Class)

Performs an additional action.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* DoAction(const char* lpszActionID, const char* lpszActionParams);

Unicode (Windows)
LPWSTR DoAction(LPCWSTR lpszActionID, LPCWSTR lpszActionParams);

char* secureblackbox_otpserver_doaction(void* lpObj, const char* lpszActionID, const char* lpszActionParams);

QString DoAction(const QString& qsActionID, const QString& qsActionParams);

Remarks

DoAction is a generic method available in every class. It is used to perform an additional action introduced after the product major release. The list of actions is not fixed, and may be flexibly extended over time.

The unique identifier (case insensitive) of the action is provided in the ActionID parameter.

ActionParams contains the value of a single parameter, or a list of multiple parameters for the action in the form of PARAM1=VALUE1;PARAM2=VALUE2;....

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.

IsHOTPPasswordValid Method (OTPServer Class)

Validates a hash-based one-time password.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
bool IsHOTPPasswordValid(const char* lpKeySecret, int lenKeySecret, int iPasswordLength, int iCounter, const char* lpszPassword);

Unicode (Windows)
INT IsHOTPPasswordValid(LPCSTR lpKeySecret, INT lenKeySecret, INT iPasswordLength, INT iCounter, LPCWSTR lpszPassword);

bool secureblackbox_otpserver_ishotppasswordvalid(void* lpObj, const char* lpKeySecret, int lenKeySecret, int iPasswordLength, int iCounter, const char* lpszPassword);

bool IsHOTPPasswordValid(QByteArray qbaKeySecret, int iPasswordLength, int iCounter, const QString& qsPassword);

Remarks

Use this method to validate a hash-based one-time password (HOTP) by using explicit HOTP parameters. For this method to work, no user details need to be provided in Users collection.

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.

IsPasswordValid Method (OTPServer Class)

Validates an OTP password for a user.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
bool IsPasswordValid(const char* lpszUsername, const char* lpszPassword);

Unicode (Windows)
INT IsPasswordValid(LPCWSTR lpszUsername, LPCWSTR lpszPassword);

bool secureblackbox_otpserver_ispasswordvalid(void* lpObj, const char* lpszUsername, const char* lpszPassword);

bool IsPasswordValid(const QString& qsUsername, const QString& qsPassword);

Remarks

Use this method to check a one-time Password for a user specified by UserID. The known users' details need to be provided in Users list.

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.

IsTOTPPasswordValid Method (OTPServer Class)

Validates a time-based one-time password.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
bool IsTOTPPasswordValid(const char* lpKeySecret, int lenKeySecret, int iPasswordLength, int iTimeInterval, const char* lpszHashAlgorithm, const char* lpszPassword);

Unicode (Windows)
INT IsTOTPPasswordValid(LPCSTR lpKeySecret, INT lenKeySecret, INT iPasswordLength, INT iTimeInterval, LPCWSTR lpszHashAlgorithm, LPCWSTR lpszPassword);

bool secureblackbox_otpserver_istotppasswordvalid(void* lpObj, const char* lpKeySecret, int lenKeySecret, int iPasswordLength, int iTimeInterval, const char* lpszHashAlgorithm, const char* lpszPassword);

bool IsTOTPPasswordValid(QByteArray qbaKeySecret, int iPasswordLength, int iTimeInterval, const QString& qsHashAlgorithm, const QString& qsPassword);

Remarks

Use this method to validate a time-based one-time password (TOTP) by using explicit TOTP parameters. For this method to work, no user details need to be provided in Users collection.

Supported hash algorithms:

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.

Reset Method (OTPServer Class)

Resets the class settings.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Reset();

Unicode (Windows)
INT Reset();

int secureblackbox_otpserver_reset(void* lpObj);

int Reset();

Remarks

Reset is a generic method available in every class.

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.)

Error Event (OTPServer Class)

Information about errors during one-time password (OTP) processing.

Syntax

• C++
• C
• Qt

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

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


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

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

#define EID_OTPSERVER_ERROR 1

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

class OTPServerErrorEventParams {
public:
  int ErrorCode();

  const QString &Description();

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

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

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

Remarks

This event is fired in case of exceptional conditions during OTP checks.

ErrorCode contains an error code and Description contains a textual description of the error.

Notification Event (OTPServer Class)

This event notifies the application about an underlying control flow event.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireNotification(OTPServerNotificationEventParams *e);

typedef struct {
  const char *EventID;
  const char *EventParam;
  int reserved;
} OTPServerNotificationEventParams;


Unicode (Windows)
virtual INT FireNotification(OTPServerNotificationEventParams *e);

typedef struct {
  LPCWSTR EventID;
  LPCWSTR EventParam;
  INT reserved;
} OTPServerNotificationEventParams;

#define EID_OTPSERVER_NOTIFICATION 2

virtual INT SECUREBLACKBOX_CALL FireNotification(LPSTR &lpszEventID, LPSTR &lpszEventParam);

class OTPServerNotificationEventParams {
public:
  const QString &EventID();

  const QString &EventParam();

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

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

// Or, subclass OTPServer and override this emitter function.
virtual int FireNotification(OTPServerNotificationEventParams *e) {...}

Remarks

The class fires this event to let the application know about some event, occurrence, or milestone in the class. For example, it may fire to report completion of the document processing. The list of events being reported is not fixed, and may be flexibly extended over time.

The unique identifier of the event is provided in the EventID parameter. EventParam contains any parameters accompanying the occurrence. Depending on the type of the class, the exact action it is performing, or the document being processed, one or both may be omitted.

UserAccount Type

A container for user account information.

Syntax

SecureBlackboxUserAccount (declared in secureblackbox.h)

Remarks

UserAccount objects are used to store user account information, such as logins and passwords.

Fields

Constructors

UserAccount()

SecureBlackboxList Type

Syntax

SecureBlackboxList<T> (declared in secureblackbox.h)

Remarks

SecureBlackboxList is a generic class that is used to hold a collection of objects of type T, where T is one of the custom types supported by the OTPServer class.

int GetCount() {}

int SetCount(int count) {}

T* Get(int index) {}

T* Set(int index, T* value) {}

Config Settings (OTPServer Class)

Base Config Settings

Trappable Errors (OTPServer 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.

OTPServer Errors