What the Class Is Used For

Use Chilkat.Prng when an application needs random bytes or random text values for cryptographic or application-level purposes. The class can seed itself automatically from the system entropy source, accept additional entropy from the application, and produce random data in raw byte form, encoded string form, or higher-level formats such as passwords and Firebase Push IDs.

Generate Random Bytes Produce random bytes as a byte array, encoded string, or append them directly to BinData.

Manage Entropy Add entropy, read entropy from the system, export accumulated entropy, and import it again after restart.

Create Random Text Generate random strings, random passwords, and random integers within an inclusive range.

Support Repeatable Tests Add non-random entropy intentionally when deterministic pseudo-random sequences are useful for testing and debugging.

Typical Workflow

Create a Prng object.
Optionally call GetEntropy or GetEntropyBytes to read entropy from the operating system.
Optionally add seed material with AddEntropy or AddEntropyBytes.
Generate random bytes with GenRandom, GenRandomBytes, or GenRandomBd.
Generate higher-level values with RandomInt, RandomString, RandomPassword, or FirebasePushId.
For long-running systems, optionally export entropy with ExportEntropy and import it after restart with ImportEntropy.
Check LastErrorText after failures or unexpected behavior.

Core Concepts

Concept	Meaning	Important Members
PRNG	A pseudo-random number generator produces random-looking bytes from an internal state that is seeded with entropy.	PrngName, GenRandom, GenRandomBytes
Fortuna	The selected PRNG algorithm. The current default and only valid PrngName value is fortuna.	PrngName
Entropy	Seed material added to the PRNG. It may come from the operating system or from application-provided sources.	GetEntropy, AddEntropy, ExportEntropy
Automatic Seeding	If no entropy has been explicitly added before the first random-generation call, Chilkat automatically adds 32 bytes of entropy from the system source.	GenRandom, GenRandomBd, GenRandomBytes
Binary Encoding	Random bytes and entropy can be represented as encoded text, such as hex or base64.	GenRandom, GetEntropy, AddEntropy
Persisted Entropy	Accumulated entropy can be exported before shutdown and imported after restart so the PRNG has useful seed material immediately.	ExportEntropy, ImportEntropy

Core Properties

Property	Purpose	Guidance
PrngName	Name of the selected PRNG algorithm.	The default and only currently valid value is fortuna. Assigning any other value is ignored until additional PRNG algorithms are added in the future.
LastErrorText	Diagnostic text for the last method or property access.	Check after failures or unexpected results. Diagnostic information may be available regardless of success or failure.

Entropy Management

Task	Method	Behavior
Add encoded entropy	AddEntropy	Adds entropy bytes supplied as encoded text, using an encoding such as hex or base64.
Add raw entropy bytes	AddEntropyBytes	Adds entropy from a byte array.
Read system entropy as encoded text	GetEntropy	Reads entropy from the operating-system source and returns it using the requested encoding.
Read system entropy as bytes	GetEntropyBytes	Reads entropy from the operating-system source and returns it as a byte array.
Export accumulated entropy	ExportEntropy	Exports accumulated entropy as a Base64 string. Internally, the entropy pools are re-hashed before export.
Import previously exported entropy	ImportEntropy	Imports entropy previously produced by ExportEntropy.

Initial seeding recommendation: The documentation recommends retrieving no more than 32 bytes of entropy to initially seed a PRNG. Larger amounts are generally not useful, although long-running applications may periodically add additional entropy.

System Entropy Sources

Platform	Entropy Source Used by GetEntropy / GetEntropyBytes
Linux / Unix / macOS	Reads from /dev/random.
Windows	Uses the Microsoft Cryptographic Service Provider’s CryptGenRandom method.

Automatic fallback: If the application does not explicitly add entropy before the first random-byte generation call, Chilkat automatically adds 32 bytes from the system entropy source to seed the PRNG.

Generating Random Bytes

Output Form	Method	Use When
Encoded string	GenRandom	Returns numBytes random bytes encoded as text, using an encoding such as hex or base64.
Byte array	GenRandomBytes	Returns numBytes random bytes directly.
Append to BinData	GenRandomBd	Appends numBytes random bytes to an existing BinData object.

Encoding note: Encoded methods use the encoding argument supplied to the method, such as hex, base64, or another supported binary encoding.

Generating Random Text and IDs

Need	Method	Behavior
Random integer	RandomInt	Returns an integer between low and high, inclusive.
Random string	RandomString	Generates a string of the requested length using selected character classes: digits, lowercase ASCII, and/or uppercase ASCII.
Random password	RandomPassword	Generates a password with optional requirements for digits, upper/lowercase letters, required special characters, and excluded characters.
Firebase Push ID	FirebasePushId	Generates a random Firebase Push ID.

RandomPassword Options

Argument	Purpose	Example / Guidance
length	Length of the generated password.	Choose the required number of characters.
mustIncludeDigit	Requires at least one digit.	When true, at least one of 0-9 is included.
upperAndLowercase	Requires both lowercase and uppercase ASCII characters.	Uses a-z and A-Z.
mustHaveOneOf	Set of non-alphanumeric characters, one of which must appear.	Example: !@#$%.
excludeChars	Characters that should not appear in the generated password.	Useful for excluding visually similar characters such as i, l, 1, L, o, 0, and O.

RandomString Options

Argument	Character Class	Included When
bDigits	Digits 0-9	Set to true.
bLower	Lowercase ASCII a-z	Set to true.
bUpper	Uppercase ASCII A-Z	Set to true.

Character-set reminder: RandomString only uses the selected digit, lowercase ASCII, and uppercase ASCII character groups.

Persisting Entropy Across Restarts

ExportEntropy and ImportEntropy allow an application to preserve useful PRNG seed material across application or system restarts.

Step	Method	Purpose
Before shutdown	ExportEntropy	Export accumulated entropy as a Base64 string and store it in a file, database, or other persistent location.
After startup	ImportEntropy	Import the previously exported entropy so adequate seed material is immediately available.
After import	GetEntropy + AddEntropy	Optionally add fresh entropy from the system source before generating random data.

Export safety note: The documentation states that when entropy is exported, the internal entropy pools are re-hashed so that the PRNG state cannot be determined from the exported entropy alone.

Deterministic Testing

The class allows entropy to be supplied by the application. In production this should be real entropy, but for testing an application may intentionally add non-random entropy to reproduce the same pseudo-random sequence.

Use Case	Method	Reason
Repeatable tests	AddEntropy, AddEntropyBytes	Supplying the same seed material can help reproduce test and debugging scenarios.
Normal production randomness	GetEntropy, GetEntropyBytes, automatic seeding	Use system entropy or automatic seeding rather than fixed test values.

Testing vs production: Non-random entropy is useful for repeatable tests, but production code should use real entropy from the system or another appropriate entropy source.

Method Summary

Category	Methods	Purpose
Entropy input	AddEntropy, AddEntropyBytes	Add seed material to the PRNG.
System entropy	GetEntropy, GetEntropyBytes	Read real entropy bytes from the operating system.
Entropy persistence	ExportEntropy, ImportEntropy	Save and restore accumulated entropy across restarts.
Random bytes	GenRandom, GenRandomBytes, GenRandomBd	Generate random bytes as encoded text, a byte array, or appended BinData.
Random values	RandomInt, RandomString, RandomPassword	Generate application-friendly random integers, strings, and passwords.
Firebase ID	FirebasePushId	Generate a random Firebase Push ID.

Diagnostics and Troubleshooting

Problem Area	Member	What to Check
General method failure	LastErrorText	Check after failed entropy import, entropy reading, random byte generation, or other unexpected behavior.
Unexpected PRNG selection	PrngName	The only currently valid value is fortuna. Assigning another value is ignored.
Encoded entropy cannot be added	AddEntropy	Confirm the entropy text matches the specified encoding, such as hex or base64.
Encoded random output is not in the expected format	GenRandom	Confirm the encoding argument passed to the method.
Password does not include expected character type	RandomPassword	Check mustIncludeDigit, upperAndLowercase, mustHaveOneOf, and excludeChars.
Random string lacks desired characters	RandomString	Make sure at least one of bDigits, bLower, or bUpper is enabled.

Common Pitfalls

Pitfall	Better Approach
Trying to select a PRNG algorithm other than Fortuna.	Leave PrngName at its default value. Currently, fortuna is the only valid choice.
Requesting excessive entropy for initial seeding.	Follow the documentation’s recommendation of no more than 32 bytes for initial seeding.
Using fixed, non-random entropy in production.	Fixed entropy is useful for repeatable tests, but production code should use real entropy sources.
Forgetting that RandomInt is inclusive.	The returned value can be equal to either low or high.
Using a password exclusion list that removes required characters.	Ensure excludeChars does not conflict with required digit, uppercase/lowercase, or special-character settings.
Assuming exported entropy is a replacement for fresh system entropy.	Import persisted entropy on startup, then optionally add fresh system entropy before generating random data.

Best Practices

Recommendation	Reason
Let the PRNG auto-seed when simple random generation is needed.	If no entropy was explicitly added, Chilkat automatically adds 32 bytes from the system source before generating random bytes.
Use GetEntropy / AddEntropy when explicit seeding is desired.	This gives the application control over when and how entropy is added.
Persist entropy for services or long-running applications.	ExportEntropy and ImportEntropy help make seed material available immediately after restart.
Use explicit encodings for random bytes and entropy strings.	Passing hex, base64, or another encoding clearly defines how binary data is represented as text.
Use RandomPassword for password-specific rules.	It can enforce digits, mixed case, required special characters, and excluded ambiguous characters.
Use GenRandomBytes or GenRandomBd when raw binary random data is needed.	These avoid unnecessary text encoding when the result will be used as bytes.
Check LastErrorText after failures.	It provides the most useful diagnostic detail for entropy, random generation, import/export, and password/string generation issues.

Summary

Chilkat.Prng is a Fortuna-based pseudo-random number generator for generating random bytes, strings, integers, passwords, and Firebase Push IDs. It can read entropy from the operating system, accept application-supplied entropy, automatically seed itself when needed, and export/import accumulated entropy for use across restarts.

For most applications, the simplest pattern is to create a Prng object and call GenRandom, GenRandomBytes, or a higher-level helper. For services and long-running applications, consider persisting entropy with ExportEntropy and restoring it with ImportEntropy.

Chilkat.Prng Class Overview