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
Check the Cosmian KMS server version
List configuration options
The KMS server offers many configuration options which can be listed using
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:
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 \
--database-type=sqlite-enc
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
"eyJncm91cF9pZCI6MzE0ODQ3NTQzOTU4OTM2Mjk5OTY2ODU4MTY1NzE0MTk0MjU5NjUyLCJrZXkiOiIzZDAyNzg3YjUyZGY5OTYzNGNkOTVmM2QxODEyNDk4YTRiZWU1Nzc1NmM5NDI0NjdhZDI5ZTYxZjFmMmM0OWViIn0="%
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 \
-H "KmsDatabaseSecret: eyJncm91cF9pZCI6MzE0ODQ3NTQzOTU4OTM2Mjk5OTY2ODU4MTY1NzE0MTk0MjU5NjUyLCJrZXkiOiIzZDAyNzg3YjUyZGY5OTYzNGNkOTVmM2QxODEyNDk4YTRiZWU1Nzc1NmM5NDI0NjdhZDI5ZTYxZjFmMmM0OWViIn0=" \
http://localhost:9998/objects/owned
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
For
- PostgreSQL, use
--database-type=postgresql - MySQL or MariaDB, use
--database-type=mysql
e.g.
docker run --rm -p 9998:9998 \
--name kms cosmian/kms \
--database-type=postgresql \
--database-url=postgres://kms_user:kms_password@pgsql-server:5432/kms
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:
-
Connect to psql under user
postgres -
Create user
kms_userwith passwordkms_password -
Create database
kmsunder ownerkms_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 \
--mysql-user-cert-file=cert.p12
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 server.mydomain.com.p12, 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/server.mydomain.com.p12:/root/cosmian-kms/server.mydomain.com.p12 \
--name kms cosmian/kms \
--database-type=mysql \
--database-url=mysql://mysql_server:3306/kms \
--https-p12-file=server.mydomain.com.p12 \
--https-p12-password=myPass
Generate a PKCS#12 from PEM files
To generate a PKCS12 from PEM files, you can use openssl:
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-hostnameoption - and the domain name owner email using the
--certbot-emailoption, 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.
Example: