Integration via KMIP

HSM supports the KMIP protocol(Key Management Interoperability Protocol) in version 1.4 with the following profiles:

Baseline Server
Symmetric Key Lifecycle Server
Symmetric Key Foundry Server
Asymmetric Key Lifecycle Server
Basic Cryptographic Server
Advanced Cryptographic Server

The port used is TCP 5696.

Message encoding must use the TTLV(Tag, Type, Length, Value) scheme. As described in the specification, this scheme is designed to minimize the use of CPU cycles and memory in the clients that encode and decode KMIP messages, as well as generating an optimized alignment for 32-bit and 64-bit processors. Minimizing bandwidth usage on the transport mechanism is a secondary concern.

To establish a KMIP session over TLS, the user who owns the partition in the HSM must be configured for TFA ( Two Factor Authentication) using x.509 certificates.

Info

The configuration details of the KMIP client with HSM address and port settings, certificate and key file paths, HSM user credentials and more must be done in accordance with the documentation provided by the manufacturer or developer of the KMIP client software.

Some requirements are necessary:

file with the user's private key (e.g: rsa2k.pem), for use by client KMIP.
file with the user's X.509 certificate (e.g: rsa2k_cert.pem), for use by client KMIP and HSM.
file with the TLS certificate of HSM (e.g: hsm_cert.pem), for use by client KMIP.

The generation of the user's private key and X.509 certificate files is outside this scope.

The TLS certificate of HSM (server KMIP) can be obtained using the hsmcon:

Download the HSM certificate

hsmcon 127.0.0.1 -g hsm_cert.pem

Info

HSM generates a new self-signed TLS certificate at each reboot when it is not configured with a specific key-certificate pair.

HSM does not work with asynchronous responses (from the point of view of the protocol and the session). The same connection is maintained throughout the process.

To prepare the HSM user for use by the KMIP software, follow the steps below.

Edit the user attributes to use TFA.

User attributes menu

Dinamo - Remote Management Console v. 4.7.33.52 2018 (c) Dinamo Networks

HSM 127.0.0.1 e - Engine 5.0.28.0 (DCD) - TCA0000000  - ID master

Users - Attributes

User ID: ukmip

Type                 - Operator
Blocked              - no
Partition MxN auth   - no
Two Factor Auth      - no

Change:
1 - Type
2 - Block
3 - Two Factor Authentication
0 - Main Menu
Option : 3_

Indicate the x.509 file that will be used.

The KMIP client must also have access to the private key corresponding to the x.509 certificate provided.

Set of user attributes with TFA X.509

Dinamo - Remote Management Console v. 4.7.33.52 2018 (c) Dinamo Networks

HSM 127.0.0.1 e - Engine 5.0.28.0 (DCD) - TCA0000000  - ID master

Users - Attributes

User ID: ukmip

Set Two Factor Authentication (y/[n]): y

Type:
1 - OATH OTP Event
2 - OATH OTP Time
3 - X.509
Option : 3

X.509 input file (local) : rsa2k_cert.pem

Two Factor Authentication for user  'ukmip' successfully set.

Press ENTER key to continue...

Test user access to the HSM using TFA with the certificate.

The user's private key file must be available.
Access to user HSM with TFA X.509
```
hsmcon 127.0.0.1 ukmip -pri rsa2k.pem -pri_cer rsa2k_cert.pem -hsm_cer hsm_cert.pem
```

Batch operation

In section 6.4 of the KMIP document the field Unique Batch Item ID is defined as OPTIONAL and section 7.2, Table 283 - Request Batch Item Structure this item is defined as REQUIRED when Batch Count > 1.

If the KMIP client communicates with the HSM does not adhere to this requirement of the standard will receive the error code MISSING-DATA in the answer.

Attention

Note: some versions of the PyKMIP client implementation are known to have this flaw.