GitHub

secure_random

API reference for secure_random.

Cryptographically secure random values as a service (Effect's effect/crypto/SecureRandom)::

random = yield from SecureRandom()
token = yield from random.random_bytes(32)
roll = yield from random.int_between(1, 6)
uuid = yield from random.uuid_v7()

make(random_bytes) builds the service from a source of random bytes; every other value is drawn from it. int_between rejects draws that would bias the result. uuid_v7 and ulid read the Clock and strictly increase per service, even when the clock moves back. layer_web_crypto draws from the WebCrypto reference. Bad sizes and empty or non-finite ranges are defects, as in Effect.

Values

AttributeTypeDescription
layer_web_cryptoLayer[SecureRandom]

Random bytes from the WebCrypto reference.

Types

TypeDefinitionDescription
UuidFormattype UuidFormat = Literal['string', 'bytes']

Classes

Functions

int_between_unsafe

int_between_unsafe(low, high, half_open, draw) -> int

An integer from ceil(low) to floor(high) (exclusive when half_open), by rejection sampling over 53-bit draws (54-bit for ranges wider than 2^53), so every integer is equally likely.

ParameterTypeDescription
lowfloat
highfloat
half_openbool
drawCallable[[], bytes]

Returns int

def int_between_unsafe(low: float, high: float, half_open: bool, draw: Callable[[], bytes]) -> int:
    """An integer from ``ceil(low)`` to ``floor(high)`` (exclusive when
    ``half_open``), by rejection sampling over 53-bit draws (54-bit for
    ranges wider than 2^53), so every integer is equally likely."""
    low_int = _to_safe_int(low, math.ceil)
    high_int = _to_safe_int(high, math.floor)
    count = high_int - low_int + (0 if half_open else 1)
    if count <= 0:
        raise ValueError("range must contain at least one integer")
    if high_int - low_int < _MAX_SAFE:
        if count == 1:
            return low_int
        bucket = (2**53 - 2**53 % count) // count
        limit = bucket * count
        while True:
            value = _read_uint53(draw())
            if value < limit:
                return low_int + value // bucket
    wide = count > 2**53
    bucket = (2**54 if wide else 2**53) // count
    limit = bucket * count
    while True:
        data = draw()
        value = _read_uint53(data) + (2**53 if wide and data[0] & 0x20 else 0)
        if value < limit:
            return low_int + value // bucket

make

make(random_bytes) -> SecureRandomService

A SecureRandom drawing every value from random_bytes(size).

ParameterTypeDescription
random_bytesCallable[[int], bytes]

Returns SecureRandomService

def make(random_bytes: Callable[[int], bytes]) -> SecureRandomService:
    """A ``SecureRandom`` drawing every value from ``random_bytes(size)``."""
    return SecureRandomService(random_bytes)

fill_random

fill_random(crypto, size) -> bytes

size bytes from crypto.get_random_values, 64 KiB at a time (Web Crypto refuses more per call).

ParameterTypeDescription
cryptoCrypto
sizeint

Returns bytes

def fill_random(crypto: Crypto, size: int) -> bytes:
    """``size`` bytes from ``crypto.get_random_values``, 64 KiB at a time
    (Web Crypto refuses more per call)."""
    buffer = bytearray(size)
    with memoryview(buffer) as view:
        for offset in range(0, size, 65_536):
            with view[offset : offset + 65_536] as chunk:
                crypto.get_random_values(chunk)
    return bytes(buffer)

random_bytes_unsafe

random_bytes_unsafe(size) -> bytes

size random bytes from the host, outside any effect.

ParameterTypeDescription
sizeint

Returns bytes

def random_bytes_unsafe(size: int) -> bytes:
    """``size`` random bytes from the host, outside any effect."""
    _check_size(size)
    return os.urandom(size)

uuid_v4_unsafe

uuid_v4_unsafe(*, format: Literal['string'] = 'string') -> str
uuid_v4_unsafe(*, format: Literal['bytes']) -> bytes

A UUIDv4 from the host's random bytes.

ParameterTypeDescription
format= 'string'
@overload
def uuid_v4_unsafe(*, format: Literal["string"] = "string") -> str: ...
@overload
def uuid_v4_unsafe(*, format: Literal["bytes"]) -> bytes: ...
def uuid_v4_unsafe(*, format: UuidFormat = "string") -> str | bytes:
    """A UUIDv4 from the host's random bytes."""
    return _formatted(_ids.v4_bytes(os.urandom(16)), format)

uuid_v7_unsafe

uuid_v7_unsafe(*, format: Literal['string'] = 'string') -> str
uuid_v7_unsafe(*, format: Literal['bytes']) -> bytes

A UUIDv7 from the system time and the host's random bytes; strictly increasing across every *_unsafe call in the process.

ParameterTypeDescription
format= 'string'
@overload
def uuid_v7_unsafe(*, format: Literal["string"] = "string") -> str: ...
@overload
def uuid_v7_unsafe(*, format: Literal["bytes"]) -> bytes: ...
def uuid_v7_unsafe(*, format: UuidFormat = "string") -> str | bytes:
    """A UUIDv7 from the system time and the host's random bytes; strictly
    increasing across every ``*_unsafe`` call in the process."""
    return _formatted(_ids.v7_monotonic(time.time() * 1000, os.urandom(16)), format)

ulid_unsafe

ulid_unsafe() -> str

A ULID from the system time and the host's random bytes; strictly increasing across the process.

Returns str

def ulid_unsafe() -> str:
    """A ULID from the system time and the host's random bytes; strictly
    increasing across the process."""
    return _ids.ulid_monotonic(time.time() * 1000, lambda: os.urandom(10))