Multitenancy (KMIP)

One KMIP Server can serve multiple HSM Partitions: each KMIP client is mapped to a Partition, and its keys and objects are created there. Additionally, the KMIP Server uses a Base Partition to store its own state. The KMIP Server logs in to all Partitions over the JCE API.

Base Partition

The Base Partition is the Partition that the KMIP Server uses to store its own state. The whole server-global state lives on this partition, stored as HSM data objects:

• kmipserver.properties - the server configuration (TLS, database, and protocol options)
• KMIP-USERS - the registry of the KMIP clients
• init.json - the trust seed with the KMIP clients and their groups
• The server keystore - the TLS certificate and private key that the server presents to clients
• The server truststore - the client CA that the server accepts in the mTLS handshake

When it starts, the KMIP Server authenticates to this partition using the values of primus.user and primus.password from the local kmipserver.properties file. Afterwards, the server reads the rest of the configuration from the data objects on the Base Partition. It merges them on top of its local configuration files, which only serve as a bootstrap. The HSM is the source of truth for the KMIP Server configuration.

These data objects are written by the Key Manager UI (see the Management section). Do not edit them manually! For this to work, the Base Partition of the KMIP Server must match the Base Partition of the Key Manager UI.

Additional Partitions

Each KMIP client is assigned an HSM partition at creation time. This is the Partition that the client uses to create and access its keys (and other objects). By default, clients are assigned the base partition. The list at KMIP Server > Clients shows the assignment in the Partition column.

You can create a KMIP client that is assigned to a different partition as follows:

1. Configure the HSM Partition to allow requests via KMIP. Follow the same steps in the installation guide as for the Base Partition.
2. Register the additional Partition in the Key Manager under Administration > HSM Partitions.
   • A registration takes the HSM Partition name (for example PART001) and its Setup Password. The password is exchanged for a permanent secret, and the secret is stored blinded in a data object on the Base Partition.
   • To use an existing partition, go to Administration > HSM Partitions and select Set up KMIP for the desired partition.
3. Assign the Partition to a KMIP client. This can only be done when you create it. Follow the Manage KMIP Clients tutorial to create a new client.
4. Restart the KMIP Server. Changes to the server configuration are only read at startup.

The Key Manager then adds the mapping to kmipserver.properties as primus.user.<client> and primus.password.<client> fields. Clients without an assignment fall back to the base partition.

From now on, when the KMIP Server receives a request from a KMIP client, it looks up which partition is assigned to this client. If it is different to the Base Partition, the KMIP Server logs into this additional partition on behalf of the client and executes the request on this partition.

Note that the separation only applies to the keys and objects of the clients. The global KMIP Server settings (such as partition login information, mTLS keystore and truststore, client registry) still remain on the Base Partition.

One HSM cluster

Multitenancy only works within an HSM cluster. A single KMIP Server can only serve partitions located on the same cluster as the Base Partition. Deploy multiple KMIP Servers if you have multiple HSM clusters (one server per cluster).