entropy_string v1.3.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.bits(10000, 10000000)
EntropyString.random(bits, :charset16)
"9e9b34d6f69ea"
Link to this section Summary
Functions
Bits of entropy 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 billion potential strings
Random string using charset characters with a 1 in a billion chance of repeat for a million potential 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 in 30 strings
Random string using charset characters with 256 bits of entropy
Validate number of bytes is sufficient to generate random strings with entropy bits using charset
Link to this section Functions
Bits of entropy required for total number of strings with a given risk
- total - potential number of strings
- risk - risk of repeat in total strings
Example
Bits of entropy for 30 strings with a 1 in a million chance of repeat
iex> import EntropyString, only: [bits: 2]
iex> bits = bits(30, 1000000)
iex> round(bits)
29
Random string using charset characters with a 1 in a trillion chance of repeat for a billion potential strings.
Default CharSet is charset32
.
Example
EntropyString.large()
"NqJLbG8htr4t64TQmRDB"
EntropyString.large(:charset16)
"f6c4d04cef266a5c3a7950f90"
Random string using charset characters with a 1 in a billion chance of repeat for a million potential strings.
Default CharSet is charset32
.
Example
EntropyString.medium()
"nndQjL7FLR9pDd"
EntropyString.medium(:charset16)
"b95d23b299eeb9bbe6"
Random string of entropy bits using charset characters
bits - entropy bits for string
- non-negative integer
- predefined atom
charset - CharSet to use
EntropyString.CharSet
- predefined atom
- Valid
String
representing the characters for theEntropyString.CharSet
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.
Examples
A million potential base32 strings with a 1 in a billion chance of a repeat
bits = EntropyString.bits(1.0e6, 1.0e9)
EntropyString.random(bits)
"NbMbLrj9fBbQP6"
A million potential hex strings with a 1 in a billion chance of a repeat
EntropyString.random(bits, :charset16)
"0746ae8fbaa2fb4d36"
A random session ID using URL and File System safe characters
EntropyString.random(:session, :charset64)
"txSdE3qBK2etQtLyCFNHGD"
Random string of entropy bits using charset characters and specified bytes
bits - entropy bits
- non-negative integer
- predefined atom
charset - CharSet to use
EntropyString.CharSet
- predefined atom
- Valid
String
representing the characters for theEntropyString.CharSet
- 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.bits(30, 1000000)
iex> bytes = <<14, 201, 32, 143>>
iex> EntropyString.random(bits, :charset16, 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
Default CharSet is charset32
.
Example
EntropyString.session()
"6pLfLgfL8MgTn7tQDN8tqPFR4b"
EntropyString.session(:charset64)
"VzhprMROlM6Iy2Pk1IRCqR"
Random string using charset characters with a 1 in a million chance of repeat in 30 strings.
Default CharSet is charset32
.
Example
EntropyString.small()
"nGrqnt"
EntropyString.small(:charset16)
"7bc250e5"
Random string using charset characters with 256 bits of entropy.
Default CharSet is the base 64 URL and file system safe character set.
Example
EntropyString.token()
"zHZ278Pv_GaOsmRYdBIR5uO8Tt0OWSESZbVuQye6grt"
EntropyString.token(:charset32)
"7fRgrB4JtqQB8gphhf8T7bppttJQqJ3PTPFjMjGQbhgJNR9FNNHD"
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