This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

Encrypt and decrypt file or string in GCM mode with AES, Serpent or Twofish as secure as possible.

Project Description


A Python 3 module to encrypt and decrypt files or string in GCM mode with AES, Serpent or Twofish as secure as possible. Contact:

General Specifications :

To install with sources archive, go in the extracted folder and run in terminal:

sudo python install

Or by Pypi, run:

sudo pip install cryptoshop

Cryptoshop encrypt files in GCM mode. with one of this three algorithms AES-256, Serpent or Twofish

  • For string encryption, cryptoshop use cascade encryption with Serpent, AES and Twofish.
  • It use Botan. Crypto and TLS library for C++11. For more information’s on Botan, go here:

It use Argon2 for key derivation/stretching :

You can use it like console application:

Linux users: Make a symlink of the module on your bin folder…

# encrypt the file test with AES-256.
# If no algo is specified, Serpent (-a srp) is default.
# Encrypted file test.cryptoshop is write in same folder:

./cryptoshop -e test -a aes

# decrypt the file test.cryptoshop.
# No need to specify algo. It is automatically detected by decryption routine.

./cryptoshop -d test.cryptoshop

You can use it like a module for your Python application:

File encryption :

from cryptoshop import encryptfile
from cryptoshop import decryptfile

result1 = encryptfile(filename="test", passphrase="mypassphrase", algo="srp")

result2 = decryptfile(filename="test.cryptoshop", passphrase="mypassphrase")

String encryption :

from cryptoshop import encryptstring
from cryptoshop import decryptstring

# No need to specify algo. Cryptoshop use cascade encryption with Serpent, AES and Twofish.
result1 = encryptstring(string= "my string to encrypt" , passphrase= "mypassword")

result2 = decryptstring(string= result1 , passphrase= "mypassword")

Advanced Specifications :

1- Key derivation/stretching :

The user passphrase derivation is performed with the winner of the Password Hashing Competition, Argon2. The output is a key of 32 bytes. This is the “masterkey”.

2- File Encryption :

  • A 32 bytes “internalkey” is generated by the random number generator.
  • the plaintext is encrypted with this key with selected algo. Serpent, AES or Twofish.
  • this key is encrypted in cascade with your master key. Cryptoshop always use Serpent, AES, and Twofish for encrypt this internal key.
  • All encryption use different random key and different uniques nonce.
  • All are authenticated.

This ensure your masterkey was not used for encrypt more and more data, and you need only to remember your passphrase. Not three 32 bytes keys :)

You can encrypt with AES-256, Serpent-256, or Twofish-256. If no algorithm is specified, Cryptoshop use Serpent-256.

Encryption is optimized for larges files:

The file is encrypted chunk by chunk with the ‘internalkey’. Etch iteration is authenticated. All encrypted chunks use a different UNIQUE nonce. It is ABSOLUTELY necessary for all counter mode like GCM or CTR… NEVER USE THE SAME KEY WITH THE SAME NONCE. For have uniques nonce, cryptoshop use uuid4, and timestamp.

The final Cryptoshop format is:

header                                                            2.5 bytes *
passsalt                                                           64 bytes *
***************************                                                 *
nonce1 + nonce2 + nonce3                                       41 * 3 bytes *
enckey + GCM Tag1 + GCM Tag2 + GCM Tag3                   21*3 + 3*16 bytes *
***************************                                                 *
nonce4 + cipherchunk1 + GCM Tag4            41 bytes + chunkSize + 16 bytes *
---------------                                                             *
nonce5 + cipherchunk2 + GCM Tag5            41 bytes + chunkSize + 16 bytes *
---------------                                                             *
nonce6 + cipherchunk3 + GCM Tag6            41 bytes + chunkSize + 16 bytes *
---------------                                                             *
nonceN + cipherchunkN + GCM Tag7            41 bytes + chunkSize + 16 bytes *
---------------                                                             *

chunksize is fixed to 0,5 Mo (500000 bytes)

3- File Decryption :

  • The decryption routine check the header before all other operations.
  • The internalkey is decrypted, and authentication is checked.
  • The decryption routine decrypt and check authentication of all chunks with the internalkey’.

4- Authentication :

Authentication is performed internally by GCM mode (the header is always included). All chunks of file have a different authentication code and all authentication are calculated with the encrypted data. NOT WITH CLEAR DATA.

More information here:

Schematic file encryption protocol

Notes on string encryption

There is no “chunk” concept with string encryption. String encryption always use cascade encryption. The header and encrypted string are authenticated.


  • Python >= 3
  • Botan library >=1.11 <— Install the last version (1.11.29). Cryptoshop don’t work with the 1.10 branch. The installation include the Python wrapper.

Python modules:

  • tqdm <— console progress-bar
  • argon2_cffi <— Python module/wrapper for Argon2


  • Cryptoshop is released under GPL3 License.
  • Botan is released under the permissive Simplified BSD license.
  • argon2_cffi and tqdm are released under The MIT License

Why Cryptoshop ?

There is a lot of bad encryption modules for python.

  • no authentication.
  • else authentication routine use naive comparison like if m1==m2 mac is good. This approach permit Timing Attack.
  • use unsecured algorithm like ECB mode, MD5 or SHA-1 etc…
  • bad use of the encryption mode. Reuse nonce in CTR, fixed initialization vector when it must be random etc…
  • Passphrase derivation/stretching with iterative hash function. Hash are NOT make for this usage.
  • Systematically use PyCrypto. This is a good module, but there is no Serpent algo, and some algo like PBKDF2 are very slow because it’s a pure Python implementation.
  • No optimization for big files.

Other resources

You should have some knowledge of cryptography before trying to use or modify this module. This is an area where it is very easy to make mistakes. Naive modifications will almost certainly not result in a secure system.

Especially recommended are:

  • Cryptography Engineering by Niels Ferguson, Bruce Schneier, and Tadayoshi Kohno
  • Security Engineering – A Guide to Building Dependable Distributed Systems by Ross Anderson available online
  • Handbook of Applied Cryptography by Alfred J. Menezes, Paul C. Van Oorschot, and Scott A. Vanstone available online

If you’re doing something non-trivial or unique, you might want to at the very least ask for review/input on a mailing list such as the metzdowd or randombit crypto lists.

Release History

Release History

This version
History Node


History Node


History Node


Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
cryptoshop-2.0.1.tar.gz (189.5 kB) Copy SHA256 Checksum SHA256 Source Apr 23, 2016

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting