Include type information in documentation

This also includes a few other cleanups moving some documentation to
docstrings.

Author: arthurdejong

docs/encryption.rst

@@ -46,11 +46,12 @@ The Encryption class
 
 .. class:: Encryption
 
-   .. attribute:: id
+   .. autoattribute:: id
 
       Optional identifier of the encryption key.
 
    .. attribute:: algorithm
+      :type: str | None
 
       A URI of the encryption algorithm used. See the section
       :ref:`encryption-algorithms` below for a list of algorithms URIs.
@@ -62,22 +63,24 @@ The Encryption class
 
 
    .. attribute:: is_encrypted
+      :type: 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.
 
-   .. attribute:: key_names
+   .. autoattribute:: key_names
 
       List of names provided for the encryption key.
 
    .. attribute:: key_name
+      :type: 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
       :attr:`key_names`. It will return ``None`` if no name is available.
 
-   .. attribute:: key
+   .. autoattribute:: key
 
       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
@@ -86,75 +89,20 @@ The Encryption class
       When using key derivation the secret key is available in this attribute
       after calling :func:`derive_key`.
 
-   .. function:: derive_key(password)
+   .. automethod:: derive_key
 
-      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.
-
-   .. attribute:: fields
+   .. autoattribute:: 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 when writing the file.
-
-      :param bytes 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 when writing the file.
-
-      :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 bytes 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.
+   .. automethod:: setup_preshared_key
 
-   .. function:: remove_encryption()
+   .. automethod:: setup_pbkdf2
 
-      Decrypt all data stored in the PSKC file and remove the encryption
-      configuration. 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.
+   .. automethod:: remove_encryption
 
 
 .. _encryption-algorithms:

docs/exceptions.rst

@@ -6,36 +6,12 @@ only raise exceptions on wildly invalid PSKC files.
 
 .. module:: pskc.exceptions
 
-.. exception:: PSKCError
+.. autoexception:: PSKCError
 
-   The base class for all exceptions that the module will raise. In some
-   cases third-party code may raise additional exceptions.
+.. autoexception:: ParseError
 
-.. exception:: ParseError
+.. autoexception:: EncryptionError
 
-   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).
+.. autoexception:: DecryptionError
 
-.. .. 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 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`,
-   :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.
+.. autoexception:: KeyDerivationError

docs/mac.rst

@@ -27,6 +27,7 @@ The MAC class
 .. class:: MAC
 
    .. attribute:: algorithm
+      :type: str | None
 
       A URI of the MAC algorithm used for message authentication. See the
       section :ref:`mac-algorithms` below for a list of algorithm URIs.
@@ -37,25 +38,14 @@ The MAC class
       ``http://www.w3.org/2001/04/xmldsig-more#hmac-sha256``.
 
    .. attribute:: key
+      :type: bytes | None
 
       For HMAC checking, this contains the binary value of the MAC key. The
       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 for creating a new PSKC file.
-
-      :param str algorithm: encryption algorithm
-      :param bytes 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.
-
-      This function will automatically be called when the configured
-      encryption algorithm requires a message authentication code.
+   .. automethod:: setup
 
 
 .. _mac-algorithms:

docs/policy.rst

@@ -19,84 +19,83 @@ The Policy class
 
 .. class:: Policy
 
-   .. attribute:: start_date
+   .. autoattribute:: start_date
 
       :class:`datetime.datetime` value that indicates that the key must not
       be used before this date.
 
-   .. attribute:: expiry_date
+   .. autoattribute:: expiry_date
 
       :class:`datetime.datetime` value that indicates that the key must not
       be used after this date. Systems should not rely upon the device to
       enforce key usage date restrictions, as some devices do not have an
       internal clock.
 
-   .. attribute:: number_of_transactions
+   .. autoattribute:: number_of_transactions
 
       The value indicates the maximum number of times a key carried within
       the PSKC document may be used by an application after having received
       it.
 
-   .. attribute:: key_usage
+   .. autoattribute:: key_usage
 
       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:`key-use-constants` below.
 
-   .. attribute:: pin_key_id
+   .. autoattribute:: pin_key_id
 
       The unique `id` of the key within the PSKC file that contains the value
       of the PIN that protects this key.
 
    .. attribute:: pin_key
+      :type: Key | None
 
       Instance of the :class:`~pskc.key.Key` (if any) that contains the value
       of the PIN referenced by :attr:`pin_key_id`.
 
    .. attribute:: pin
+      :type: str | None
 
       PIN value referenced by :attr:`pin_key_id` (if any). The value is
       transparently decrypted if possible.
 
-   .. attribute:: pin_usage
+   .. autoattribute:: pin_usage
 
       Describe how the PIN is used during the usage of the key. See
       :ref:`pin-use-constants` below.
 
-   .. attribute:: pin_max_failed_attempts
+   .. autoattribute:: pin_max_failed_attempts
 
       The maximum number of times the PIN may be entered wrongly before it
       MUST NOT be possible to use the key any more.
 
-   .. attribute:: pin_min_length
+   .. autoattribute:: pin_min_length
 
       The minimum length of a PIN that can be set to protect the associated
       key.
 
-   .. attribute:: pin_max_length
+   .. autoattribute:: pin_max_length
 
       The maximum length of a PIN that can be set to protect this key.
 
-   .. attribute:: pin_encoding
+   .. autoattribute:: pin_encoding
 
       The encoding of the PIN which is one of ``DECIMAL``, ``HEXADECIMAL``,
       ``ALPHANUMERIC``, ``BASE64``, or ``BINARY`` (see
       :attr:`~pskc.key.Key.challenge_encoding`).
 
    .. attribute:: unknown_policy_elements
+      :type: bool
 
       Boolean that is set to ``True`` if the PSKC policy information contains
       unknown or unsupported definitions or values. A conforming
       implementation must assume that key usage is not permitted if this
       value is ``True`` to ensure that the lack of understanding of certain
       extensions does not lead to unintended key usage.
 
-   .. function:: may_use(usage=None, now=None)
-
-      Check whether the key may be used for the provided purpose. The key
-      :attr:`start_date` and :attr:`expiry_date` are also checked. The `now`
-      argument can be used to specify another point in time to check against.
+   .. automethod:: may_use
 
 .. _key-use-constants:
 

docs/signatures.rst

@@ -31,84 +31,54 @@ The Signature class
 .. class:: Signature
 
    .. attribute:: is_signed
+      :type: bool
 
       A boolan value that indicates whether an XML signature is present in
       the PSKC file. This property does not indicate whether the signature
       is validated.
 
    .. attribute:: algorithm
+      :type: str | None
 
       A URI of the signing algorithm used.
       Assigned values to this attribute will be converted to the canonical
       URI for the algorithm if it is known.
 
-   .. attribute:: canonicalization_method
+   .. autoattribute:: canonicalization_method
 
       A URI that is used to identify the XML canonicalization method used.
 
-   .. attribute:: digest_algorithm
+   .. autoattribute:: digest_algorithm
 
       A URI that identifies that hashing algorithm that is used to construct
       the signature.
 
-   .. attribute:: issuer
+   .. autoattribute:: issuer
 
       A distinguished name of the issuer of the certificate that belongs to
       the key that is used for the signature.
 
-   .. attribute:: serial
+   .. autoattribute:: serial
 
       A serial number of the certificate that belongs to the key that is used
       for the signature.
 
-   .. attribute:: key
+   .. autoattribute:: key
 
       A PEM encoded key that will be used to create the signed PSKC file.
 
-   .. attribute:: certificate
+   .. autoattribute:: certificate
 
       A PEM encoded certificate that is embedded inside the signature that
       can be used to validate the signature.
 
    .. attribute:: signed_pskc
+      :type: PSKC
 
       A :class:`~pskc.PSKC` instance that contains the signed contents of the
       PSKC file. It is usually required to call :func:`verify` before
       accessing this attribute without raising an exception.
 
-   .. function:: verify(certificate=None, ca_pem_file=None)
+   .. automethod:: verify
 
-      Verify the validity of the embedded XML signature. This function will
-      raise an exception when the validation fails.
-
-      :param bytes certificate: a PEM encoded certificate that is used for verification
-      :param str ca_pem_file: the name of a file that contains a CA certificate
-
-      The signature can be verified in three ways:
-
-      * The signature was made with a key that has a certificate that is
-        signed by a CA that is configured in the system CA store. In this
-        case neither `certificate` or `ca_pem_file` need to be specified (but
-        a certificate needs to be embedded inside the PSKC file).
-      * The signature was made with a key and a certificate for the key was
-        transmitted out-of-band. In this case the `certificate` argument
-        needs to be present.
-      * The signature was made with a key and has a certificate that is
-        signed by a specific CA who's certificate was transmitted
-        out-of-band. In this case the `ca_pem_file` is used to point to a CA
-        certificate file (but a certificate needs to be embedded inside the
-        PSKC file).
-
-      After calling this function a verified version of the PSKC file will
-      be present in the :attr:`signed_pskc` attribute.
-
-   .. function:: sign(key, certificate=None)
-
-      Set up a key and optionally a certificate that will be used to create an
-      embedded XML signature when writing the file.
-
-      :param bytes key: PEM encoded key used for signing
-      :param bytes certificate: PEM encoded certificate that will be embedded
-
-      This is a utility function that is used to configure the properties
-      needed to create a signed PSKC file.
+   .. automethod:: sign