Rnd Class

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

Rnd

Remarks

Use Rnd control to generate pseudo-random numbers or sequences. Methods like NextBytes and NextInt return the next PRNG output, whereas SeedBytes or SeedInt 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. RND random = new RND(); // Random password System.out.println(random.nextPass(true,true,true,true,16)); // Output: O7#}?XL26#Gy8aYS // Generating a hex string random.setAlphabet("abcdef1234567890"); // Setting the characters to create a hex string System.out.println(random.nextString(16)); // Output: 8b40f2e93427286b

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

Alphabet to use for random string generation.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetAlphabet();
int SetAlphabet(const char* lpszAlphabet);

Unicode (Windows)
LPWSTR GetAlphabet();
INT SetAlphabet(LPCWSTR lpszAlphabet);

char* secureblackbox_rnd_getalphabet(void* lpObj);
int secureblackbox_rnd_setalphabet(void* lpObj, const char* lpszAlphabet);

QString GetAlphabet();
int SetAlphabet(QString qsAlphabet);

Default Value

""

Remarks

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

Data Type

String

FIPSMode Property (Rnd 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_rnd_getfipsmode(void* lpObj);
int secureblackbox_rnd_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

Source Property (Rnd Class)

Sets the source of random data.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSource();
int SetSource(int iSource);

Unicode (Windows)
INT GetSource();
INT SetSource(INT iSource);

RND_UNKNOWN(0), 
RND_BUILT_IN(1), 
RND_SYSTEM(2), 
RND_BOTH(3)

int secureblackbox_rnd_getsource(void* lpObj);
int secureblackbox_rnd_setsource(void* lpObj, int iSource);

int GetSource();
int SetSource(int iSource);

Default Value

3

Remarks

Use this property to specify the source of random data to be used by the class.

Data Type

Integer

Config Method (Rnd 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_rnd_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 (Rnd 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_rnd_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.

NextBytes Method (Rnd Class)

Generates an array of random bytes.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* NextBytes(int iLen, int *lpSize = NULL);

Unicode (Windows)
LPSTR NextBytes(INT iLen, LPINT lpSize = NULL);

char* secureblackbox_rnd_nextbytes(void* lpObj, int iLen, int *lpSize);

QByteArray NextBytes(int iLen);

Remarks

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

Error Handling (C++)

This method returns a Byte Array value (with length lpSize); 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.

NextInt Method (Rnd Class)

Generates a random integer.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int NextInt();

Unicode (Windows)
INT NextInt();

int secureblackbox_rnd_nextint(void* lpObj);

int NextInt();

Remarks

Use this method to generate a random integer value.

Error Handling (C++)

This method returns an Integer 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.

NextPass Method (Rnd Class)

Generates a random password.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* NextPass(int bLowercase, int bUppercase, int bDigits, int bSpecials, int iLen);

Unicode (Windows)
LPWSTR NextPass(BOOL bLowercase, BOOL bUppercase, BOOL bDigits, BOOL bSpecials, INT iLen);

char* secureblackbox_rnd_nextpass(void* lpObj, int bLowercase, int bUppercase, int bDigits, int bSpecials, int iLen);

QString NextPass(bool bLowercase, bool bUppercase, bool bDigits, bool bSpecials, int iLen);

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.

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.

NextString Method (Rnd Class)

Generates a random string of characters.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* NextString(int iLen);

Unicode (Windows)
LPWSTR NextString(INT iLen);

char* secureblackbox_rnd_nextstring(void* lpObj, int iLen);

QString NextString(int iLen);

Remarks

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

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.

Randomize Method (Rnd Class)

Seeds the random generator with a system-originating input.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Randomize();

Unicode (Windows)
INT Randomize();

int secureblackbox_rnd_randomize(void* lpObj);

int Randomize();

Remarks

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

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

Reset Method (Rnd Class)

Resets the class settings.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Reset();

Unicode (Windows)
INT Reset();

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

SeedBytes Method (Rnd Class)

Seeds the generator with a data in a byte array.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SeedBytes(const char* lpValue, int lenValue);

Unicode (Windows)
INT SeedBytes(LPCSTR lpValue, INT lenValue);

int secureblackbox_rnd_seedbytes(void* lpObj, const char* lpValue, int lenValue);

int SeedBytes(QByteArray qbaValue);

Remarks

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

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

SeedInt Method (Rnd Class)

Seeds the generator with an integer value.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SeedInt(int iIntValue);

Unicode (Windows)
INT SeedInt(INT iIntValue);

int secureblackbox_rnd_seedint(void* lpObj, int iIntValue);

int SeedInt(int iIntValue);

Remarks

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

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

SeedString Method (Rnd Class)

Seeds the generator with a string value.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SeedString(const char* lpszStrValue);

Unicode (Windows)
INT SeedString(LPCWSTR lpszStrValue);

int secureblackbox_rnd_seedstring(void* lpObj, const char* lpszStrValue);

int SeedString(const QString& qsStrValue);

Remarks

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

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

SeedTime Method (Rnd Class)

Seeds the generator with current time.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SeedTime();

Unicode (Windows)
INT SeedTime();

int secureblackbox_rnd_seedtime(void* lpObj);

int SeedTime();

Remarks

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

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

Informs about errors during cryptographic operations.

Syntax

• C++
• C
• Qt

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

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


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

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

#define EID_RND_ERROR 1

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

class RndErrorEventParams {
public:
  int ErrorCode();

  const QString &Description();

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

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

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

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.

Notification Event (Rnd Class)

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

Syntax

• C++
• C
• Qt

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

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


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

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

#define EID_RND_NOTIFICATION 2

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

class RndNotificationEventParams {
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(RndNotificationEventParams *e);

// Or, subclass Rnd and override this emitter function.
virtual int FireNotification(RndNotificationEventParams *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.

Config Settings (Rnd Class)

Base Config Settings

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

Rnd Errors