docs/documentation/platform/kms/kmip.mdx
Infisical 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.
At a high level, the KMIP integration follows this architecture:
At a high level, the KMIP integration works as follows:
The KMIP server itself is deployed using the Infisical CLI (infisical kmip start command) and serves as an intermediary between your KMIP clients and Infisical's key management system.
The Infisical KMIP server supports the following operations for symmetric keys:
Infisical KMIP supports KMIP versions 1.0 to 1.4, ensuring compatibility with a wide range of clients and security tools.
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 → Infisical Platform: The KMIP server needs outbound HTTP access to Infisical. For self-hosted instances, ensure connectivity to your custom domain.
Follow these steps in order to set up KMIP integration with Infisical:
<Steps> <Step title="Create a Machine Identity for the KMIP Server"> The KMIP server needs a machine identity to authenticate with Infisical and proxy requests on behalf of clients.Configure a [machine identity](/documentation/platform/identities/machine-identities#machine-identities) 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](/documentation/platform/identities/universal-auth) method for the machine identity but you can choose any supported authentication method.
This machine identity will be used by the KMIP server to authenticate and forward client requests to Infisical KMS.
Create a custom organization role and give it the **Proxy KMIP** permission.
This permission allows the KMIP server to act as an intermediary between KMIP clients and Infisical.
Assign the machine identity to the custom organization role.
This grants the machine identity the ability to serve KMIP client requests and forward them from your KMIP server to Infisical.
Once you have your infrastructure ready, you'll need to install the Infisical CLI on the server where you want to run the KMIP server.
To install the latest Infisical CLI visit [Infisical CLI instructions](https://infisical.com/docs/cli/overview).
If you need to install specific versions of the CLI, you can find them on the [Infisical CLI GitHub Releases](https://github.com/Infisical/cli/releases).
Then, launch the KMIP server with the following command:
```bash
infisical kmip start \
--identity-client-id=example-client-id \
--identity-client-secret=example-client-secret \
--domain=https://my-infisical-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 Infisical using the machine identity and proxy all KMIP operations.
<Info>
**Running as a Background Service (Linux):** For production deployments on Linux, you can install the KMIP server as a systemd service using `sudo infisical kmip systemd install`. This ensures the server starts automatically on boot and restarts on failure. See the [KMIP CLI Command Reference](/cli/commands/kmip) for details.
</Info>
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**.
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.
This creates a KMIP client entity in Infisical that will be authenticated via mTLS certificates.
Click **Generate Certificate** for your newly created client.
Provide the desired TTL (time-to-live) and key algorithm, then click **Generate Client Certificate**.
Download the generated client certificate, certificate chain, and private key.
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 Infisical 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 Infisical KMS project:
client-cert.pem) - Identifies your KMIP clientclient-key.pem) - Used for mTLS authenticationcert-chain.pem) - Verifies the KMIP server**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.
- **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 Infisical provides by default.
**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:**
```ini
[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
```
If the connection is successful, your KMIP client is now integrated with Infisical 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:
```bash
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.