Skip to content

Configuration

Jump to bottom
Andreas Auernhammer edited this page May 12, 2020 · 13 revisions

The configuration section provides general information about KES configuration and helps you finding the right knob to tweak for your use case.

KES Client

In general, a KES client needs to know the KES server endpoint, its own client certificate and the corresponding private key.

Command Line

For example, the KES CLI client requires the following three environment variables:

  • The KES server endpoint: 
    export KES_SERVER=https://127.0.0.1:7373
  • The client X.509 certificate: 
    export KES_CLIENT_CERT=$HOME/root.cert
  • The private key that corresponds to the public key embedded in the certificate: 
    export KES_CLIENT_KEY=$HOME/root.key

SDK

When using an SDK, you need to provide a server endpoint and fetch the client's private key and certificate and have:

package main

import (
	"crypto/tls"
	"log"

	"github.com/minio/kes"
)

func main() {
	const (
		endpoint = "https://127.0.0.1:7373"
		certFile = "./root.cert"
		keyFile  = "./root.key"
	)
	certificate, err := tls.LoadX509KeyPair(certFile, keyFile)
	if err != nil {
		log.Fatalln(err)
	}

	client := kes.NewClient(endpoint, certificate)

	// actually use the client to perform operations...
	_ = client
}

KES Server

The KES server needs at least a TCP address (e.g. IP and port) to listen for incoming requests, a X.509 certificate as well as the corresponding private key and a root identity. These four parameters can be specified via CLI flags or via the config file. If a CLI flag is present it takes precedence over the corresponding config file entry. If no TCP address is specified the KES server will try to listen on all available network interfaces on port 7373.

The following command will start a KES server listening on all network interfaces on port 7373 with the X.509 TLS certificate server.crt, the corresponding private key server.key and the root identity taken from the environment variable $ROOT_IDENTITY:

kes server --cert server.crt --key private.key --root $ROOT_IDENTITY

Config File

The KES server behavior can be customized via a YAML config file. The config file is separated into various sections:

  • A general server configuration section - e.g. the server address and root identity.
  • A TLS section. - e.g. the server key/certificate and TLS proxy configuration.
  • A cache section. It controls how (long) the KES server caches keys in memory.
  • A logging section. It controls what log messages are written to STDOUT and STDERR.
  • A policy section. It controls who can perform which API operations.
  • A KMS / key store section. It specifies where to store and fetch keys.

TLS Configuration

In the TLS configuration section you usually specify the X.509 certificate of the KES server and the corresponding private key:

tls:
  cert: server.crt
  key:  server.key

Further, the TLS section contains a TLS proxy configuration section. Since KES uses mTLS for authentication it is not possible to insert a TLS proxy between the client and the server without specific configuration. For a detailed explanation, recommendations and configuration examples take a look at our TLS proxy page.

Cache Configuration

In the cache configuration section you specify how the KES server should cache keys fetched from the external KMS.

cache:
  expiry:
    any:    5m0s
    unused: 20s

By specifying different expiry values you can control how often the KES server has to fetch keys from the external KMS again. For example, any: 5m0s means that the KES server clears the in-memory cache every 5 min. Similarly, unused: 20s means that the KES server removes any key from the cache that has not been used within last 20 seconds.

The choice of cache expiry values is a trade-off between security and performance. For example, if you set any: 1m0s then the KES server has to communicate to the external KMS 5x more often compared to any: 5m0s. However, you would also reduce the time window where the KES server can act without any control by the external KMS.

The following values may help you make a decision.

Security Level any unused
liberal 5m0s 30s
moderate 1m0s 20s
conservative 30s 5s

Logging Configuration

In the log configuration section you specify which log events are written to STDOUT resp. STDERR. In general, the KES server distinguishes error and audit log events. By default the server will write error events to STDERR but does not log audit events to STDOUT.

Usually, error events indicate that some configuration or operational error occurred. For example, an error event is logged when fetching a key from the KMS fails for some unexpected reason. In contrast to error events, a audit event is produced whenever the KES server accepts a client request. The audit event describes the request-response pair and contains information about who issued the request.

Since a KES server may produce many audit events logging to STDOUT is disabled by default.

log:
  error: on  # To disable error logging to STDERR - explicitly set it to off
  audit: off # To enable audit logging to STDOUT - explicitly set it to on

Note that the log section only controls event logging to STDOUT and STDERR. The KES server also provides audit and error log tracing via the /v1/log/audit/trace and /v1/log/error/trace APIs. A client (with sufficient permissions) can subscribe to the audit or error log at any point in time.

Clone this wiki locally