PSKC encryption

Some of the information in PSKC files (e.g. key material) can be encrypted with either pre-shared keys, passphrase-based keys or asymmetric keys (asymmetric keys are currently unimplemented).

Embedded PSKC encryption is handled inside the Encryption class that defines encryption key or means of deriving keys. It is accessed from the encryption attribute of a PSKC instance:

>>> from binascii import a2b_hex
>>> from pskc import PSKC
>>> pskc = PSKC('somefile.pskcxml')
>>> pskc.encryption.key = a2b_hex('12345678901234567890123456789012')

or:

>>> pskc.encryption.derive_key('qwerty')

Once the encryption key has been set up, any encrypted key values from the PSKC file are available transparently.

If no key or an incorrect key has been configured, upon accessing encrypted information (e.g. the secret attribute of a Key instance) a DecryptionError exception will be raised.

When writing out a PSKC file, encryption can be configured with the setup_preshared_key() or setup_pbkdf2() function:

>>> from pskc import PSKC
>>> pskc = PSKC()
>>> pskc.encryption.setup_preshared_key(algorithm='AES256-CBC')

or:

>>> pskc.encryption.setup_pbkdf2(password='verysecure')

The Encryption class

class pskc.encryption.Encryption

id: str | None

Optional identifier of the encryption key.

algorithm: str | None

A URI of the encryption algorithm used. See the section Supported encryption algorithms below for a list of algorithms URIs.

Assigned values to this attribute will be converted to the canonical URI for the algorithm if it is known. For instance, the value 3DES-CBC will automatically be converted into http://www.w3.org/2001/04/xmlenc#tripledes-cbc.

is_encrypted: bool

An indicator of whether the PSKC file requires an additional pre-shared key or passphrase to decrypt the contents of the file. Will be True if a key or passphrase is needed, False otherwise.

key_names: list[str]

List of names provided for the encryption key.

key_name: str | None

Since usually only one name is defined for a key but the schema allows for multiple names, this is a shortcut for accessing the first value of key_names. It will return None if no name is available.

key: bytes | None

The binary value of the encryption key. In the case of pre-shared keys this value should be set before trying to access encrypted information in the PSKC file.

When using key derivation the secret key is available in this attribute after calling derive_key().

derive_key(password: str | bytes | bytearray) → None

Derive a key from the password.

The supplied password, together with the information embedded in the PSKC file (generally algorithm, salt, etc.) is used to create a decryption key.

This function may raise a KeyDerivationError exception if key derivation fails.

fields: list[str]

A list of Key instance field names that will be encrypted when the PSKC file is written. List values can contain secret, counter, time_offset, time_interval and time_drift.

setup_preshared_key(*, key: bytes | None = None, id: str | None = None, algorithm: str | None = None, key_length: int | None = None, key_name: str | None = None, key_names: list[str] | None = None, fields: list[str] | None = None) → None

Configure pre-shared key encryption when writing the file.

Parameters:

• key – the encryption key to use

• id – encryption key identifier

• algorithm – encryption algorithm

• key_length – encryption key length in bytes

• key_name – a name for the key

• key_names – a number of names for the key

• fields – a list of fields to encrypt

This is a utility function to easily set up encryption. Encryption can also be set up by manually by setting the correct Encryption properties.

This method will generate a key if required and set the passed values. By default AES128-CBC encryption will be configured and unless a key is specified one of the correct length will be generated. If the algorithm does not provide integrity checks (e.g. CBC-mode algorithms) integrity checking in the PSKC file will be set up using setup().

By default only the secret property will be encrypted when writing the file.

setup_pbkdf2(password: str | bytes | bytearray, *, id: str | None = None, algorithm: str | None = None, key_name: str | None = None, key_names: list[str] | None = None, key_length: int | None = None, fields: list[str] | None = None, salt: bytes | None = None, salt_length: int = 16, iterations: int | None = None, prf: str | None = None) → None

Configure password-based PSKC encryption when writing the file.

Parameters:

• password – the password to use (required)

• id – encryption key identifier

• algorithm – encryption algorithm

• key_length – encryption key length in bytes

• key_name – a name for the key

• key_names – a number of names for the key

• fields – a list of fields to encrypt

• salt – PBKDF2 salt

• salt_length – used when generating random salt

• iterations – number of PBKDF2 iterations

• prf – PBKDF2 pseudorandom function

Defaults for the above parameters are similar to those for setup_preshared_key() but the password parameter is required.

By default 12000 iterations will be used and a random salt with the length of the to-be-generated encryption key will be used.

remove_encryption() → None

Decrypt all values and remove the encryption from the PSKC file.

This can be used to read and encrypted PSKC file, decrypt the file, remove the encryption and output an unencrypted PSKC file or to replace the encryption algorithm.

Supported encryption algorithms

The following encryption algorithms are currently supported by python-pskc.

URI	Description
http://www.w3.org/2001/04/xmlenc#aes128-cbc http://www.w3.org/2001/04/xmlenc#aes192-cbc http://www.w3.org/2001/04/xmlenc#aes256-cbc	AES encryption in CBC mode with various key lengths
http://www.w3.org/2001/04/xmlenc#kw-aes128 http://www.w3.org/2001/04/xmlenc#kw-aes192 http://www.w3.org/2001/04/xmlenc#kw-aes256	AES key wrap with various key lengths
http://www.w3.org/2001/04/xmlenc#tripledes-cbc	Triple DES (3DES) encryption in CBC mode
http://www.w3.org/2001/04/xmlenc#kw-tripledes	Triple DES (3DES) key wrap