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[source]

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')[source]

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')[source]

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[source]

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__()[source]
keys[source]

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

verify(key_id, data, signature)[source]

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')[source]

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)[source]

Bases: ecdsa.keys.SigningKey, object

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

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')[source]

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

classmethod from_secret_exponent(*args, **kwargs)[source]

Create a private key from a random integer.

Note: it’s a low level method, it’s recommended to use the generate() method to create private keys.

Parameters
  • secexp (int) – secret multiplier (the actual private key in ECDSA). Needs to be an integer between 1 and the curve order.

  • curve (ecdsa.curves.Curve) – The curve on which the point needs to reside

  • hashfunc (callable) – The default hash function that will be used for signing, needs to implement the same interface as hashlib.sha1

Raises
  • MalformedPointError – when the provided secexp is too large or too small for the curve selected

  • RuntimeError – if the generation of public key from private key failed

Returns

Initialised SigningKey object

Return type

SigningKey

classmethod from_string(string, **kwargs)[source]

Decode the private key from raw encoding.

Note: the name of this method is a misnomer coming from days of Python 2, when binary strings and character strings shared a type. In Python 3, the expected type is bytes.

Parameters
  • string (bytes like object) – the raw encoding of the private key

  • curve (ecdsa.curves.Curve) – The curve on which the point needs to reside

  • hashfunc (callable) – The default hash function that will be used for signing, needs to implement the same interface as hashlib.sha1

Raises
  • MalformedPointError – if the length of encoding doesn’t match the provided curve or the encoded values is too large

  • RuntimeError – if the generation of public key from private key failed

Returns

Initialised SigningKey object

Return type

SigningKey

id[source]

An optional string identifier for this key instance.

sign_dict(data, signature_encoding='base64')[source]

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)[source]

Bases: ecdsa.keys.VerifyingKey, object

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

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

classmethod from_public_point(*args, **kwargs)[source]

Initialise the object from a Point object.

This is a low-level method, generally you will not want to use it.

Parameters
  • point (ecdsa.ellipticcurve.Point) – The point to wrap around, the actual public key

  • curve (ecdsa.curves.Curve) – The curve on which the point needs to reside, defaults to NIST192p

  • hashfunc (callable) – The default hash function that will be used for verification, needs to implement the same interface as hashlib.sha1

Raises

MalformedPointError – if the public point does not lay on the curve

Returns

Initialised VerifyingKey object

Return type

VerifyingKey

classmethod from_string(string, **kwargs)[source]

Initialise the object from byte encoding of public key.

The method does accept and automatically detect the type of point encoding used. It supports the raw encoding, uncompressed, compressed, and hybrid encodings. It also works with the native encoding of Ed25519 and Ed448 public keys (technically those are compressed, but encoded differently than in other signature systems).

Note, while the method is named “from_string” it’s a misnomer from Python 2 days when there were no binary strings. In Python 3 the input needs to be a bytes-like object.

Parameters
  • string (bytes-like object) – single point encoding of the public key

  • curve (ecdsa.curves.Curve) – the curve on which the public key is expected to lay

  • hashfunc (callable) – The default hash function that will be used for verification, needs to implement the same interface as hashlib.sha1. Ignored for EdDSA.

  • validate_point (bool) – whether to verify that the point lays on the provided curve or not, defaults to True. Ignored for EdDSA.

  • valid_encodings (set-like object) – list of acceptable point encoding formats, supported ones are: uncompressed, compressed, hybrid, and raw encoding (specified with raw name). All formats by default (specified with None). Ignored for EdDSA.

Raises

MalformedPointError – if the public point does not lay on the curve or the encoding is invalid

Returns

Initialised VerifyingKey object

Return type

VerifyingKey

id[source]

An optional string identifier for this key instance.

verify_dict(data, signature_encoding='base64')[source]

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.