python-pskc branch master updated. 0.1-44-gf084735

[Date Prev][Date Next] [Thread Prev][Thread Next]
From: Commits of the python-pskc project <python-pskc-commits [at] lists.arthurdejong.org>
To: python-pskc-commits [at] lists.arthurdejong.org
Reply-to: python-pskc-users [at] lists.arthurdejong.org
Subject: python-pskc branch master updated. 0.1-44-gf084735
Date: Mon, 16 Jun 2014 21:49:50 +0200 (CEST)
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "python-pskc".

The branch, master has been updated
       via  f084735eef4d57282af93899f326277367f9f281 (commit)
       via  d84e7614525437a7a397664f05e1b7c720e903ef (commit)
      from  50b429d5f8698373dd8c0b0dbe554d4b98f1487c (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
http://arthurdejong.org/git/python-pskc/commit/?id=f084735eef4d57282af93899f326277367f9f281

commit f084735eef4d57282af93899f326277367f9f281
Author: Arthur de Jong <arthur@arthurdejong.org>
Date:   Mon Jun 16 21:40:53 2014 +0200

    Update documentation
    
    This updates the documentation with the current API, adding information
    on exceptions raised, HMAC algorithms supported and changes to the MAC
    checking.
    
    This also includes some editorial changes to some of the text and making
    references shorter by not including the full package path.

diff --git a/README b/README
index a833747..5573c77 100644
--- a/README
+++ b/README
@@ -3,9 +3,9 @@ Python PSKC module
 
 A Python module to handle Portable Symmetric Key Container (PSKC) files as
 defined in `RFC 6030 <https://tools.ietf.org/html/rfc6030>`_. PSKC files are
-used to transport and provision symmetric keys and key related meta data to
-different types of crypto modules. The format is commonly used for one-time
-password tokens or other authentication devices.
+used to transport and provision symmetric keys and key meta data to different
+types of crypto modules. The format is commonly used for one-time password
+tokens or other authentication devices.
 
 The goal of this module is mainly to provide parsing of PSKC files in order
 to extract secret keys for use in an OTP authentication system. At a later
diff --git a/docs/encryption.rst b/docs/encryption.rst
index 8213e8e..e0c8ca0 100644
--- a/docs/encryption.rst
+++ b/docs/encryption.rst
@@ -3,26 +3,31 @@ PSKC encryption
 
 .. module:: pskc.encryption
 
-The keys (and some other data) in PSKC files can be encrypted. Encryption of
-embedded data is defined in a PSKC file with either pre-shared keys,
-passphrase-based keys or asymmetric keys (asymmetric keys are currently
-unimplemented).
+The keys (and some embedded data) in PSKC files 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 :class:`Encryption` class that
-defines encryption key and means of deriving keys. It is accessed from
-:attr:`pskc.PSKC.encryption`::
+defines encryption key and means of deriving keys. It is accessed from the
+:attr:`~pskc.PSKC.encryption` attribute of a :class:`~pskc.PSKC` instance::
 
-   from pskc import PSKC
-   pskc = PSKC('somefile.pskcxml')
-   pskc.encryption.key = '12345678901234567890123456789012'.decode('hex')
+   >>> from pskc import PSKC
+   >>> pskc = PSKC('somefile.pskcxml')
+   >>> pskc.encryption.key = '12345678901234567890123456789012'.decode('hex')
 
 or::
 
-   pskc.encryption.derive_key('qwerty')
+   >>> 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 an incorrect key has been set up, only 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.
+
+
 .. class:: Encryption
 
    .. attribute:: id
@@ -52,3 +57,6 @@ PSKC file are available transparently.
 
       Derive a key from the supplied password and information in the PSKC
       file (generally algorithm, salt, etc.).
+
+      This function may raise a :exc:`~pskc.exceptions.KeyDerivationError`
+      exception if key derivation fails for some reason.
diff --git a/docs/exceptions.rst b/docs/exceptions.rst
new file mode 100644
index 0000000..bf1414f
--- /dev/null
+++ b/docs/exceptions.rst
@@ -0,0 +1,38 @@
+Exceptions
+==========
+
+.. module:: pskc.exceptions
+
+.. exception:: PSKCError
+
+   The base class for all exceptions that the module will raise. In some
+   cases third-party code may raise additional exceptions.
+
+.. exception:: ParseError
+
+   Raised when the PSKC file cannot be correctly read due to invalid XML or
+   some required element or attribute is missing. This exception should only
+   be raised when parsing the file (i.e. when the :class:`~pskc.PSKC` class is
+   instantiated).
+
+.. .. exception:: EncryptionError
+
+   Raised when encrypting a value is not possible due to key length issues,
+   missing or wrong length plain text, or other issues.
+
+.. exception:: DecryptionError
+
+   Raised when decrypting the embedded encrypted value fails due to missing
+   or incorrect key, unsupported decryption or MAC algorithm, failed message
+   authentication check or other error.
+
+   This exception is generally raised when accessing encrypted information
+   (i.e. the :attr:`~pskc.key.Key.secret`, :attr:`~pskc.key.Key.counter`,
+   :attr:`~pskc.key.Key.time_offset`, :attr:`~pskc.key.Key.time_interval` or
+   :attr:`~pskc.key.Key.time_drift` attributes of the :class:`~pskc.key.Key`
+   class).
+
+.. exception:: KeyDerivationError
+
+   Raised when key derivation fails due to an unsupported algorithm or
+   missing information in the PSKC file.
diff --git a/docs/index.rst b/docs/index.rst
index 131eb76..79c863c 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -12,6 +12,7 @@ Contents
    encryption
    mac
    policy
+   exceptions
 
 
 Security considerations
diff --git a/docs/mac.rst b/docs/mac.rst
index 1df1dae..6e50626 100644
--- a/docs/mac.rst
+++ b/docs/mac.rst
@@ -11,8 +11,9 @@ stored within the PSKC file.
 
    .. attribute:: algorithm
 
-      The name of the MAC algorithm to use (currently only ``HMAC_SHA1`` is
-      supported).
+      The name of the MAC algorithm to use (currently ``HMAC-MD5``,
+      ``HMAC-SHA1``, ``HMAC-SHA224``, ``HMAC-SHA256``, ``HMAC-SHA384`` and
+      ``HMAC-SHA512`` are supported).
 
    .. attribute:: key
 
@@ -21,9 +22,13 @@ stored within the PSKC file.
       the PSKC encryption key, so the PSKC file should be decrypted first
       (see :doc:`encryption`).
 
-Once the PSKC encryption key has been set up key values can be checked using
-the :func:`pskc.key.Key.check` method::
 
-   pskc = PSKC('somefile.pskcxml')
-   pskc.encryption.derive_key('qwerty')
-   all(key.check() for key in pskc.keys)
+Once the PSKC encryption key has been set up key values can be explicitly
+checked using the :func:`~pskc.key.Key.check` method::
+
+   >>> pskc = PSKC('somefile.pskcxml')
+   >>> pskc.encryption.derive_key('qwerty')
+   >>> pskc.mac.algorithm
+   'http://www.w3.org/2000/09/xmldsig#hmac-sha1'
+   >>> all(key.check() for key in pskc.keys)
+   True
diff --git a/docs/policy.rst b/docs/policy.rst
index d50484b..91c51e2 100644
--- a/docs/policy.rst
+++ b/docs/policy.rst
@@ -6,7 +6,12 @@ Key usage policy
 The PSKC format allows for specifying `key and pin usage policy 
<https://tools.ietf.org/html/rfc6030#section-5>`__.
 
 Instances of the :class:`Policy` class provide attributes that describe
-limits that are placed on key usage and requirements for key PIN protection.
+limits that are placed on key usage and requirements for key PIN protection::
+
+   >>> key = pskc.keys[0]
+   >>> key.policy.may_use(key.policy.KEY_USE_OTP)
+   True
+
 
 .. class:: Policy
 
@@ -43,7 +48,7 @@ limits that are placed on key usage and requirements for key 
PIN protection.
 
    .. attribute:: pin_key
 
-      Instance of the :class:`pskc.key.Key` (if any) that contains the value
+      Instance of the :class:`~pskc.key.Key` (if any) that contains the value
       of the PIN referenced by :attr:`pin_key_id`.
 
    .. attribute:: pin
@@ -74,7 +79,7 @@ limits that are placed on key usage and requirements for key 
PIN protection.
 
       The encoding of the PIN which is one of ``DECIMAL``, ``HEXADECIMAL``,
       ``ALPHANUMERIC``, ``BASE64``, or ``BINARY`` (see
-      :attr:`pskc.key.Key.challenge_encoding`).
+      :attr:`~pskc.key.Key.challenge_encoding`).
 
    .. attribute:: unknown_policy_elements
 
@@ -92,7 +97,7 @@ limits that are placed on key usage and requirements for key 
PIN protection.
 .. _key-use-constants:
 
 The :class:`Policy` class provides the following key use constants (see
-:attr:`Policy.key_usage` and :func:`Policy.may_use`):
+:attr:`~Policy.key_usage` and :func:`~Policy.may_use`):
 
    .. autoattribute:: Policy.KEY_USE_OTP
 
@@ -147,7 +152,7 @@ The :class:`Policy` class provides the following key use 
constants (see
 .. _pin-use-constants:
 
 The following constants for PIN use are defined  in the :class:`Policy`
-class (see :attr:`Policy.pin_usage`):
+class (see :attr:`~Policy.pin_usage`):
 
    .. autoattribute:: Policy.PIN_USE_LOCAL
 
diff --git a/docs/usage.rst b/docs/usage.rst
index 0aab59e..10d01e2 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -2,7 +2,9 @@ Basic usage
 ===========
 
 The :mod:`pskc` module implements a simple and efficient API for parsing PSKC
-files.
+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.
 
 
 Opening a PSKC file
@@ -10,17 +12,23 @@ Opening a PSKC file
 
 .. module:: pskc
 
-Importing data from a PSKC file can be done by instantiating a :class:`PSKC`
-class::
+Importing data from a PSKC file can be done by instantiating a
+:class:`~pskc.PSKC` class::
 
-   from pskc import PSKC
-   pskc = PSKC('somefile.pskcxml')
+    >>> from pskc import PSKC
+    >>> pskc = PSKC('somefile.pskcxml')
+    >>> pskc.version
+    '1.0'
 
-.. class:: PSKC(filename)
+
+.. class:: PSKC([filename])
 
    The :class:`PSKC` class is used as a wrapper to access information from a
-   PSKC file. The whole file is parsed in one go. Instances of this class
-   provide the following attributes:
+   PSKC file.
+
+   The whole file is parsed in one go. Instances of this class provide the
+   following attributes: If parsing the PSKC file fails, a
+   :exc:`~pskc.exceptions.ParseError` exception is raised.
 
    .. attribute:: version
 
@@ -34,18 +42,17 @@ class::
 
    .. attribute:: keys
 
-      A list of :class:`pskc.key.Key` instances that represent the keys
+      A list of :class:`~pskc.key.Key` instances that represent the keys
       within the PSKC file.
 
    .. attribute:: encryption
 
-      Instance of the :class:`pskc.encryption.Encryption` class that handles
-      PSKC file encryption.
+      :class:`~pskc.encryption.Encryption` instance that handles PSKC file
+      encryption.
 
    .. attribute:: mac
 
-      Instance of the :class:`pskc.mac.MAC` class that handles integrity
-      checking.
+      :class:`~pskc.mac.MAC` instance that handles integrity checking.
 
 
 Examining keys
@@ -53,15 +60,27 @@ Examining keys
 
 .. module:: pskc.key
 
-The :attr:`pskc.PSKC.keys` attribute provides access to the keys contained in
-the PSKC file. Instances of the :class:`Key` class provide access to a number
-of attributes that provide information on the transmitted keys::
+The :attr:`~pskc.PSKC.keys` attribute of a :class:`~pskc.PSKC` instance
+provides access to a list of keys contained in the PSKC file. :class:`Key`
+instances provide access to a number of attributes that provide information
+on the transmitted keys::
 
-   pskc = PSKC('somefile.pskcxml')
-   first_key = pskc.keys[0]
+    >>> pskc = PSKC('somefile.pskcxml')
+    >>> first_key = pskc.keys[0]
+    >>> first_key.id
+    'some-id'
+    >>> first_key.algorithm
+    'urn:ietf:params:xml:ns:keyprov:pskc:hotp'
+    >>> first_key.secret
+    'SOME_SECRET_VALUE'
 
 Attribute values will be ``None`` if it the value is not present in the PSKC
-file.
+file. If any of the :attr:`~pskc.key.Key.secret`,
+:attr:`~pskc.key.Key.counter`, :attr:`~pskc.key.Key.time_offset`,
+:attr:`~pskc.key.Key.time_interval` or :attr:`~pskc.key.Key.time_drift`
+values are accessed while they are encrypted and decryption is unsuccessful a
+:exc:`~pskc.exceptions.DecryptionError` exception is raised.
+
 
 .. class:: Key()
 
@@ -91,27 +110,33 @@ file.
 
       The binary value of the transported secret key. If the key information
       is encrypted in the PSKC file it is transparently decrypted if
-      possible.
+      possible. Accessing the value may raise
+      :exc:`~pskc.exceptions.DecryptionError` if decryption fails.
 
    .. attribute:: counter
 
-      The event counter for event-based OTP algorithms.
+      The event counter for event-based OTP algorithms. Will also be
+      transparently decrypted and may also raise
+      :exc:`~pskc.exceptions.DecryptionError`.
 
    .. attribute:: time_offset
 
       The time offset offset for time-based OTP algorithms. If time intervals
       are used it carries the number of time intervals passed from an
-      algorithm-dependent start point.
+      algorithm-dependent start point. Will also be transparently decrypted
+      and may also raise :exc:`~pskc.exceptions.DecryptionError`.
 
    .. attribute:: time_interval
 
       The time interval in seconds for time-based OTP algorithms (usually
-      ``30`` or ``60``).
+      ``30`` or ``60``). Will also be transparently decrypted and may also
+      raise :exc:`~pskc.exceptions.DecryptionError`.
 
    .. attribute:: time_drift
 
       For time-based OTP algorithms this contains the device clock drift in
-      number of intervals.
+      number of intervals. Will also be transparently decrypted and may also
+      raise :exc:`~pskc.exceptions.DecryptionError`.
 
    .. attribute:: issuer
 
@@ -155,8 +180,8 @@ file.
    .. attribute:: serial
 
       The serial number of the device to which the key is provisioned.
-      Together with :attr:`manufacturer` (and perhaps :attr:`issue_no`)
-      this should uniquely identify the device.
+      Together with :attr:`manufacturer` (and possibly :attr:`issue_no`) this
+      should uniquely identify the device.
 
    .. attribute:: model
 
@@ -243,11 +268,12 @@ file.
 
    .. attribute:: policy
 
-      Instance of :class:`pskc.policy.Policy` that provides key and PIN
-      policy information. See :doc:`policy`.
+      :class:`~pskc.policy.Policy` instance that provides key and PIN policy
+      information. See :doc:`policy`.
 
    .. function:: check()
 
       Check if any MACs in the key data embedded in the PSKC file are valid.
-      Will return a boolean or ``None`` if no MACs are defined for the key.
-      See :doc:`mac`.
+      This will return None if there is no MAC to be checked. It will return
+      True if all the MACs match. If any MAC fails a
+      :exc:`~pskc.exceptions.DecryptionError` exception is raised.

http://arthurdejong.org/git/python-pskc/commit/?id=d84e7614525437a7a397664f05e1b7c720e903ef

commit d84e7614525437a7a397664f05e1b7c720e903ef
Author: Arthur de Jong <arthur@arthurdejong.org>
Date:   Sun Jun 15 22:14:49 2014 +0200

    Simplify finding ElementTree implementation
    
    These are the only ElementTree implementations that have been tested to
    provide the needed functionality (mostly namespaces).

diff --git a/pskc/parse.py b/pskc/parse.py
index 4f3a7ec..a08bfc1 100644
--- a/pskc/parse.py
+++ b/pskc/parse.py
@@ -27,16 +27,7 @@ This module provides some utility functions for parsing PSKC 
files.
 try:
     from lxml import etree
 except ImportError:  # pragma: no cover (different implementations)
-    try:
-        import xml.etree.cElementTree as etree
-    except ImportError:
-        try:
-            import xml.etree.ElementTree as etree
-        except ImportError:
-            try:
-                import cElementTree as etree
-            except ImportError:
-                import elementtree.ElementTree as etree
+    import xml.etree.ElementTree as etree
 
 
 # the relevant XML namespaces for PSKC

-----------------------------------------------------------------------

Summary of changes:
 README              |    6 ++--
 docs/encryption.rst |   28 +++++++++++------
 docs/exceptions.rst |   38 +++++++++++++++++++++++
 docs/index.rst      |    1 +
 docs/mac.rst        |   19 +++++++-----
 docs/policy.rst     |   15 ++++++---
 docs/usage.rst      |   86 +++++++++++++++++++++++++++++++++------------------
 pskc/parse.py       |   11 +------
 8 files changed, 139 insertions(+), 65 deletions(-)
 create mode 100644 docs/exceptions.rst


hooks/post-receive
-- 
python-pskc
-- 
To unsubscribe send an email to
python-pskc-commits-unsubscribe@lists.arthurdejong.org or see
http://lists.arthurdejong.org/python-pskc-commits/
python-pskc branch master updated. 0.1-44-gf084735, Commits of the python-pskc project
Prev by Date: python-pskc branch master updated. 0.1-42-g50b429d
Next by Date: python-pskc branch master updated. 0.1-49-g09eb6b3
Previous by thread: python-pskc branch master updated. 0.1-42-g50b429d
Next by thread: python-pskc branch master updated. 0.1-49-g09eb6b3