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
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
- Returns
The decrypted data.
- Return type
- 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 theopenssl
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
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.
- 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.
- class SigningKey(*args, **kwargs)[source]
Bases:
SigningKey
,object
- classmethod from_dict(value, encoding='base64', **kwargs)[source]
Load the signing key from the specified dict object.
- Parameters
- Returns
The new signing key.
- Return type
- 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 andsha256
as the message digest. This usesopenssl_decrypt_data()
internally for decrypting the data.- Parameters
- Returns
A tuple of the key’s ID, and the new
SigningKey
instance.- Return type
- 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 (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
- 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 (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
- 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 thejson.dumps()
function is used and the resulting data is then UTF-8 encoded.
- class VerifyingKey(*args, **kwargs)[source]
Bases:
VerifyingKey
,object
- classmethod from_dict(value, encoding='base64', **kwargs)[source]
Load the verifying key from the specified dict object.
- Parameters
- Returns
The new verifying key.
- Return type
- 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 (AbstractPoint) – The point to wrap around, the actual public key
curve (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
- 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 (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 withNone
). 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
- 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 thejson.dumps()
function is used and the resulting data is then UTF-8 encoded.