encryption¶

class cincoconfig.KeyFile(filename)¶

The cincoconfig key file, containing a randomly generated 32 byte encryption key. The cinco key file is used by SecureField to encrypt and decrypt values as they are written to and read from the configuration file.

The keyfile is loaded as needed by using this class as a context manager. The key has an internal reference count and is only freed once the reference count is 0 (all context managers exited). THe key is cached internally so that the keyfile only has to be open and read once per configuration load or save.

To encrypt a value:

with keyfile as ctx:
    secret = ctx.encrypt(method='xor', text='hello, world')

Parameters: filename (str) – the cinco key filename

_get_provider(method)¶

Get the encryption provider. method must be one of

aes - returns AesProvider
xor - returns XorProvider
best - returns the best available encryption provider: AesProvider if AES encryption is available (cryptography is installed), XorProvider if AES is not available

The resolved method is returned. For example, if best if specified, the best encryption method will be resolved and returned.

The return value is a tuple of encryption provider instance and the resolved method.

Return type: Tuple[IEncryptionProvider, str]
Returns: a tuple of (provider, method)

decrypt(secret)¶

Parameters: secret (SecureValue) – encrypted value
Return type: bytes
Returns: decrypted value

encrypt(text, method='best')¶

Parameters

text (Union[str, bytes]) – plaintext to encrypt
method (str) – encryption method to use

Return type

SecureValue

Returns

the encrypted value

generate_key()¶

Generate a random 32 byte key and save it to filename.

Return type: None

class cincoconfig.encryption.SecureValue(method, ciphertext)¶

An encrypted value tuple containing the encryption method and the ciphertext.

method¶: the encryption method (str)

ciphertext¶: the encrypted value (bytes)

cincoconfig.encryption.AES_AVAILABLE¶: AES is available (cryptography is installed)

Internal Classes¶

class cincoconfig.encryption.IEncryptionProvider¶

Interface class for an encryption algorithm provider. An encryption provider implements both encryption and decryption of string values.

The encrypt and decrypt methods must be deterministic.

b'message' == provider.decrypt(provider.decrypt(b'message'))

The constructor for subclasses will receive a single argument: the encryption key.

decrypt(ciphertext)¶

Decrypt a value.

Parameters: ciphertext (bytes) – encrypted value to decrypt
Return type: bytes
Returns: decrypted value

encrypt(text)¶

Encrypt a value.

Parameters: text (bytes) – plain text value to encrypt
Return type: bytes
Returns: encrypted value

class cincoconfig.encryption.XorProvider(key)¶

XOR-bitwise “encryption”. The XOR provider should only be used to obfuscate, not encrypt, a value since XOR operations can be easily reversed.

decrypt(ciphertext)¶

Return type: bytes
Returns: the decrypted values

encrypt(text)¶

Return type: bytes
Returns: the encrypted value

class cincoconfig.encryption.AesProvider(key)¶

AES-256 encryption provider. This class requires the cryptography library. Each encrypted value has a randomly generated 16-byte IV.

decrypt(ciphertext)¶

Return type: bytes
Returns: the plaintext value

encrypt(text)¶

Return type: bytes
Returns: the encrypted value