entropy_string v1.1.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

Deprecated: Use bits/2 instead

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

Link to this function bits(total, risk)

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
Link to this function entropy_bits(total, risk)

Deprecated: Use bits/2 instead

Link to this function large(charset \\ :charset32)

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"
Link to this function large_id(charset \\ CharSet.charset32())

Deprecated: Use large/1 instead

Link to this function medium(charset \\ :charset32)

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"
Link to this function medium_id(charset \\ CharSet.charset32())

Deprecated: Use medium/1 instead

Link to this function random(bits, charset \\ :charset32)

Random string of entropy bits using charset characters

Returns string of at least entropy bits using characters from charset; or

  • {:error, "Negative entropy"} if bits is negative.
  • {:error, reason} if EntropyString.CharSet.validate(charset) is not true.

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"
Link to this function random(bits, charset, bytes)

Random string of entropy bits using charset characters and specified bytes

Returns random string of at least entropy bits; or

  • {:error, "Negative entropy"} if bits is negative.
  • {:error, reason} if EntropyString.CharSet.validate(charset) is not true.
  • {:error, reason} if validate_byte_count(bits, charset, bytes) is not true.

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.

Link to this function random_string(bits, charset \\ EntropyString.CharSet.charset32())

Deprecated: Use random/2 instead

Link to this function random_string(bits, charset, bytes)

Deprecated: Use random/3 instead

Link to this function session(charset \\ :charset32)

Random string using charset characters suitable for 128-bit OWASP Session ID

Default CharSet is charset32.

Example

EntropyString.session()
"6pLfLgfL8MgTn7tQDN8tqPFR4b"

EntropyString.session(:charset64)
"VzhprMROlM6Iy2Pk1IRCqR"
Link to this function session_id(charset \\ CharSet.charset32())

Deprecated: Use session/1 instead

Link to this function small(charset \\ :charset32)

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"
Link to this function small_id(charset \\ CharSet.charset32())

Deprecated: Use small/1 instead

Link to this function token(charset \\ CharSet.charset64())

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"
Link to this function validate_byte_count(bits, charset, bytes)

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