Updating the client documentation with configuration info

This change updates the client documentation, adding in the
client configuration information available in the README. This
consolidates all client information in the same place and
prepares the README for an upcoming change.

docs/source/client.rst

@@ -3,6 +3,121 @@ Client
 The PyKMIP client allows developers to connect to a KMIP-compliant key
 management server and conduct key management operations.
 
+Configuration
+-------------
+The client settings can be managed by a configuration file, by default
+located at ``/etc/pykmip/pykmip.conf``. An example client configuration
+settings block, as found in the configuration file, is shown below:
+
+.. code-block:: console
+
+    [client]
+    host=127.0.0.1
+    port=5696
+    certfile=/path/to/certificate/file
+    keyfile=/path/to/certificate/key/file
+    ca_certs=/path/to/ca/certificate/file
+    cert_reqs=CERT_REQUIRED
+    ssl_version=PROTOCOL_SSLv23
+    do_handshake_on_connect=True
+    suppress_ragged_eofs=True
+    username=example_username
+    password=example_password
+
+The configuration file can contain multiple settings blocks. Only one,
+``[client]``, is shown above. You can swap between different settings
+blocks by simply providing the name of the block as the ``config``
+parameter (see below).
+
+The client can also be configured manually via Python. The following example
+shows how to create the ``ProxyKmipClient`` in Python code, directly
+specifying the different configuration values:
+
+.. code-block:: python
+
+    >>> import ssl
+    >>> from kmip.pie.client import ProxyKmipClient
+    >>> client = ProxyKmipClient(
+    ...     hostname='127.0.0.1',
+    ...     port=5696,
+    ...     cert='/path/to/certificate/file',
+    ...     key='/path/to/certificate/key/file',
+    ...     ca='/path/to/ca/certificate/file',
+    ...     ssl_version=ssl.PROTOCOL_SSLv23,
+    ...     username='example_username',
+    ...     password='example_password'
+    ...     config='client'
+    ... )
+
+Settings specified at runtime, as in the above example, will take precedence
+over the default values found in the configuration file.
+
+The different configuration options are defined below:
+
+* ``host``
+    A string representing either a hostname in Internet domain notation or an
+    IPv4 address.
+* ``port``
+    An integer representing a port number. Recommended to be ``5696``
+    according to the KMIP specification.
+* ``certfile``
+    A string representing a path to a PEM-encoded client certificate file. For
+    more information, see the `ssl`_ documentation.
+* ``keyfile``
+    A string representing a path to a PEM-encoded client certificate key file.
+    The private key contained in the file must correspond to the certificate
+    pointed to by ``certfile``. For more information, see the `ssl`_
+    documentation.
+* ``ca_certs``
+    A string representing a path to a PEM-encoded certificate authority
+    certificate file. This certificate will be used to verify the server's
+    certificate when establishing a TLS connection. For more information, see
+    the `ssl`_ documentation.
+* ``cert_reqs``
+    A flag indicating the enforcement level to use when validating the
+    certificate received from the server. Options include: ``CERT_NONE``,
+    ``CERT_OPTIONAL``, and ``CERT_REQUIRED``. ``CERT_REQUIRED`` is the most
+    secure option and should be used at all times. The other options can be
+    helpful when debugging TLS connections. For more information, see the
+    `ssl`_ documentation.
+* ``ssl_version``
+    A flag indicating the SSL/TLS version to use when establishing a TLS
+    connection with a server. Options are derived from the `ssl`_ module.
+    The recommended value is ``PROTOCOL_SSLv23`` or ``PROTOCOL_TLS``, which
+    automatically allows the client to pick the most secure option provided
+    by the server. For more information, see the `ssl`_ documentation.
+* ``do_handshake_on_connect``
+    A boolean flag indicating when the client should perform the TLS handshake
+    when establishing the TLS connection. The recommended value is ``True``.
+    For more information, see the `ssl`_ documentation.
+
+    .. note::
+       This configuration option is deprecated and will be removed in a future
+       version of PyKMIP.
+* ``suppress_ragged_eofs``
+    A boolean flag indicating how the client should handle unexpected EOF from
+    the TLS connection. The recommended value is ``True``. For more
+    information, see the `ssl`_ documentation.
+
+    .. note::
+       This configuration option is deprecated and will be removed in a future
+       version of PyKMIP.
+* ``username``
+    A string representing the username to use for KMIP requests. Optional
+    depending on server access policies. Leave blank if not needed.
+* ``password``
+    A string representing the password to use for KMIP requests. Optional
+    depending on server access policies. Leave blank if not needed.
+
+Usage
+-----
+
+The following class documentation provides numerous examples detailing how to
+use the client. For additional examples, demo scripts for different operations
+are available in the ``kmip/demos/pie`` directory.
+
+Class Documentation
+-------------------
 .. py:module:: kmip.pie.client
 
 .. py:class:: ProxyKmipClient(hostname=None, port=None, cert=None, key=None, ca=None, ssl_version=None, username=None, password=None, config='client')
@@ -972,3 +1087,6 @@ management server and conduct key management operations.
     .. py:method:: mac(data, uid=None, algorithm=None)
 
         Documentation coming soon.
+
+
+.. _`ssl`: https://docs.python.org/dev/library/ssl.html#socket-creation