Struct secureblackbox::OTPServer

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

secureblackbox::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 struct can check the validity of HMAC-Based One-Time Passwords (HOTP) and Time-Based One-Time Passwords (TOTP).

Object Lifetime

The new() method returns a mutable reference to a struct instance. The object itself is kept in the global list maintained by SecureBlackbox. Due to this, the OTPServer struct cannot be disposed of automatically. Please, call the dispose(&mut self) method of OTPServer when you have finished using the instance.

Property List

---

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

Method List

---

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

Event List

---

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

Config Settings

---

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

base_time property (OTPServer Struct)

Specifies the TOTP client's base time.

Syntax

fn base_time(&self ) -> Result<String, SecureBlackboxError> 
fn set_base_time(&self, value : &str) ->  Option<SecureBlackboxError> 
fn set_base_time_ref(&self, value : &String) ->  Option<SecureBlackboxError> 

Default Value

""

Remarks

Specifies the TOTP (Time-based OTP, RFC 6238) server's base time parameter. Any times passed to this property must be in UTC.

Data Type

String

delta property (OTPServer Struct)

Specifies the resynchronization limit.

Syntax

fn delta(&self ) -> Result<i32, SecureBlackboxError> 
fn set_delta(&self, value : i32) ->  Option<SecureBlackboxError> 

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

i32

fips_mode property (OTPServer Struct)

Reserved.

Syntax

fn fips_mode(&self ) -> Result<bool, SecureBlackboxError> 
fn set_fips_mode(&self, value : bool) ->  Option<SecureBlackboxError> 

Default Value

false

Remarks

This property is reserved for future use.

Data Type

bool

user_count property (OTPServer Struct)

The number of records in the User arrays.

Syntax

fn user_count(&self ) -> Result<i32, SecureBlackboxError> 
fn set_user_count(&self, value : i32) ->  Option<SecureBlackboxError> 

Default Value

0

Remarks

This property controls the size of the following arrays:

• user_associated_data
• user_base_path
• user_certificate
• user_data
• user_email
• user_handle
• user_hash_algorithm
• user_incoming_speed_limit
• username
• user_otp_algorithm
• user_otp_len
• user_otp_value
• user_outgoing_speed_limit
• user_password
• user_shared_secret
• user_ssh_key

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

Data Type

i32

user_associated_data property (OTPServer Struct)

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

Syntax

fn user_associated_data(&self , UserIndex : i32) -> Result<Vec<u8>, SecureBlackboxError> 
fn set_user_associated_data(&self, UserIndex : i32, value : Vec<u8>) ->  Option<SecureBlackboxError> 
fn set_user_associated_data_ref(&self, UserIndex : i32, value : &[u8]) ->  Option<SecureBlackboxError> 

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.

Data Type

Vec

user_base_path property (OTPServer Struct)

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

Syntax

fn user_base_path(&self , UserIndex : i32) -> Result<String, SecureBlackboxError> 
fn set_user_base_path(&self, UserIndex : i32, value : &str) ->  Option<SecureBlackboxError> 
fn set_user_base_path_ref(&self, UserIndex : i32, value : &String) ->  Option<SecureBlackboxError> 

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.

Data Type

String

user_certificate property (OTPServer Struct)

Contains the user's certificate.

Syntax

fn user_certificate(&self , UserIndex : i32) -> Result<Vec<u8>, SecureBlackboxError> 
fn set_user_certificate(&self, UserIndex : i32, value : Vec<u8>) ->  Option<SecureBlackboxError> 
fn set_user_certificate_ref(&self, UserIndex : i32, value : &[u8]) ->  Option<SecureBlackboxError> 

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.

Data Type

Vec

user_data property (OTPServer Struct)

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

Syntax

fn user_data(&self , UserIndex : i32) -> Result<String, SecureBlackboxError> 
fn set_user_data(&self, UserIndex : i32, value : &str) ->  Option<SecureBlackboxError> 
fn set_user_data_ref(&self, UserIndex : i32, value : &String) ->  Option<SecureBlackboxError> 

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.

Data Type

String

user_email property (OTPServer Struct)

The user's email address.

Syntax

fn user_email(&self , UserIndex : i32) -> Result<String, SecureBlackboxError> 
fn set_user_email(&self, UserIndex : i32, value : &str) ->  Option<SecureBlackboxError> 
fn set_user_email_ref(&self, UserIndex : i32, value : &String) ->  Option<SecureBlackboxError> 

Default Value

""

Remarks

The user's email address.

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

Data Type

String

user_handle property (OTPServer Struct)

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

Syntax

fn user_handle(&self , UserIndex : i32) -> Result<i64, SecureBlackboxError> 
fn set_user_handle(&self, UserIndex : i32, value : i64) ->  Option<SecureBlackboxError> 

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.

Data Type

i64

user_hash_algorithm property (OTPServer Struct)

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

Syntax

fn user_hash_algorithm(&self , UserIndex : i32) -> Result<String, SecureBlackboxError> 
fn set_user_hash_algorithm(&self, UserIndex : i32, value : &str) ->  Option<SecureBlackboxError> 
fn set_user_hash_algorithm_ref(&self, UserIndex : i32, value : &String) ->  Option<SecureBlackboxError> 

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.

Data Type

String

user_incoming_speed_limit property (OTPServer Struct)

Specifies the incoming speed limit for this user.

Syntax

fn user_incoming_speed_limit(&self , UserIndex : i32) -> Result<i32, SecureBlackboxError> 
fn set_user_incoming_speed_limit(&self, UserIndex : i32, value : i32) ->  Option<SecureBlackboxError> 

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.

Data Type

i32

user_otp_algorithm property (OTPServer Struct)

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

Syntax

fn user_otp_algorithm(&self , UserIndex : i32) -> Result<i32, SecureBlackboxError> 
fn set_user_otp_algorithm(&self, UserIndex : i32, value : i32) ->  Option<SecureBlackboxError> 

Possible Values

0   // None
1   // Hmac
2   // Time

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.

Data Type

i32

user_otp_len property (OTPServer Struct)

Specifies the length of the user's OTP password.

Syntax

fn user_otp_len(&self , UserIndex : i32) -> Result<i32, SecureBlackboxError> 
fn set_user_otp_len(&self, UserIndex : i32, value : i32) ->  Option<SecureBlackboxError> 

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.

Data Type

i32

user_otp_value property (OTPServer Struct)

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

Syntax

fn user_otp_value(&self , UserIndex : i32) -> Result<i32, SecureBlackboxError> 
fn set_user_otp_value(&self, UserIndex : i32, value : i32) ->  Option<SecureBlackboxError> 

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.

Data Type

i32

user_outgoing_speed_limit property (OTPServer Struct)

Specifies the outgoing speed limit for this user.

Syntax

fn user_outgoing_speed_limit(&self , UserIndex : i32) -> Result<i32, SecureBlackboxError> 
fn set_user_outgoing_speed_limit(&self, UserIndex : i32, value : i32) ->  Option<SecureBlackboxError> 

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.

Data Type

i32

user_password property (OTPServer Struct)

The user's authentication password.

Syntax

fn user_password(&self , UserIndex : i32) -> Result<String, SecureBlackboxError> 
fn set_user_password(&self, UserIndex : i32, value : &str) ->  Option<SecureBlackboxError> 
fn set_user_password_ref(&self, UserIndex : i32, value : &String) ->  Option<SecureBlackboxError> 

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.

Data Type

String

user_shared_secret property (OTPServer Struct)

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

Syntax

fn user_shared_secret(&self , UserIndex : i32) -> Result<Vec<u8>, SecureBlackboxError> 
fn set_user_shared_secret(&self, UserIndex : i32, value : Vec<u8>) ->  Option<SecureBlackboxError> 
fn set_user_shared_secret_ref(&self, UserIndex : i32, value : &[u8]) ->  Option<SecureBlackboxError> 

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.

Data Type

Vec

user_ssh_key property (OTPServer Struct)

Contains the user's SSH key.

Syntax

fn user_ssh_key(&self , UserIndex : i32) -> Result<Vec<u8>, SecureBlackboxError> 
fn set_user_ssh_key(&self, UserIndex : i32, value : Vec<u8>) ->  Option<SecureBlackboxError> 
fn set_user_ssh_key_ref(&self, UserIndex : i32, value : &[u8]) ->  Option<SecureBlackboxError> 

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.

Data Type

Vec

username property (OTPServer Struct)

The registered name (login) of the user.

Syntax

fn username(&self , UserIndex : i32) -> Result<String, SecureBlackboxError> 
fn set_username(&self, UserIndex : i32, value : &str) ->  Option<SecureBlackboxError> 
fn set_username_ref(&self, UserIndex : i32, value : &String) ->  Option<SecureBlackboxError> 

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.

Data Type

String

config method (OTPServer Struct)

Sets or retrieves a configuration setting.

Syntax

fn config(&self, configuration_string : &str) ->  Result<String, SecureBlackboxError>

Remarks

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

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

do_action method (OTPServer Struct)

Performs an additional action.

Syntax

fn do_action(&self, action_id : &str, action_params : &str) ->  Result<String, SecureBlackboxError>

Remarks

do_action is a generic method available in every struct. 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;....

Common ActionIDs:

is_hotp_password_valid method (OTPServer Struct)

Validates a hash-based one-time password.

Syntax

fn is_hotp_password_valid(&self, key_secret : &[u8], password_length : i32, counter : i32, password : &str) ->  Result<bool, SecureBlackboxError>

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.

is_password_valid method (OTPServer Struct)

Validates an OTP password for a user.

Syntax

fn is_password_valid(&self, username : &str, password : &str) ->  Result<bool, SecureBlackboxError>

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.

is_totp_password_valid method (OTPServer Struct)

Validates a time-based one-time password.

Syntax

fn is_totp_password_valid(&self, key_secret : &[u8], password_length : i32, time_interval : i32, hash_algorithm : &str, password : &str) ->  Result<bool, SecureBlackboxError>

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:

reset method (OTPServer Struct)

Resets the struct settings.

Syntax

fn reset(&self) -> Result<(), SecureBlackboxError>

Remarks

reset is a generic method available in every struct.

on_error event (OTPServer Struct)

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

Syntax

// OTPServerErrorEventArgs carries the OTPServer Error event's parameters.
pub struct OTPServerErrorEventArgs {
  fn error_code(&self) -> i32
  fn description(&self) -> &String
}

// OTPServerErrorEvent defines the signature of the OTPServer Error event's handler function.
pub trait OTPServerErrorEvent {
  fn on_error(&self, sender : OTPServer, e : &mut OTPServerErrorEventArgs);
}

impl <'a> OTPServer<'a> {
  pub fn on_error(&self) -> &'a dyn OTPServerErrorEvent;
  pub fn set_on_error(&mut self, value : &'a dyn OTPServerErrorEvent);
  ...
}

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.

on_notification event (OTPServer Struct)

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

Syntax

// OTPServerNotificationEventArgs carries the OTPServer Notification event's parameters.
pub struct OTPServerNotificationEventArgs {
  fn event_id(&self) -> &String
  fn event_param(&self) -> &String
}

// OTPServerNotificationEvent defines the signature of the OTPServer Notification event's handler function.
pub trait OTPServerNotificationEvent {
  fn on_notification(&self, sender : OTPServer, e : &mut OTPServerNotificationEventArgs);
}

impl <'a> OTPServer<'a> {
  pub fn on_notification(&self) -> &'a dyn OTPServerNotificationEvent;
  pub fn set_on_notification(&mut self, value : &'a dyn OTPServerNotificationEvent);
  ...
}

Remarks

The struct fires this event to let the application know about some event, occurrence, or milestone in the struct. 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 struct, the exact action it is performing, or the document being processed, one or both may be omitted.

Config Settings (OTPServer Struct)

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

Base Config Settings

Trappable Errors (OTPServer Struct)

OTPServer Errors