Adding documentation for basic usage

This change adds a few samples of the basic usage of Castellan
including; storing, retrieving, and deleting managed objects.

Change-Id: I640f076447da47a57d5186e46b49193e1172d64a

doc/source/usage.rst

@@ -2,10 +2,78 @@
 Usage
 ========
 
-To use castellan in a project::
+This document describes some of the common usage patterns for Castellan. When
+incorporating this package into your applications, care should be taken to
+consider the key manager behavior you wish to encapsulate and the OpenStack
+deployments on which your application will run.
 
-    import castellan
+Basic usage
+~~~~~~~~~~~
 
+Castellan works on the principle of providing an abstracted key manager based
+on your configuration. In this manner, several different management services
+can be supported through a single interface.
+
+In addition to the key manager, Castellan also provides primitives for
+various types of secrets (for example, asymmetric keys, simple passphrases,
+and certificates). These primitives are used in conjuction with the key
+manager to create, store, retrieve, and destroy managed secrets.
+
+Another fundamental concept to using Castellan is the context object, most
+frequently inherited from ``oslo.context.RequestContext``. This object
+represents information that is contained in the current request, and is
+usually populated in the WSGI pipeline. The information contained in this
+object will be used by Castellan to interact with the specific key manager
+that is being abstracted.
+
+**Example. Creating and storing a key.**
+
+.. code:: python
+
+    import myapp
+    from castellan.common.objects import passphrase
+    from castellan import key_manager
+
+    key = passphrase.Passphrase('super_secret_password')
+    manager = key_manager.API()
+    stored_key_id = manager.store(myapp.context(), key)
+
+To begin with, we'd like to create a key to manage. We create a simple
+passphrase key, then instantiate the key manager, and finally store it to
+the manager service. We record the key identifier for later usage.
+
+**Example. Retrieving a key and checking the contents.**
+
+.. code:: python
+
+    import myapp
+    from castellan import key_manager
+
+    manager = key_manager.API()
+    key = manager.store(myapp.context(), stored_key_id)
+    if key.get_encoded() == 'super_secret_password':
+        myapp.do_secret_stuff()
+
+This example demonstrates retrieving a stored key from the key manager service
+and checking its contents. First we instantiate the key manager, then
+retrieve the key using a previously stored identifier, and finally we check
+the validity of key before performing our restricted actions.
+
+**Example. Deleting a key.**
+
+.. code:: python
+
+    import myapp
+    from castellan import key_manager
+
+    manager = key_manager.API()
+    manager.delete(myapp.context(), stored_key_id)
+
+Having finished our work with the key, we can now delete it from the key
+manager service. We once again instantiate a key manager, then we simply
+delete the key by using its identifier. Under normal conditions, this call
+will not return anything but may raise exceptions if there are communication,
+identification, or authorization issues.
 
 Configuring castellan
 ~~~~~~~~~~~~~~~~~~~~~