Getting started with the Cosmian KMS
The Cosmian Key Management System (KMS) is a high-performance, open-source, server application written in Rust that provides a KMIP REST API to store and manage keys used in many standard (AES, ECIES,…) cryptographic stacks as well as Cosmian cryptographic stacks (Covercrypt, Findex). The KMS can also be used to perform encryption and decryption operations.
The Cosmian KMS is designed to operate in zero-trust environments, such as the public cloud, using confidential VMs and a fully application-level encrypted database.
Quick start
To quick-start a Cosmian KMS server on http://localhost:9998 that stores its data inside the container, simply run
Check the Cosmian KMS server version
Open source¶
The server’s code is open-sourced on Github so that it can be audited and improved by anyone.
KMIP 2.1 API¶
The Cosmian KMS server exposes a KMIP 2.1 REST API on the /kmip_2_1 endpoint that follows the JSON profile of the OASIS-normalized KMIP 2.1 specifications.
Check the KMIP 2.1 page for details.
State-of-the-art authentication¶
State-of-the-art authentication facilitates integration with existing IT infrastructure and allows single sign-on scenarios.
Server access is secured using native TLS combined with Open ID-compliant JWT access tokens or TLS client certificates.
Check the enabling TLS documentation as well as the authentication documentation for details.
High-availability and databases¶
The Cosmian KMS may be deployed either in single-server mode or for high availability using simple horizontal scaling of the servers.
For additional security, the server supports concurrent user encrypted databases in single-server mode and an application-level encrypted database on top of Redis in a high-availability scenario.
Designed for the Cloud and Zero-Trust environments¶
Thanks to its “bootstrap” design, the use of confidential VMs, and a fully application-level encrypted database on top of Redis, the Cosmian KMS is able to securely operate in zero-trust environments, such as the public cloud.
See the dedicated page for running the KMS in a zero-trust environment.
Support for object tagging¶
The KMS server supports user tagging of objects to facilitate their management. Specify as many user tags as needed when creating and importing objects.
In addition, the KMS server will automatically add a system tag based on the object type:
_sk: for a private key_pk: for a public key_kk: for a symmetric key_uk: for a Covercrypt user decryption key_cert: for a X509 certificate
In addition for the X509 certificate, KMIP Certificate object not having a key block with Attributes, the following tags are also added:
_cert_uid=<certificate_uid>added on private key and public key to establish the link with the certificate_cert_spki=<hash>added on X509 certificates where the Subject Public Key Identifier is the hash of the public key_cert_ca=<Subject Common Name>on CACertificateobject
Use the tags to export objects, locate them, or request data encryption and decryption.
Command line interface client¶
The KMS has an easy-to-use command line interface client built for many operating systems.
The ckms CLI can manage the server, and the keys and perform operations such as encryption or decryption.
Check the ckms documentation for details.
Easy to deploy: Docker image and pre-built binaries¶
The KMS server is available as a Docker image on the Cosmian public Docker repository.
Raw binaries for multiple operating systems are also available on the Cosmian public packages repository
Integrated with Cloudproof libraries¶
To build the next generation of privacy-by-design applications with end-to-end encryption, the KMS server is integrated with the Cloudproof libraries to deliver keys and secrets to the client-side cryptographic stacks or perform delegated encryption and decryption.
The libraries are available in many languages, including Javascript, Java, Dart, and Python. Check their documentation for details.
Comprehensive inline help¶
Just like the ckms Command Line Interface, the KMS server has a built-in help system that can be accessed using the --help command line option.
The options are enabled on the docker command line or using the environment variables listed in the options help.
Options help¶
Cosmian Key Management Service
Usage: cosmian_kms_server [OPTIONS]
Options:
--database-type <DATABASE_TYPE>
The database type of the KMS server
- postgresql: PostgreSQL. The database url must be provided
- mysql: MySql or MariaDB. The database url must be provided
- sqlite: SQLite. The data will be stored at the sqlite_path directory
- sqlite-enc: SQLite encrypted at rest. the data will be stored at the sqlite_path directory.
A key must be supplied on every call
- redis-findex: a Redis database with encrypted data and encrypted indexes thanks to Findex.
The Redis url must be provided, as well as the redis-master-password and the redis-findex-label
The database configuration can be securely provided via the bootstrap server. Check the documentation.
[env: KMS_DATABASE_TYPE=]
[possible values: postgresql, mysql, sqlite, sqlite-enc, redis-findex]
--database-url <DATABASE_URL>
The url of the database for postgresql, mysql or findex-redis
[env: KMS_DATABASE_URL=]
--sqlite-path <SQLITE_PATH>
The directory path of the sqlite or sqlite-enc
[env: KMS_SQLITE_PATH=]
[default: ./sqlite-data]
--redis-master-password <REDIS_MASTER_PASSWORD>
redis-findex: a master password used to encrypt the Redis data and indexes
[env: KMS_REDIS_MASTER_PASSWORD=]
--redis-findex-label <REDIS_FINDEX_LABEL>
redis-findex: a public arbitrary label that can be changed to rotate the Findex ciphertexts without changing the key
[env: KMS_REDIS_FINDEX_LABEL=]
--clear-database
Clear the database on start.
WARNING: This will delete ALL the data in the database
[env: KMS_CLEAR_DATABASE=]
--port <PORT>
The KMS server port
[env: KMS_PORT=]
[default: 9998]
--hostname <HOSTNAME>
The KMS server (and bootstrap server) hostname
[env: KMS_HOSTNAME=]
[default: 0.0.0.0]
--https-p12-file <HTTPS_P12_FILE>
The KMS server optional PKCS#12 Certificates and Key file. If provided, this will start the server in HTTPS mode.
The PKCS#12 can be securely provided via the bootstrap server. Check the documentation.
[env: KMS_HTTPS_P12_FILE=]
--https-p12-password <HTTPS_P12_PASSWORD>
The password to open the PKCS#12 Certificates and Key file
The PKCS#12 password can be securely provided via the bootstrap server. Check the documentation.
[env: KMS_HTTPS_P12_PASSWORD=]
[default: ]
--authority-cert-file <AUTHORITY_CERT_FILE>
The server optional authority X509 certificate in PEM format used to validate the client certificate presented for authentication. If provided, this will require clients to present a certificate signed by this authority for authentication. The server must run in TLS mode for this to be used
[env: KMS_AUTHORITY_CERT_FILE=]
--jwt-issuer-uri <JWT_ISSUER_URI>
The issuer URI of the JWT token
For Auth0, this is the delegated authority domain configured on Auth0, for instance `https://<your-tenant>.<region>.auth0.com/`
For Google, this would be `https://accounts.google.com`
[env: KMS_JWT_ISSUER_URI=]
--jwks-uri <JWKS_URI>
The JWKS (Json Web Key Set) URI of the JWT token
For Auth0, this would be `https://<your-tenant>.<region>.auth0.com/.well-known/jwks.json`
For Google, this would be `https://www.googleapis.com/oauth2/v3/certs`
Defaults to `<jwt-issuer-uri>/.well-known/jwks.json` is not set
[env: KMS_JWKS_URI=]
--jwt-audience <JWT_AUDIENCE>
The audience of the JWT token
Optional: the server will validate the JWT `aud` claim against this value if set
[env: KMS_JST_AUDIENCE=]
--use-bootstrap-server
Whether configuration should be finalized using a bootstrap server
[env: KMS_USE_BOOTSTRAP_SERVER=]
--bootstrap-server-common-name <BOOTSTRAP_SERVER_COMMON_NAME>
The name that will be the CN in the bootstrap server self-signed certificate
[env: KMS_BOOTSTRAP_SERVER_COMMON_NAME=]
[default: cosmian.kms]
--bootstrap-server-port <BOOTSTRAP_SERVER_PORT>
The bootstrap server may be started on a specific port, The hostname will be that configured in --hostname
[env: KMS_BOOTSTRAP_SERVER_PORT=]
[default: 9998]
--root-data-path <ROOT_DATA_PATH>
The root folder where the KMS will store its data A relative path is taken relative to the user HOME directory
[env: KMS_ROOT_DATA_PATH=]
[default: ./cosmian-kms]
--tmp-path <TMP_PATH>
The folder to store temporary data (non-persistent data readable by no-one but the current instance during the current execution)
[env: KMS_TMP_PATH=]
[default: /tmp]
--use-certbot
Enable TLS and use Let's Encrypt certbot to get a certificate
[env: KMS_USE_CERTBOT=]
--certbot-hostname <CERTBOT_HOSTNAME>
The hostname of the KMS HTTPS server that will be used as the Common Name in the Let's Encrypt certificate
[env: KMS_CERTBOT_HOSTNAME=]
[default: ]
--certbot-email <CERTBOT_EMAIL>
The email used during the Let's Encrypt certbot certification process
[env: KMS_CERTBOT_EMAIL=]
[default: ]
--certbot-ssl-path <CERTBOT_SSL_PATH>
The folder where the KMS will store the SSL material created by certbot
A relative path is taken relative to the root_data_path
[env: KMS_CERTBOT_SSL_PATH=]
[default: ./certbot-ssl]
--default-username <DEFAULT_USERNAME>
The default username to use when no authentication method is provided
[env: KMS_DEFAULT_USERNAME=]
[default: admin]
--force-default-username
When an authentication method is provided, perform the authentication but always use the default username instead of the one provided by the authentication method
[env: KMS_FORCE_DEFAULT_USERNAME=]
--jwk-private-key <JWK_PRIVATE_KEY>
Enable the use of encryption by providing a JWK private key as JSON
[env: JWK_PRIVATE_KEY=]
--enclave-dir-path <ENCLAVE_DIR_PATH>
The directory where the manifest and public key files are located This path should not be encrypted by the enclave and should be directly readable from it
A relative path is taken relative to the root_data_path
[env: KMS_ENCLAVE_DIR_PATH=]
[default: ./enclave]
--manifest-filename <MANIFEST_FILENAME>
The filename of the sgx manifest
[env: KMS_ENCLAVE_MANIFEST_FILENAME=]
[default: kms.manifest.sgx]
--public-key-filename <PUBLIC_KEY_FILENAME>
The filename of the public key
[env: KMS_ENCLAVE_PUBLIC_KEY_FILENAME=]
[default: mr-signer-key.pub]
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version