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 Cosmian VMs and an application-level encrypted database indexed with Findex.
Docker Quick start
To quick-start a Cosmian KMS server on http://localhost:9998 that stores its data
inside the container, simply run the following command:
Check the Cosmian KMS server version
Alternatively KMS binaries are also available on Cosmian packages.
- Public Source Code
- KMIP 2.1 API
- Supports Google Workspace Client Side Encryption
- Supports Microsoft Double Key Encryption
- FIPS Mode
- PKCS11 provider support for Veracrypt
- State-of-the-art authentication
- High-availability and databases
- Designed to securely run in the Cloud or other Zero-Trust environments
- Support for object tagging
- Command line interface client
- Easy to deploy: Docker image and pre-built binaries
- Integrated with Cloudproof libraries
- Comprehensive inline help
- TOML configuration file
Public Source Code¶
The server’s source code is fully available on Github under a Business Source License 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.
Supports Google Workspace Client Side Encryption¶
The KMS server can be used as a Key Management System for the Google Workspace Client Side Encryption feature. Please check the Google Workspace Client Side Encryption page for details.
Supports Microsoft Double Key Encryption¶
The KMS server can be used as a Key Management System for the Microsoft Double Key Encryption feature. Please check the Microsoft Double Key Encryption page for details.
FIPS Mode¶
The server exposes all lot of advanced cryptographic algorithms and can also be run in FIPS mode. In this mode, the server is only built with FIPS 140-2 validated cryptographic libraries and the cryptographic operations are performed in a FIPS 140-2 validated mode.
PKCS11 provider support for Veracrypt¶
The KMS server can be used as a PKCS#11 provider for Veracrypt and provide keys on the fly to mount encrypted volumes. Check the Veracrypt Disk Encryption 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 to securely run in the Cloud or other Zero-Trust environments¶
Thanks to its design, running on top of Cosmian VMs with 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
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.
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
[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 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
[env: KMS_HTTPS_P12_FILE=]
--https-p12-password <HTTPS_P12_PASSWORD>
The password to open the PKCS#12 Certificates and Key file
[env: KMS_HTTPS_P12_PASSWORD=]
--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
To handle multiple identity managers, add different parameters under each argument
(jwt-issuer-uri, jwks-uri and optionally jwt-audience), keeping them in
the same order
--jwt-issuer-uri <JWT_ISSUER_URI_1> <JWT_ISSUER_URI_2>
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
To handle multiple identity managers, add different parameters under each argument
(jwt-issuer-uri, jwks-uri and optionally jwt-audience), keeping them in
the same order
--jwks-uri <JWKS_URI_1> <JWKS_URI_2>
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` if 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=]
--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]
--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=]
--google-cse-kacls-url <GOOGLE_CSE_KACLS_URL>
This setting enables the Google Workspace Client Side Encryption feature of this KMS server.
It should contain the external URL of this server as configured in Google Workspace client side encryption settings For instance, if this server is running on domain `cse.my_domain.com`, the URL should be something like <https://cse.my_domain.com/google_cse>
[env: KMS_GOOGLE_CSE_KACLS_URL=]
--ms-dke-service-url <MS_DKE_SERVICE_URL>
This setting enables the Microsoft Double Key Encryption service feature of this server.
It should contain the external URL of this server as configured in Azure App Registrations
as the DKE Service (https://learn.microsoft.com/en-us/purview/double-key-encryption-setup#register-your-key-store)
The URL should be something like <https://cse.my_domain.com/ms_dke>
[env: KMS_MS_DKE_SERVICE_URL=]
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version
TOML configuration file¶
If a file is found at /etc/cosmian_kms/server.toml, the KMS server will use it to configure
itself.
The location of the file can be changed using the COSMIAN_KMS_CONF environment variable.
The file should be a TOML file with the following structure:
default_username = "[default username]"
force_default_username = false
google_cse_kacls_url = "[google cse kacls url]"
ms_dke_service_url = "[ms dke service url]"
[db]
database_type = "[redis-findex, postgresql,...]"
database_url = "[redis urls]"
sqlite_path = "[sqlite path]"
redis_master_password = "[redis master password]"
redis_findex_label = "[redis findex label]"
clear_database = false
[http]
port = 443
hostname = "[hostname]"
https_p12_file = "[https p12 file]"
https_p12_password = "[https p12 password]"
authority_cert_file = "[authority cert file]"
[auth]
jwt_issuer_uri = ["[jwt issuer uri]"]
jwks_uri = ["[jwks uri]"]
jwt_audience = ["[jwt audience]"]
[workspace]
root_data_path = "[root data path]"
tmp_path = "[tmp path]"