OTPServer Component

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

TsbxOTPServer

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 component 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 component with short descriptions. Click on the links for further details.

Method List

---

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

Event List

---

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

Config Settings

---

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

FIPSMode Property (OTPServer Component)

Reserved.

Syntax

__property bool FIPSMode = { read=FFIPSMode, write=FSetFIPSMode };

Default Value

false

Remarks

This property is reserved for future use.

Data Type

Boolean

UserCount Property (OTPServer Component)

The number of records in the User arrays.

Syntax

__property int UserCount = { read=FUserCount, write=FSetUserCount };

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 (OTPServer Component)

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

Syntax

__property DynamicArray UserAssociatedData[int UserIndex] = { read=FUserAssociatedData, write=FSetUserAssociatedData };

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 (OTPServer Component)

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

Syntax

__property String UserBasePath[int UserIndex] = { read=FUserBasePath, write=FSetUserBasePath };

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 (OTPServer Component)

Contains the user's certificate.

Syntax

__property DynamicArray UserCert[int UserIndex] = { read=FUserCert, write=FSetUserCert };

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 (OTPServer Component)

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

Syntax

__property String UserData[int UserIndex] = { read=FUserData, write=FSetUserData };

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 (OTPServer Component)

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

Syntax

__property __int64 UserHandle[int UserIndex] = { read=FUserHandle, write=FSetUserHandle };

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 (OTPServer Component)

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

Syntax

__property String UserHashAlgorithm[int UserIndex] = { read=FUserHashAlgorithm, write=FSetUserHashAlgorithm };

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 (OTPServer Component)

Specifies the incoming speed limit for this user.

Syntax

__property int UserIncomingSpeedLimit[int UserIndex] = { read=FUserIncomingSpeedLimit, write=FSetUserIncomingSpeedLimit };

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 (OTPServer Component)

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

Syntax

__property TsbxOTPServerUserOtpAlgorithms UserOtpAlgorithm[int UserIndex] = { read=FUserOtpAlgorithm, write=FSetUserOtpAlgorithm };

enum TsbxOTPServerUserOtpAlgorithms {
  oaNone=0,
  oaHmac=1,
  oaTime=2
};

Default Value

oaNone

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 (OTPServer Component)

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

Syntax

__property int UserOtpValue[int UserIndex] = { read=FUserOtpValue, write=FSetUserOtpValue };

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 (OTPServer Component)

Specifies the outgoing speed limit for this user.

Syntax

__property int UserOutgoingSpeedLimit[int UserIndex] = { read=FUserOutgoingSpeedLimit, write=FSetUserOutgoingSpeedLimit };

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 (OTPServer Component)

The user's authentication password.

Syntax

__property String UserPassword[int UserIndex] = { read=FUserPassword, write=FSetUserPassword };

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 (OTPServer Component)

Specifies the length of the user's OTP password.

Syntax

__property int UserPasswordLen[int UserIndex] = { read=FUserPasswordLen, write=FSetUserPasswordLen };

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 (OTPServer Component)

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

Syntax

__property DynamicArray UserSharedSecret[int UserIndex] = { read=FUserSharedSecret, write=FSetUserSharedSecret };

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 (OTPServer Component)

Contains the user's SSH key.

Syntax

__property DynamicArray UserSSHKey[int UserIndex] = { read=FUserSSHKey, write=FSetUserSSHKey };

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 (OTPServer Component)

The registered name (login) of the user.

Syntax

__property String UserUsername[int UserIndex] = { read=FUserUsername, write=FSetUserUsername };

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 (OTPServer Component)

Sets or retrieves a configuration setting.

Syntax

String __fastcall Config(String ConfigurationString);

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, 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 (OTPServer Component)

Performs an additional action.

Syntax

String __fastcall DoAction(String ActionID, String ActionParams);

Remarks

DoAction is a generic method available in every component. 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 insencitive) 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 (OTPServer Component)

Validates a hash-based one-time password.

Syntax

bool __fastcall IsHOTPPasswordValid(DynamicArray<Byte> KeySecret, int PasswordLength, int Counter, String 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 (OTPServer Component)

Validates an OTP password for a user.

Syntax

bool __fastcall IsPasswordValid(String Username, String 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 (OTPServer Component)

Validates a time-based one-time password.

Syntax

bool __fastcall IsTOTPPasswordValid(DynamicArray<Byte> KeySecret, int PasswordLength, int TimeInterval, String HashAlgorithm, String 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 (OTPServer Component)

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

Syntax

typedef struct {
  int ErrorCode;
  String Description;
} TsbxOTPServerErrorEventParams;
typedef void __fastcall (__closure *TsbxOTPServerErrorEvent)(System::TObject* Sender, TsbxOTPServerErrorEventParams *e);
__property TsbxOTPServerErrorEvent OnError = { read=FOnError, write=FOnError };

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

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

Syntax

typedef struct {
  String EventID;
  String EventParam;
} TsbxOTPServerNotificationEventParams;
typedef void __fastcall (__closure *TsbxOTPServerNotificationEvent)(System::TObject* Sender, TsbxOTPServerNotificationEventParams *e);
__property TsbxOTPServerNotificationEvent OnNotification = { read=FOnNotification, write=FOnNotification };

Remarks

The component fires this event to let the application know about some event, occurrence, or milestone in the component. 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 EventID parameter. EventParam contains any parameters accompanying the occurrence. Depending on the type of the component, the exact action it is performing, or the document being processed, one or both may be omitted.

Config Settings (OTPServer Component)

The component 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 component, access to these internal properties is provided through the Config method.

OTPServer Config Settings

Base Config Settings

Trappable Errors (OTPServer Component)

OTPServer Errors

	1048577   Invalid parameter value (SB_ERROR_INVALID_PARAMETER)
	1048578   Component 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)