diff options
| author | Arthur de Jong <arthur@arthurdejong.org> | 2016-03-27 17:53:26 +0200 |
|---|---|---|
| committer | Arthur de Jong <arthur@arthurdejong.org> | 2016-03-27 17:53:26 +0200 |
| commit | b4a6c720cb202f44b07ad2d0f9d8812ab7212ea5 (patch) | |
| tree | fe056384a6a3112dd6ca9f34f3d722413fe931e1 /docs | |
| parent | 8b5f6c27e0dde5f8b995b89dd2e3c9fa3caed3d5 (diff) | |
| parent | 59aa65be6d3349e78d2f17e94ae34f6767113a87 (diff) | |
Implement writing encrypted files
This adds support for setting up encryption keys and password-based key
derivation when writing PSKC files. Also MAC keys are set up when
needed.
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/conf.py | 2 | ||||
| -rw-r--r-- | docs/encryption.rst | 74 | ||||
| -rw-r--r-- | docs/mac.rst | 11 | ||||
| -rw-r--r-- | docs/usage.rst | 25 |
4 files changed, 96 insertions, 16 deletions
diff --git a/docs/conf.py b/docs/conf.py index 268d158..5a7ecbf 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -46,7 +46,7 @@ master_doc = 'index' # General information about the project. project = u'python-pskc' -copyright = u'2014-2015 Arthur de Jong' +copyright = u'2014-2016 Arthur de Jong' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the diff --git a/docs/encryption.rst b/docs/encryption.rst index 9bedf8c..cafdb74 100644 --- a/docs/encryption.rst +++ b/docs/encryption.rst @@ -23,11 +23,23 @@ or:: 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 set configured, upon accessing encrypted +If no key or an incorrect key has been configured, upon accessing encrypted information (e.g. the :attr:`~pskc.key.Key.secret` attribute of a :class:`~pskc.key.Key` instance) a :exc:`~pskc.exceptions.DecryptionError` exception will be raised. +When writing out a PSKC file, encryption can be configured with the +:func:`~pskc.encryption.Encryption.setup_preshared_key()` or +:func:`~pskc.encryption.Encryption.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 -------------------- @@ -40,7 +52,10 @@ The Encryption class .. attribute:: algorithm - A URI of the encryption algorithm used. + A URI of the encryption algorithm used. Setting a value for this + attribute will result in an attempt to use the canonical URI for this + algorithm. For instance setting a `3DES-CBC` value will automatically + be converted to `http://www.w3.org/2001/04/xmlenc#aes128-cbc`. .. attribute:: key_names @@ -68,3 +83,58 @@ The Encryption class This function may raise a :exc:`~pskc.exceptions.KeyDerivationError` exception if key derivation fails for some reason. + + .. attribute:: fields + + A list of :class:`~pskc.key.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``. + + .. function:: setup_preshared_key(...) + + Configure pre-shared key encryption. + + :param binary key: the encryption key to use + :param str id: encryption key identifier + :param str algorithm: encryption algorithm + :param int key_length: encryption key length in bytes + :param str key_name: a name for the key + :param list key_names: a number of names for the key + :param list 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 + :class:`~pskc.encryption.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 + :func:`~pskc.mac.MAC.setup()`. + + By default only the :attr:`~pskc.key.Key.secret` property will be + encrypted when writing the file. + + .. function:: setup_pbkdf2(...) + + Configure password-based PSKC encryption. + + :param str password: the password to use (required) + :param str id: encryption key identifier + :param str algorithm: encryption algorithm + :param int key_length: encryption key length in bytes + :param str key_name: a name for the key + :param list key_names: a number of names for the key + :param list fields: a list of fields to encrypt + :param binary salt: PBKDF2 salt + :param int salt_length: used when generating random salt + :param int iterations: number of PBKDF2 iterations + :param function prf: PBKDF2 pseudorandom function + + Defaults for the above parameters are similar to those for + :func:`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. diff --git a/docs/mac.rst b/docs/mac.rst index 4847071..0e8e5d5 100644 --- a/docs/mac.rst +++ b/docs/mac.rst @@ -38,3 +38,14 @@ The MAC class MAC key is generated specifically for each PSKC file and encrypted with the PSKC encryption key, so the PSKC file should be decrypted first (see :doc:`encryption`). + + .. function:: setup(...) + + Configure an encrypted MAC key. + + :param str algorithm: encryption algorithm + :param binary key: the encryption key to use + + None of the arguments are required. By default HMAC-SHA1 will be used + as a MAC algorithm. If no key is configured a random key will be + generated with the length of the output of the configured hash. diff --git a/docs/usage.rst b/docs/usage.rst index 7a9cdcb..5e0edfc 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -1,13 +1,13 @@ Basic usage =========== -The :mod:`pskc` module implements a simple and efficient API for parsing PSKC -files. The :class:`~pskc.PSKC` class is used to access the file as a whole -which provides access to a list of :class:`~pskc.key.Key` instances which -contain most of the useful information from the PSKC file. +The :mod:`pskc` module implements a simple and efficient API for parsing and +creating PSKC files. The :class:`~pskc.PSKC` class is used to access the file +as a whole which provides access to a list of :class:`~pskc.key.Key` +instances which contain most of the useful information of the PSKC file. -Opening a PSKC file +Reading a PSKC file ------------------- Importing data from a PSKC file can be done by instantiating the @@ -50,16 +50,15 @@ adding keys with :func:`~pskc.PSKC.add_key()` and writing the result:: >>> from pskc import PSKC >>> pskc = PSKC() - >>> key = pskc.add_key(id='456', manufacturer='Manufacturer') - >>> key.id - '456' - >>> key.secret = '987654321' - >>> key.algorithm = 'urn:ietf:params:xml:ns:keyprov:pskc:hotp' + >>> key = pskc.add_key( + ... id='456', secret='987654321', manufacturer='Manufacturer', + ... algorithm = 'urn:ietf:params:xml:ns:keyprov:pskc:hotp') >>> pskc.write('output.pskcxml') -Writing the data in encrypted form in the PSKC file is not yet supported so -currently opening an encrypted PSKC file, providing the encryption key and -writing the file should result in the same file but with encryption removed. +By default an unencrypted PSKC file will be created but an encryption can be +configured using the +:func:`~pskc.encryption.Encryption.setup_preshared_key()` or +:func:`~pskc.encryption.Encryption.setup_pbkdf2()` function. The PSKC class |