ExkPasswd.Random (ExkPasswd v0.1.1)

View Source

Cryptographically secure random number generation utilities.

This module provides secure random selection and generation functions using :crypto.strong_rand_bytes/1 to ensure all randomness is cryptographically secure and suitable for password generation.

Security

NEVER use :rand module or Enum.random/1 for password generation. These functions use predictable pseudo-random number generators that are NOT suitable for security-critical applications.

All functions in this module use :crypto.strong_rand_bytes/1 which provides cryptographically secure randomness backed by the operating system's secure random number generator.

Examples

iex> value = ExkPasswd.Random.select([1, 2, 3, 4, 5])
...> value in [1, 2, 3, 4, 5]
true

iex> n = ExkPasswd.Random.integer(100)
...> n >= 0 and n < 100
true

iex> is_boolean(ExkPasswd.Random.boolean())
true

Summary

Functions

boolean()

Generates a cryptographically secure random boolean.

integer(max)

Generates a cryptographically secure random integer between 0 and max-1.

integer_between(min, max)

Generates a cryptographically secure random integer in a range.

select(enumerable)

Securely selects a random element from an enumerable.

Functions

boolean()

@spec boolean() :: boolean()

Generates a cryptographically secure random boolean.

Returns

true or false with equal probability.

Examples

iex> is_boolean(ExkPasswd.Random.boolean())
true

integer(max)

@spec integer(pos_integer()) :: non_neg_integer()

Generates a cryptographically secure random integer between 0 and max-1.

Uses :crypto.strong_rand_bytes/1 with rejection sampling to eliminate modulo bias and ensure uniform distribution.

Security

This function uses rejection sampling to avoid modulo bias. When max doesn't evenly divide 2^32, naive modulo creates statistical bias where some values appear more frequently. This implementation rejects biased values and retries.

Performance: Rejection rate is ~(max/2^32), negligible for all practical values.

Parameters

  • max - Upper bound (exclusive). Must be a positive integer.

Returns

A random integer n where 0 <= n < max.

Examples

iex> n = ExkPasswd.Random.integer(10)
...> n >= 0 and n < 10
true

iex> n = ExkPasswd.Random.integer(1)
...> n
0

integer_between(min, max)

@spec integer_between(integer(), integer()) :: integer()

Generates a cryptographically secure random integer in a range.

Parameters

  • min - Lower bound (inclusive)
  • max - Upper bound (inclusive)

Returns

A random integer n where min <= n <= max.

Examples

iex> n = ExkPasswd.Random.integer_between(5, 10)
...> n >= 5 and n <= 10
true

iex> ExkPasswd.Random.integer_between(7, 7)
7

select(enumerable)

@spec select(Enum.t()) :: any() | nil

Securely selects a random element from an enumerable.

Returns nil if the enumerable is empty.

Parameters

  • enumerable - Any enumerable (list, range, etc.)

Returns

A randomly selected element, or nil if empty.

Examples

iex> value = ExkPasswd.Random.select([1, 2, 3])
...> value in [1, 2, 3]
true

iex> ExkPasswd.Random.select([])
nil

iex> value = ExkPasswd.Random.select(1..5)
...> value in 1..5
true