Codebase list python-castellan / 82a0ded
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 7 years ago
1 changed file(s) with 70 addition(s) and 2 deletion(s). Raw diff Collapse all Expand all
11 Usage
22 ========
33
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.
58
6 import castellan
9 Basic usage
10 ~~~~~~~~~~~
711
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.
876
977 Configuring castellan
1078 ~~~~~~~~~~~~~~~~~~~~~