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
This commit is contained in:
parent
3f4292592a
commit
82a0ded5c8
|
@ -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
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
|
Loading…
Reference in New Issue