Prng Chilkat2 Perl Reference Documentation
Chilkat2::Prng
Current Version: 11.7.0
Markdown version of this page for AI tools (v 11.7.0) · all AI docs
Chilkat.Prng
Use
Generate random byte data for keys, IVs, nonces, salts, tokens, test
data, or protocol-specific binary values.
Produce random values encoded as Base64, hex, URL-safe text, or other
supported encodings when binary data must be represented as text.
Create random passwords using configurable character sets and length
requirements.
Allow the PRNG to seed from the system entropy source and optionally add
application-provided entropy.
Generate random integers, booleans, GUID-style values, and other
convenient random outputs for application logic.
Create Firebase-style push IDs for applications that need sortable,
client-generated identifiers.
For an extended overview, see
Prng Class Overview.
Generate random bytes, encoded values, passwords, and application identifiers.
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 as raw
bytes, encoded strings, passwords, integers, booleans, GUID-style values, or
higher-level identifiers such as Firebase Push IDs.
Random bytes
Encoded random strings
Password generation
Entropy input
Random application values
Firebase Push IDs
Prng to create random material in the form required by the
caller: bytes for cryptographic inputs, encoded strings for tokens or API
values, passwords for user-facing credentials, or Firebase Push IDs for
sortable identifiers. For cryptographic workflows, generate enough random
bytes for the algorithm or protocol and avoid reducing randomness by
truncating or reformatting values incorrectly.
Object Creation
use Chilkat2;
my $prng = Chilkat2::Prng->new;
# or set properties (and RaiseError) at creation:
# my $prng = Chilkat2::Prng->new(VerboseLogging => 1, RaiseError => 1);Creates the object. The optional pairs set writable properties (and RaiseError) in order, as if set one by one; an unknown or read-only name croaks. use Chilkat2; loads every class; the Chilkat2/Prng.pm file holds only this class's documentation (perldoc Chilkat2::Prng).
Perl frees the object when its last reference goes (undef $prng, or the variable going out of scope); there is nothing to close. Objects returned by methods are independent and freed the same way. The class may be subclassed (use parent -norequire, 'Chilkat2::Prng';): an object is a blessed hash reference whose hash is free for the subclass's own fields.
When false (the default), a method that fails returns false (or undef), and the reason is in LastErrorText. When true, it dies with a Chilkat2::Error instead, as DBI does with its RaiseError. Objects returned by a method inherit the value of the object that returned them.
Errors
A Chilkat2::Error stringifies to the failed call's full LastErrorText, and has the methods text, class ('Chilkat2::Prng'), method (the method name) and object. Methods that look something up and find nothing return undef without dying (each such method says so), methods that answer a question (HasMember, IsUnlocked, ...) return a plain boolean, and property reads and writes never fail for Chilkat reasons.
Misuse always croaks, with your file and line, whatever RaiseError is: a wrong number of arguments, a reference or undef where a string or number is expected, an object of the wrong class, an out-of-range integer, a string containing a NUL character, a wide character in a byte string, or a write to a read-only property.
Strings are Perl character strings in both directions (length, regexes and :encoding layers see characters); binary data (BinData) is a byte string. Unlocking: call Chilkat2::Global->new->UnlockBundle('...') once at startup.
Properties
DebugLogFilePath
my $strVal = $prng->DebugLogFilePath;
$prng->DebugLogFilePath($strVal);
If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. This logging helps identify the context and history of Chilkat calls leading up to any crash or hang, aiding in debugging.
Enabling the VerboseLogging property provides more detailed information. This property is mainly used for debugging rare instances where a Chilkat method call causes a hang or crash, which should generally not happen.
Possible causes of hangs include:
- A timeout property set to 0, indicating an infinite timeout.
- A hang occurring within an event callback in the application code.
- An internal bug in the Chilkat code causing the hang.
LastErrorHtml
my $strVal = $prng->LastErrorHtml;
Provides HTML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
topLastErrorText
my $strVal = $prng->LastErrorText;
Provides plain text information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
LastErrorXml
my $strVal = $prng->LastErrorXml;
Provides XML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
topLastMethodSuccess
my $boolVal = $prng->LastMethodSuccess;
$prng->LastMethodSuccess($boolVal);
Indicates the success or failure of the most recent method call: 1 means success, 0 means failure. This property remains unchanged by property setters or getters. This method is present to address challenges in checking for null or Nothing returns in certain programming languages. Note: This property does not apply to methods that return integer values or to boolean-returning methods where the boolean does not indicate success or failure.
PrngName
my $strVal = $prng->PrngName;
$prng->PrngName($strVal);
Selects the pseudo-random number generator used by this object. The only supported value is fortuna, which is also the default. Chilkat's Fortuna implementation uses AES-256 for generation and SHA-256 in its entropy-processing and reseeding design.
fortuna is ignored. Applications should normally leave this property unchanged.VerboseLogging
my $boolVal = $prng->VerboseLogging;
$prng->VerboseLogging($boolVal);
If set to 1, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is 0. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.
Version
my $strVal = $prng->Version;
Methods
AddEntropy
# $encoding is a string
# $success is true or false
my $success = $prng->AddEntropy($entropy, $encoding);
Adds caller-supplied seed material to the PRNG. $entropy$encodinghex, base64, or ascii. For Fortuna, the decoded bytes are incorporated into the internal entropy pools and become available to later reseeding.
This method is optional and is not the normal way an application obtains entropy for the PRNG. It may be called more than once and at any point during the lifetime of the object. It returns 1 when the input is decoded and accepted, or 0 if the encoding is invalid or another error occurs.
AddEntropy only when the application has additional trustworthy entropy to contribute or deliberately needs deterministic seeding for testing.Prng object can be seeded with the same deterministic values to reproduce the same output sequence, provided the same entropy calls and random-generation calls occur in the same order. Predictable seed material is appropriate only for tests and debugging. Do not use it for real keys, nonces, passwords, or tokens.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
ExportEntropy
my $str = $prng->ExportEntropy();
Exports a Base64-encoded value derived from the PRNG's accumulated entropy pools. The internal pools are rehashed for export so the returned value is not a direct disclosure of the generator state.
The returned value can be persisted and supplied to ImportEntropy when a later process starts. For language bindings in which this method directly returns a string, check LastMethodSuccess before using the result.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
FirebasePushId
my $str = $prng->FirebasePushId();
Generates a Firebase-compatible push ID. A push ID is a 20-character identifier built from a 48-bit millisecond timestamp followed by 72 bits of randomness, encoded with Firebase's ordered 64-character alphabet.
The timestamp prefix makes push IDs sort approximately by creation time, while the random portion makes collisions highly unlikely across independent clients. For language bindings in which this method directly returns a string, check LastMethodSuccess before using the result.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GenRandom
# $encoding is a string
# $str is a string or undef
my $str = $prng->GenRandom($numBytes, $encoding);
Generates $numBytes$encodinghex, base64, or base64url. $numBytes
If no entropy has been added before the first request for random output, Chilkat automatically obtains 32 bytes from the platform's cryptographic system entropy source to seed the PRNG.
For language bindings in which this method directly returns a string, check LastMethodSuccess before using the result.
numBytes from the security requirement of the key, nonce, salt, or token—not from the desired text length.Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GenRandomBd
# $bd is a Chilkat2::BinData
# $success is true or false
my $success = $prng->GenRandomBd($numBytes, $bd);
Generates $numBytesBinData object passed in $bd
If no entropy has been added before the first request for random output, Chilkat automatically obtains 32 bytes from the platform's cryptographic system entropy source to seed the PRNG.
Returns 1 on success or 0 on failure.
BinData.Clear first when the destination should contain only the newly generated bytes.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GetEntropy
# $encoding is a string
# $str is a string or undef
my $str = $prng->GetEntropy($numBytes, $encoding);
Requests $numBytes$encodingGenRandom.
For seeding this PRNG, 32 bytes normally provide the full 256-bit seed input expected by the implementation. Applications may request another amount when a protocol specifically requires raw bytes from the system source.
For language bindings in which this method directly returns a string, check LastMethodSuccess before using the result.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
ImportEntropy
# $success is true or false
my $success = $prng->ImportEntropy($entropy);
Imports the Base64-encoded entropy value previously returned by ExportEntropy. The imported material is supplied to the PRNG for use in its entropy and reseeding process.
Returns 1 if the value is valid and imported successfully. Returns 0 if it cannot be decoded or imported; check LastErrorText for details.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
RandomInt
# $high is an integer
# $n is an integer
my $n = $prng->RandomInt($low, $high);
Returns a pseudorandom integer in the inclusive range from $low$highRandomInt(4, 8) can return 4, 5, 6, 7, or 8.
The caller should ensure that $low$high
GenRandom, GenRandomBytes, or GenRandomBd when a protocol requires an exact number of random bytes. Do not assemble keys or nonces from decimal random integers unless the protocol explicitly defines that representation.RandomPassword
# $mustIncludeDigit is a boolean
# $upperAndLowercase is a boolean
# $mustHaveOneOf is a string
# $excludeChars is a string
# $str is a string or undef
my $str = $prng->RandomPassword($length, $mustIncludeDigit, $upperAndLowercase, $mustHaveOneOf, $excludeChars);
Generates a password of exactly $length
| Argument | Effect |
|---|---|
| When 1, require at least one digit from 0-9. |
| When 1, require at least one lowercase and at least one uppercase US-ASCII letter. |
| When nonempty, require at least one character from this supplied set, such as !@#$%. |
| Exclude every listed character from the generated password. This is useful for ambiguous characters such as iIlL1oO0. |
The requested length must be large enough to satisfy all enabled requirements, and exclusions must not remove every usable character from a required category. For language bindings in which this method directly returns a string, check LastMethodSuccess before using the result.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
RandomString
# $bDigits is a boolean
# $bLower is a boolean
# $bUpper is a boolean
# $str is a string or undef
my $str = $prng->RandomString($length, $bDigits, $bLower, $bUpper);
Generates a string of exactly $length
| Argument | When 1 |
|---|---|
| Include digits 0-9. |
| Include lowercase ASCII letters a-z. |
| Include uppercase ASCII letters A-Z. |
At least one character category must be enabled. The flags define the pool from which each character is chosen; they do not guarantee that every enabled category appears in a particular result.
RandomPassword instead when the result must contain at least one digit, both uppercase and lowercase letters, or a required special character.Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.