Configuring encryption with the Vormetric DSM key server

Follow these steps:

1. On the IBM Spectrum Scale node that you are configuring for encryption, run the mmgskkm command to create the client credentials. Enter 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 Spectrum Scale key client. Valid characters are alphanumeric characters, hyphen (-), and period (.). The name can be up to 54 characters long. In Vormetric DSM, names are not case-sensitive, so the use of uppercase letters is not recommended. For more information, see the Vormetric 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-2. 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. Run the mmgskkm command again to create a PKCS#12 keystore and to store the certificate and private key of the client in it. Enter the following command on one line:

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

   where:

   --cert certFile

   Specifies the client certificate file that you created in Step 1.

   --priv privFile

   Species the private key file that you created in Step 1.

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

   In the following example, the current directory contains the client credentials from Step 1. The command is entered on one line:

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

   The output file is a keystore that contains the client credentials of the key client:

   • ksVormetric.keystore
   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 Vormetric DSM server.
   Note: Before you can do this next step, you must install the Vormetric 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 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 pwdfile 
       --keypass keypass --fips fips --nist nist

   where:

   --host host

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

   --port port

   Specifies the port on the remote system for communicating with the Vormetric 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 pwdFile

   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-2. 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/mmssklmconfig restcert --host hostVormetric --port 8445 --prefix DSM
        --keystore ksVormetric.keystore --keypass pwdFile --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
   • DSM2.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 labelServer 
       --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-2. 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/mmssklmconfig 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 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 Spectrum Scale node to the directory that contains the client certificate file. Select the certificate file.
5. Create one or more keys for the client to use as master encryption keys (MEKs).
   1. From the DSM Management Console, click Keys > Key Templates. Follow the 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.

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 Vormetric DSM key server.
   1. On the IBM Spectrum 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 Vormetric 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 Vormetric 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 Spectrum 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 filesystem 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.