Rnd Class

Properties   Methods   Events   Config Settings   Errors  

The Rnd class class is a basic provider of random number generation functionality.

Syntax

class secureblackbox.Rnd

Remarks

Use Rnd control to generate pseudo-random numbers or sequences. Methods like next_bytes and next_int return the next PRNG output, whereas seed_bytes or seed_int seed the generator with outside entropy.

It is a good idea to use one shared (singleton) Rnd object per process, as it helps spread the entropy across many part of the project, resulting in better and more secure randomization.

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.

alphabet Property

Alphabet to use for random string generation.

Syntax

def get_alphabet() -> str: ...
def set_alphabet(value: str) -> None: ...

alphabet = property(get_alphabet, set_alphabet)

Default Value

""

Remarks

Use this property to provide a list of characters to be used by next_string method. The empty value has a special meaning, and is equivalent to 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'.

fips_mode Property

Reserved.

Syntax

def get_fips_mode() -> bool: ...
def set_fips_mode(value: bool) -> None: ...

fips_mode = property(get_fips_mode, set_fips_mode)

Default Value

FALSE

Remarks

This property is reserved for future use.

config Method

Sets or retrieves a configuration setting.

Syntax

def config(configuration_string: str) -> str: ...

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.

do_action Method

Performs an additional action.

Syntax

def do_action(action_id: str, action_params: str) -> str: ...

Remarks

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

next_bytes Method

Generates an array of random bytes.

Syntax

def next_bytes(len: int) -> bytes: ...

Remarks

Call this method to generate an array of random bytes of length Len.

next_int Method

Generates a random integer.

Syntax

def next_int() -> int: ...

Remarks

Use this method to generate a random integer value.

next_pass Method

Generates a random password.

Syntax

def next_pass(lowercase: bool, uppercase: bool, digits: bool, specials: bool, len: int) -> str: ...

Remarks

Use this method to generate a random password. Tune up the desired length and composition of the password using Lowercase, Uppercase, Digits, Specials, and Len parameters.

next_string Method

Generates a random string of characters.

Syntax

def next_string(len: int) -> str: ...

Remarks

Use this method to generate a random string using characters supplied via the alphabet property.

randomize Method

Seeds the random generator with a system-originating input.

Syntax

def randomize() -> None: ...

Remarks

Use this method to randomize the generator by seeding it with a system-produced random input.

seed_bytes Method

Seeds the generator with a data in a byte array.

Syntax

def seed_bytes(value: bytes) -> None: ...

Remarks

Use this method to seed the generator with data provided in a byte array.

seed_int Method

Seeds the generator with an integer value.

Syntax

def seed_int(int_value: int) -> None: ...

Remarks

Use this method to seed the generator with an integer value.

seed_string Method

Seeds the generator with a string value.

Syntax

def seed_string(str_value: str) -> None: ...

Remarks

Use this method to seed the generator with a string value.

seed_time Method

Seeds the generator with current time.

Syntax

def seed_time() -> None: ...

Remarks

Use this method to seed the generator with current system time.

on_error Event

Informs about errors during cryptographic operations.

Syntax

class RndErrorEventParams(object):
  @property
  def error_code() -> int: ...

  @property
  def description() -> str: ...

# In class Rnd:
@property
def on_error() -> Callable[[RndErrorEventParams], None]: ...
@on_error.setter
def on_error(event_hook: Callable[[RndErrorEventParams], None]) -> None: ...

Remarks

Class fires this event if an error happens during a cryptographic operation.

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

on_notification Event

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

Syntax

class RndNotificationEventParams(object):
  @property
  def event_id() -> str: ...

  @property
  def event_param() -> str: ...

# In class Rnd:
@property
def on_notification() -> Callable[[RndNotificationEventParams], None]: ...
@on_notification.setter
def on_notification(event_hook: Callable[[RndNotificationEventParams], None]) -> None: ...

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.

Rnd Config Settings

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.

Base Config Settings

Rnd Errors

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