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

kcm

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)

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)

max_secrets (integer)

max_uid_secrets (integer)

max_payload_size (integer)

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)

auth_type (string)

auth_header_name (string)

auth_header_value (string)

forward_headers (list of strings)

verify_peer (boolean)

verify_host (boolean)

capath (string)

cacert (string)

cert (string)

key (string)

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

curl -H "Content-Type: application/json" \


     --unix-socket /var/run/secrets.socket \


     -XGET http://localhost/secrets/


                        

Retrieving a secret

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

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

curl -H "Content-Type: application/json" \


     --unix-socket /var/run/secrets.socket \


     -XPOST http://localhost/secrets/mycontainer/


                        

http://localhost/secrets/mycontainer/mysecret


                        

Deleting a secret or a container

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