entropy_string v1.0.0 EntropyString
Efficiently generate cryptographically strong random strings of specified entropy from various character sets.
Example
Ten thousand potential hexidecimal strings with a 1 in 10 million chance of repeat
bits = EntropyString.Entropy.bits(10000, 10000000)
charSet = EntropyString.CharSet.charset16
string = EntropyString.random_string(bits, charSet)
"9e9b34d6f69ea"
Link to this section Summary
Functions
Entropy bits required for total number of strings with a given risk
Random string using charset characters with a 1 in a trillion chance of repeat for a potential of a billion strings
Random string using charset characters with a 1 in a billion chance of repeat for a potential of a million strings
Random string of entropy bits using charset characters
Random string of entropy bits using charset characters and specified bytes
Random string using charset characters suitable for 128-bit OWASP Session ID
Random string using charset characters with a 1 in a million chance of repeat for a potential of 30 strings
Convenience for specifying total number of strings or acceptable associated risk as power of ten
Random string using charset characters with 256 entropy bits
Validate number of bytes is sufficient to generate random strings with entropy bits using charset
Link to this section Functions
Entropy bits required for total number of strings with a given risk
- total - potential number of strings
- risk - risk of repeat in total strings
Example
Entropy bits required for 30 strings with a 1 in a million chance of repeat
iex> import EntropyString, only: [entropy_bits: 2]
iex> bits = entropy_bits(30, 1000000)
iex> round(bits)
29
Random string using charset characters with a 1 in a trillion chance of repeat for a potential of a billion strings.
Default CharSet is CharSet.charset32
.
Example
charSet = EntropyString.CharSet.charset32
large_id = EntropyString.small_id(charSet)
"NqJLbG8htr4t64TQmRDB"
Random string using charset characters with a 1 in a billion chance of repeat for a potential of a million strings.
Example
charSet = EntropyString.CharSet.charset32
medium_id = EntropyString.small_id(charSet)
"nndQjL7FLR9pDd"
Random string of entropy bits using charset characters
- bits - entropy bits for string
- charset - CharSet to use
Returns string of at least entropy bits using characters from charset; or
{:error, "Negative entropy"}
if bits is negative.{:error, reason}
ifEntropyString.CharSet.validate(charset)
is nottrue
.
Since the generated random strings carry an entropy that is a multiple of the bits per character for charset, the returned entropy is the minimum that equals or exceeds the specified bits.
Default CharSet is CharSet.charset32
.
Example
A million potential base32 strings with a 1 in a billion chance of a repeat
total = EntropyString.ten_p(6)
risk = EntropyString.ten_p(9)
bits = EntropyString.entropy_bits(total, risk)
charSet = EntropyString.CharSet.charset32
string = EntropyString.random_string(bits, charSet)
"NbMbLrj9fBbQP6"
Random string of entropy bits using charset characters and specified bytes
- bits - entropy bits for string
- charset - CharSet to use
- bytes - Bytes to use
Returns random string of at least entropy bits; or
{:error, "Negative entropy"}
if bits is negative.{:error, reason}
ifEntropyString.CharSet.validate(charset)
is nottrue
.{:error, reason}
ifvalidate_byte_count(bits, charset, bytes)
is nottrue
.
Since the generated random strings carry an entropy that is a multiple of the bits per character for charset, the returned entropy is the minimum that equals or exceeds the specified bits.
Example
30 potential random hex strings with a 1 in a million chance of a repeat
iex> bits = EntropyString.entropy_bits(30, 1000000)
iex> charSet = EntropyString.CharSet.charset16
iex> bytes = <<14, 201, 32, 143>>
iex> EntropyString.random_string(bits, charSet, bytes)
"0ec9208f"
Use EntropyString.CharSet.bytes_needed(bits, charset)
to determine how many bytes are
actually needed.
Random string using charset characters suitable for 128-bit OWASP Session ID
Example
charSet = EntropyString.CharSet.charset32
session_id = EntropyString.session_id(charSet)
"6pLfLgfL8MgTn7tQDN8tqPFR4b"
Random string using charset characters with a 1 in a million chance of repeat for a potential of 30 strings.
Default CharSet is CharSet.charset32
.
Example
charSet = EntropyString.CharSet.charset32
small_id = EntropyString.small_id(charSet)
"nGrqnt"
Convenience for specifying total number of strings or acceptable associated risk as power of ten.
Example
iex> import EntropyString, only: [ten_p: 1]
iex> ten_p(12)
1.0e12
Random string using charset characters with 256 entropy bits.
Default CharSet is the base 64 URL and file system safe character set.
Example
token = EntropyString.token
"6pLfLgfL8MgTn7tQDN8tqPFR4b"
Validate number of bytes is sufficient to generate random strings with entropy bits using charset
- bits - entropy bits for random string
- charset - characters in use
- bytes - bytes to validate
Validations
- bytes count must be sufficient to generate entropy bits string from charset
Use EntropyString.CharSet.bytes_needed(bits, charset)
to determine how many bytes are needed