Enabling TLS

The KMS activates two internal listeners: a socket server and an HTTP server.

The socket server listens to KMIP binary requests on the IANA-registered 5696 port. The socket server will only start if the TLS configuration is provided and client certificate authentication is enabled.

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. The HTTP server is always started, even if the TLS configuration is not provided.

The KMS server should be started using HTTPS when running in a zero-trust environment. Check the running in a zero-trust environment section for more information.

Quick start: the configuration wizard

The fastest way to enable TLS is the built-in interactive wizard:

cosmian_kms configure

At step 3/9 the wizard asks whether to enable TLS and then offers two paths:

The wizard creates a complete PKI under a directory you choose (default /etc/cosmian/):

File	Description
`ca.crt`	Self-signed CA certificate (RSA-4096, valid 10 years)
`server.crt`	Server leaf certificate signed by the CA (RSA-2048)
`server.key`	Server private key (PKCS#8 PEM)
`client.crt`	Client certificate — distribute to mTLS clients
`client.key`	Client private key (PKCS#8 PEM)

It then asks whether to enable mutual TLS (mTLS) and optionally restricts the cipher suites. The resulting paths are written automatically to the TOML file.

At the end the wizard writes the resulting kms.toml and prints the start command. See the full wizard reference for all steps and the self-signed PKI file table.

Obtaining a CA-signed certificate

For production deployments, use certbot or your organisation's PKI to obtain a valid certificate, then point the TOML fields to those files. See the certificate procedures guide for step-by-step instructions (certbot, BYO certs, PEM → PKCS#12 conversion).

Providing certificates

The KMS server supports two certificate formats depending on the build variant:

FIPS mode (default build): Requires PEM-formatted certificates and keys.

Server certificate in PEM format (may include full chain)
Private key in PEM format (PKCS#8 or traditional format)
Optional separate chain file for intermediate CAs

Non-FIPS mode: Supports PKCS#12 format.

Key and full certificate chain in PKCS#12 format
Password to open the PKCS#12 file

When enabling client certificate authentication, the server's authority X509 certificate in PEM format must also be provided (for both modes). Multiple CA certificates can be concatenated in a single PEM file to support different certificate authorities.

Reference: manual configuration

Note

The sections below document the raw TOML and CLI options. The cosmian_kms configure wizard writes exactly these fields for you — use it to avoid manual editing. See Quick start: the configuration wizard above.

TOML configuration file

Certificate information must be provided in the [tls] section of the TOML configuration file.

For FIPS mode (default build):

# TLS configuration of the Socket server and HTTP server
[tls]

# The server's X.509 certificate in PEM format.
# Provide a PEM containing the server leaf certificate,
# optionally followed by intermediate certificates (full chain).
tls_cert_file = "path/to/server.crt"

# The server's private key in PEM format (PKCS#8 or traditional format).
tls_key_file = "path/to/server.key"

# Optional certificate chain in PEM format (intermediate CAs).
# If not provided, the chain may be appended to tls_cert_file instead.
tls_chain_file = "path/to/chain.pem"

For non-FIPS mode:

# 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 = "path/to/server.p12"

# The password to open the PKCS#12 Certificates and Key file.
tls_p12_password = "your_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.
# Multiple CA certificates can be concatenated in a single PEM file.
clients_ca_cert_file = "[authority cert file]"

# Optional colon-separated list of TLS cipher suites to enable.
# If not specified, OpenSSL default cipher suites will be used.
# Example: "TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256"
# ANSSI-recommended cipher suites:
# - For TLS 1.3 (preferred): TLS_AES_256_GCM_SHA384, TLS_AES_128_GCM_SHA256, TLS_CHACHA20_POLY1305_SHA256
# - For TLS 1.2 (compatibility): TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
tls_cipher_suites = "[cipher suites]"

Command-line flags

Certificate information can be provided using the command line interface.

# 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.
# Multiple CA certificates can be concatenated in a single PEM file.
--clients-ca-cert-file "[authority cert file]"

# Optional colon-separated list of TLS cipher suites to enable.
# If not specified, OpenSSL default cipher suites will be used.
# Example: "TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256"
--tls-cipher-suites "[cipher suites]"

Generate a PKCS#12 from PEM files

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

openssl pkcs12 -export \
-in server.mydomain.com.fullchain.pem \
-inkey server.mydomain.com.privkey.pem \
-out server.mydomain.com.p12

Advanced TLS Configuration

TLS Protocol Versions

By default, the KMS server accepts both TLS 1.2 and TLS 1.3 connections. Internally it uses the OpenSSL mozilla_intermediate_v5 profile, which sets TLS 1.2 as the minimum protocol version and TLS 1.3 as the maximum.

The active protocol version range is automatically derived from the cipher suites you configure (see TLS Cipher Suites Selection below):

`--tls-cipher-suites` value	minimum TLS version	maximum TLS version
(not set — default)	TLS 1.2	TLS 1.3
Only TLS 1.3 suites	TLS 1.3	TLS 1.3
Only TLS 1.2 suites	TLS 1.2	TLS 1.3
Mixed TLS 1.2 + TLS 1.3 suites	TLS 1.2	TLS 1.3

Enforce TLS 1.3 only — specify at least one TLS 1.3 cipher suite and no TLS 1.2 suites:

--tls-cipher-suites "TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256"

Keep TLS 1.2 compatibility — either leave --tls-cipher-suites unset (default), or include at least one TLS 1.2 cipher suite:

--tls-cipher-suites "TLS_AES_256_GCM_SHA384:TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"

TLS 1.2 security considerations

TLS 1.2 is still considered secure when used with AEAD cipher suites (GCM/ChaCha20), but TLS 1.3 is preferred. Avoid enabling TLS 1.2 unless required for legacy client compatibility.

TLS Cipher Suites Selection

The KMS server supports custom TLS cipher suite configuration to meet specific security requirements. You can specify which cipher suites to enable using a colon-separated list.

The cipher suites are automatically categorized into TLS 1.3 and TLS 1.2 suites:

TLS 1.3 cipher suites (preferred): TLS_AES_256_GCM_SHA384, TLS_AES_128_GCM_SHA256, TLS_CHACHA20_POLY1305_SHA256, TLS_AES_128_CCM_SHA256, TLS_AES_128_CCM_8_SHA256
TLS 1.2 cipher suites (for compatibility): TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256

If only TLS 1.3 cipher suites are specified, the server will enforce TLS 1.3 minimum protocol version. If only TLS 1.2 cipher suites are specified, the server will support TLS 1.2 and above.

Example configurations:

# ANSSI-recommended TLS 1.3 only configuration
--tls-cipher-suites "TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256:TLS_CHACHA20_POLY1305_SHA256"

# Mixed TLS 1.2/1.3 configuration for compatibility
--tls-cipher-suites "TLS_AES_256_GCM_SHA384:TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384:TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"

Multiple Certificate Authorities

The KMS server supports multiple certificate authorities for client certificate validation. You can concatenate multiple CA certificates in PEM format into a single file.

Example of multiple CA certificates in one file:

This allows clients with certificates issued by any of the specified CAs to authenticate successfully. The server will validate client certificates against all provided CA certificates.

Keyboard shortcuts