1.14. security_keys

This module provides functionality for working with security keys that are used for data integrity checks. Verification is performed using ECDSA keys.

1.14.1. Data

ecdsa_curves

A dictionary of ecdsa.curves.Curve objects keyed by their ecdsa and OpenSSL compatible names.

1.14.2. Functions

openssl_decrypt_data(ciphertext, password, digest='sha256', encoding='utf-8')

Decrypt ciphertext in the same way as OpenSSL. For the meaning of digest see the openssl_derive_key_and_iv() function documentation.

Note

This function can be used to decrypt ciphertext created with the openssl command line utility.

openssl enc -e -aes-256-cbc -in file -out file.enc -md sha256

Parameters:

• ciphertext (bytes) – The encrypted data to decrypt.
• password (str) – The password to use when deriving the decryption key.
• digest (str) – The name of hashing function to use to generate the key.
• encoding (str) – The name of the encoding to use for the password.

Returns:

The decrypted data.

Return type:

bytes

openssl_derive_key_and_iv(password, salt, key_length, iv_length, digest='sha256', encoding='utf-8')

Derive an encryption key and initialization vector (IV) in the same way as OpenSSL.

Note

Different versions of OpenSSL use a different default value for the digest function used to derive keys and initialization vectors. A specific one can be used by passing the -md option to the openssl command which corresponds to the digest parameter of this function.

Parameters:

• password (str) – The password to use when deriving the key and IV.
• salt (bytes) – A value to use as a salt for the operation.
• key_length (int) – The length in bytes of the key to return.
• iv_length (int) – The length in bytes of the IV to return.
• digest (str) – The name of hashing function to use to generate the key.
• encoding (str) – The name of the encoding to use for the password.

Returns:

The key and IV as a tuple.

Return type:

tuple

1.14.3. Classes

class SecurityKeys

Bases: object

The security keys that are installed on the system. These are then used to validate the signatures of downloaded files to ensure they have not been corrupted or tampered with.

Note

Keys are first loaded from the security.json file included with the application source code and then from an optional security.local.json file. Keys loaded from the optional file can not over write keys loaded from the system file.

__init__()

Initialize self. See help(type(self)) for accurate signature.

keys = None

The dictionary of the loaded security keys, keyed by their identity string.

verify(key_id, data, signature)

Verify the data with the specified signature as signed by the specified key. This function will raise an exception if the verification fails for any reason, including if the key can not be found.

Parameters:

• key_id (str) – The key’s identifier.
• data (bytes) – The data to verify against the signature.
• signature (bytes) – The signature of the data to verify.

verify_dict(data, signature_encoding='base64')

Verify the signed dictionary, using the key specified within the ‘signed-by’ key. This function will raise an exception if the verification fails for any reason, including if the key can not be found.

Parameters:

• key_id (str) – The key’s identifier.
• data (bytes) – The data to verify against the signature.
• signature (bytes) – The signature of the data to verify.

class SigningKey(*args, **kwargs)

Bases: ecdsa.keys.SigningKey, object

classmethod from_dict(value, encoding='base64', **kwargs)

Load the signing key from the specified dict object.

Parameters:

• value (dict) – The dictionary to load the key data from.
• encoding (str) – The encoding of the required ‘data’ key.
• kwargs (dict) – Additional key word arguments to pass to the class on initialization.

Returns:

The new signing key.

Return type:

SigningKey

classmethod from_file(file_path, password=None, encoding='utf-8')

Load the signing key from the specified file. If password is specified, the file is assumed to have been encrypted using OpenSSL with aes-256-cbc as the cipher and sha256 as the message digest. This uses openssl_decrypt_data() internally for decrypting the data.

Parameters:

• file_path (str) – The path to the file to load.
• password (str) – An optional password to use for decrypting the file.
• encoding (str) – The encoding of the data.

Returns:

A tuple of the key’s ID, and the new SigningKey instance.

Return type:

tuple

id = None

An optional string identifier for this key instance.

sign_dict(data, signature_encoding='base64')

Sign a dictionary object. The dictionary will have a ‘signature’ key added is required by the VerifyingKey.verify_dict() method. To serialize the dictionary to data suitable for the operation the json.dumps() function is used and the resulting data is then UTF-8 encoded.

Parameters:

• data (dict) – The dictionary of data to sign.
• signature_encoding (str) – The encoding name of the signature data.

Returns:

The dictionary object is returned with the ‘signature’ key added.

class VerifyingKey(*args, **kwargs)

Bases: ecdsa.keys.VerifyingKey, object

classmethod from_dict(value, encoding='base64', **kwargs)

Load the verifying key from the specified dict object.

Parameters:

• value (dict) – The dictionary to load the key data from.
• encoding (str) – The encoding of the required ‘data’ key.
• kwargs (dict) – Additional key word arguments to pass to the class on initialization.

Returns:

The new verifying key.

Return type:

VerifyingKey

id = None

An optional string identifier for this key instance.

verify_dict(data, signature_encoding='base64')

Verify a signed dictionary object. The dictionary must have a ‘signature’ key as added by the SigningKey.sign_dict() method. To serialize the dictionary to data suitable for the operation the json.dumps() function is used and the resulting data is then UTF-8 encoded.

Parameters:

• data (dict) – The dictionary of data to verify.
• signature_encoding (str) – The encoding name of the signature data.