1SSSD-SECRETS(5) File Formats and Conventions SSSD-SECRETS(5)
2
6 sssd-secrets - SSSD Secrets responder
7
9 This manual page describes the configuration of the Secrets responder
10 for sssd(8). For a detailed syntax reference, refer to the “FILE
11 FORMAT” section of the sssd.conf(5) manual page.
12 Many system and user applications need to store private information
14 such as passwords or service keys and have no good way to properly deal
15 with them. The simple approach is to embed these “secrets” into
16 configuration files potentially ending up exposing sensitive key
17 material to backups, config management system and in general making it
18 harder to secure data.
19 The custodia[1] project was born to deal with this problem in cloud
21 like environments, but we found the idea compelling even at a single
22 system level. As a security service, SSSD is ideal to host this
23 capability while offering the same API via a UNIX Socket. This will
24 make it possible to use local calls and have them transparently routed
25 to a local or a remote key management store like IPA Vault for storage,
26 escrow and recovery.
27 The secrets are simple key-value pairs. Each user's secrets are
29 namespaced using their user ID, which means the secrets will never
30 collide between users. Secrets can be stored inside “containers” which
31 can be nested.
32 Since the secrets responder can be used both externally to store
34 general secrets, as described in the rest of this man page, but also
35 internally by other SSSD components to store their secret material,
36 some configuration options, like quotas can be configured per “hive” in
37 a configuration subsection named after the hive. The currently
38 supported hives are:
39 secrets
41 secrets for general usage
42 kcm
44 used by the sssd-kcm(8) service.
45
47 The UNIX socket the SSSD responder listens on is located at
48 /var/run/secrets.socket.
49 The secrets responder is socket-activated by systemd(1). Unlike other
51 SSSD responders, it cannot be started by adding the “secrets” string to
52 the “service” directive. The systemd socket unit is called
53 “sssd-secrets.socket” and the corresponding service file is called
54 “sssd-secrets.service”. In order for the service to be
55 socket-activated, make sure the socket is enabled and active and the
56 service is enabled:
57 systemctl start sssd-secrets.socket
59 systemctl enable sssd-secrets.socket
60 systemctl enable sssd-secrets.service
61 Please note your distribution may already configure the units for you.
64
66 The generic SSSD responder options such as “debug_level” or “fd_limit”
67 are accepted by the secrets responder. Please refer to the sssd.conf(5)
68 manual page for a complete list. In addition, there are some
69 secrets-specific options as well.
70 The secrets responder is configured with a global “[secrets]” section
72 and an optional per-user “[secrets/users/$uid]” section in sssd.conf.
73 Please note that some options, notably as the provider type, can only
74 be specified in the per-user subsections.
75 provider (string)
77 This option specifies where should the secrets be stored. The
78 secrets responder can configure a per-user subsections (e.g.
79 “[secrets/users/123]” - see bottom of this manual page for a full
80 example using Custodia for a particular user) that define which
81 provider store the secrets for this particular user. The per-user
82 subsections should contain all options for that user's provider.
83 Please note that currently the global provider is always local, the
84 proxy provider can only be specified in a per-user section. The
85 following providers are supported:
86 local
88 The secrets are stored in a local database, encrypted at rest
89 with a master key. The local provider does not have any
90 additional config options at the moment.
91 proxy
93 The secrets responder forwards the requests to a Custodia
94 server. The proxy provider supports several additional options
95 (see below).
96 Default: local
98 The following options affect only the secrets “hive” and therefore
100 should be set in a per-hive subsection. Setting the option to 0 means
101 "unlimited".
102 containers_nest_level (integer)
104 This option specifies the maximum allowed number of nested
105 containers.
106 Default: 4
108 max_secrets (integer)
110 This option specifies the maximum number of secrets that can be
111 stored in the hive.
112 Default: 1024 (secrets hive), 256 (kcm hive)
114 max_uid_secrets (integer)
116 This option specifies the maximum number of secrets that can be
117 stored per-UID in the hive.
118 Default: 256 (secrets hive), 64 (kcm hive)
120 max_payload_size (integer)
122 This option specifies the maximum payload size allowed for a secret
123 payload in kilobytes.
124 Default: 16 (secrets hive), 65536 (64 MiB) (kcm hive)
126 For example, to adjust quotas differently for both the “secrets” and
128 the “kcm” hives, configure the following:
129 [secrets/secrets]
131 max_payload_size = 128
132 [secrets/kcm]
134 max_payload_size = 256
135 The following options are only applicable for configurations that use
138 the “proxy” provider.
139 proxy_url (string)
141 The URL the Custodia server is listening on. At the moment, http
142 and https protocols are supported.
143 The format of the URI must match the format defined in RFC 2732:
145 http[s]://<host>[:port]
147 Example: http://localhost:8080
149 auth_type (string)
151 The method to use when authenticating to a Custodia server. The
152 following authentication methods are supported:
153 basic_auth
155 Authenticate with a username and a password as set in the
156 “username” and “password” options.
157 header
159 Authenticate with HTTP header value as defined in the
160 “auth_header_name” and “auth_header_value” configuration
161 options.
162 auth_header_name (string)
164 If set, the secrets responder would put a header with this name
165 into the HTTP request with the value defined in the
166 “auth_header_value” configuration option.
167 Example: MYSECRETNAME
169 auth_header_value (string)
171 The value sssd-secrets would use for the “auth_header_name”.
172 Example: mysecret
174 forward_headers (list of strings)
176 The list of HTTP headers to forward to the Custodia server together
177 with the request.
178 Default: not set
180 verify_peer (boolean)
182 Whether peer's certificate should be verified and valid if HTTPS
183 protocol is used with the proxy provider.
184 Default: true
186 verify_host (boolean)
188 Whether peer's hostname must match with hostname in its certificate
189 if HTTPS protocol is used with the proxy provider.
190 Default: true
192 capath (string)
194 Path to directory containing stored certificate authority
195 certificates. System default path is used if this option is not
196 set.
197 Default: not set
199 cacert (string)
201 Path to file containing server's certificate authority certificate.
202 If this option is not set then the CA's certificate is looked up in
203 “capath”.
204 Default: not set
206 cert (string)
208 Path to file containing client's certificate if required by the
209 server. This file may also contain private key or the private key
210 may be in separate file set with “key”.
211 Default: not set
213 key (string)
215 Path to file containing client's private key.
216 Default: not set
218
220 This section lists the available commands and includes examples using
221 the curl(1) utility. All requests towards the proxy provider must set
222 the Content Type header to “application/json”. In addition, the local
223 provider also supports Content Type set to “application/octet-stream”.
224 Secrets stored with requests that set the Content Type header to
225 “application/octet-stream” are base64-encoded when stored and decoded
226 when retrieved, so it's not possible to store a secret with one Content
227 Type and retrieve with another. The secret URI must begin with
228 /secrets/.
229 Listing secrets
231 To list the available secrets, send a HTTP GET request with a
232 trailing slash appended to the container path.
233 Example:
235 curl -H "Content-Type: application/json" \
237 --unix-socket /var/run/secrets.socket \
238 -XGET http://localhost/secrets/
239 Retrieving a secret
243 To read a value of a single secret, send a HTTP GET request without
244 a trailing slash. The last portion of the URI is the name of the
245 secret.
246 Examples:
248 curl -H "Content-Type: application/json" \
250 --unix-socket /var/run/secrets.socket \
251 -XGET http://localhost/secrets/foo
252 curl -H "Content-Type: application/octet-stream" \
255 --unix-socket /var/run/secrets.socket \
256 -XGET http://localhost/secrets/bar
257 Setting a secret
261 To set a secret using the “application/json” type, send a HTTP PUT
262 request with a JSON payload that includes type and value. The type
263 should be set to "simple" and the value should be set to the secret
264 value. If a secret with that name already exists, the response is a
265 409 HTTP error.
266 The “application/json” type just sends the secret as the message
268 payload.
269 The following example sets a secret named 'foo' to a value of
271 'foosecret' and a secret named 'bar' to a value of 'barsecret'
272 using a different Content Type.
273 curl -H "Content-Type: application/json" \
275 --unix-socket /var/run/secrets.socket \
276 -XPUT http://localhost/secrets/foo \
277 -d'{"type":"simple","value":"foosecret"}'
278 curl -H "Content-Type: application/octet-stream" \
281 --unix-socket /var/run/secrets.socket \
282 -XPUT http://localhost/secrets/bar \
283 -d'barsecret'
284 Creating a container
288 Containers provide an additional namespace for this user's secrets.
289 To create a container, send a HTTP POST request, whose URI ends
290 with the container name. Please note the URI must end with a
291 trailing slash.
292 The following example creates a container named 'mycontainer':
294 curl -H "Content-Type: application/json" \
296 --unix-socket /var/run/secrets.socket \
297 -XPOST http://localhost/secrets/mycontainer/
298 To manipulate secrets under this container, just nest the secrets
301 underneath the container path:
302 http://localhost/secrets/mycontainer/mysecret
304 Deleting a secret or a container
308 To delete a secret or a container, send a HTTP DELETE request with
309 a path to the secret or the container.
310 The following example deletes a secret named 'foo'.
312 curl -H "Content-Type: application/json" \
314 --unix-socket /var/run/secrets.socket \
315 -XDELETE http://localhost/secrets/foo
316
320 For testing the proxy provider, you need to set up a Custodia server to
321 proxy requests to. Please always consult the Custodia documentation,
322 the configuration directives might change with different Custodia
323 versions.
324 This configuration will set up a Custodia server listening on
326 http://localhost:8080, allowing anyone with header named MYSECRETNAME
327 set to mysecretkey to communicate with the Custodia server. Place the
328 contents into a file (for example, custodia.conf):
329 [global]
331 server_version = "Secret/0.0.7"
332 server_url = http://localhost:8080/
333 auditlog = /var/log/custodia.log
334 debug = True
335 [store:simple]
337 handler = custodia.store.sqlite.SqliteStore
338 dburi = /var/lib/custodia.db
339 table = secrets
340 [auth:header]
342 handler = custodia.httpd.authenticators.SimpleHeaderAuth
343 header = MYSECRETNAME
344 value = mysecretkey
345 [authz:paths]
347 handler = custodia.httpd.authorizers.SimplePathAuthz
348 paths = /secrets
349 [/]
351 handler = custodia.root.Root
352 store = simple
353 Then run the custodia command, pointing it at the config file as a
356 command line argument.
357 Please note that currently it's not possible to proxy all requests
359 globally to a Custodia instance. Instead, per-user subsections for user
360 IDs that should proxy requests to Custodia must be defined. The
361 following example illustrates a configuration, where the user with UID
362 123 would proxy their requests to Custodia, but all other user's
363 requests would be handled by a local provider.
364 [secrets]
366 [secrets/users/123]
368 provider = proxy
369 proxy_url = http://localhost:8080/secrets/
370 auth_type = header
371 auth_header_name = MYSECRETNAME
372 auth_header_value = mysecretkey
373
376 The SSSD upstream - https://pagure.io/SSSD/sssd/
377
379 1. custodia
380 https://github.com/latchset/custodia
381SSSD 04/25/2019 SSSD-SECRETS(5)