🎲 libprng

---

💼 Purpose | 🛠️️ Installation | ⚙️ Usage | 🛡️ Security | 📋 Backlog | ⚖️ License

---

Purpose

This package provides a set of pseudo-random number generators (PRNGs). These are not meant to be cryptologically secure, but rather enable the reproduction of "random" number sequences regardless of the platform that they are being generated on.

Creation of this package was inspired by capture-the-flag competitions where random number generation using glibc's rand function on a typical Windows or Linux target would not match those generated on a macOS device (macOS generally uses Clang rather than glibc). This package exists to fill that gap and enable reproduction regardless of platform.

This package currently supports PRNGs used for rand() on a version of the GNU, macOS, and FreeBSD C libraries. It is the author's intent to eventually expand out the scope of algorithms available alongside perform additional testing to determine the versions used by individual operating systems.

Installation

This package is available on PyPI and can be installed using pip:

python3 -m pip install libprng

Note

Your Python command may differ depending on how it was installed on your system. Some installations omit the version (python) while others are minor-version specific (ex. python3.9).

You may also install the latest development releases from GitHub:

python3 -m pip install git+https://github.com/Jayson-Fong/libprng

📦 Installing Using a Virtual Environment

In most cases, you should install this package within a Python virtual environment. This enables you to leverage multiple versions of this package across various projects on your system.

To create a virtual environment:

python3 -m venv .venv

You will then need to activate your virtual environment. On Linux or macOS:

source .venv/bin/activate

On Windows, the activation command depends on what interpreter you are using. For command prompt:

.\.venv\Scripts\activate.bat

For PowerShell:

.\.venv\Scripts\Activate.ps1

Or when using GitBash:

source .venv/Scripts/activate

You may then install using pip normally:

python3 -m pip install libprng

Usage

Important

This package is under active development, and the API may change at any time. If using this package in your project, consider pinning it to a specific version.

🐂 GNU C Library (glibc): Traditional Usage

Initialize the global PRNG random data instance with a seed and generate a single random 31-bit integer:

from libprng.glibc import srand, rand


srand(1234)
print(rand())

Create a PRNG object that is unaffected by other rand() calls:

from libprng.glibc import GlibcRandom


random_generator: GlibcRandom = GlibcRandom(1234)

# Request a single random integers
print(random_generator.generate())

# Loop through random numbers until one is even:
for random_int in random_generator:
    print(random_int)
    if random_int % 2 == 0:
        break

🐂 GNU C Library (glibc): Reentrant

Generate a random integer with a seed of 1234:

from libprng.glibc import rand_r


result, _next_seed = rand_r(1234)
print(result)

Generate a random integer with a seed of 1234 without having to update the seed yourself:

from libprng.glibc import rand_r, Seed


seed: Seed = Seed(1234)
print(rand_r(seed))
print(rand_r(seed))

Leverage rand_r as a generator:

from libprng.glibc import GlibcReentrantRandom


random_generator: GlibcReentrantRandom = GlibcReentrantRandom(1234)

# Request a single random integers
print(random_generator.generate())

# Loop through random numbers until one is even:
for random_int in random_generator:
    print(random_int)
    if random_int % 2 == 0:
        break

🍎 Apple / Former FreeBSD C Library: Non-Weak Seeding

This uses the current algorithm used on macOS. It was formerly used on FreeBSD; however, it is no longer available in recent versions.

There is an additional version of the algorithm available on macOS and former versions of FreeBSD when electing to use weak seeding (or ancient versions), which is not yet available in this package.

Initialize the global PRNG random data instance with a seed and generate a single random integer:

from libprng.apple import srand, rand


srand(1234)
print(rand())

Security

Pseudo-random number generators are generally insufficient for cryptographic or security-sensitive use cases. Likewise, this package was designed for reproducibility—not security or cryptography. You should not use this package for security-sensitive use cases, such as password generation, encryption, or key derivation.

Backlog

This package is still under active development. The following features are expected:

• Implementations:
  • FreeBSD Current
  • Apple/FreeBSD with Weak Seeding
  • Python
• Command-line PRNG utility

License

While this package's author seeks to provide this software openly and under the MIT License, it contains derivative works from open-source projects such as the GNU C Library. As a result, the overall distribution is licensed under the GNU Lesser General Public License version 2.1 or later (at your choosing). Files that are not licensed under the MIT License contain a banner explicitly noting so alongside notes on which sections are licensed under the MIT License, if applicable.