OTPServer Class

Properties   Methods   Events   Config Settings   Errors  

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

Class Name

SecureBlackbox_OTPServer

Procedural Interface

 secureblackbox_otpserver_open();
 secureblackbox_otpserver_close($res);
 secureblackbox_otpserver_register_callback($res, $id, $function);
 secureblackbox_otpserver_get_last_error($res);
 secureblackbox_otpserver_get_last_error_code($res);
 secureblackbox_otpserver_set($res, $id, $index, $value);
 secureblackbox_otpserver_get($res, $id, $index);
 secureblackbox_otpserver_do_config($res, $configurationstring);
 secureblackbox_otpserver_do_doaction($res, $actionid, $actionparams);
 secureblackbox_otpserver_do_ishotppasswordvalid($res, $keysecret, $passwordlength, $counter, $password);
 secureblackbox_otpserver_do_ispasswordvalid($res, $username, $password);
 secureblackbox_otpserver_do_istotppasswordvalid($res, $keysecret, $passwordlength, $timeinterval, $hashalgorithm, $password);

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.

FIPSMode Property (SecureBlackbox_OTPServer Class)

Reserved.

Object Oriented Interface

public function getFIPSMode();


public function setFIPSMode($value);

Procedural Interface

secureblackbox_otpserver_get($res, 1 );


secureblackbox_otpserver_set($res, 1, $value );

Default Value

false

Remarks

This property is reserved for future use.

Data Type

Boolean

UserCount Property (SecureBlackbox_OTPServer Class)

The number of records in the User arrays.

Object Oriented Interface

public function getUserCount();


public function setUserCount($value);

Procedural Interface

secureblackbox_otpserver_get($res, 2 );


secureblackbox_otpserver_set($res, 2, $value );

Default Value

0

Remarks

This property controls the size of the following arrays:

• UserAssociatedData
• UserBasePath
• UserCert
• UserData
• UserHandle
• UserHashAlgorithm
• UserIncomingSpeedLimit
• UserOtpAlgorithm
• UserOtpValue
• UserOutgoingSpeedLimit
• UserPassword
• UserPasswordLen
• UserSharedSecret
• UserSSHKey
• UserUsername

The array indices start at 0 and end at UserCount - 1.

This property is not available at design time.

Data Type

Integer

UserAssociatedData Property (SecureBlackbox_OTPServer Class)

Contains the user's Associated Data when SSH AEAD (Authenticated Encryption with Associated Data) algorithm is used.

Object Oriented Interface

public function getUserAssociatedData($userindex);


public function setUserAssociatedData($userindex, $value);

Procedural Interface

secureblackbox_otpserver_get($res, 3 , $userindex);


secureblackbox_otpserver_set($res, 3, $value , $userindex);

Remarks

Contains the user's Associated Data when SSH AEAD (Authenticated Encryption with Associated Data) algorithm is used.

The $userindex parameter specifies the index of the item in the array. The size of the array is controlled by the UserCount property.

This property is not available at design time.

Data Type

Byte Array

UserBasePath Property (SecureBlackbox_OTPServer Class)

Base path for this user in the server's file system.

Object Oriented Interface

public function getUserBasePath($userindex);


public function setUserBasePath($userindex, $value);

Procedural Interface

secureblackbox_otpserver_get($res, 4 , $userindex);


secureblackbox_otpserver_set($res, 4, $value , $userindex);

Default Value

''

Remarks

Base path for this user in the server's file system.

The $userindex parameter specifies the index of the item in the array. The size of the array is controlled by the UserCount property.

This property is not available at design time.

Data Type

String

UserCert Property (SecureBlackbox_OTPServer Class)

Contains the user's certificate.

Object Oriented Interface

public function getUserCert($userindex);


public function setUserCert($userindex, $value);

Procedural Interface

secureblackbox_otpserver_get($res, 5 , $userindex);


secureblackbox_otpserver_set($res, 5, $value , $userindex);

Remarks

Contains the user's certificate.

The $userindex parameter specifies the index of the item in the array. The size of the array is controlled by the UserCount property.

This property is not available at design time.

Data Type

Byte Array

UserData Property (SecureBlackbox_OTPServer Class)

Contains uninterpreted user-defined data that should be associated with the user account, such as comments or custom settings.

Object Oriented Interface

public function getUserData($userindex);


public function setUserData($userindex, $value);

Procedural Interface

secureblackbox_otpserver_get($res, 6 , $userindex);


secureblackbox_otpserver_set($res, 6, $value , $userindex);

Default Value

''

Remarks

Contains uninterpreted user-defined data that should be associated with the user account, such as comments or custom settings.

The $userindex parameter specifies the index of the item in the array. The size of the array is controlled by the UserCount property.

This property is not available at design time.

Data Type

String

UserHandle Property (SecureBlackbox_OTPServer Class)

Allows to get or set a 'handle', a unique identifier of the underlying property object.

Object Oriented Interface

public function getUserHandle($userindex);


public function setUserHandle($userindex, $value);

Procedural Interface

secureblackbox_otpserver_get($res, 7 , $userindex);


secureblackbox_otpserver_set($res, 7, $value , $userindex);

Default Value

0

Remarks

Allows to get or set a 'handle', a unique identifier of the underlying property object. Use this property to assign objects of the same type in a quicker manner, without copying them fieldwise.

When you pass a handle of one object to another, the source object is copied to the destination rather than assigned. It is safe to get rid of the original object after such operation. pdfSigner.setSigningCertHandle(certMgr.getCertHandle());

The $userindex parameter specifies the index of the item in the array. The size of the array is controlled by the UserCount property.

This property is not available at design time.

Data Type

Long64

UserHashAlgorithm Property (SecureBlackbox_OTPServer Class)

Specifies the hash algorithm used to generate TOTP (Time-based One-Time Passwords) passwords for this user.

Object Oriented Interface

public function getUserHashAlgorithm($userindex);


public function setUserHashAlgorithm($userindex, $value);

Procedural Interface

secureblackbox_otpserver_get($res, 8 , $userindex);


secureblackbox_otpserver_set($res, 8, $value , $userindex);

Default Value

''

Remarks

Specifies the hash algorithm used to generate TOTP (Time-based One-Time Passwords) passwords for this user. Three HMAC algorithms are supported, with SHA-1, SHA-256, and SHA-512 digests:

The $userindex parameter specifies the index of the item in the array. The size of the array is controlled by the UserCount property.

This property is not available at design time.

Data Type

String

UserIncomingSpeedLimit Property (SecureBlackbox_OTPServer Class)

Specifies the incoming speed limit for this user.

Object Oriented Interface

public function getUserIncomingSpeedLimit($userindex);


public function setUserIncomingSpeedLimit($userindex, $value);

Procedural Interface

secureblackbox_otpserver_get($res, 9 , $userindex);


secureblackbox_otpserver_set($res, 9, $value , $userindex);

Default Value

0

Remarks

Specifies the incoming speed limit for this user. The value of 0 (zero) means "no limitation".

The $userindex parameter specifies the index of the item in the array. The size of the array is controlled by the UserCount property.

This property is not available at design time.

Data Type

Integer

UserOtpAlgorithm Property (SecureBlackbox_OTPServer Class)

The algorithm used to generate one-time passwords (OTP) for this user, either HOTP (Hash-based OTP) or TOTP (Time-based OTP).

Object Oriented Interface

public function getUserOtpAlgorithm($userindex);


public function setUserOtpAlgorithm($userindex, $value);

Procedural Interface

secureblackbox_otpserver_get($res, 10 , $userindex);


secureblackbox_otpserver_set($res, 10, $value , $userindex);

Default Value

0

Remarks

The algorithm used to generate one-time passwords (OTP) for this user, either HOTP (Hash-based OTP) or TOTP (Time-based OTP). In the former case, a value of a dedicated counter is used to generate a unique password, while in the latter the password is generated on the basis of the current time value.

The $userindex parameter specifies the index of the item in the array. The size of the array is controlled by the UserCount property.

This property is not available at design time.

Data Type

Integer

UserOtpValue Property (SecureBlackbox_OTPServer Class)

The user's time interval (TOTP) or Counter (HOTP).

Object Oriented Interface

public function getUserOtpValue($userindex);


public function setUserOtpValue($userindex, $value);

Procedural Interface

secureblackbox_otpserver_get($res, 11 , $userindex);


secureblackbox_otpserver_set($res, 11, $value , $userindex);

Default Value

0

Remarks

The user's time interval (TOTP) or Counter (HOTP).

The $userindex parameter specifies the index of the item in the array. The size of the array is controlled by the UserCount property.

This property is not available at design time.

Data Type

Integer

UserOutgoingSpeedLimit Property (SecureBlackbox_OTPServer Class)

Specifies the outgoing speed limit for this user.

Object Oriented Interface

public function getUserOutgoingSpeedLimit($userindex);


public function setUserOutgoingSpeedLimit($userindex, $value);

Procedural Interface

secureblackbox_otpserver_get($res, 12 , $userindex);


secureblackbox_otpserver_set($res, 12, $value , $userindex);

Default Value

0

Remarks

Specifies the outgoing speed limit for this user. The value of 0 (zero) means "no limitation".

The $userindex parameter specifies the index of the item in the array. The size of the array is controlled by the UserCount property.

This property is not available at design time.

Data Type

Integer

UserPassword Property (SecureBlackbox_OTPServer Class)

The user's authentication password.

Object Oriented Interface

public function getUserPassword($userindex);


public function setUserPassword($userindex, $value);

Procedural Interface

secureblackbox_otpserver_get($res, 13 , $userindex);


secureblackbox_otpserver_set($res, 13, $value , $userindex);

Default Value

''

Remarks

The user's authentication password.

The $userindex parameter specifies the index of the item in the array. The size of the array is controlled by the UserCount property.

This property is not available at design time.

Data Type

String

UserPasswordLen Property (SecureBlackbox_OTPServer Class)

Specifies the length of the user's OTP password.

Object Oriented Interface

public function getUserPasswordLen($userindex);


public function setUserPasswordLen($userindex, $value);

Procedural Interface

secureblackbox_otpserver_get($res, 14 , $userindex);


secureblackbox_otpserver_set($res, 14, $value , $userindex);

Default Value

0

Remarks

Specifies the length of the user's OTP password.

The $userindex parameter specifies the index of the item in the array. The size of the array is controlled by the UserCount property.

This property is not available at design time.

Data Type

Integer

UserSharedSecret Property (SecureBlackbox_OTPServer Class)

Contains the user's secret key, which is essentially a shared secret between the client and server.

Object Oriented Interface

public function getUserSharedSecret($userindex);


public function setUserSharedSecret($userindex, $value);

Procedural Interface

secureblackbox_otpserver_get($res, 15 , $userindex);


secureblackbox_otpserver_set($res, 15, $value , $userindex);

Remarks

Contains the user's secret key, which is essentially a shared secret between the client and server.

Shared secrets can be used in TLS-driven protocols, as well as in OTP (where it is called a 'key secret') for generating one-time passwords on one side, and validate them on the other.

The $userindex parameter specifies the index of the item in the array. The size of the array is controlled by the UserCount property.

This property is not available at design time.

Data Type

Byte Array

UserSSHKey Property (SecureBlackbox_OTPServer Class)

Contains the user's SSH key.

Object Oriented Interface

public function getUserSSHKey($userindex);


public function setUserSSHKey($userindex, $value);

Procedural Interface

secureblackbox_otpserver_get($res, 16 , $userindex);


secureblackbox_otpserver_set($res, 16, $value , $userindex);

Remarks

Contains the user's SSH key.

The $userindex parameter specifies the index of the item in the array. The size of the array is controlled by the UserCount property.

This property is not available at design time.

Data Type

Byte Array

UserUsername Property (SecureBlackbox_OTPServer Class)

The registered name (login) of the user.

Object Oriented Interface

public function getUserUsername($userindex);


public function setUserUsername($userindex, $value);

Procedural Interface

secureblackbox_otpserver_get($res, 17 , $userindex);


secureblackbox_otpserver_set($res, 17, $value , $userindex);

Default Value

''

Remarks

The registered name (login) of the user.

The $userindex parameter specifies the index of the item in the array. The size of the array is controlled by the UserCount property.

This property is not available at design time.

Data Type

String

Config Method (SecureBlackbox_OTPServer Class)

Sets or retrieves a configuration setting.

Object Oriented Interface

public function doConfig($configurationstring);

Procedural Interface

secureblackbox_otpserver_do_config($res, $configurationstring);

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.

DoAction Method (SecureBlackbox_OTPServer Class)

Performs an additional action.

Object Oriented Interface

public function doDoAction($actionid, $actionparams);

Procedural Interface

secureblackbox_otpserver_do_doaction($res, $actionid, $actionparams);

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

IsHOTPPasswordValid Method (SecureBlackbox_OTPServer Class)

Validates a hash-based one-time password.

Object Oriented Interface

public function doIsHOTPPasswordValid($keysecret, $passwordlength, $counter, $password);

Procedural Interface

secureblackbox_otpserver_do_ishotppasswordvalid($res, $keysecret, $passwordlength, $counter, $password);

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.

IsPasswordValid Method (SecureBlackbox_OTPServer Class)

Validates an OTP password for a user.

Object Oriented Interface

public function doIsPasswordValid($username, $password);

Procedural Interface

secureblackbox_otpserver_do_ispasswordvalid($res, $username, $password);

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.

IsTOTPPasswordValid Method (SecureBlackbox_OTPServer Class)

Validates a time-based one-time password.

Object Oriented Interface

public function doIsTOTPPasswordValid($keysecret, $passwordlength, $timeinterval, $hashalgorithm, $password);

Procedural Interface

secureblackbox_otpserver_do_istotppasswordvalid($res, $keysecret, $passwordlength, $timeinterval, $hashalgorithm, $password);

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 Event (SecureBlackbox_OTPServer Class)

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

Object Oriented Interface

public function fireError($param);

Procedural Interface

secureblackbox_otpserver_register_callback($res, 1, array($this, 'fireError'));

Parameter List

 'errorcode'
 'description'

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 (SecureBlackbox_OTPServer Class)

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

Object Oriented Interface

public function fireNotification($param);

Procedural Interface

secureblackbox_otpserver_register_callback($res, 2, array($this, 'fireNotification'));

Parameter List

 'eventid'
 'eventparam'

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.

Config Settings (OTPServer Class)

The class accepts one or more of the following configuration settings. Configuration 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.

OTPServer Config Settings

Base Config Settings

Trappable Errors (OTPServer Class)

OTPServer Errors

	1048577   Invalid parameter value (SB_ERROR_INVALID_PARAMETER)
	1048578   Class is configured incorrectly (SB_ERROR_INVALID_SETUP)
	1048579   Operation cannot be executed in the current state (SB_ERROR_INVALID_STATE)
	1048580   Attempt to set an invalid value to a property (SB_ERROR_INVALID_VALUE)
	1048581   Certificate does not have its private key loaded (SB_ERROR_NO_PRIVATE_KEY)
	1048581   Cancelled by the user (SB_ERROR_CANCELLED_BY_USER)
	25165825   User not found (SB_ERROR_OTP_USER_NOT_FOUND)