Configuration

Configuration for Veraison services is specified in YAML format. By default, each executable will try to read configuration from a file called config.yaml in that executable's current working directory (i.e. the directory it was launched from -- not the directory the executable itself is located). An alternative configuration file may be specified using --config option when launching the executable.

Deployment configuration

Services configured to run as part of a deployment (e.g. via systemd units) will typically look for configuration in config/services/config.yaml under the deployment's location. For example, services installed via deb or rpm packages will have their configuration inside /opt/veraison/config/services/config.yaml.

For docker and aws deployments, you normally shouldn't be modifying the configuration inside the containers/EC2 instances directly. Please refer to the deployments' documentation for information on how they may be configured.

Top-level entries

The following top-level entries will be read for the config file:

  • auth: authentication configuration (used by management and provisioning services)
  • ear-signer: EAR signer configuration (used by vts service)
  • en-store: endorsements key-value store configuration (used by vts service)
  • logging: logging configuration (used by all services)
  • management: management REST API service configuration (used by management service)
  • plugin: plugin loader configuration (used by vts and management services)
  • provisioning: provisioning REST API service configuration (used by provisioning service)
  • po-store: policy key-value store configuration (used by vts and management services)
  • sessionmanager: verification service's session manager configuration (used by verification service)
  • ta-store: trust anchors key-value store configuration (used by vts service)
  • verification: verification REST API service configuration (used by verification service)
  • vts: Veraison Trusted Services configuration (used by vts service)

Each service executable will only look for the top-level entries it expects and will ignore the rest.

auth configuration

See Authentication configuration below.

ear-signer configuration

  • alg: the JWS algorithm used for signing, e.g.: ES256, RS512.
  • key: URL with the location of the private key to be used with alg. The following URL schems are supported:
    • file: URL path is the path to a local file
    • aws: URL path is in the form <region>:<secret-name> where <region> is an AWS region, and <secrete-name> is the name under which the key is stored in AWS Secrets Manager. If a scheme is not specified, file is assumed. The key is in JWK format.

en-store configuration

See KV Store configuration below.

logging configuration

  • level (optional): specify the minimum enabled logging level. Supported values (from lowest to highest) are: debug, info, warn, error. Defaults to info.
  • format (optional): specify the format of the log records (e.g. which entries appear in it). Currently supported formats:
    production: default zap production config.
    development: default zap development config.
    bare: a relatively bare format, featuring only log level (colored), logger name, and its message, suffixed with any fields.
  • development (optional): set to true to put the logger into development mode. This changes the behavior of DPanic and takes stacktraces more liberally.
  • disable-stacktrace (optional): set to true to completely disable automatic stacktrace capturing.
  • sampling (optional): set the sampling policy. There are two possible sub-settings: initial and thereafter, each is an integer value. initial specifies how many messages, of a given level, will be logged as-is every second. After than, only every thereafter'th message will be logged within that seconds. e.g. 
      sampling:
    initial: 10
    thereafer: 5
    means, for very level (debug, info, etc) log the first 10 messages that occur in 1 second. If more messages occur within the second, log every 5th message after the first 10.
  • encoding (optional): specifies logger encoding. Supported values: console, json.
  • output-paths (optional): a list of URLs or file paths to write logging output to. By default, output is written to stdout (which may also be specified as a "path" along other locations). In case the same configuration is used by multiple services, you can insert "{{ .service }}" somewhere in paths (part from stdout/stderr) to have different services log into different files.
  • err-output-paths (optional): a list of URLs or file paths to write internal logger errors to (note: not the error-level logging output). Defaults to stderr. In case the same configuration is used by multiple services, you can insert "{{ .service }}" somewhere in paths (part from stdout/stderr) to have different services log into different files.
  • initial-fields (optional): a map of key-value fields to add to log records (in addition to those added by specific logging sites).

management configuration

  • listen-addr (optional): the address, in the form <host>:<port> the management server will be listening on. If not specified, this defaults to localhost:8088.
  • protocol (optional): the protocol that will be used. Must be either "http" or "https". Defaults to "https" if not specified.
  • cert: path to the x509 certificate to be used. Must be specified if protocol is "https"
  • cert-key: path to the key associated with the certificate specified in cert. Must be specified if protocol is "https"

plugin configuration

The following directives are currently supported:

  • backend: specifies which plugin mechanism will be used. Currently the only supported plugin backend is go-plugin.
  • <backend name> (in practice, just go-plugin): configuration specific to the backend.
  • builtin: configuration used when plugins are disabled and scheme-specific functionally is compiled into the VTS service executable. (Currently just a place-holder as there is no configuration for the built-in loading mechanism.) Note: enabling or disabling of plugins is a build-time option. It is not possible to do so via configuration.

go-plugin backend configuration

  • dir: path to the directory that will be scanned for plugin executables.

po-store configuration

See KV Store configuration below.

po-agent configuration

The following policy agent configuration directives are currently supported:

  • backend: specified which policy backend will be used. Currently supported backends: opa.
  • <backend name>: an entry with the name of a backend is used to specify configuration for that backend. Multiple such entries may exist in a single config, but only the one for the backend specified by the backend directive will be used.

opa backend configuration

Currently, opa backend does not support any configuration.

provisioning configuration

  • listen-addr (optional): the address, in the form <host>:<port> the provisioning server will be listening on. If not specified, this defaults to localhost:8443.
  • protocol (optional): the protocol that will be used. Must be either "http" or "https". Defaults to "https" if not specified.
  • cert: path to the x509 certificate to be used. Must be specified if protocol is "https"
  • cert-key: path to the key associated with the certificate specified in cert. Must be specified if protocol is "https"

sessionmanager configuration

Session manager has a single configuration point: backend. This specifies which ISessionManager implementation will be used. The following backends are supported:

  • ttlcache: the default; this creates the session cache in memory of the verification-service process.
  • memcached: uses an external memcached server.

All other entries under sessionmanager must be backend names (i.e. ttlcache or memcached), providing backend-specific configuration. Only configuration for the backend selected by backend entry will actually be used.

ttlcache backend

ttlcache backend does not have any configuration points.

memcached backend

memcached backend has the following configuration points:

  • servers (optional): a list of servers in ":" format that will be used by the backend. The servers will be used with equal weight. Adding the same entry multiple times increases its weight. If this is not specified, it will default to ["localhost:11211"].

ta-store configuration

See KV Store configuration below.

verification configuration

  • listen-addr (optional): the address, in the form <host>:<port> the verification server will be listening on. If not specified, this defaults to localhost:8080.
  • protocol (optional): the protocol that will be used. Defaults to "https" if not specified. Must be either "http" or "https".
  • cert: path to the x509 certificate to be used. Must be specified if protocol is "https"
  • cert-key: path to the key associated with the certificate specified in cert. Must be specified if protocol is "https"

vts configuration

  • server-addr (optional): address of the VTS server in the form <host>:<port>. If not specified, this defaults to 127.0.0.1:50051. Unless listen-addr is specified (see below), VTS server will extract the port to listen on from this setting (but will listen on all local interfaces)
  • listen-addr (optional): The address the VTS server will listen on in the form <host>:<port>. Only specify this if you want to restrict the server to listen on a particular interface; otherwise, the server will listen on all interfaces on the port specified in server-addr.
  • tls (optional): specifies whether TLS should be used for client connections. Defaults to true.
  • cert: path to the file containing the certificate that should be used by the server if tls (see above) is true.
  • cert-key: path to the file containing the key associated with the certificate specified by server-cert (see above).
  • ca-certs (optional): a list of paths to certificates that will be used in addition to system certs during mutual validation with the client when tls (see above) is true.

Authentication configuration

Authentication configuration is specified under auth top-level entry.

  • backend: specifies which auth backend will be used by the service. The valid options are:

    • passthrough: a backend that does not perform any authentication, allowing all requests.
    • none: alias for passthrough.
    • basic: Uses the Basic HTTP authentication scheme. See RFC7617 for details. This is not intended for production.
    • keycloak: Uses OpenID Connect protocol as implemented by the Keycloak authentication server.

The rest of the expected entries are defined by the value of backend. See below for details of how to configure individual backends.

Passthrough

No additional configuration is required. passthrough will allow all requests. This is the default if auth configuration is not provided.

Basic

  • users: this is a mapping of user names onto their bcrypt password hashes and roles. The key of the mapping is the user name, the value is a further mapping for the details with the following fields:

    • password: the bcrypt hash of the user's password.
    • roles: either a single role or a list of roles associated with the user. API authrization will be performed based on the user's roles.

On Linux, bcrypt hashes can be generated on the command line using mkpasswd utility, e.g.:

mkpasswd -m bcrypt --stdin <<< Passw0rd!

For example:

auth:
  backend: basic
  users:
    user1:
      password: "$2b$05$XgVBveh6QPrRHXI.8S/J9uobBR7Wv9z4CL8yACHEmKIQmYSSyKAqC" # Passw0rd!
      roles: provisioner
    user2:
      password: "$2b$05$x5fvAV5WPkX0KXzqf5FMKODz0uyi2ioew1lOrF2Czp2aNH1LQmhki" # @s3cr3t
      roles: [manager, provisioner]

Keycloak

  • host (optional): host name of the Keycloak service. Defaults to localhost.
  • port (optional): the port on which the Keycloak service is listening. Defaults to 11111.
  • realm (optional): the Keycloak realm used by Veraison. A realm contains the configuration for clients, users, roles, etc. It is roughly analogous to a "tenant id". Defaults to veraison.
  • ca-cert: the path to a PEM-encoded x509 cert that will be added to CA certs when establishing connection to the Keycloak server. This should be specified if the server has HTTPS enabled and the root CA for its cert is not installed in the system.

For example:

auth:
  backend: keycloak
  host: keycloak.example.com
  port: 11111
  realm: veraison

KV Store configuration

kvstore expects the following entries in configuration:

  • backend: the name of the backend to use for the store. Currently supported backends: memory, sql.
  • <backend name>: an entry with the name of a backend is used to specify the configuration for that backend. There may be multiple such entries for different backends. Only the entry matching the active backend specified by backend directive will actually be used. The contents for each entry is specific to the backend.

Note: in a config file, kvstore configuration will typically be namespaced under the name of a particular store instance, e.g.

ta-store:
  backend: sql
  sql:
    driver: sqlite3

memory backend configuration

Currently, memory backend does not support any configuration.

sql backend configuration

note

sqlite3, the default driver for the backend, is unsuitable for production or performance testing.

  • driver: The name of the golang SQL driver. Veraison currently includes the following drivers: sqlite3, mysql (MySQL and MariaDB), and pgx (Postgres).
  • datasource: This points to the database the driver will access. The format is driver-dependent.
    • sqlite3: the path to the sqlite3 database file
    • pgx: a URL in the form postgresql://<user>:<passwd>@<host>:<port>/<database>
    • mysql: string in the form <user>:<password>@<protocol>(<address>)/<database> (Please see the drivers' documentation for more details.)
  • tablename (optional): the name of the table within the SQL database that will be used by the store. If this is not specified, it will default to "kvstore".
  • max_connections (optional): the maximum number of parallel connections to DBMS that will be opened by the SQL driver. Once this number is reached, further transactions will block until a connection becomes available. Defaults to 10.

note

max_connections, like all settings above, is specific to the store for which it is being configured. This means that the total maximum numer of connectins Veraison will try to open is the sum of the max_connections values for all three stores (30 by default).

Example

This is an example of a complete configuration for all Veraison services.

auth:
   backend: keycloak
   host: keycloak.example.com
   port: 11111
ear-signer:
  alg: ES256
  key: /opt/veraison/signing/skey.jwk
en-store:
  backend: sql
  sql:
    max_connections: 8
    driver: pgx
    datasource: postgres://veraison:p4ssw0rd@postgres.example.com:5432/veraison
    tablename: endorsements
logging:
  level: info
  output-paths:
    - stdout
    - /opt/veraison/logs/{{ .service }}-stdout.log
management:
  listen-addr: 0.0.0.0:8088
  protocol: https
  cert: /opt/veraison/certs/management.crt
  cert-key: /opt/veraison/certs/management.key
plugin:
  backend: go-plugin
  go-plugin:
    dir: /opt/veraison/plugins/
po-agent:
    backend: opa
po-store:
  backend: sql
  sql:
    max_connections: 8
    driver: pgx
    datasource: postgres://veraison:p4ssw0rd@postgres.example.com:5432/veraison
    tablename: policies
provisioning:
  listen-addr: 0.0.0.0:8888
  protocol: https
  cert: /opt/veraison/certs/provisioning.crt
  cert-key: /opt/veraison/certs/provisioning.key
sessionmanager:
  backend: memcached
  memcached:
    servers:
        - memcached1.example.com:11211
        - memcached2.example.com:11211
ta-store:
  backend: sql
  sql:
    max_connections: 8
    driver: pgx
    datasource: postgres://veraison:p4ssw0rd@postgres.example.com:5432/veraison
    tablename: trust_anchors
verification:
  listen-addr: 0.0.0.0:8080
  protocol: https
  cert: /opt/veraison/certs/verification.crt
  cert-key: /opt/veraison/certs/verification.key
vts:
  server-addr: localhost:50051
  tls: true
  cert: /opt/veraison/certs/vts.crt
  cert-key: /opt/veraison/certs/vts.key
  ca-certs: /opt/veraison/certs/rootCA.crt