TOML configuration file¶
The KMS server can be configured using a TOML file. When a configuration file is provided, the command line arguments are ignored.
By default, the configuration filepath is retrieved in the following order:
- If the environment variable
COSMIAN_KMS_CONFis set and the path behind exists, the KMS server will use this configuration file, - Otherwise, if a file is found at
/etc/cosmian/kms.toml, the KMS server will use this file. - Finally, if none of the above is found, the KMS server will use the command line arguments
The file should be a TOML file with the following structure:
# The default username to use when no authentication method is provided.
default_username = "admin"
# When an authentication method is provided, perform the authentication
# but always use the default username instead of the one provided by the authentication method
force_default_username = false
# This setting enables this server's Microsoft Double Key Encryption service feature.
# 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>
ms_dke_service_url = "<ms dke service url>"
# This setting defines the public URL where the KMS is accessible (e.g., behind a proxy).
# It is used :
# - during the authentication flow initiated from the KMS UI. See the [ui_config] section below.
# - for cse endpoints: it is required if google cse configuration is activated ;
# If this server is running on the domain `cse.my_domain.com` with this public URL,
# The configured URL from Google admin should be something like <https://cse.my_domain.com/google_cse>
kms_public_url = "kms-public-url"
# Print the server configuration information and exit
info = false
# The following fields are only needed if an HSM is used.
# Check the HSMs documentation pages for more information.
hsm_model = "<hsm_name>"
hsm_admin = "<hsm admin username>" #for Create operation on HSM
hsm_slot = [1, 2, ...]
hsm_password = ["<password_of_1st_slot1>", "<password_of_2bd_slot2>", ...]
# Force all newly created and imported keys to be wrapped by the key specified in this field.
# This is most useful to ensure that an HSM key wraps all keys in the KMS database.
# Note: This setting is ignored when a key is imported in JSON TTLV format and is already wrapped.
key_encryption_key = "kek ID"
# All users can create and import objects in the KMS by default.
# Only these users can create and import objects when this setting contains a user ID list.
privileged_users = ["<user_id_1>", "<user_id_2>"]
# Check the database configuration documentation pages for more information
[db]
database_type = "postgresql", "mysql", "sqlite", "redis-findex"
database_url = "<database-url>"
sqlite_path = "<sqlite-path>"
redis_master_password = "<redis master password>"
redis_findex_label = "<redis findex label>"
# Clear the database at startup. WARNING: This will delete all objects in the database.
clear_database = false
# When a wrapped object is fetched from the database,
# it is unwrapped and stored in the unwrapped cache.
# This option specifies the maximum age in minutes of the unwrapped objects in the cache
# after its last use.
# The default is 15 minutes.
# About 2/3 of the objects will be evicted after this time; the other 1/3 will be evicted
# after a maximum of 150% of the time.
unwrapped_cache_max_age = 15 # minutes
# TLS configuration of the Socket server and HTTP server
[tls]
# The KMS server's optional PKCS#12 Certificates and Key file.
# If provided, this will start the server in HTTPS mode.
tls_p12_file = "[tls p12 file]"
# The password to open the PKCS#12 certificates and key file.
tls_p12_password = "[tls p12 password]"
# The server's optional authority X509 certificate in PEM format
# used to validate the client certificate presented for authentication.
# If provided, clients must present a certificate signed by this authority for authentication.
# The server must run in TLS mode for this to be used.
clients_ca_cert_file = "[authority cert file]"
# The socket server listens to KMIP binary requests on the IANA-registered 4696 port.
# The socket server will only start if the TLS configuration is provided **and** client certificate authentication
# is enabled.
[socket_server]
# Start the socket server. See comments above on conditions for starting the server.
socket_server_start = false
# The socket server port - defaults to 5696
socket_server_port = 5696
# The socket server hostname - defaults to "0.0.0.0"
socket_server_hostname = "0.0.0.0"
# The HTTP server listens to KMIP requests on the /kmip and /kmip/2_1 endpoints.
# It also serves the web UI on the /ui endpoint.
# If the TLS configuration is provided, the server will start in HTTPS mode.
[http]
# The KMS server port - defaults to 9998
port = 9998
# The KMS server hostname - defaults to 0.0.0.0
hostname = "0.0.0.0"
# If using a forward proxy for outbound JWKS requests,
# set the proxy parameters here.
[proxy]
# The URL of the proxy server, including the protocol and port.
# - e.g., "https://secure.example" for an HTTP proxy
# - e.g., "socks5://192.168.1.1:9000" for a SOCKS proxy
proxy_url = "https://proxy.example.com:8080"
# The username to use for basic authentication with the proxy server.
proxy_basic_auth_username = "[proxy username]"
# The password to use for basic authentication with the proxy server.
proxy_basic_auth_password = "[proxy password]"
# Use a custom proxy authentication header instead of the standard Basic authentication.
proxy_custom_auth_header = "my_custom_auth_token"
# The list of domains to exclude from the proxy.
proxy_exclusion_list = ["domain1", "domain2"]
# Check the Authenticating Users documentation pages for more information.
[auth]
# 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 in the three lists.
# 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`
jwt_issuer_uri = ["<jwt issuer 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
# To set an identity provider configuration element to None, set its value to an empty string.
# 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
jwks_uri = ["<jwks uri>"]
# The audience of the JWT token
# Optional: the server will validate the JWT `aud` claim against this value if set
jwt_audience = ["<jwt audience>"]
[workspace]
# The root folder where the KMS will store its data
# A relative path is taken relative to the user's HOME directory
root_data_path = "./cosmian-kms"
# The folder to store temporary data (non-persistent data readable
# by no one but the current instance during the current execution)
tmp_path = "/tmp"
# Check the logging documentation pages for more information
[logging]
# The log level of the KMS server. This is an alternative to the `RUST_LOG` environment variable.
rust_log = "info,cosmian_kms=debug"
# The Open Telemetry OTLP collector URL.
otlp = "http://localhost:4317"
# If set to true, the KMS server will not output logs to stdout. Telemetry will still be sent to the OTLP collector,
# if configured.
quiet = false
# If set to true, the KMS server will log to syslog instead of stdout.
log_to_syslog = false
# The Telemetry will also contain metering and tracing events if set to true.
enable_metering = false
# When using telemetry, this setting will show the KMS environment: "production", "development", "staging", "testing"...
environment = "development"
# Generic configuration to edit the path to static UI application files
# To use the Web UI, ensure the `kms_public_url` is set to the correct public URL above.
[ui_config]
ui_index_html_folder = "path/kms/ui/dist"
# Configuration for the handling of authentication with OIDC from the KMS UI.
# This is used to authenticate users when they access the KMS UI.
# The same Identity Provider must **also** be configured in the [auth] section above.
[ui_config.ui_oidc_auth]
ui_oidc_client_id = "<client id>"
ui_oidc_client_secret = "<client secret>" (optional)
ui_oidc_issuer_url = "<issuer-url>"
ui_oidc_logout_url = "<logout-url>"
[google_cse_config]
# This setting turns on endpoints handling Google CSE feature
google_cse_enable = false
# This setting disables the validation of the tokens used by the Google Workspace CSE feature of this server
# Useful for testing purposes
google_cse_disable_tokens_validation = false
# This setting contains the list of KACLS server URLs that can access this server for Google CSE migration, through
# the privilegedunwrap endpoint (used to fetch exposed jwks on server start)
google_cse_incoming_url_whitelist = ["[kacls_url_1]", "[kacls_url_2]"]
# PEM PKCS8 RSA private key used to ensure consistency of certificate handling and privileged unwrap operations
# across server restarts and multiple server instances. If not provided, a random key will be generated at server startup.
google_cse_migration_key = "<google_cse_existing_migration_key>"