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 the HSM. - file with the HSM's TLS certificate (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.

HSM's TLS certificate (server KMIP) can be obtained using the hsmcon:

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.

1. Edit the user attributes to use TFA.

   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_
   

2. 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.

   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...
   

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

   The user's private key file must be available.

   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 communicating with the HSM does not adhere to this requirement of the standard, it will receive an error code MISSING-DATA in the answer.

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