Debian Codegraph @

README

raw
1 .. WARNING: AUTO-GENERATED FILE. DO NOT EDIT.
2
3 |Build Status|
4
5 Custodia
6 ========
7
8 A tool for managing secrets.
9
10 See our `Quick Start Guide <docs/source/quick.rst>`__
11
12 Custodia is a project that aims to define an API for modern cloud
13 applications that allows to easily store and share passwords, tokens,
14 certificates and any other secret in a way that keeps data secure,
15 manageable and auditable.
16
17 The Custodia project offers example implementations of clear text and
18 encrypted backends, and aims to soon provide drivers to store data in
19 external data stores like the Vault Project, OpenStack's Barbican,
20 FreeIPA's Vault and similar.
21
22 In future the Custodia project plans to enhance and enrich the API to
23 provide access to even more secure means of dealing with private keys,
24 like HSM as a Service and other similar security systems.
25
26 See the Custodia documentation for more information:
27 https://custodia.readthedocs.io
28
29 Requirements
30 ------------
31
32 Runtime
33 ~~~~~~~
34
35 - configparser (Python 2.7)
36 - cryptography
37 - jwcrypto >= 0.2
38 - requests
39 - six
40
41 Testing
42 ~~~~~~~
43
44 - pip
45 - setuptools >= 18.0
46 - tox >= 2.3.1
47 - wheel
48
49 custodia.ipa depends on several binary extensions and shared libraries
50 for e.g. python-cryptography, python-gssapi, python-ldap, and
51 python-nss. For testing and installation in a virtual environment, a C
52 compiler and several development packages are required.
53
54 Fedora
55 ^^^^^^
56
57 ::
58
59 $ sudo dnf install python2 python-pip python-virtualenv python-devel \
60 gcc redhat-rpm-config krb5-workstation krb5-devel libffi-devel \
61 nss-devel openldap-devel cyrus-sasl-devel openssl-devel
62
63 Debian / Ubuntu
64 ^^^^^^^^^^^^^^^
65
66 ::
67
68 $ sudo apt-get update
69 $ sudo apt-get install -y python2.7 python-pip python-virtualenv python-dev \
70 gcc krb5-user libkrb5-dev libffi-dev libnss3-dev libldap2-dev \
71 libsasl2-dev libssl-dev
72
73 API stability
74 -------------
75
76 Some APIs are provisional and may change in the future.
77
78 - Command line interface in module ``custodia.cli``.
79 - The script custodia-cli.
80 - *custodia.ipa* plugins
81
82 --------------
83
84 custodia.ipa — IPA plugins for Custodia
85 =======================================
86
87 **WARNING** *custodia.ipa is a tech preview with a provisional API.*
88
89 custodia.ipa is a collection of plugins for
90 `Custodia <https://custodia.readthedocs.io/>`__. It provides integration
91 with `FreeIPA <http://www.freeipa.org>`__. The *IPAVault* plugin is an
92 interface to `FreeIPA
93 vault <https://www.freeipa.org/page/V4/Password_Vault>`__. Secrets are
94 encrypted and stored in `Dogtag <http://www.dogtagpki.org>`__'s Key
95 Recovery Agent. The *IPACertRequest* plugin creates private key and
96 signed certificates on-demand. Finally the *IPAInterface* plugin is a
97 helper plugin that wraps ipalib and GSSAPI authentication.
98
99 custodia.ipa requirements
100 -------------------------
101
102 - ipalib >= 4.5.0
103 - ipaclient >= 4.5.0
104 - Python 2.7 (Python 3 support in IPA vault is unstable.)
105
106 ipalib and ipaclient are not pulled in and install by default. The
107 packages depend on additional OS packages for Kerberos/GSSAPI, LDAP and
108 NSS crypto library. The dependencies are listed under *testing*
109 requirements above.
110
111 ::
112
113 $ pip install custodia[ipa]
114
115 custodia.ipa requires an IPA-enrolled host and a Kerberos TGT for
116 authentication. It is recommended to provide credentials with a keytab
117 file or GSS-Proxy. Furthermore *IPAVault* depends on Key Recovery Agent
118 service (``ipa-kra-install``).
119
120 --------------
121
122 Example configuration
123 ---------------------
124
125 Create directories
126
127 ::
128
129 $ sudo mkdir /etc/custodia /var/lib/custodia /var/log/custodia /var/run/custodia
130 $ sudo chown USER:GROUP /var/lib/custodia /var/log/custodia /var/run/custodia
131 $ sudo chmod 750 /var/lib/custodia /var/log/custodia
132
133 Create service account and keytab
134
135 ::
136
137 $ kinit admin
138 $ ipa service-add custodia/$HOSTNAME
139 $ ipa service-allow-create-keytab custodia/$HOSTNAME --users=admin
140 $ mkdir -p /etc/custodia
141 $ ipa-getkeytab -p custodia/$HOSTNAME -k /etc/custodia/ipa.keytab
142 $ chown custodia:custodia /etc/custodia/ipa.keytab
143
144 The IPA cert request plugin needs additional permissions
145
146 ::
147
148 $ ipa privilege-add \
149 --desc="Create and request service certs with Custodia" \
150 "Custodia Service Certs"
151 $ ipa privilege-add-permission \
152 --permissions="Retrieve Certificates from the CA" \
153 --permissions="Request Certificate" \
154 --permissions="Revoke Certificate" \
155 --permissions="System: Modify Services" \
156 "Custodia Service Certs"
157 # for add_principal=True
158 $ ipa privilege-add-permission \
159 --permissions="System: Add Services" \
160 "Custodia Service Certs"
161 $ ipa role-add \
162 --desc="Create and request service certs with Custodia" \
163 "Custodia Service Cert Adminstrator"
164 $ ipa role-add-privilege \
165 --privileges="Custodia Service Certs" \
166 "Custodia Service Cert Adminstrator"
167 $ ipa role-add-member \
168 --services="custodia/$HOSTNAME" \
169 "Custodia Service Cert Adminstrator"
170
171 Create ``/etc/custodia/ipa.conf``
172
173 ::
174
175 # /etc/custodia/ipa.conf
176
177 [global]
178 debug = true
179 makedirs = true
180
181 [auth:ipa]
182 handler = IPAInterface
183 keytab = ${configdir}/${instance}.keytab
184 ccache = FILE:${rundir}/ccache
185
186 [auth:creds]
187 handler = SimpleCredsAuth
188 uid = root
189 gid = root
190
191 [authz:paths]
192 handler = SimplePathAuthz
193 paths = /. /secrets
194
195 [store:vault]
196 handler = IPAVault
197
198 [store:cert]
199 handler = IPACertRequest
200 backing_store = vault
201
202 [/]
203 handler = Root
204
205 [/secrets]
206 handler = Secrets
207 store = vault
208
209 [/secrets/certs]
210 handler = Secrets
211 store = cert
212
213 Create ``/etc/systemd/system/[email protected]/override.conf``
214
215 On Fedora 26 and newer, the Custodia service file defaults to Python 3.
216 Although FreeIPA 4.5 has support for Python 3, it's not stable yet.
217 Therefore it is necessary to run the ``custodia.ipa`` plugins with
218 Python 2.7. You can either use ``systemctl edit [email protected]``
219 to create an override or copy the file manually. Don't forget to run
220 ``systemctl daemon-reload`` in the latter case.
221
222 ::
223
224 [Service]
225 ExecStart=
226 ExecStart=/usr/sbin/custodia-2 --instance=%i /etc/custodia/%i.conf
227
228 Run Custodia server
229
230 ::
231
232 $ systemctl start [email protected]
233
234 IPA cert request
235 ----------------
236
237 The *IPACertRequest* store plugin generates or revokes certificates on
238 the fly. It uses a backing store to cache certs and private keys. The
239 plugin can create service principal automatically. However the host must
240 already exist. The *IPACertRequest* does not create host entries on
241 demand.
242
243 A request like ``GET /path/to/store/HTTP/client1.ipa.example`` generates
244 a private key and CSR for the service ``HTTP/client1.ipa.example`` with
245 DNS subject alternative name ``client1.ipa.example``. The CSR is then
246 forwarded to IPA and signed by Dogtag. The resulting cert and its trust
247 chain is returned together with the private key as a PEM bundle.
248
249 ::
250
251 $ export CUSTODIA_INSTANCE=ipa
252 $ custodia-cli get /certs/HTTP/client1.ipa.example
253 -----BEGIN RSA PRIVATE KEY-----
254 ...
255 -----END RSA PRIVATE KEY-----
256
257 Issuer: organizationName=IPA.EXAMPLE, commonName=Certificate Authority
258 Subject: organizationName=IPA.EXAMPLE, commonName=client1.ipa.example
259 Serial Number: 22
260 Validity:
261 Not Before: 2017-04-27 09:44:20
262 Not After: 2019-04-28 09:44:20
263 -----BEGIN CERTIFICATE-----
264 ...
265 -----END CERTIFICATE-----
266
267 Issuer: organizationName=IPA.EXAMPLE, commonName=Certificate Authority
268 Issuer: organizationName=IPA.EXAMPLE, commonName=Certificate Authority
269 Serial Number: 1
270 Validity:
271 Not Before: 2017-04-26 08:24:11
272 Not After: 2037-04-26 08:24:11
273 -----BEGIN CERTIFICATE-----
274 ...
275 -----END CERTIFICATE-----
276
277 A DELETE request removes the cert/key pair from the backing store and
278 revokes the cert at the same time.
279
280 Automatic renewal of revoked or expired certificates is not implemented
281 yet.
282
283 FreeIPA 4.4 support
284 ~~~~~~~~~~~~~~~~~~~
285
286 The default settings and permissions are tuned for FreeIPA >= 4.5. For
287 4.4, the plugin must be configured with ``chain=False``. The additional
288 permission ``Request Certificate with SubjectAltName`` is required, too.
289
290 ::
291
292 ipa privilege-add-permission \
293 --permissions="Request Certificate with SubjectAltName" \
294 "Custodia Service Certs"
295
296 .. |Build Status| image:: https://travis-ci.org/latchset/custodia.svg?branch=master
297 :target: https://travis-ci.org/latchset/custodia