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
Michael McCune
8 years ago
| 1 | 1 | Usage |
| 2 | 2 | ======== |
| 3 | 3 | |
| 4 | To use castellan in a project:: | |
| 4 | This document describes some of the common usage patterns for Castellan. When | |
| 5 | incorporating this package into your applications, care should be taken to | |
| 6 | consider the key manager behavior you wish to encapsulate and the OpenStack | |
| 7 | deployments on which your application will run. | |
| 5 | 8 | |
| 6 | import castellan | |
| 9 | Basic usage | |
| 10 | ~~~~~~~~~~~ | |
| 7 | 11 | |
| 12 | Castellan works on the principle of providing an abstracted key manager based | |
| 13 | on your configuration. In this manner, several different management services | |
| 14 | can be supported through a single interface. | |
| 15 | ||
| 16 | In addition to the key manager, Castellan also provides primitives for | |
| 17 | various types of secrets (for example, asymmetric keys, simple passphrases, | |
| 18 | and certificates). These primitives are used in conjuction with the key | |
| 19 | manager to create, store, retrieve, and destroy managed secrets. | |
| 20 | ||
| 21 | Another fundamental concept to using Castellan is the context object, most | |
| 22 | frequently inherited from ``oslo.context.RequestContext``. This object | |
| 23 | represents information that is contained in the current request, and is | |
| 24 | usually populated in the WSGI pipeline. The information contained in this | |
| 25 | object will be used by Castellan to interact with the specific key manager | |
| 26 | that is being abstracted. | |
| 27 | ||
| 28 | **Example. Creating and storing a key.** | |
| 29 | ||
| 30 | .. code:: python | |
| 31 | ||
| 32 | import myapp | |
| 33 | from castellan.common.objects import passphrase | |
| 34 | from castellan import key_manager | |
| 35 | ||
| 36 | key = passphrase.Passphrase('super_secret_password') | |
| 37 | manager = key_manager.API() | |
| 38 | stored_key_id = manager.store(myapp.context(), key) | |
| 39 | ||
| 40 | To begin with, we'd like to create a key to manage. We create a simple | |
| 41 | passphrase key, then instantiate the key manager, and finally store it to | |
| 42 | the manager service. We record the key identifier for later usage. | |
| 43 | ||
| 44 | **Example. Retrieving a key and checking the contents.** | |
| 45 | ||
| 46 | .. code:: python | |
| 47 | ||
| 48 | import myapp | |
| 49 | from castellan import key_manager | |
| 50 | ||
| 51 | manager = key_manager.API() | |
| 52 | key = manager.store(myapp.context(), stored_key_id) | |
| 53 | if key.get_encoded() == 'super_secret_password': | |
| 54 | myapp.do_secret_stuff() | |
| 55 | ||
| 56 | This example demonstrates retrieving a stored key from the key manager service | |
| 57 | and checking its contents. First we instantiate the key manager, then | |
| 58 | retrieve the key using a previously stored identifier, and finally we check | |
| 59 | the validity of key before performing our restricted actions. | |
| 60 | ||
| 61 | **Example. Deleting a key.** | |
| 62 | ||
| 63 | .. code:: python | |
| 64 | ||
| 65 | import myapp | |
| 66 | from castellan import key_manager | |
| 67 | ||
| 68 | manager = key_manager.API() | |
| 69 | manager.delete(myapp.context(), stored_key_id) | |
| 70 | ||
| 71 | Having finished our work with the key, we can now delete it from the key | |
| 72 | manager service. We once again instantiate a key manager, then we simply | |
| 73 | delete the key by using its identifier. Under normal conditions, this call | |
| 74 | will not return anything but may raise exceptions if there are communication, | |
| 75 | identification, or authorization issues. | |
| 8 | 76 | |
| 9 | 77 | Configuring castellan |
| 10 | 78 | ~~~~~~~~~~~~~~~~~~~~~ |