KMIP Server

The craton-hsm-kmip crate implements an OASIS KMIP server that speaks the binary Tag-Type-Length-Value (TTLV) protocol on the wire and dispatches requests to Craton HSM's key store and crypto backend. It provides a drop-in KMIP endpoint for applications that already speak KMIP.

• Crate: craton-hsm-kmip
• License: BSL 1.1
• MSRV: Rust 1.75
• Safety: #![deny(unsafe_code)] at the crate root.
• Status: production-ready

Protocol Version Coverage

The crate's Cargo.toml description lists KMIP 2.1. The implemented surface is a KMIP 1.4-compatible subset sufficient for the operations below. Full 2.1 feature coverage is not claimed.

Supported Operations

• Create — generate a symmetric or asymmetric key.
• Register — import externally supplied key material.
• Get — retrieve a key by unique identifier.
• GetAttributes — read individual attributes.
• Activate — transition Pre-Active → Active.
• Revoke — transition to Deactivated.
• Destroy — zero and remove a key.
• Locate — find keys by attribute predicate.
• Query — advertise server capabilities.

Object types supported: asymmetric, symmetric, secret-data, and opaque. Profiles beyond that (PGP, split keys, certificate chains) are not implemented.

Modules

• ttlv — binary codec for KMIP messages.
• types — KMIP enumerations (tags, operations, result reasons, object types, attribute names).
• operations — per-operation request and response handlers.
• server — top-level message dispatcher, authentication hand-off, and the auth-rate-limiter.

TTLV Codec

The TTLV parser enforces two bounds to prevent a malicious client from exhausting the parser:

• Maximum nesting depth: 32 structure levels.
• Maximum per-value length: 1 MiB.

Depth violations surface as TtlvError::DepthExceeded; oversize values surface with a size-limit error variant.

Authentication Model

KMIP authentication is not handled inside the KMIP payload. The expected deployment pattern is:

1. A TLS terminator (rustls, nginx, or similar) performs mTLS and validates the client certificate chain.
2. The peer certificate subject or SPKI hash is passed into craton-hsm-auth as the authenticated identity.
3. RBAC is enforced against that identity before the operation is dispatched.

Per-client rate limiting runs at the server layer and tracks failures over a sliding window keyed by token hash.

Feature Flag

Usage

use craton_hsm_kmip::server::KmipServer;
use craton_hsm_kmip::operations::InMemoryKeyStore;
use std::sync::Arc;

let store  = Arc::new(InMemoryKeyStore::new());
let server = KmipServer::new(store);

// Decode, dispatch, and encode a TTLV message.
let request_bytes : Vec<u8> = vec![/* ... */];
let response_bytes          = server.process_message(&request_bytes)?;
# Ok::<(), Box<dyn std::error::Error>>(())

The KMIP well-known port is 5696. Wire the server into a real transport (typically TLS over TCP) in your binary crate. No runnable examples are shipped in the crate's examples/.

Security Properties

• #![deny(unsafe_code)] at the crate root.
• TTLV parser bounds (depth 32, per-value length 1 MiB).
• Authentication rate limiting per client-token hash.
• mTLS expected at the transport layer; identity hand-off to craton-hsm-auth for RBAC.
• Key material crosses trust boundaries in Zeroizing buffers.

Client Interop Notes

• The server advertises KMIP 2.1 as the default protocol version in responses but negotiates down to 1.4 for clients that do not speak 2.x.
• The Credential / Authentication KMIP attribute structures are not fully modeled; authentication happens outside the KMIP payload, so KMIP clients that expect an in-payload bearer will need to switch to mTLS.
• InMemoryKeyStore is intended for tests. Production deployments provide their own KmipKeyStore implementation — typically backed by the replicated state machine in craton-hsm-cluster.
• Tested against common KMIP toolchains; interop gaps against a specific client should be filed as bugs with a captured TTLV trace.

Limitations

• KMIP 1.4 subset, not full 2.1.
• No built-in transport. The crate is a message dispatcher; embed it in your own TLS server.
• No persistence contract beyond what the supplied KmipKeyStore implementation provides.
• In-payload credential structures not modeled — use mTLS + craton-hsm-auth.

Error Reporting

TTLV parsing failures surface as TtlvError, including DepthExceeded. Dispatched-operation errors surface through standard KMIP result codes in the response message.

Related Documents

• Authentication and RBAC — identity hand-off after mTLS termination.
• Cluster and replication — replicated state machine for KmipKeyStore.