mrhsm init

Creates the KMIP token and initializes the KMIP configuration for first use.

Use the mrhsm init command to create the KMIP token for the first time and initialize the KMIP configuration. On successful initialization, the command creates the KMIP token that is used for authentication and communication with the external KMIP key store. In addition, the command generates a random user PIN used to encrypt the KMIP configuration in /opt/mapr/conf/tokens/mrhsm.conf.

Syntax

mrhsm init 
  [ -cacert <ca-cert> ]     Path to KMIP server CA certificate in PEM format
  [ -clientcert <cert> ]    Path to client certificate in PEM format
  [ -clientkey <key> ]      Path to client private key in PEM format
  [ -ip <ip1,ip2,...> ]     Comma-separated list of KMIP server IP addresses
  [ -kmipversion <version>] KMIP version: 1.0, 1.1, 1.2, 1.3, or 1.4. Default: 1.1
  -label <text>             Defines the label of the object or the token.
  [ -storetype file|kmip ]  Store type. Default: kmip
  [ -port <kmip-port> ]     KMIP port number. Default is 5696
  -sopin <so-pin>           PIN for SO (Security Officer)

Parameters

The list of parameters are as follows. Only the PKCS#11 label and SO PIN are required; you can configure the remainder later using the mrhsm set command.

IMPORTANT
Other than the KMIP port number and version which have default values, you must configure all parameters before you use the mrhsm enable command to establish a connection to the KMIP server and initialize it.
cacert
The full or relative path name of the CA certificate chain in PEM format used to sign the KMIP server certificate. The Data Fabric KMIP client enforces peer validation and requires the CA certificate chain to verify the KMIP server. At the minimum, the root CA certificate is required. If an intermediate CA is used to sign the KMIP server certificate, then this file must contain all the certificates in the chain starting from the root CA certificate in PEM format.

Refer to the KMIP Integration Guide for the respective KMIP server (Utimaco ESKM Integration Guide, Gemalto SafeNet KeySecure Key Manager Integration Guide, or Vormetric Data Security Manager (DSM) Integration Guide) for instructions on how to obtain the CA certificate chain.

clientcert
The full or relative path name of the CA certificate chain in PEM format used to sign the KMIP server certificate. The Data Fabric KMIP client enforces peer validation and requires the CA certificate chain to verify the KMIP server. At the minimum, the root CA certificate is required. If an intermediate CA is used to sign the KMIP server certificate, then this file must contain all the certificates in the chain starting from the root CA certificate in PEM format.

Refer to the KMIP Integration Guide for the respective KMIP server (Utimaco ESKM Integration Guide, Gemalto SafeNet KeySecure Key Manager Integration Guide, or Vormetric Data Security Manager (DSM) Integration Guide) for instructions on how to obtain the client certificate.

clientkey

The full or relative path name of the client private key used to generate the client CSR.

Refer to the KMIP Integration Guide for the respective KMIP server (Utimaco ESKM Integration Guide, Gemalto SafeNet KeySecure Key Manager Integration Guide, or Vormetric Data Security Manager (DSM) Integration Guide) for instructions on how to obtain the client private key.

ip
A comma-separated list of host names or IP addresses of KMIP servers. Most KMIP deployments have at least two KMIP servers in the HSM cluster for reliability and high availability. The Data Fabric KMIP client cycles through each KMIP server in the list in a round-robin manner until an accessible server is reached.
kmipversion

The KMIP version to use when communicating with the external KMIP -enabled key management appliance. Supported values are 1.0, 1.1, 1.2, 1.3 and 1.4

Refer to the vendor-specific documentation for information about the KMIP versions they support. At present, set this value to 1.1 for SafeNet KeySecure. Utimaco ESKM and Vormetric DSM should work with all Data Fabric supported KMIP versions. Default value is 1.1.

storetype
A descriptor for the type of object store. Beginning with release 7.0.0, possible values are file and kmip. The default store type is set to kmip. The file option designates a file-based object store.
Note these considerations:
  • The -ip, -port, -cacert, -clientcert, -clientkey, and -kmipversion options do not apply to file-based stores. Specifying any of these options with the -storetype file option results in an error.
  • The mrhsm init should be invoked only once per node, regardless of whether the file or kmip store type is used. Subsequent configuration changes should be performed using mrhsm set.
  • Specifying -storetype file in mrhsm init sets the objectstore.backend parameter in the mrhsm configuration file ${MAPR_HOME}/conf/maprhsm.conf to a value of file.
label
An ASCII string which defines the label of the object or the token. The maximum length is 32 characters.
port
The listening port number of the KMIP server. All KMIP servers in the HSM cluster must listen to the same port. Port numbers must be from 1-65535 inclusive and cannot start with a 0.

Default is 5696.

sopin
The PIN for the Security Officer. If not specified in the command line, a prompt will be displayed to enter the SO PIN.

Example

The following code demonstrates an example of a sample session.

# mrhsm init -label "Utimaco ESKM"
Slot 0 has a free/uninitialized token.
Enter SO PIN (4-255 characters): ********
Please reenter SO PIN: ********
Generated random user PIN Ve%h*tz^G7Qev@8