Provided by: sssd-common_1.16.3-3.1ubuntu1_amd64 bug

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