SSSD Manual pages
sssd-secrets
5
File Formats and Conventions
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
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.
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.
provider (string)
This option specifies where should the secrets
be stored. The secrets responder can configure a
per-user subsections that define which provider store
the secrets for this particular user. The per-user
subsections should contain all options for that user's
provider. If a per-user section does not exist, the
global settings from the secret responder's section
are used. 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
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.
Default: 1024
max_payload_size (integer)
This option specifies the maximum payload size allowed for
a secret payload in kilobytes.
Default: 16
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