Managing KMIP Clients

In this tutorial you will learn how to create and manage KMIP clients.

Background

Access to the KMIP Server is controlled via mutual TLS (mTLS). Only registered KMIP clients can access the KMIP Server (and through it, the HSM Partition).

Every KMIP client is identified by the Subject Common Name (CN) of its client certificate. The name can be chosen freely when the certificate is issued. The CN also identifies the client in the KMIP Server logs, for example:

INFO  [26E0F496-1:admin] op Certificate from 10.28.3.135:40236 dn: CN=admin, OU=Securosys Key Manager KMIP, O=Securosys SA, C=CH

KMIP clients are managed in the Key Manager UI under Add-ons > KMIP Server > Clients.

Overview

Onboarding a client application always follows the same steps:

1. Create the KMIP client under add-ons Add-ons > KMIP Server > Clients using one of the three onboarding modes.
2. Install the client keystore in the client application: its own private key and certificate, used to authenticate itself to the KMIP Server.
3. Install the client truststore in the client application: the KMIP Server's certificate, used to verify it is talking to the right server.
4. Connect the client application to the KMIP Server.

Keystore and truststore are the two halves of mutual TLS (mTLS): the keystore proves the client's identity, the truststore verifies the server's.

Create KMIP Client

The Add User wizard offers three onboarding modes. They differ in who generates the client key pair, where the private key lives, and whether the KMIP Server must be restarted:

Sign a Certificate Request (CSR)

• The client application generates its own key pair and provides a CSR; the CN of the CSR becomes the username.
• The Key Manager signs it with the KMIP User CA and returns the client certificate together with the CA certificate.
• The private key never leaves the client application.
• No KMIP Server restart is required - the issuing KMIP User CA is already trusted.

Managed Client

• The key pair is generated on the HSM (RSA-2048/4096 or EC P-256) and the client certificate is issued by the KMIP User CA.
• The credentials are downloaded as a password-protected PKCS#12 client keystore, together with the client truststore.
• Use this mode for applications that cannot generate their own key pair or want HSM entropy.
• No KMIP Server restart is required - the issuing KMIP User CA is already trusted.

Import Certificate

• The client application already has a key pair and certificate (issued by a corporate PKI, or self-signed); you only register the certificate. The CN of the certificate becomes the username.
• Optionally upload the issuing CA certificate: then that CA is trusted and the client certificate is verified to chain to it; otherwise exactly the uploaded certificate is trusted (pinned).
• A KMIP Server restart is required. An imported certificate is not signed by the KMIP User CA, so its trust anchor must be newly pinned in the KMIP Server truststore, which the KMIP Server only reads at startup. Until the restart, the imported client cannot connect. The Key Manager shows a restart banner after the import.

If in doubt, restart the KMIP Server to make sure that it reloads the updated client list.

Client Truststore

To download the KMIP Server's certificate, go to add-ons KMIP Server > Clients, click Client Truststore, and choose the format:

• Truststore (.p12): for Java clients; protected by a password you set at download.
• Certificate (PEM): for OpenSSL, curl, or Python clients; no password.

Delete KMIP Clients

To delete a KMIP client, open the Delete action in the user's row and confirm by typing the username. The client loses access immediately; no KMIP Server restart is needed.

The KMIP User CA

The Key Manager automatically provisions a dedicated issuing CA for KMIP client certificates, the KMIP User CA. Its private key is generated on the Base Partition (key label kmip.user.ca), is non-extractable, and never leaves the HSM. It signs the client certificates of CSR-based and managed KMIP clients, and it is pinned once in the KMIP Server truststore. Since every CA-signed client certificate validates against this anchor, adding or removing such clients requires no KMIP Server restart.

The relevant details of the CA certificate (openssl x509 -text -noout):

Serial Number: 0 (0x0)
Signature Algorithm: sha256WithRSAEncryption
Issuer: C=CH, O=Securosys SA, OU=Securosys Key Manager KMIP, CN=KMS KMIP User CA
Validity
    Not Before: Jul 24 00:00:00 2026 GMT
    Not After : Jul 21 00:00:00 2036 GMT
Subject: C=CH, O=Securosys SA, OU=Securosys Key Manager KMIP, CN=KMS KMIP User CA
Subject Public Key Info:
    Public Key Algorithm: rsaEncryption
        Public-Key: (4096 bit)
X509v3 extensions:
    X509v3 Basic Constraints:
        CA:TRUE
    X509v3 Key Usage: critical
        Certificate Sign, CRL Sign

It is a self-signed root (Issuer = Subject) with a validity of 10 years. The CA key is managed by the Key Manager, do not delete it.