Provided by: sssd-common_1.16.1-1ubuntu1.8_amd64 
NAME
sssd-secrets - SSSD Secrets responder
DESCRIPTION
This manual page describes the configuration of the Secrets responder for sssd(8). For a detailed syntax
reference, refer to the “FILE FORMAT” section of the sssd.conf(5) manual page.
Many system and user applications need to store private information such as passwords or service keys and
have no good way to properly deal with them. The simple approach is to embed these “secrets” into
configuration files potentially ending up exposing sensitive key material to backups, config management
system and in general making it harder to secure data.
The custodia[1] project was born to deal with this problem in cloud like environments, but we found the
idea compelling even at a single system level. As a security service, SSSD is ideal to host this
capability while offering the same API via a UNIX Socket. This will make it possible to use local calls
and have them transparently routed to a local or a remote key management store like IPA Vault for
storage, escrow and recovery.
The secrets are simple key-value pairs. Each user's secrets are namespaced using their user ID, which
means the secrets will never collide between users. Secrets can be stored inside “containers” which can
be nested.
Since the secrets responder can be used both externally to store general secrets, as described in the
rest of this man page, but also internally by other SSSD components to store their secret material, some
configuration options, like quotas can be configured per “hive” in a configuration subsection named after
the hive. The currently supported hives are:
secrets
secrets for general usage
kcm
used by the sssd-kcm(8) service.
USING THE SECRETS RESPONDER
The UNIX socket the SSSD responder listens on is located at /var/run/secrets.socket.
The secrets responder is socket-activated by systemd(1). Unlike other SSSD responders, it cannot be
started by adding the “secrets” string to the “service” directive. The systemd socket unit is called
“sssd-secrets.socket” and the corresponding service file is called “sssd-secrets.service”. In order for
the service to be socket-activated, make sure the socket is enabled and active and the service is
enabled:
systemctl start sssd-secrets.socket
systemctl enable sssd-secrets.socket
systemctl enable sssd-secrets.service
Please note your distribution may already configure the units for you.
CONFIGURATION OPTIONS
The generic SSSD responder options such as “debug_level” or “fd_limit” are accepted by the secrets
responder. Please refer to the sssd.conf(5) manual page for a complete list. In addition, there are some
secrets-specific options as well.
The secrets responder is configured with a global “[secrets]” section and an optional per-user
“[secrets/users/$uid]” section in sssd.conf. Please note that some options, notably as the provider type,
can only be specified in the per-user subsections.
provider (string)
This option specifies where should the secrets be stored. The secrets responder can configure a
per-user subsections (e.g. “[secrets/users/123]” - see bottom of this manual page for a full example
using Custodia for a particular user) that define which provider store the secrets for this
particular user. The per-user subsections should contain all options for that user's provider. Please
note that currently the global provider is always local, the proxy provider can only be specified in
a per-user section. The following providers are supported:
local
The secrets are stored in a local database, encrypted at rest with a master key. The local
provider does not have any additional config options at the moment.
proxy
The secrets responder forwards the requests to a Custodia server. The proxy provider supports
several additional options (see below).
Default: local
The following options affect only the secrets “hive” and therefore should be set in a per-hive
subsection. Setting the option to 0 means "unlimited".
containers_nest_level (integer)
This option specifies the maximum allowed number of nested containers.
Default: 4
max_secrets (integer)
This option specifies the maximum number of secrets that can be stored in the hive.
Default: 1024 (secrets hive), 256 (kcm hive)
max_uid_secrets (integer)
This option specifies the maximum number of secrets that can be stored per-UID in the hive.
Default: 256 (secrets hive), 64 (kcm hive)
max_payload_size (integer)
This option specifies the maximum payload size allowed for a secret payload in kilobytes.
Default: 16 (secrets hive), 65536 (64 MiB) (kcm hive)
For example, to adjust quotas differently for both the “secrets” and the “kcm” hives, configure the
following:
[secrets/secrets]
max_payload_size = 128
[secrets/kcm]
max_payload_size = 256
The following options are only applicable for configurations that use the “proxy” provider.
proxy_url (string)
The URL the Custodia server is listening on. At the moment, http and https protocols are supported.
The format of the URI must match the format defined in RFC 2732:
http[s]://<host>[:port]
Example: http://localhost:8080
auth_type (string)
The method to use when authenticating to a Custodia server. The following authentication methods are
supported:
basic_auth
Authenticate with a username and a password as set in the “username” and “password” options.
header
Authenticate with HTTP header value as defined in the “auth_header_name” and “auth_header_value”
configuration options.
auth_header_name (string)
If set, the secrets responder would put a header with this name into the HTTP request with the value
defined in the “auth_header_value” configuration option.
Example: MYSECRETNAME
auth_header_value (string)
The value sssd-secrets would use for the “auth_header_name”.
Example: mysecret
forward_headers (list of strings)
The list of HTTP headers to forward to the Custodia server together with the request.
Default: not set
verify_peer (boolean)
Whether peer's certificate should be verified and valid if HTTPS protocol is used with the proxy
provider.
Default: true
verify_host (boolean)
Whether peer's hostname must match with hostname in its certificate if HTTPS protocol is used with
the proxy provider.
Default: true
capath (string)
Path to directory containing stored certificate authority certificates. System default path is used
if this option is not set.
Default: not set
cacert (string)
Path to file containing server's certificate authority certificate. If this option is not set then
the CA's certificate is looked up in “capath”.
Default: not set
cert (string)
Path to file containing client's certificate if required by the server. This file may also contain
private key or the private key may be in separate file set with “key”.
Default: not set
key (string)
Path to file containing client's private key.
Default: not set
USING THE REST API
This section lists the available commands and includes examples using the curl(1) utility. All requests
towards the proxy provider must set the Content Type header to “application/json”. In addition, the local
provider also supports Content Type set to “application/octet-stream”. Secrets stored with requests that
set the Content Type header to “application/octet-stream” are base64-encoded when stored and decoded when
retrieved, so it's not possible to store a secret with one Content Type and retrieve with another. The
secret URI must begin with /secrets/.
Listing secrets
To list the available secrets, send a HTTP GET request with a trailing slash appended to the
container path.
Example:
curl -H "Content-Type: application/json" \
--unix-socket /var/run/secrets.socket \
-XGET http://localhost/secrets/
Retrieving a secret
To read a value of a single secret, send a HTTP GET request without a trailing slash. The last
portion of the URI is the name of the secret.
Examples:
curl -H "Content-Type: application/json" \
--unix-socket /var/run/secrets.socket \
-XGET http://localhost/secrets/foo
curl -H "Content-Type: application/octet-stream" \
--unix-socket /var/run/secrets.socket \
-XGET http://localhost/secrets/bar
Setting a secret
To set a secret using the “application/json” type, send a HTTP PUT request with a JSON payload that
includes type and value. The type should be set to "simple" and the value should be set to the secret
value. If a secret with that name already exists, the response is a 409 HTTP error.
The “application/json” type just sends the secret as the message payload.
The following example sets a secret named 'foo' to a value of 'foosecret' and a secret named 'bar' to
a value of 'barsecret' using a different Content Type.
curl -H "Content-Type: application/json" \
--unix-socket /var/run/secrets.socket \
-XPUT http://localhost/secrets/foo \
-d'{"type":"simple","value":"foosecret"}'
curl -H "Content-Type: application/octet-stream" \
--unix-socket /var/run/secrets.socket \
-XPUT http://localhost/secrets/bar \
-d'barsecret'
Creating a container
Containers provide an additional namespace for this user's secrets. To create a container, send a
HTTP POST request, whose URI ends with the container name. Please note the URI must end with a
trailing slash.
The following example creates a container named 'mycontainer':
curl -H "Content-Type: application/json" \
--unix-socket /var/run/secrets.socket \
-XPOST http://localhost/secrets/mycontainer/
To manipulate secrets under this container, just nest the secrets underneath the container path:
http://localhost/secrets/mycontainer/mysecret
Deleting a secret or a container
To delete a secret or a container, send a HTTP DELETE request with a path to the secret or the
container.
The following example deletes a secret named 'foo'.
curl -H "Content-Type: application/json" \
--unix-socket /var/run/secrets.socket \
-XDELETE http://localhost/secrets/foo
EXAMPLE CUSTODIA AND PROXY PROVIDER CONFIGURATION
For testing the proxy provider, you need to set up a Custodia server to proxy requests to. Please always
consult the Custodia documentation, the configuration directives might change with different Custodia
versions.
This configuration will set up a Custodia server listening on http://localhost:8080, allowing anyone with
header named MYSECRETNAME set to mysecretkey to communicate with the Custodia server. Place the contents
into a file (for example, custodia.conf):
[global]
server_version = "Secret/0.0.7"
server_url = http://localhost:8080/
auditlog = /var/log/custodia.log
debug = True
[store:simple]
handler = custodia.store.sqlite.SqliteStore
dburi = /var/lib/custodia.db
table = secrets
[auth:header]
handler = custodia.httpd.authenticators.SimpleHeaderAuth
header = MYSECRETNAME
value = mysecretkey
[authz:paths]
handler = custodia.httpd.authorizers.SimplePathAuthz
paths = /secrets
[/]
handler = custodia.root.Root
store = simple
Then run the custodia command, pointing it at the config file as a command line argument.
Please note that currently it's not possible to proxy all requests globally to a Custodia instance.
Instead, per-user subsections for user IDs that should proxy requests to Custodia must be defined. The
following example illustrates a configuration, where the user with UID 123 would proxy their requests to
Custodia, but all other user's requests would be handled by a local provider.
[secrets]
[secrets/users/123]
provider = proxy
proxy_url = http://localhost:8080/secrets/
auth_type = header
auth_header_name = MYSECRETNAME
auth_header_value = mysecretkey
AUTHORS
The SSSD upstream - https://pagure.io/SSSD/sssd/
NOTES
1. custodia
https://github.com/latchset/custodia
SSSD 08/18/2021 SSSD-SECRETS(5)