Skip to content

Installing and running

The KMS server is available as a Docker image on the Cosmian public docker hub.

Quick start

To start a Cosmian KMS server on http://localhost:9998 that stores its data inside the container, simply run

docker run -p 9998:9998 --name kms cosmian/kms

Check the Cosmian KMS server version

curl http://localhost:9998/version

List configuration options

The KMS server offers many configuration options which can be listed using

docker run --rm cosmian/kms --help

Most of these options can be passed on the command line or using the environment variables listed by the --help command.

Single server mode

The single server mode uses an embedded SQLite database stored on a filesystem and therefore does not require access to an external database.

To run in single server mode, using the defaults, run the container as follows:

docker run -p 9998:9998 --name kms cosmian/kms

The KMS will be available on http://localhost:9998 and data will be stored inside the container in /root/cosmian-kms/sqlite-data.

Persisting data between restarts

To persist data between restarts, map the /root/cosmian-kms/sqlite-data path to a filesystem directory or a Docker volume, e.g. with a volume named cosmian-kms:

docker run --rm -p 9998:9998 \
  -v cosmian-kms:/root/cosmian-kms/sqlite-data \
  --name kms cosmian/kms

Using encrypted databases

To start the KMS server with encrypted SQLite databases, pass the --database-type=sqlite-enc on start, e.g.

docker run --rm -p 9998:9998 \
  -v cosmian-kms:/root/cosmian-kms/sqlite-data \
  --name kms cosmian/kms \

Important: encrypted databases must be created first

Before using an encrypted database, you must create it by calling the POST /new_database endpoint. The call will return a secret

➜ curl -X POST http://localhost:9998/new_database

The secret is the value between the quotes "". This secret is only displayed once and is not stored anywhere on the server.

⚠️ Each call to /new_database will create a new additional database. It will not return the secret of the last created database and it will not overwrite the last created database.

Once an encrypted database is created, the secret must be passed every subsequent query to the KMS using a KmsDatabaseSecret HTTP header, e.g.

curl \

Each encrypted database owns its encrypted file. Encrypted databases can be used concurrently on the same KMS server.

Replicated mode

In replicated mode, the server can use PostgreSQL, Maria DB, or MySQL. Since the KMS servers are stateless, they can be scaled horizontally by connecting to the same database.

With the correct database-type, a database-url must also be provided


  • PostgreSQL, use --database-type=postgresql
  • MySQL or MariaDB, use --database-type=mysql


docker run --rm -p 9998:9998 \
  --name kms cosmian/kms \
  --database-type=postgresql \

Setting up a PostgreSQL database

Before running the server a dedicated database with a dedicated user should be created on the PostgreSQL instance. These sample instructions create a database called kms owned by a user kms_user with password kms_password:

  1. Connect to psql under user postgres

    sudo -u postgres psql  # or `psql -U postgres`

  2. Create user kms_user with password kms_password

    create user kms_user with encrypted password 'kms_password';

  3. Create database kms under owner kms_user

    create database kms owner=kms_user;

Using a certificate to authenticate to MySQL or Maria DB

Use a certificate to authenticate to MySQL or Maria DB with the --mysql-user-cert-file option. Specify the certificate file name and mount the file to docker.

Say the certificate is called cert.p12 and is in a directory called /certificate on the host disk.

docker run --rm -p 9998:9998 \
  --name kms cosmian/kms \
  -v /certificate/cert.p12:/root/cosmian-kms/cert.p12 \
  --database-type=mysql \
  --database-url=mysql://mysql_server:3306/kms \

Enabling HTTPS

The server may be started using http/s by either installing certificates or using certbot.

Installing certificates

The certificate (key and full chain) must be available in a PKCS#12 format. Specify the certificate name and mount the file to docker.

Say the certificate is called, is protected by the password myPass, and is in a directory called /certificate on the host disk.

docker run --rm -p 443:9998 \
  -v /certificate/ \
  --name kms cosmian/kms \
  --database-type=mysql \
  --database-url=mysql://mysql_server:3306/kms \ \

Generate a PKCS#12 from PEM files

To generate a PKCS12 from PEM files, you can use openssl:

openssl pkcs12 -export \
-in \
-inkey \

Using the certificate bot

The Cosmian KMS server has support for a certificate bot that can automatically obtain and renew its certificates from Let’s Encrypt using the acme protocol.

To enable the use of the certificate bot, enable the --use-certbot switch then specify

  • the KMS hostname (Common Name in the certificate) using the --certbot-hostname option
  • and the domain name owner email using the --certbot-email option, e.g.

The hostname must be a valid DNS A or AAAA record pointing to the IP address of this server as the Let’s Encrypt server will attempt to connect to the server during the process.

By default, the certificates will be saved inside the container in the /root/cosmian-kms/certbot-ssl directory. This directory is adjustable with the --certbot-ssl-path option. To persist the generated certificates between restarts, this directory should be mapped to a host directory or persistent docker volume.


docker run --rm -p 443:9998 \
  -v cosmian-kms:/root/cosmian-kms/sqlite-data \
  -v cosmian-kms-certs:/root/cosmian-kms/certbot-ssl \
  --name kms cosmian/kms \
  --database-type=sqlite-enc \
  --use-certbot \
  --certbot-server-name \
© Copyright 2018-2023 Cosmian. All rights reserved.