Update documentation

This updates the documentation with the new features (writing PSKC
files) as well as many editorial improvements, some rewording and a few
typo fixes. Some things were moved around a little in order to be more
easily readable and easier to find.

Author: arthurdejong

README

@@ -8,8 +8,7 @@ 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
-time support for writing files may be added.
+to extract secret keys for use in an OTP authentication system.
 
 http://arthurdejong.org/python-pskc/
 
@@ -20,7 +19,7 @@ API
 The module provides a straightforward API that is mostly geared towards
 parsing existing PSKC files.
 
-Extracting key matarial from PSKC files is as simple as.
+Extracting key matarial from encrypted PSKC files is as simple as.
 
 >>> from pskc import PSKC
 >>> pskc = PSKC('tests/rfc6030-figure7.pskcxml')
@@ -45,7 +44,7 @@ private key material.
 Copyright
 ---------
 
-Copyright (C) 2014 Arthur de Jong
+Copyright (C) 2014-2015 Arthur de Jong
 
 This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public

docs/conf.py

@@ -46,7 +46,7 @@
 
 # General information about the project.
 project = u'python-pskc'
-copyright = u'2014, Arthur de Jong'
+copyright = u'2014-2015 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

docs/encryption.rst

@@ -8,26 +8,30 @@ 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 the
+defines encryption key or means of deriving keys. It is accessed from the
 :attr:`~pskc.PSKC.encryption` attribute of a :class:`~pskc.PSKC` instance::
 
+   >>> rom binascii import a2b_hex
    >>> from pskc import PSKC
    >>> pskc = PSKC('somefile.pskcxml')
-   >>> pskc.encryption.key = '12345678901234567890123456789012'.decode('hex')
+   >>> 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
+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
+If an incorrect key has been set up, 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.
 
 
+The Encryption class
+--------------------
+
 .. class:: Encryption
 
    .. attribute:: id

docs/exceptions.rst

@@ -22,9 +22,9 @@ Exceptions
 
 .. 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.
+   Raised when decrypting a 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`,

docs/mac.rst

@@ -7,6 +7,23 @@ The PSKC format allows for `message authentication and integrity checking
 <https://tools.ietf.org/html/rfc6030#section-6.1.1>`_ for some of the values
 stored within the PSKC file.
 
+Integrity checking is done transparently when accessing attributes that
+are encrypted and contain a ValueMAC.
+
+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
+
+
+The MAC class
+-------------
+
 .. class:: MAC
 
    .. attribute:: algorithm
@@ -21,14 +38,3 @@ stored within the PSKC file.
       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`).
-
-
-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

docs/policy.rst

@@ -3,7 +3,8 @@ Key usage policy
 
 .. module:: pskc.policy
 
-The PSKC format allows for specifying `key and pin usage policy <https://tools.ietf.org/html/rfc6030#section-5>`__.
+The PSKC format allows for specifying `key and pin usage policy <https://tools.ietf.org/html/rfc6030#section-5>`__
+per key.
 
 Instances of the :class:`Policy` class provide attributes that describe
 limits that are placed on key usage and requirements for key PIN protection::
@@ -13,6 +14,9 @@ limits that are placed on key usage and requirements for key PIN protection::
    True
 
 
+The Policy class
+----------------
+
 .. class:: Policy
 
    .. attribute:: start_date
@@ -38,13 +42,12 @@ limits that are placed on key usage and requirements for key PIN protection::
       A list of `valid usage scenarios
       <https://www.iana.org/assignments/pskc/#key-usage>`__ for the
       key that the recipient should check against the intended usage of the
-      key. Also see :func:`may_use` and :ref:`the list of key usage constants
-      below <key-use-constants>`.
+      key. Also see :func:`may_use` and :ref:`key-use-constants` below.
 
    .. attribute:: pin_key_id
 
-      The unique `id` value used to reference the key within the PSKC file
-      that contains the value of the PIN that protects this key.
+      The unique `id` of the key within the PSKC file that contains the value
+      of the PIN that protects this key.
 
    .. attribute:: pin_key
 
@@ -58,8 +61,8 @@ limits that are placed on key usage and requirements for key PIN protection::
 
    .. attribute:: pin_usage
 
-      Describe how the PIN is used during the usage of the key. See :ref:`the
-      list of pin usage constants below <pin-use-constants>`.
+      Describe how the PIN is used during the usage of the key. See
+      :ref:`pin-use-constants` below.
 
    .. attribute:: pin_max_failed_attemtps
 
@@ -92,10 +95,14 @@ limits that are placed on key usage and requirements for key PIN protection::
    .. function:: may_use(usage)
 
       Check whether the key may be used for the provided purpose. See
-      :ref:`the list of key usage constants below <key-use-constants>`.
+      :ref:`key-use-constants` below.
+
 
 .. _key-use-constants:
 
+Key usage constants
+-------------------
+
 The :class:`Policy` class provides the following key use constants (see
 :attr:`~Policy.key_usage` and :func:`~Policy.may_use`):
 
@@ -149,8 +156,12 @@ The :class:`Policy` class provides the following key use constants (see
       The key is used to generate a new key based on a random number and the
       previous value of the key.
 
+
 .. _pin-use-constants:
 
+Pin usage constants
+-------------------
+
 The following constants for PIN use are defined  in the :class:`Policy`
 class (see :attr:`~Policy.pin_usage`):