server-config.yaml

# The config file version. Currently this field is optional but future
# KES versions will require it. The only valid value is "v1".
version: v1

# The TCP address (ip:port) for the KES server to listen on.
address: 0.0.0.0:7373 # The pseudo address 0.0.0.0 refers to all network interfaces

admin:
  # The admin identity identifies the public/private key pair
  # that can perform any API operation.
  # The admin account can be disabled by setting a value that
  # cannot match any public key - for example, "foobar" or "disabled".
  identity: c84cc9b91ae2399b043da7eca616048d4b4200edf2ff418d8af3835911db945d

# The TLS configuration for the KES server. A KES server
# accepts HTTP only over TLS (HTTPS). Therefore, a TLS
# private key and public certificate must be specified,
# either here as part of the config file or via CLI arguments.
tls:
  key:      ./server.key   # Path to the TLS private key
  cert:     ./server.cert  # Path to the TLS certificate
  password: ""             # An optional password to decrypt the TLS private key

  # Specify how/whether the KES server verifies certificates presented
  # by clients. Valid values are "on" and "off". Defaults to off, which
  # is recommended for most use cases.
  auth:     ""

  # An optional path to a file or directory containing X.509 certificate(s).
  # If set, the certificate(s) get added to the list of CA certificates for
  # verifying the mTLS certificates sent by the KES clients.
  #
  # If empty, the system root CAs will be used.
  ca:       ""

  # The TLS proxy configuration. A TLS proxy, like nginx, sits in
  # between a KES client and the KES server and usually acts as a
  # load balancer or common endpoint.
  # All connections from the KES client to the TLS proxy as well
  # the connections from the TLS proxy to the KES server must be
  # established over TLS.
  proxy:
    # The identities of all TLS proxies directly connected to the
    # KES server.
    #
    # Note that a TLS proxy can act as any identity (including root)
    # since it can forward arbitrary client certificates. Client certificates
    # aren't secret information and a malicious TLS proxy can fake any
    # identity it has seen before. Therefore, its critical that all TLS proxy
    # identities are secure and trusted servers.
    identities: []
    # The HTTP header sent by the TLS proxy to forward certain data
    # about the client to the KES server.
    header:
      # The HTTP header containing the URL-escaped and PEM-encoded
      # certificate of the kes client forwarded by the TLS proxy.
      cert: X-Tls-Client-Cert

# The API configuration. The APIs exposed by the KES server can
# be adjusted here. Each API is identified by its API path.
#
# In general, the KES server uses reasonable defaults for all APIs.
# Only customize the APIs if there is a real need.
#
# An example of when you might disable authentication could be to
# allow the liveness and readiness probes in a Kubernetes environment.
#
# When authentication is disabled, the particular API can be
# accessed by any client that can send HTTPS requests to the
# KES server.
#
# When disabling authentication for any API, the KES server will
# change its TLS handshake behavior. By default, KES requires that
# a client sends a client certificate during the handshake or KES
# aborts the handshake. This means that a client can only send an
# HTTP request to KES when it provides a certificate during the
# handshake. This is no longer the case when authentication is
# disabled for at least one API. Clients should be able to call
# the API even without a certificate. Hence, KES can no longer
# require a certificate during the TLS handshake but instead has
# to check the certificate when executing the API handler.
#
# Now, these two behaviors have slightly different semantics:
# By default, KES does not accept connections from clients without
# a TLS certificate. When disabling authentication for one API, KES
# has to accept connections from any client for all APIs. However,
# the API handlers that still require authentication will reject
# requests from clients without a certificate. Instead of a TLS
# error these clients will receive an HTTP error.
#
# Currently, authentication can only be disabled for the
# following APIs:
#   - /v1/ready
#   - /v1/status
#   - /v1/metrics
#   - /v1/api
#
api:
  /v1/ready:
    skip_auth: false
    timeout:   15s

# The (pre-defined) policy definitions.
#
# A policy must have an unique name (e.g my-app) and specifies which
# server APIs can be accessed. An API path pattern is a glob pattern
# of the following form:
#   <API-version>/<API>/<operation>/[<argument-0>/<argument-1>/...]>
#
# Each KES server API has an unique path - for example, /v1/key/create/<key-name>.
# A client request is allowed if and only if no deny pattern AND at least one
# allow pattern matches the request URL path.
#
# A policy has zero (by default) or more assigned identities. However,
# an identity can never be assigned to more than one policy at the same
# time. So, one policy has N assigned identities but one identity is
# assigned to at most one policy.
#
# In general, each user/application should only have the minimal
# set of policy permissions to accomplish whatever it needs to do.
# Therefore, it is recommended to define policies based on workflows
# and then assign them to the identities.

# The following policy section shows some example policy definitions.
# Please remove/adjust to your needs.
policy:
  my-app:
    allow:
    - /v1/key/create/my-app*
    - /v1/key/generate/my-app*
    - /v1/key/decrypt/my-app*
    deny:
    - /v1/key/generate/my-app-internal*
    - /v1/key/decrypt/my-app-internal*
    identities:
    - df7281ca3fed4ef7d06297eb7cb9d590a4edc863b4425f4762bb2afaebfd3258
    - c0ecd5962eaf937422268b80a93dde4786dc9783fb2480ddea0f3e5fe471a731

  my-app-ops:
    allow:
    - /v1/key/delete/my-app*
    - /v1/policy/show/my-app
    - /v1/identity/assign/my-app/*
    identities:
    - 7ec8095a5308a535b72b35c7ccd4ce1d7c14af713acd22e2935a9d6e4fe18127

cache:
  # Cache expiry specifies when cache entries expire.
  expiry:
    # Period after which any cache entries are discarded.
    # It determines how often the KES server has to fetch
    # a secret key from the KMS.
    #
    # If not set, KES will default to an expiry of 5 minutes.
    any: 5m0s
    # Period after which all unused cache entries are discarded.
    # It determines how often "not frequently" used secret keys
    # must be fetched from the KMS.
    #
    # If not set, KES will default to an expiry of 30 seconds.
    unused: 20s
    # Period after which any cache entries in the offline cache
    # are discarded.
    # It determines how long the KES server can serve stateless
    # requests when the KMS key store has become unavailable -
    # for example, due to a network outage.
    #
    # If not set, KES will disable the offline cache.
    #
    # Offline caching should only be enabled when trying to
    # reduce the impact of the KMS key store being unavailable.
    offline: 0s

# The console logging configuration. In general, the KES server
# distinguishes between (operational) errors and audit events.
# By default, the KES server logs error events to STDERR but
# does not log audit log events to STDOUT.
#
# The following log configuration only affects logging to console.
log:
  # Enable/Disable logging error events to STDERR. Valid values
  # are "on" or "off". If not set the default is "on". If no error
  # events should be logged to STDERR it has to be set explicitly
  # to: "off".
  error: on

  # Enable/Disable logging audit events to STDOUT. Valid values
  # are "on" and "off". If not set the default is "off".
  # Logging audit events to STDOUT may flood your console since
  # there will be one audit log event per request-response pair.
  #
  # For tracing/monitoring audit logs, see the
  # /v1/log/audit/trace API.
  #
  # Each audit event is a JSON object representing a request-response
  # pair that contains the time, client identity, the API path, HTTP
  # response status code etc.
  # {
  #   "time": "2006-01-02T15:04:05Z07:00",
  #   "request": {
  #     "ip":       "87.149.99.199",
  #     "enclave":  "default",
  #     "path":     "/v1/key/create/my-app-key",
  #     "identity": "4067503933d4a78358f908a2df7ec14e554c612acf8a9d1aa29b7da4aa018ec9",
  #   },
  #   "response": {
  #     "status": 200
  #   }
  # }
  # The server will write such an audit log entry for every HTTP
  # request-response pair - including invalid requests.
  audit: off

# In the keys section, pre-defined keys can be specified. The KES
# server will try to create the listed keys before startup.
keys:
  - name: some-key-name
  - name: another-key-name

# The keystore section specifies which KMS - or in general key store - is
# used to store and fetch encryption keys.
# A KES server can only use one KMS / key store at the same time.
# If no store is explicitly specified, the server will store
# keys in-memory. In this case all keys are lost when the KES server
# restarts.
keystore:
  # Configuration for storing keys on the filesystem.
  # The path must be path to a directory. If it doesn't
  # exist then the KES server will create the directory.
  #
  # The main purpose of the fs configuration is testing
  # and development. It should not be used for production.
  fs:
    path: "" # Path to directory. Keys will be stored as files.

  # Hashicorp Vault configuration. The KES server will store/fetch
  # secret keys at/from Vault's key-value backend.
  #
  # For more information, see:
  # https://www.vaultproject.io/api/secret/kv/kv-v1.html
  vault:
    endpoint: ""  # The Vault endpoint - for example, https://127.0.0.1:8200
    engine: ""    # The path of the K/V engine - for example, secrets. If empty, defaults to: kv. (Vault default)
    version: ""   # The K/V engine version - either "v1" or "v2". The "v1" engine is recommended.
    namespace: "" # An optional Vault namespace. See: https://www.vaultproject.io/docs/enterprise/namespaces/index.html
    prefix: ""    # An optional K/V prefix. The server will store keys under this prefix.
    transit:      # Optionally encrypt keys stored on the K/V engine with a Vault-managed key.
      engine: ""  # The path of the transit engine - for example, "my-transit". If empty, defaults to: transit (Vault default)
      key: ""     # The key name that should be used to encrypt entries stored on the K/V engine.
    approle:    # AppRole credentials. See: https://www.vaultproject.io/docs/auth/approle.html
      namespace: "" # Optional Vault namespace used only for authentication. For the Vault root namespace, use "/".
      engine: ""    # The path to the AppRole engine, for example: authenticate. If empty, defaults to: approle. (Vault default)
      id: ""        # Your AppRole Role ID
      secret: ""    # Your AppRole Secret ID
    kubernetes: # Kubernetes credentials. See: https://www.vaultproject.io/docs/auth/kubernetes
      namespace: "" # Optional Vault namespace used only for authentication. For the Vault root namespace, use "/".
      engine: ""    # The path of the Kubernetes engine for example, authenticate. If empty, defaults to: kubernetes. (Vault default)
      role: ""      # The Kubernetes JWT role
      jwt:  ""      # Either the JWT provided by K8S or a path to a K8S secret containing the JWT.
    tls:        # The Vault client TLS configuration for mTLS authentication and certificate verification
      key: ""     # Path to the TLS client private key for mTLS authentication to Vault
      cert: ""    # Path to the TLS client certificate for mTLS authentication to Vault
      ca: ""      # Path to one or more PEM root CA certificates
    status:     # Vault status configuration. The server will periodically reach out to Vault to check its status.
      ping: 10s   # Duration until the server checks Vault's status again.

  fortanix:
    # The Fortanix SDKMS key store. The server will store secret keys at the Fortanix SDKMS.
    # See: https://www.fortanix.com/products/data-security-manager/key-management-service
    sdkms:
      endpoint: ""   # The Fortanix SDKMS endpoint - for example: https://sdkms.fortanix.com
      group_id: ""   # An optional group ID newly created keys will be placed at. For example: ce08d547-2a82-411e-ae2d-83655a4b7617
                     # If empty, the applications default group is used.
      credentials:   # The Fortanix SDKMS access credentials
        key: ""      # The application's API key - for example: NWMyMWZlNzktZDRmZS00NDFhLWFjMzMtNjZmY2U0Y2ViMThhOnJWQlh0M1lZaDcxZC1NNnh4OGV2MWNQSDVVSEt1eXEyaURqMHRrRU1pZDg=
      tls:           # The KeySecure client TLS configuration
        ca: ""       # Path to one or more PEM-encoded CA certificates for verifying the Fortanix SDKMS TLS certificate.
  aws:
    # The AWS SecretsManager key store. The server will store
    # secret keys at the AWS SecretsManager encrypted with
    # AWS-KMS. See: https://aws.amazon.com/secrets-manager
    secretsmanager:
      endpoint: ""   # The AWS SecretsManager endpoint - for example,: secretsmanager.us-east-2.amazonaws.com
      region: ""     # The AWS region of the SecretsManager - for example,: us-east-2
      kmskey: ""     # The AWS-KMS key ID used to en/decrypt secrets at the SecretsManager. By default (if not set) the default AWS-KMS key will be used.
      credentials:   # The AWS credentials for accessing secrets at the AWS SecretsManager.
        accesskey: ""  # Your AWS Access Key
        secretkey: ""  # Your AWS Secret Key
        token: ""      # Your AWS session token (usually optional)

  gemalto:
    # The Gemalto KeySecure key store. The server will store
    # keys as secrets on the KeySecure instance.
    keysecure:
      endpoint: ""    # The KeySecure endpoint - for example, https://127.0.0.1
      credentials:    # The authentication to access the KeySecure instance.
        token: ""     # The refresh token to obtain new short-lived authentication tokens.
        domain: ""    # The KeySecure domain for which the refresh token is valid. If empty, defaults to the root domain.
        retry: 15s    # The time the KES server waits before it tries to re-authenticate after connection loss.
      tls:            # The KeySecure client TLS configuration
        ca: ""        # Path to one or more PEM-encoded CA certificates for verifying the KeySecure TLS certificate.

  gcp:
    # The Google Cloud Platform secret manager.
    # For more information, see:
    # https://cloud.google.com/secret-manager
    secretmanager:
      # The project ID is a unique, user-assigned ID that can be used by Google APIs.
      # The project ID must be a unique string of 6 to 30 lowercase letters, digits, or hyphens.
      # It must start with a letter, and cannot have a trailing hyphen.
      # See: https://cloud.google.com/resource-manager/docs/creating-managing-projects#before_you_begin
      project_id: ""
      # An optional GCP SecretManager endpoint. If not set, defaults to: secretmanager.googleapis.com:443
      endpoint: ""
      # An optional list of GCP OAuth2 scopes. For a list of GCP scopes refer to: https://developers.google.com/identity/protocols/oauth2/scopes
      # If not set, the GCP default scopes are used.
      scopes:
      - ""
      # The credentials for your GCP service account. If running inside GCP (app engine) the credentials
      # can be empty and will be fetched from the app engine environment automatically.
      credentials:
        client_email:   "" # The service account email       - for example, <account>@<project-ID>.iam.gserviceaccount.com
        client_id:      "" # The service account client ID   - for example, 113491952745362495489"
        private_key_id: "" # The service account private key - for example, 381514ebd3cf45a64ca8adc561f0ce28fca5ec06
        private_key:    "" # The raw encoded private key of the service account -
                     #   for example, "-----BEGIN PRIVATE KEY-----\n ... \n-----END PRIVATE KEY-----\n

  azure:
    # The Azure KeyVault configuration.
    # For more information, see:
    # https://azure.microsoft.com/services/key-vault
    keyvault:
      endpoint: ""         # The KeyVault endpoint - for example, https://my-instance.vault.azure.net
      # Azure client credentials used to
      # authenticate to Azure KeyVault.
      credentials:
        tenant_id: ""      # The ID of the tenant the client belongs to - that is, a UUID.
        client_id: ""      # The ID of the client - that is, a UUID.
        client_secret: ""  # The value of the client secret.
      # Azure managed identity used to
      # authenticate to Azure KeyVault
      # with Azure managed credentials.
      managed_identity:
        client_id: ""      # The Azure managed identity of the client - that is, a UUID.

  entrust:
    # The Entrust KeyControl configuration.
    # For more information, see:
    # https://www.entrust.com/digital-security/key-management/keycontrol
    keycontrol:
      endpoint: ""     # The KeyControl endpoint - for example, https://keycontrol.my-org.com
      vault_id: ""     # The Vault ID            - for example, e30497c1-bff7-4e81-beb7-fb35c4b7410c
      box_id:   ""     # The Box name or ID      - for example, tenant-1
      # The KeyControl access credentials
      credentials:
        username: ""   # A username with access to the Vault and Box.
        password: ""   # The user password
      # The KeyControl client TLS configuration
      tls:
        ca: ""         # Path to one or more PEM-encoded CA certificates for verifying the KeyControl TLS certificate.