Encryption Configuration

The cshelve module supports encrypting data before it is sent to the storage provider. This feature is particularly useful for ensuring data integrity and mitigating potential security risks associated with pickles.

Note

Only the values (pickled data) are encrypted, not the keys.

Caution

Encryption is CPU-intensive and may impact performance.

Installation

Encryption functionality is not included by default. To enable encryption, install the additional dependencies by running:

$ pip install cshelve[encryption]

Configuration File

Encryption settings are defined in an INI file. Below is an example configuration file named config.ini:

[default]
provider        = in-memory
persist-key     = compression
exists          = true

[encryption]
algorithm   = aes256
# Development configuration: encryption key stored directly in the file.
key         = Sixteen byte key

In this example, the encryption algorithm is set to aes256, and the encryption key is defined as my encryption key.

Using Environment Variables for Keys

For improved security, it is recommended to avoid storing encryption keys directly in configuration files. Instead, use an environment variable to supply the key. Here’s an updated example using an environment variable named ENCRYPTION_KEY:

[default]
provider        = in-memory
persist-key     = compression
exists          = true

[encryption]
algorithm   = aes256
# The encryption key is retrieved from the environment variable `ENCRYPTION_KEY`.
environment_key = ENCRYPTION_KEY

Supported Algorithms

Currently, cshelve supports the following encryption algorithm:

• `aes256`: A widely-used symmetric encryption standard.

Using Encryption

Once encryption is configured in the config.ini file, data will automatically be encrypted before storage and decrypted upon retrieval. No changes are required in the application code. For example:

import cshelve

# Writing encrypted data
with cshelve.open('config.ini') as db:
    db['data'] = 'This is some data that will be encrypted.'

# Reading encrypted data
with cshelve.open('config.ini') as db:
    data = db['data']
    print(data)  # Output: This is some data that will be encrypted.

In this example, the data is transparently encrypted when stored and decrypted when retrieved, as specified in the configuration.

Error Handling

If an unsupported encryption algorithm is specified in the configuration file, cshelve will raise an UnknownEncryptionAlgorithmError. Additionally, the following errors may occur:

• MissingEncryptionKeyError: Raised when no encryption key is provided for encryption.

• EncryptedDataCorruptionError: Raised when the encrypted data is found to be corrupted during decryption.

Ensure that the algorithm listed in the config.ini file matches one of the supported options and that the encryption key is correctly provided.