KMIP Integration

Learn more about integrating with Hanzo KMS using KMIP (Key Management Interoperability Protocol).

KMIP integration is an Enterprise-only feature. Please reach out to sales@hanzo.ai if you have any questions.

Hanzo KMS provides Key Management Interoperability Protocol (KMIP) support for integration with KMIP-compatible clients. This allows for enhanced key management across various applications that support the KMIP 1.4 protocol.

How KMIP Works with Hanzo KMS

At a high level, the KMIP integration follows this architecture:

KMIP Architecture Diagram

At a high level, the KMIP integration works as follows:

KMIP clients (your applications or tools) communicate with the KMIP server

The KMIP server acts as a proxy and forwards requests to Hanzo KMS

The KMIP server authenticates to Hanzo KMS using a machine identity

The KMIP server itself is deployed using the KMS CLI (kms kmip start command) and serves as an intermediary between your KMIP clients and Hanzo KMS's key management system.

Supported Operations

The Hanzo KMS KMIP server supports the following operations for symmetric keys:

Create - Generate symmetric keys

Register - Register externally created keys

Locate - Find keys using attributes

Get - Retrieve keys securely

Activate - Enable keys for usage

Revoke - Revoke existing keys

Destroy - Permanently remove keys

Get Attributes - Retrieve metadata associated with keys

Query - Query server capabilities and supported operations

Compatibility

Hanzo KMS KMIP supports KMIP versions 1.0 to 1.4, ensuring compatibility with a wide range of clients and security tools.

Network Requirements

Ensure the following network connectivity is in place:

KMIP Client → KMIP Server: KMIP clients must be able to reach the KMIP server on port 5696 (or your configured port). Ensure firewalls allow this traffic and DNS resolution works if using hostnames.

KMIP Server → KMS Platform: The KMIP server needs outbound HTTP access to Hanzo KMS. For self-hosted instances, ensure connectivity to your custom domain.

Configure and Deploy the KMIP Server

Follow these steps in order to set up KMIP integration with Hanzo KMS:

The KMIP server needs a machine identity to authenticate with Hanzo KMS and proxy requests on behalf of clients.

Configure a machine identity by heading to your organization's Access Control and switching over to the identities tab. From there you can click Create Identity.

This guide assumes you'll be using the Universal Auth method for the machine identity but you can choose any supported authentication method.

KMIP create machine identity

This machine identity will be used by the KMIP server to authenticate and forward client requests to Hanzo KMS.

The machine identity needs permission to proxy KMIP requests.

Create a custom organization role and give it the Proxy KMIP permission.

KMIP create custom role KMIP assign proxy to role

This permission allows the KMIP server to act as an intermediary between KMIP clients and Hanzo KMS.

Now connect the machine identity to the role you just created.

Assign the machine identity to the custom organization role.

KMIP assign role to machine identity

This grants the machine identity the ability to serve KMIP client requests and forward them from your KMIP server to Hanzo KMS.

Now you're ready to deploy the KMIP server. You can run the KMIP server on any infrastructure that can reach the Hanzo KMS platform, such as a VM or container.

Once you have your infrastructure ready, you'll need to install the KMS CLI on the server where you want to run the KMIP server.

To install the latest KMS CLI visit KMS CLI instructions. If you need to install specific versions of the CLI, you can find them on the KMS CLI GitHub Releases.

Then, launch the KMIP server with the following command:

kms kmip start \
  --identity-client-id=example-client-id \
  --identity-client-secret=example-client-secret \
  --domain=https://my-kms-instance.com \
  --listen-address="0.0.0.0:5696" \
  --hostnames-or-ips="my-kmip-server.com"

Available flags:

listen-address (default: localhost:5696): The address the KMIP server listens on. In most cases you'll want to listen on all interfaces (0.0.0.0:5696)
identity-auth-method (default: universal-auth): The authentication method for the machine identity
identity-client-id: The client ID of the machine identity (can be set via INFISICAL_UNIVERSAL_AUTH_CLIENT_ID env var)
identity-client-secret: The client secret of the machine identity (can be set via INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET env var)
server-name (default: "kmip-server"): The name of the KMIP server
certificate-ttl (default: "1y"): The duration for which the server certificate is valid
hostnames-or-ips: The IP address or the hostname of the server where you have deployed the KMIP server.

Once started, your KMIP server is now running and ready to accept client connections. It will authenticate to Hanzo KMS using the machine identity and proxy all KMIP operations.

Now that the KMIP server is running, you need to register KMIP clients that will connect to it.

Navigate to the desired KMS project if you already have one or create a new project of type KMS, then select KMIP once inside the project, and click Add KMIP Client.

KMIP client overview

Define the client and its permissions.

In the modal, provide the details of your client. The selected permissions determine what KMIP operations (Create, Get, Revoke, etc.) can be performed in your KMS project.

KMIP client modal

This creates a KMIP client entity in Hanzo KMS that will be authenticated via mTLS certificates.

Each KMIP client needs its own certificate for mTLS authentication.

Click Generate Certificate for your newly created client.

KMIP generate client cert

Provide the desired TTL (time-to-live) and key algorithm, then click Generate Client Certificate.

KMIP client cert config

Download the generated client certificate, certificate chain, and private key.

KMIP client cert modal

Configure your KMIP-compatible applications or tools to use these credentials when connecting to the KMIP server. The client will now authenticate via mTLS and perform authorized key management operations through the KMIP server, which proxies requests to Hanzo KMS.

Connecting your KMIP Client to Hanzo KMS

After completing the setup, configure your KMIP compatible application to connect to the KMIP server.

While exact configuration steps vary by application, you'll generally need to provide:

KMIP Server Address: The hostname or IP and port where your KMIP server is listening (e.g., my-kmip-server.com:5696)

Client Certificates: The certificate credentials generated from your Hanzo KMS project:

Client Certificate (client-cert.pem) - Identifies your KMIP client
Client Private Key (client-key.pem) - Used for mTLS authentication
Certificate Chain (cert-chain.pem) - Verifies the KMIP server

General Configuration Steps

Determine the address where your KMIP server is accessible. This should match one of the hostnames or IPs you specified when starting the KMIP server with the --hostnames-or-ips flag.

Example endpoints:

my-kmip-server.com:5696
10.0.1.50:5696
kmip.example.com:5696

The default port is 5696, but this can be changed using the --listen-address flag when starting the server.

Organize the certificate materials you downloaded when generating the client certificate from the Hanzo KMS project. You should have three files:

client-cert.pem - The client certificate
cert-chain.pem - The certificate chain (includes intermediate and root CA certificates)
client-key.pem - The private key

Most KMIP clients require these files in PEM format, which is what Hanzo KMS provides by default.

The exact configuration steps vary depending on your KMIP client application. Generally, you'll need to specify:

Common configuration parameters:

Server hostname/IP: Your KMIP server address (e.g., my-kmip-server.com)
Server port: Default is 5696
Client certificate: Path to client-cert.pem
Client private key: Path to client-key.pem
CA certificate: Path to cert-chain.pem (used to verify the server)
Protocol version: KMIP 1.0 through 1.4 are supported

Example configuration for PyKMIP:

[client]
host=my-kmip-server.com
port=5696
certfile=/path/to/client-cert.pem
keyfile=/path/to/client-key.pem
ca_certs=/path/to/cert-chain.pem

Once configured, test the connection by performing a simple KMIP operation, such as:

Querying server capabilities
Creating a test key
Listing available keys

If the connection is successful, your KMIP client is now integrated with Hanzo KMS and can perform key management operations according to the permissions you assigned.

Troubleshooting connection issues:

Verify network connectivity between your KMIP client and the KMIP server
Check that certificate files are readable and in the correct format
Ensure the KMIP server is running and accessible
Review KMIP server logs for authentication errors
Confirm the client certificate has not expired

If you require further verification of your certificate details and connectivity to the KMIP server from your KMIP client, you can use the following command from your client machine:

openssl s_client -connect kmip-server-ip-here:5696 --cert /path/to/client-cert.pem --key /path/to/client-cert.pem --CAfile /path/to/cert-chain.pem --tls1_2 --showcerts --state --debug

This command attempts to establish a TLS connection to the KMIP server using your client certificate and key, displaying detailed information about the handshake process. If the connection is successful, you'll see the server's certificate chain and a message indicating that the handshake was completed.