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

Deprecated: Explicitly use 1.0eNN instead.

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 entropy_bits(total, risk)

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
Link to this function large_id(charset \\ 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_id(charSet)
"NqJLbG8htr4t64TQmRDB"
Link to this function medium_id(charset \\ 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_id(charSet)
"nndQjL7FLR9pDd"
Link to this function random_string(bits, charset \\ EntropyString.CharSet.charset32())

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} 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.

Default CharSet is charset32.

Example

A million potential base32 strings with a 1 in a billion chance of a repeat

bits = EntropyString.entropy_bits(1.0e6, 1.0e9)
charSet = EntropyString.CharSet.charset32
string = EntropyString.random_string(bits, charSet)

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

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} 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.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.

Link to this function session_id(charset \\ CharSet.charset32())

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

Default CharSet is charset32.

Example

EntropyString.session_id(charSet)
"6pLfLgfL8MgTn7tQDN8tqPFR4b"
Link to this function small_id(charset \\ 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_id
"nGrqnt"

Deprecated: Explicitly use 1.0eNN instead.

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
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"
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