Configuring encryption with the Thales Vormetric DSM key server

Follow the procedure shown. If you are using certificates for the client that are signed by a certificate authority (CA), skip Step 1 and go to Step 2.

1. On the IBM Storage Scale node that you are configuring for encryption, run the mmgskkm command to create the client credentials. Issue the following command on one line:

   /usr/lpp/mmfs/bin/mmgskkm gen --prefix prefix --cname cname --pwd pwd --fips fips --nist nist
       --days valid_days --keylen keylen

   where:

   --prefix prefix

   Specifies the path and file name prefix of the directory where the output files are generated. For example, if you want directory /var/mmfs/etc/RKMcerts to contain the output files, and you want the output files to have the prefix kcVormetric, you can specify the parameter as follows:

   --prefix /var/mmfs/etc/RKMcerts/kcVormetric

   --cname cname

   Specifies the name of the IBM Storage Scale key client. Valid characters are alphanumeric characters, hyphen (-), and period (.). The name can be up to 54 characters long. In DSM, names are not case-sensitive but avoid the use of uppercase letters. For more information, see the DSM documentation.

   --pwd pwd

   Specifies the password for the private key that this command creates.

   --fips fips

   Specifies whether the key client complies with FIPS 140. Specify on or off.

   --nist nist

   Specifies whether the key client complies with NIST SP800-131a. Specify on or off.

   --validdays validdays

   Specifies the number of days that the client certificate is valid.

   --keylen keylen

   Specifies the length in bits of the RSA key that is generated.

   In the following example, the current directory is the output directory. Enter the command on one line:

   /usr/lpp/mmfs/bin/mmgskkm gen --prefix kcVormetric --cname kcVormetric --pwd pwpkVormetric
       --fips off --nist on --days 180 --keylen 2048

   The output files are a client certificate, a private key, and a public key. For example,

   • kcVormetric.cert
   • kcVormetric.priv
   • kcVormetric.pub
2. Issue the mmgskkm command to create a PKCS#12 keystore and to store the certificate and private key of the client in it.
   Note: The input files must follow the specified format as shown in the following list:

   • The certificates and private key must be in PEM base64 encoded format.
   • The client private key must be unencrypted.
   • The chain file must contain the CA root certificate, one or more CA intermediate certificates, and the CA end-point certificate. It must not contain the client certificate.
   If you are using the certificate and private file from Step 1, issue the command with the following parameters:

   /usr/lpp/mmfs/bin/mmgskkm store --cert certFile --priv privFile --label label 
   --pwd pwd --out keystore

   If you are using a certificate chain that is signed by a CA and the certificates are concatenated in a single file, issue the command with the following parameters:

   /usr/lpp/mmfs/bin/mmgskkm store --cert certFile --priv privFile  --chain CACertChainFile 
    --label label --pwd pwd --out keystore

   If you are using a certificate signed by a CA and the certificates are in separate files with the same file prefix, issue the command with the following parameters:

   /usr/lpp/mmfs/bin/mmgskkm store --cert certFile --priv privFile  --prefix CACertFilesPrefix 
    --label label --pwd pwd --out keystore

   The parameters have the same meanings across all three forms of the command:

   --cert certFile

   Specifies the client certificate file that you created in Step 1 or the client certificate file that is signed by the CA.

   --priv privFile

   Species the private key file that you created in Step 1 or that matches the client certificate that is signed by the CA.

   --chain CACertChainFile

   Specifies the CA certificate chain file, which contains the CA certificate chain that was used to sign the client certificate. The chain starts with the CA root certificate, continues with any intermediate CA certificates in order, and ends with CA certificate that signed the client certificate. All the certificates are in base64 encoded PEM format. On UNIX-like systems, you can create such a file by concatenating the CA certificates that you received or downloaded from the CA into a single file with the cat command.

   --prefix CACertFilesPrefix

   Specifies the full path prefix of the CA certificates that are used to sign the client certificate. The CA certificate files must have the format <CACertFilesPrefix><n>.cert, where CACertFilesPrefix is the full path prefix for the CA certificate files, such as /tmp/CA/certfiles, and <n> is a CA certificate index. The index is 0 for the CA root certificate and n - 1 for the last intermediate CA certificate that signed the client certificate.

   --label label

   Specifies the label under which the private key is stored in the keystore.

   --pwd pwd

   Specifies the password of the keystore. You can use the same password that you specified for the private key in Step 1.

   --out keystore

   The file name of the keystore.

   The output of the command is a client keystore that contains the private key of the client and the certificate or certificate chain of the client.
   In the following example, the current directory contains the client credentials from Step 1. The command is on one line:

   mmgskkm store --cert kcVormetric.cert --priv kcVormetric.priv --label lapkVormetric
       --pwd pwpkVormetric --out ksVormetric.keystore

   In the following example, the current directory contains the client certificate, the private key, and the client certificate chain. The command is on one line:

   mmgskkm store --cert kcVormetric.cert --priv kcVormetric.key --chain CACertChain.pem --label lapkVormetric 
   --pwd pwpkVormetric --out ksVormetric.keystore

   In the following example, the current directory contains the client certificate, the private key file, and the files in the certificate chain. The certificate files have the format /tmp/CACert<n>.cert, where <n> is the index of the CA certificate in the certificate chain, starting with 0 for the CA root certificate. The command is on one line:

   mmgskkm store --cert kcVormetric.cert --priv kcVormetric.key --prefix /tmp/CACert --label lapkVormetric 
   --pwd pwpkVormetric --out ksVormetric.keystore

   In all three examples, the output file is the client keystore ksVormetric.keystore, which contains the client credentials.

   Important: The keystore must be record-locked when the GPFS daemon starts. If the keystore files are stored on an NFS mount, the encryption initialization process can hang. The cause is a bug that affects the way NFS handles record locking. If you encounter this problem, upgrade your version of NFS or store your keystore file on a local file system. If an upgrade is not possible and no local file system is available, use a RAM drive to store the keystore files.
3. Retrieve the certificate chain of the DSM server.
   Note: Before you can do this next step, you must install the DSM server, set up the DSM networking configuration, and set up the server certificate. If you do not, then you might not be able to connect to the DSM server or you might retrieve an invalid, default certificate chain.

   Note: DSM does not support the use of imported server certificate chains for the TLS communication on the KMIP port. You must create and use a server certificate chain that is signed by the DSM internal certificate authority (CA).

   Enter the following command on one line:

   /usr/lpp/mmfs/bin/mmsklmconfig restcert --host host --port port --prefix prefix --keystore keystore 
       --keypass keypass --fips fips --nist nist

   where:

   --host host

   Specifies the name or IP address of the remote system where the DSM server is running.

   --port port

   Specifies the port on the remote system for communicating with the DSM server (default 8445).

   --prefix prefix

   Specifies the path and file name prefix of the directory where the files in the certificate chain are stored. For example, if you want to store the certificate chain in the directory /var/mmfs/etc/RKMcerts, and you want the certificate files to have the prefix DSMServer, you can specify the parameter as follows:

   --prefix /var/mmfs/etc/RKMcerts/DSMServer

   --keystore keystore

   Specifies the path and file name of the client keystore that you created in Step 2.

   --keypass keypass

   Specifies a text file that contains the password of the client keystore as the first line. You must create this text file. Store the password that you provided in Step 2.

   --fips fips

   Specifies whether the key client complies with FIPS 140. Specify on or off.

   --nist nist

   Specifies whether the key client complies with NIST SP800-131a. Specify on or off.

   In the following example, the current directory contains the client keystore that was created in Step 2. Enter the command on one line:

   /usr/lpp/mmfs/bin/mmsklmconfig restcert --host hostVormetric --port 8445 --prefix DSM
        --keystore ksVormetric.keystore --keypass keypass --fips off --nist on

   The command connects to the DSM server, retrieves the server certificate chain, and stores each certificate into a separate local file in Base64-encoded DER format. Each file name has the format prefixN.cert, where prefix is the prefix that you specified in the command and N is a digit that begins at 0 and increases by 1 for each certificate in the chain, as in the following example:

   • DSM0.cert
   • DSM1.cert
4. Verify that the SHA-256 fingerprint in each retrieved certificate matches the fingerprint of the DSM server:
   1. To display the details of each certificate, enter the following sequence at the client command line, where prefix is the prefix that you provided in Step 3:

      for c in prefix*.cert; do /usr/lpp/mmfs/bin/mmgskkm print --cert $c; done

   2. Log in to the graphical user interface of the DSM server and display its SHA-256 fingerprint.
   3. Verify that the fingerprints in the certificates match the fingerprint in the DSM server.

5. Add the certificates to the PKCS#12 keystore of the key client as trusted certificates. Enter the following command on one line:

   /usr/lpp/mmfs/bin/mmgskkm trust --prefix prefix --pwd pwd --out keystore --label serverLabel 
       --fips fips --nist nist

   where:

   --prefix prefix

   Specifies the prefix that you specified in Step 3.

   --pwd pwd

   Specifies the password of the client keystore, which you provided in Step 3.

   --out keystore

   Specifies the path name of the keystore of the key client.

   --label serverLabel

   Specifies the label under which the server certificate chain is stored in the client keystore.

   --fips fips

   Specifies whether the key client complies with FIPS 140. Specify on or off.

   --nist nist

   Specifies whether the key client complies with NIST SP800-131a. Specify on or off.

   In the following example, the current directory contains the client keystore and the certificate chain. Enter the following command on one line:

   /usr/lpp/mmfs/bin/mmgskkm trust --prefix DSM --pwd pwpkVormetric --out ksVormetric.keystore
       --label laccVormetric --fips off --nist on

1. Install a Key Management Interoperability Protocol (KMIP)-enabled license in DSM.
   Important: You must complete this step before you create a DSM domain. For security reasons, you cannot create a KMIP-enabled domain in DSM until you install a KMIP-enabled license. For example, you cannot create a regular domain, install a KMIP-enabled license, and then convert the domain to a KMIP-enabled domain.
   1. On the DSM Management Console, click System > License.
   2. Select a KMIP-enabled license that you obtained from DSM.
   3. Click Upload License File.
   The license is installed.
2. Create a DSM domain.
   1. On the DSM Management Console, click Domains > Manage Domains.
   2. Follow the instructions to create a domain. Make sure that you configure the domain as KMIP Supported.
3. Create a Domain and Security Administrator for the new domain.
   Note: In these instructions, a single Domain and Security Administrator is created who combines the responsibilities of administering the domain and controlling its security. For security reasons, you might want to create a Domain Administrator and a Security Administrator as separate roles. For more information, see the DSM documentation.
   1. Log in as the DSM System Administrator. On the Management Console, click Administrators.
   2. On the Administrators page, click Add.
   3. In the Add Administrator window, complete all the input fields except the RSA User ID field. In the User Type field, click Domain and Security Administrator.
      Note: The passwords are temporary. The new administrator must enter a new password on the first login to the DSM Management Console.
   4. Click OK.
   5. Limit the scope of the administrator's control to the domain that you created in Step 2.
4. Add the client CA certificates to the DSM trust store.

   If the client KMIP certificate is self-signed, this step is not required and you can skip to the Step 5, "Add a host to the domain".

   If the client KMIP certificate was signed by a CA, import the CA certificates that signed the client certificate to the DSM trust store. You must add all the CA certificates in the chain including the CA root certificate:

   1. Log in to DSM as Admin.
   2. Navigate to Settings > KMIP Trusted CA Certificates > Browse.
   3. Select the CA certificate file to import. The file can contain the entire certificate chain.

5. Add a host to the domain.
   1. Log in as the new administrator:
      1. Enter a password when prompted.
      2. Select I am a local domain administrator.
      3. Enter or select the domain name from Step 2.
   2. On the Management Console, click Hosts > Hosts.
   3. On the Hosts screen, click Add to add a KMIP host. Set the Host Name to the name that you specified for the key client (the value for the cname parameter) when you created the client credentials in Part 1. In these instructions, the key client name is kcVormetric.
   4. In the list of hosts, select the host that you created in the previous step. Click Import KMIP Cert.
      If no Import KMIP Cert button is displayed, verify that the DSM license is KMIP-enabled and that you created the domain after you installed the KMIP-enabled license.
   5. In the window that opens, go through the directories of the IBM Storage Scale node to the directory that contains the client certificate file. Select the certificate file.
6. Create one or more keys for the client to use as master encryption keys (MEKs).
   The substeps in this step depend on the version of DSM that is installed:

   • For DSM 5.2.3 or any version of DSM that is later than 5.2.3 and earlier than 6.0.2, follow these steps:
     1. From the DSM Management Console page, click Keys > Key Templates.. Follow the DSM instructions to create a key template. Select AES256 as the key algorithm.
     2. Create a key from the template. Specify a name for the key and then select the template.
     3. Make a note of the UUID of the key. You need it in Part 3.

   • For DSM 6.2 and later, follow these steps:
     1. On the DSM Management Console page, click Keys > KMIP Objects.
     2. On the KMIP Objects page, click Add to create a new key.
     3. On the Create KMIP Key window, enter a name for the key and select AES_256 as the key type.
     4. Click OK to close the window. The new key is added to the list of KMIP objects at the bottom of the KMIP Objects page.
     5. Make a note of the UUID of the key. You need it in Part 3.

1. Create an RKM.conf file and add a remote key management (RKM) stanza to it that contains the information that is necessary to communicate with the DSM key server.
   1. On the IBM Storage Scale node, create a text file with the following path and name:

      /var/mmfs/etc/RKM.conf

   2. Add a stanza with the following format:

      stanzaName {
         type = KMIP
         kmipServerUri = tls://raclette.zurich.ibm.com:5696
         keyStore = /var/mmfs/etc/RKMcerts/ksVormetricDMS.p12
         passphrase = a_password
         clientCertLabel = a_label
      }
      

      where the rows of the stanza have the following meanings:

      stanzaName

      A name (RKM ID) for the stanza. Make a note of the name: you need it in the next step.

      It is a good practice to use a format like the following one to ensure that the RKM ID is unique:

      keyServerName_keyClientName

      where keyClientName is the key client name from Part 1, Step 1. For example, the RKM ID for the key server and key client in these instructions is: raclette_kcVormetric.

      type

      Always KMIP for the DSM server.

      kmipServerUri

      The DNS name or IP address of the DSM server and the DSM SSL port. Multiple kmipServerUri entries may be added for high availability (HA), but note that the DSM servers must then be configured in an active-active setup. In the regular DSM HA setup, the passive failover nodes do not serve keys over KMIP. For more information, consult the DSM documentation.

      keyStore

      The path and name of the client keystore from Part 1.

      passphrase

      The password of the client keystore and client certificate from Part 1.

      clientCertLabel

      The label of the client certificate in the client keystore from Part 1.

2. Set up an encryption policy on the node that you are configuring for encryption.
   1. Create a policy that instructs GPFS to do the encryption tasks that you want.
      The following policy is an example policy. It instructs IBM Storage Scale to encrypt all files in the file system with a file encryption key (FEK) and to wrap the FEK with a master encryption key (MEK):

      RULE ’p1’ SET POOL ’system’ /* one placement rule is required at all times */
      RULE ’Encrypt all files in file system with rule E1’
      SET ENCRYPTION ’E1’
      WHERE NAME LIKE ’%’
      RULE ’simpleEncRule’ ENCRYPTION ’E1’ IS
      ALGO ’DEFAULTNISTSP800131A’
      KEYS('01-10:raclette_kcVormetric')
      

      In the last line, the character string within single quotation marks (') is the key name. A key name is a compound of two parts in the following format:

      KeyID:RkmID

      where:

      KeyID

      Specifies the UUID of the master encryption key that you created in the DSM Management Console in Part 2.

      RkmID

      Specifies the name of the RKM stanza that you created in the /var/mmfs/etc/RKM.conf file in Step 1.

   2. Install the policy rule with the mmchpolicy command.
      CAUTION:

      Installing a new policy with the mmchpolicy command removes all the statements in the previous policy. To add statements to an existing policy without deleting the previous contents, collect all policy statements for the file system into one file. Add the new statements to the file and install the contents of the file with the mmchpolicy command.
   From now on, the encryption policy rule causes each newly created file to be encrypted with a file encryption key (FEK) that is wrapped in a master encryption key (MEK).

1. To replicate an encryption configuration on another node, you must copy some configuration files from the configured node to the target node:
   1. Copy the /var/mmfs/etc/RKM.conf file to the same directory on the target node.
   2. Copy the keystore files that the RKM file references to the same directories on the target node. The recommended location for the keystore files on the configured node is /var/mmfs/etc/RKMcerts/.
2. To create a different encryption configuration on another node, follow the steps that are described in the preceding subtopics. Note the following design points:
   • On a single node:
     • The RKM.conf file can contain multiple stanzas. Each stanza represents a connection between a key client and a DSM host.
     • You can create multiple keystores.
   • Across different nodes:
     • The contents of RKM.conf files can be different.
     • The contents of keystores can be different.
     • If an encryption policy succeeds on one node and fails on another in the same cluster, verify that the failing node has the correct client keystore and stanza.
       Remember: All nodes that mount a file system need to be able to access all the keys used in that file system.