Securely Manage Sensitive Data with a Custom Python Secrets Module

In software development, handling sensitive information like API keys, passwords, and encryption secrets requires robust security measures. Python's built-in secrets module provides tools for generating cryptographically strong random numbers for managing such secrets. This challenge asks you to implement a simplified, custom version of this module to understand the underlying principles of secure secret generation.

Problem Description

Your task is to create a Python module named my_secrets that provides functions to generate different types of secure secrets. This module should mimic some of the core functionalities of Python's standard secrets module, focusing on generating strings suitable for use as passwords or tokens.

Key Requirements:

1. my_secrets.token_hex(nbytes): Generate a random hexadecimal string of length 2 * nbytes. This means for every byte of randomness, you'll produce two hexadecimal characters.
2. my_secrets.token_urlsafe(nbytes): Generate a random URL-safe text string. The string will contain nbytes random bytes. The generated string is base64 encoded and any '+' or '/' characters are replaced with '-' and '_' respectively. It will contain at most nbytes * 4 // 3 + 1 characters.
3. my_secrets.choice(seq): Return a randomly chosen element from a non-empty sequence seq.

Expected Behavior:

• The generated secrets should be cryptographically secure, meaning they should be unpredictable and suitable for security-sensitive applications. You should leverage Python's os.urandom() function for generating random bytes, as it provides access to the operating system's source of randomness.
• The functions should handle invalid inputs gracefully (e.g., non-integer nbytes, empty sequences).

Edge Cases to Consider:

• nbytes being zero or negative for token_hex and token_urlsafe.
• Providing an empty sequence to choice.
• The underlying random number generator failing (though os.urandom is highly reliable).

Examples

Example 1: token_hex

import my_secrets

# Generate a 16-byte random hex token
hex_token = my_secrets.token_hex(16)
print(hex_token)
print(len(hex_token))

Output:

a1b2c3d4e5f678901234567890abcdef # (example output, will be different each time)
32

Explanation: my_secrets.token_hex(16) generates 16 bytes of random data. Each byte is represented by two hexadecimal characters (0-9, a-f). Therefore, 16 bytes result in a string of 32 hexadecimal characters.

Example 2: token_urlsafe

import my_secrets

# Generate a 32-byte random URL-safe token
urlsafe_token = my_secrets.token_urlsafe(32)
print(urlsafe_token)
print(len(urlsafe_token))

Output:

a1b2c3d4e5f67890ABCDEFghijklmnOPQRSTUVWXYZ_ # (example output, will be different each time)
43

Explanation: my_secrets.token_urlsafe(32) generates 32 bytes of random data and encodes it using base64, making it safe for URLs. The output is approximately 32 * 4/3 = 42.66 characters, so it's rounded up, resulting in 43 characters. Plus signs and slashes are replaced with hyphens and underscores.

Example 3: choice

import my_secrets

password_characters = "abcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*"
random_char = my_secrets.choice(password_characters)
print(random_char)

my_list = [1, 2, 3, "apple", "banana"]
random_item = my_secrets.choice(my_list)
print(random_item)

Output:

$ # (example output, will be different each time)
banana # (example output, will be different each time)

Explanation: my_secrets.choice() picks a single character from the password_characters string or a single item from the my_list list randomly.

Example 4: Edge Case - Empty Sequence

import my_secrets

try:
    my_secrets.choice([])
except ValueError as e:
    print(e)

Output:

sequence may not be empty

Explanation: Attempting to choose from an empty sequence raises a ValueError.

Constraints

• You must use os.urandom() as the source of randomness for generating secure bytes. Do not use random.random() or random.choice() directly from the standard random module for the core random byte generation.
• The my_secrets module should be a single Python file named my_secrets.py.
• For token_hex and token_urlsafe, the input nbytes will be an integer.
• For choice, the input seq will be a non-empty sequence (list, tuple, string).
• Your implementation should be reasonably efficient; avoid overly complex or slow operations.

Notes

• Consider how you'll convert raw random bytes into hexadecimal and URL-safe base64 representations. Python's built-in string formatting or encoding methods might be helpful.
• For token_urlsafe, pay close attention to the specific replacements required for URL-safe characters.
• The secrets module internally uses os.urandom() for its cryptographic randomness. This is the standard and recommended way to obtain cryptographically secure random bytes in Python.
• Think about how to handle potential errors, such as invalid input types or values, and raise appropriate exceptions.