Veeam Backup & Replication — KMS Encryption Key Management

Veeam Backup & Replication supports delegating backup encryption key management to an external KMIP-compliant Key Management Server. By connecting Veeam to Eviden KMS, encryption keys for backup jobs are never stored on the Veeam infrastructure itself: they are managed in a centrally audited, optionally HSM-backed key store.

Overview

Item	Details
Protocol	KMIP 1.4 over TCP/TLS with mutual certificate authentication
Port	5696 (IANA-registered KMIP port)
Key type	RSA-2048 asymmetric key pair
Veeam version	Veeam Backup & Replication 12 and above
Eviden KMS feature	Works with both FIPS and non-FIPS builds

What Veeam does

When you configure an external KMS in Veeam, the Veeam server performs the following KMIP operations for each protected backup job:

Step	KMIP Operation	Purpose
1	`Locate`	Find an existing key by name / identifier
2	`Get` (PublicKey)	Retrieve the RSA public key to encrypt backup metadata
3	`CreateKeyPair`	Create a new RSA-2048 key pair when none exists
4	`Activate`	Transition the key pair from PreActive to Active state
5	`Get` (PrivateKey)	Retrieve the RSA private key for decryption during restore
6	`Destroy`	Delete the key pair on job removal or rotation

Compatibility fixes in Eviden KMS

Two fixes were required for full Veeam Backup & Replication compatibility. Both are included in Eviden KMS as of the version that introduced this documentation:

KeyValue attributes in Get response (bug fix): Veeam's KMIP 1.4 decoder for PublicKey and PrivateKey expects the KeyValue structure to contain only key material — it does not support any Attribute elements inside KeyValue. Previous versions of Eviden KMS embedded all object metadata attributes (state, identifiers, links, etc.) inside KeyValue when converting from the internal KMIP-2.1 representation to KMIP-1.4 wire format. This caused Veeam to throw KmipUnexpectedTagException: Unexpected Tag 66, expected Attribute and abort the key retrieval. The server now strips all attributes from KeyValue for asymmetric keys when responding to KMIP 1.x clients.
TLS session ID context (bug fix): Veeam reuses KMIP connections via TLS session resumption. When both SSL_VERIFY_PEER and OpenSSL session caching are active, OpenSSL requires a session-ID context to be set on the server acceptor. Without it, session-resumption attempts fail with ssl_get_prev_session:session id context uninitialized, causing each reconnect to produce an SSPI authentication error on the Veeam side. The server now calls SSL_CTX_set_session_id_context during TLS acceptor initialisation.

Prerequisites

Eviden KMS server 4.x or later (both FIPS and non-FIPS builds are supported)
TLS enabled on the KMS socket server (port 5696) with mutual certificate authentication
A server TLS certificate and the corresponding CA to be trusted by Veeam
A client certificate (signed by a CA known to the KMS) to authenticate Veeam

Server-Side Setup

1. Configure TLS and the KMIP socket server

Edit your kms.toml:

[tls]
tls_p12_file     = "/etc/cosmian/kms/server.p12"
tls_p12_password = "your-p12-password"
clients_ca_cert_file = "/etc/cosmian/kms/clients-ca.crt"

[socket_server]
socket_server_start    = true
socket_server_port     = 5696
socket_server_hostname = "0.0.0.0"

2. Issue a client certificate for Veeam

Veeam identifies itself to the KMS using a client TLS certificate signed by the clients_ca_cert_file CA:

# Generate a CA and a client certificate
openssl genrsa -out clients-ca.key 4096
openssl req -new -x509 -days 3650 -key clients-ca.key \
  -subj "/CN=KMS Clients CA" -out clients-ca.crt

openssl genrsa -out veeam-client.key 2048
openssl req -new -key veeam-client.key \
  -subj "/CN=veeam-backup-server" -out veeam-client.csr
openssl x509 -req -days 3650 -in veeam-client.csr \
  -CA clients-ca.crt -CAkey clients-ca.key -CAcreateserial \
  -out veeam-client.crt

Bundle the client certificate and key as a PKCS#12 file for import into Veeam:

openssl pkcs12 -export \
  -in veeam-client.crt -inkey veeam-client.key \
  -certfile clients-ca.crt \
  -out veeam-client.p12 -passout pass:veeam-p12-password

3. Start Eviden KMS

cosmian_kms --config /etc/cosmian/kms/kms.toml

Or via Docker (note the -p 5696:5696 for the KMIP socket port):

docker run -p 9998:9998 -p 5696:5696 \
  -v /etc/cosmian/kms:/etc/cosmian/kms:ro \
  -e COSMIAN_KMS_CONF=/etc/cosmian/kms/kms.toml \
  ghcr.io/cosmian/kms:latest

Veeam-Side Configuration

In the Veeam Backup & Replication console, open Menu → Manage Credentials (or Encryption Manager depending on your version).
Add a new KMS Server with the following parameters:

Field	Value
Server name / IP	Hostname or IP of your Eviden KMS host
Port	`5696`
Certificate	Upload the PKCS#12 file (`veeam-client.p12`)
Password	The PKCS#12 password
KMS CA Certificate	Upload the KMS server CA certificate (`ca.crt` or the CA that signed the server certificate)

Click Test Connection. Veeam will perform a Locate probe against the server. A successful test shows a green check-mark.
Assign the KMS server to a backup job under Job Properties → Storage → Advanced → Encryption.

Troubleshooting

Symptom	Likely cause	Fix
`KmipUnexpectedTagException: Unexpected Tag 66, expected Attribute`	Old Eviden KMS version (pre-fix) embedding attributes inside `KeyValue`	Upgrade Eviden KMS
`A call to SSPI failed` / `SSL_ERROR_SSL` on reconnect	TLS session-ID context not set	Upgrade Eviden KMS
`Test Connection` fails with certificate error	CA mismatch or self-signed cert	Verify `clients_ca_cert_file` contains the CA that signed the Veeam client cert, and that Veeam trusts the KMS server certificate
Key not found after Veeam server migration	Unique identifier stored by Veeam differs from KMS	Re-configure the KMS server entry in Veeam; the keys remain in the KMS store

Keyboard shortcuts