imitation-game is a Python utility package for secure message processing. It provides a high-level interface for both Symmetric (shared secret) and Asymmetric (Public/Private key) encryption.
Symmetric Encryption Fast and efficient encryption using a single shared key. Best for internal data storage or pre-shared secrets.
generate_symmetric_key: Creates a cryptographically secure random key.encrypt_symmetric: Encrypts a plaintext message using a symmetric key.decrypt_symmetric: Restores an encrypted message back to plaintext using the same key.
Asymmetric Encryption (RSA) Secure communication between two parties without needing to share a secret key beforehand. Uses sender/receiver key combinations where the sender encrypts with the receiver's public key AND signs with their own private key. This provides both confidentiality (only receiver can decrypt) and authenticity (receiver can verify the sender's identity), similar to PGP encryption.
generate_asymmetric_key: Generates a pair of RSA keys: a Public Key (for encryption/verification) and a Private Key (for decryption/signing).encrypt_asymmetric: Encrypts a message using the receiver's public key and signs it with the sender's private key. Takes parameters: (message, receiver_public_key, sender_private_key).decrypt_asymmetric: Decrypts a message using the receiver's private key and verifies the sender's signature using the sender's public key. Takes parameters: (encrypted_data, receiver_private_key, sender_public_key).
There are many message encoding and decoding related packages on the PyPI server. We have selected a few key examples that with similar functionality as our package.
- Cipher-symmetric: Focuses exclusively on symmetric string encryption, acting as a high-level wrapper for the cryptography module.
- Encryption: A broad educational tool demonstrating AES, RSA, and hashing via
pycryptodome. It is comprehensive but often requires more boilerplate code to implement. - encrypt_data: Specializes in Hybrid Encryption, which uses asymmetric keys to securely exchange symmetric keys.
While the packages above are powerful, they often cater to either a single encryption style or require deep cryptographic knowledge to configure properly. The primary benefit of imitation-game is its focus on a unified, high-level API that abstracts away the complexity of both symmetric and asymmetric workflows.
pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ imitation-gameDependencies:
pycryptodome- Cryptographic operationspathvalidate- File path validation
Test PyPI: https://test.pypi.org/project/imitation_game
Note: All outputted keys will vary on uses of generate_symmetric_key and generate_asymmetric_key.
>>> from imitation_game import generate_symmetric_key
>>> # Generate a secure random key for symmetric encryption
>>> key = generate_symmetric_key() # Returns: 32-byte key (e.g., b'\x8f\x9a\x1b...')
>>> print(f"Generated key: {key[:10]}...") # Shows first 10 characters
Generated key: Vy7K5usqcE...
# Save the key keys/my_encryption_key.txt for later use
>>> key = generate_symmetric_key("keys/my_encryption_key.txt")>>> from imitation_game import generate_symmetric_key, encrypt_symmetric, decrypt_symmetric
# Generate key
>>> key = generate_symmetric_key()
# Encrypts and decrypts message with key
>>> message = "Secret message"
>>> encrypted_data = encrypt_symmetric(message, key)
>>> print(f"Encrypted: {encrypted_data[:20]}...")
Encrypted: 6k8HkEQUosOXaOFGW1hq...
>>> decrypted_message = decrypt_symmetric(encrypted_data, key)
>>> print(decrypted_message)
Secret message>>> from imitation_game import generate_asymmetric_key, encrypt_asymmetric, decrypt_asymmetric
# Generate key pairs for sender and receiver
# NOTE: Printed output has been shortened for ease of this README.
# The function will print out the full keys.
>>> sender_private, sender_public = generate_asymmetric_key()
PRIVATE KEY:
b'-----BEGIN RSA PRIVATE KEY-----\nMIIEogIBAAK......V8WZ5NRcY=\n-----END RSA PRIVATE KEY-----'
PUBLIC KEY:
b'-----BEGIN PUBLIC KEY-----\nMIIBIjANBg......L4\n8wIDAQAB\n-----END PUBLIC KEY-----'
>>> receiver_private, receiver_public = generate_asymmetric_key()
PRIVATE KEY:
b'-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAK......azpF3S3lzNWJ\n-----END RSA PRIVATE KEY-----'
PUBLIC KEY:
b'-----BEGIN PUBLIC KEY-----\nMIIBIjANBg......T8G\nowIDAQAB\n-----END PUBLIC KEY-----'
# Sender encrypts message with receiver's public key and signs with their private key
>>> message = "Secret message"
>>> encrypted_data = encrypt_asymmetric(message, receiver_public, sender_private)
>>> print(f"Encrypted data length: {len(encrypted_data)} bytes")
Encrypted data length: 512 bytes
# Receiver decrypts with their private key and verifies sender's signature
>>> decrypted_message = decrypt_asymmetric(encrypted_data, receiver_private, sender_public)
>>> print(decrypted_message)
Secret messageThis project uses conda for environment management, but dependencies are defined in pyproject.toml. Follow these steps to set up your development environment:
-
Create a conda environment with Python 3.10 or higher:
conda create -n imitation-game python=3.12 conda activate imitation-game
Alternatively, use the provided
environment.ymlfile:conda env create -f environment.yml conda activate imitation-game
-
Install the package in editable mode with all development dependencies:
# Clone the repository git clone https://github.com/UBC-MDS/imitation_game.git cd imitation_game # Install the package with all optional dependencies (dev, docs, tests, build) pip install -e ".[dev,docs,tests,build]"
This will install:
- The package itself in editable mode
- Development tools:
hatch,pre-commit - Documentation tools:
quartodoc - Testing tools:
pytest,pytest-cov,pytest-raises,pytest-randomly,pytest-xdist,flake8-pyproject - Build tools:
pip-audit,twine
Tests are located in the tests/ directory and can be run using pytest:
# Run all tests
pytest
# Run tests with coverage report
pytest --cov=imitation_game --cov-report=term-missing
# Run tests using hatch (recommended)
hatch run +py=3.12 test:runThe test suite includes both unit tests (tests/unit/) and integration tests (tests/integration/).
Documentation is built using Quarto and quartodoc. To build the documentation locally:
-
Ensure Quarto is installed:
- Download and install Quarto from https://quarto.org/docs/get-started/
-
Build the documentation:
# Generate API reference documentation quartodoc build # Render the Quarto website quarto render
-
Preview the documentation locally:
quarto preview
The documentation will be generated in the _site/ directory (or similar, depending on your Quarto configuration).
Documentation is automatically built and deployed to GitHub Pages when:
- Changes are pushed to the
mainbranch - The workflow is manually triggered via GitHub Actions
The deployment workflow (.github/workflows/docs.yml) handles:
- Building the Quarto documentation
- Publishing to the
gh-pagesbranch - Making the documentation available at the repository's GitHub Pages URL
No manual intervention is required for documentation deployment once changes are merged to main.
Documentation is deployed here
Pull requests get an automatic documentation preview so you can see how the docs will look before merging. The preview is built by .github/workflows/docs.yml and deployed to Netlify; a comment with the preview URL is posted on each PR.
Every new PR will get a Netlify deploy preview and a comment with the preview link.
We use GitHub Actions for continuous integration and deployment:
- Tests: Run automatically on every push and pull request via
build.yml - Deploy: Automatically deploys to TestPyPI when changes are pushed to main via
deploy.yml - Docs: Documentation is built and deployed to GitHub Pages on every push via
docs.yml - Docs preview: Each pull request gets a documentation preview deployed to Netlify via
docs.yml(requires Netlify secrets; see above)
For information about how to contribute to this package, please review our Contributing document. All contributors must abide by our Code of Conduct
This packages uses the MIT License, more information can be found here alongside reasoning for this license here.
If you use this package in your research or project, please cite it as:
@software{imitation_game2026,
author = {Valson, Vinay and Joshi, Tirth and Kwong, Teem and Wen, Alexander},
title = {imitation-game: A Python Package for Secure Message Encryption},
year = {2026},
publisher = {GitHub},
url = {https://github.com/UBC-MDS/imitation_game}
}APA Style: Valson, V., Joshi, T., Kwong, T., & Wen, A. (2026). imitation-game: A Python Package for Secure Message Encryption [Computer software]. GitHub. https://github.com/UBC-MDS/imitation_game
This package implements cryptographic operations based on established standards and best practices:
- AES (Advanced Encryption Standard): FIPS PUB 197 - Federal Information Processing Standards Publication for symmetric encryption
- RSA Cryptography: RFC 8017 - PKCS #1: RSA Cryptography Specifications Version 2.2 - Standard for asymmetric encryption
- SHA-256 Hashing: FIPS PUB 180-4 - Secure Hash Standard used in digital signatures
- OWASP Cryptographic Storage Cheat Sheet: OWASP Guidelines
- NIST Cryptographic Standards and Guidelines: NIST Computer Security Resource Center
- PyCryptodome Documentation: https://pycryptodome.readthedocs.io/ - The underlying cryptographic library used in this package
This package imitation-game is created with [pyOpenSci copier template] (https://github.com/pyOpenSci/pyos-package-template)
- Affiliation: University of British Columbia
- GitHub: @Vin-dictive
- Affiliation: University of British Columbia
- GitHub: @tirthjoship
- Affiliation: University of British Columbia
- GitHub: @mdskwong
- Affiliation: University of British Columbia
- GitHub: @alxwen711