ExkPasswd.Random (ExkPasswd v0.3.0)

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 reads enough bytes to represent the requested range, then uses rejection sampling. This avoids the statistical bias introduced by reducing every random value with rem/2.

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