KMIP Best Practices
Recommendations for running a DuoKey KMIP endpoint securely, grounded in what the platform actually enforces.
Authentication and transport
Client traffic is TLS on the KMIP port (default 5696), and client authentication is optional mutual TLS.
Enforce validated mTLS
Configure a trusted client-CA bundle so presented client certificates are validated and their identity can be trusted for authorization.
Require client certificates
Turn on require_client_cert on the endpoint and keep the allowed authentication methods to mtls (and token only if a client needs it).
Avoid anonymous access
Do not enable anonymous access on a production endpoint — use it only for a quick connectivity check.
# PEM bundle of client-CA certificates the KMIP listener will trust.
KMIP_CLIENT_CA_BUNDLE=/etc/duokey/kmip/client-ca-bundle.pemWithout KMIP_CLIENT_CA_BUNDLE, presented client certificates are accepted without CA validation and must not be trusted. In production the listener refuses to start until a bundle is configured — always set one.
Least-privilege endpoint policy
Each endpoint carries its own policy. Scope it to exactly what the connecting system needs:
| Control | Recommendation |
|---|---|
| Allowed operations | Grant only the operations the client uses (for example Create, Get, Activate, Encrypt/Decrypt). Disallowed operations return OperationNotSupported. |
| Allowed object types | Restrict to the object types in use — typically SymmetricKey. |
| One endpoint per purpose | Provision separate endpoints for separate systems or environments rather than sharing one broadly-scoped endpoint. |
Deploying and managing a hosted endpoint (the Server tab) uses the same endpoint permissions as other PKI protocol endpoints; connecting to external KMIP servers (the Client tab) is governed by the Operations.Kmip permissions (view, create, update, delete, test). Grant management rights only to the roles that need them.
Auditing
Enable audit logging on the endpoint so every KMIP operation is recorded, and review it from the endpoint's Operations tab in the KMIP menu. Watch for repeated authentication failures and unexpected operations.
Key hygiene
| Practice | Detail |
|---|---|
| Use AES-256 | The default and recommended symmetric key size. HMAC keys should be 256-bit or larger. |
| Activate deliberately | A key is PreActive until activated. Activate only when the key is ready to be used. |
| Rotate with ReKey | Roll keys with ReKey, which mints fresh material under a new identifier and links it to the previous key so existing data can still be decrypted. |
| Revoke before Destroy | Mark a key Compromised with Revoke as soon as it may have been exposed, then Destroy it once it is no longer needed. Destroy is irreversible. |
The server generates symmetric keys (AES, HMAC). It does not mint RSA or EC key pairs, and it does not provide signing, archival, or key-export operations — plan integrations around symmetric key management.
Protecting key material at rest
Key material is stored encrypted at rest in the Cockpit database, sealed with AES-256-GCM under the platform encryption key — the same protection used for vault credentials.
The security of stored KMIP keys depends on the platform encryption key. Protect it, restrict access to the Cockpit database, and include both in your backup and recovery plan. Losing the platform key means the stored key material cannot be decrypted.
Certificate lifecycle
- The KMIP listener presents the same TLS certificate as the Cockpit's HTTPS endpoint — manage that certificate's renewal as part of Cockpit operations.
- Rotate client certificates on a regular schedule and remove trust for retired client CAs from the bundle.
Validate before production
Use the built-in Client Simulator to run the full lifecycle (create → activate → get → encrypt/decrypt → revoke → destroy) against an endpoint before connecting a production system. Interoperability is also validated with the OASIS reference client, PyKMIP.
Production checklist
| Area | Before go-live |
|---|---|
| mTLS | Client-CA bundle configured; require_client_cert on; anonymous access off. |
| Policy | Allowed operations and object types scoped to the client. |
| Audit | Audit logging enabled on the endpoint. |
| Keys | Default algorithm AES-256; activation and rotation approach agreed. |
| Backup | Cockpit database and platform encryption key included in backups. |
| Validation | Endpoint exercised with the Client Simulator; endpoint is Running. |