TimeRelease 2.0.0

Python utility to cryptographically lock secrets for a preset amount of time.

TimeRelease

Introduction

A simple Python utility to lock (or encrypt) secrets, such that they require a preset amount of compute to unlock (or decrypt) them later.

Since each cryptographic step requires the last, it (by design) cannot be parallelized.

This could potentially be useful if you want to wait, for example, an hour, before being able to access a password; as a form of stolen device protection.

WARNING!

Always keep your "encrypted" file secret, treating it as if it were a password. It is effectively unencrypted as it can be used to decrypt the secret (if such an attacker has sufficient time to complete the puzzle) without any other knowledge of the secret or the individual who encrypted it.

Table of Contents

• Usage
  • Setup
  • Encryption
  • Decryption
• Module API
• Development Usage

---

Usage

Setup

Install the package and its dependencies in a venv:

python3 -m venv ./venv
source ./venv/bin/activate
pip install TimeRelease

Encryption

To encrypt a file somefile.txt -> somefile.txt.timerelease:

# Specify # of seconds it should take to unlock on your machine
timerelease --encrypt somefile.txt somefile.txt.timerelease --time 3600
# Or, specify raw # of iterations needed to unlock the file
timerelease --encrypt somefile.txt somefile.txt.timerelease --iters 1073741824

You can use this to determine how long (on your hardware) the decryption process will take. Encryption should be nearly instant for most settings, even for comically large numbers of iterations.

Decryption

To decrypt a file somefile.txt.timerelease -> somefile.txt:

timerelease --decrypt somefile.txt.timerelease somefile.txt

It will take however long the person who encrypted the file dictates. The only way to speed it up is to find a CPU with really, really fast single-core performance.

Module API

Like any module, TimeRelease can be installed via pip (pip install TimeRelease) and imported (import TimeRelease). The API for the TimeRelease module is as follows:

TimeRelease.decrypt_secret(enc_package, logging=True)

• Given a dictionary which was generated by encrypt_secret(), decrypt_secret() decrypts it and returns the secret as a byte string.
• If logging (defaults to True) is set to True, a progress bar is printed, along with extra debug information.

TimeRelease.encrypt_secret(secret, iterations, logging=True)

• Given a byte string secret, encrypt_secret() applies iterations iterations to it, "encrypting" it.
• If logging (defaults to True) is set to True, extra debug information is printed.

TimeRelease.run_single_benchmark(iterations, logging=True)

• Determines how long it takes for the CPU to run a fixed number of iterations.
• Amount of time elapsed is returned in seconds as a float.
• If logging (defaults to True) is set to True, extra debug information is printed.

TimeRelease.run_benchmark(benches, logging=True)

• Determines how many iterations a single core of the user's CPU is capable of processing, on average, per second (as an integer).
• benches (defaults to 10) describes the number of times the benchmark will be run.
• Higher values of benches = greater certainty in running time, but more time is spent benchmarking.
• If logging (defaults to True) is set to True, extra debug information is printed.

Development Usage

To install development versions of this package, clone this repo and cd into it, then run:

python3 -m venv ./venv
source ./venv/bin/activate
pip install -e .[dev]
pre-commit install 

To test the codebase, simply run pytest. To apply proper formatting to the codebase, run ruff format .. To ensure that the code has no other issues with PEP8 compliance, run ruff check. And to ensure that there are no type errors, please run ty check TimeRelease. Please do all of these things before you commit, and not after!

To build a distribution package, first update the version number in pyproject.toml, and make a tag for that release version at the current commit. Then:

python3 -m build

To upload this build to PyPI, run:

python3 -m twine upload dist/* --skip-existing