Configuring encryption with the Thales CipherTrust Manager key server by using a local certificate authority

The following instructions describe how to configure the CipherTrust Manager key server to communicate with an IBM Storage Scale key client.

1. Configuring the KMIP interface.

   Interfaces are services that the CipherTrust Manager hosts. Since IBM Storage Scale uses the KMIP service, the server certificate on the KMIP interface must be configured.

   1. On the CipherTrust Manager window, click Access Management > Registration Tokens link. In the Create New Registration Token window, enter the token name and select the local Certificate Authority (CA).
   2. Click Create New Registration Token and click Copy to copy the generated registration token, click Add Token.
   3. To edit and configure the KMIP interface, complete the following steps:
      1. Open the CipherTrust Manager window, click Admin Settings > Interfaces.
      2. Expand the KMIP interface by clicking the ellipsis (...), then View/Edit.
      3. In the Configure KMIP page, select Auto Registration and paste the registration token.
      4. Select the mode as TLS, verify client cert, username taken from client cert, auth request is optional.
      5. Ensure that Username Location in Certificate is set to CN.
      6. Under Local Trusted CAs, ensure that the local CipherTrust Manager CA is selected, click Update.
2. Creating a key client certificate.
   A key client can request master encryption keys from the key server. The key client certificate must be signed by the same CA that signed the server certificate, in this case the CipherTrust Manager local CA. To generate a client certificate in CipherTrust Manager, complete the following steps:
   1. On the CipherTrust Manager window, click CA > Local. Click the name of the Local Certificate Authority to view its details.
   2. Click Issue Certificate.
   3. Enter the Display Name, Common Name, and other client certificate information. Make a note of the client’s common name (CN), it is needed in the further steps. Save the generated certificate sign request (CSR) and the private key.
   4. Click Issue Certificate. The newly generated client certificate appears in the list of certificates that are generated by the local CA.
   5. Expand the client certificate by clicking the ellipsis (...), then click Download, save the client certificate. The client certificate is needed in Part 3.
   6. Download the CipherTrust Manager local CA. On the CipherTrust Manager window, click CA > Local.
   7. Expand the local CA that is being used by clicking the ellipsis (...), then click Download, and then save the CA certificate chain. The certificate chain is needed in Part 3.
3. Adding the key client as a user in CipherTrust Manager.
   A user is an authenticated entity or a server where IBM Storage Scale is installed. The user can make KMIP calls to CipherTrust Manager to retrieve encryption keys. To create a user, complete the following steps:
   1. In the CipherTrust Manager window, click Access Management > Users > Create New User. The Username must be similar to the client’s common name (CN) specified when creating the client’s certificate.
   2. Click the newly created user and expand GROUPS. Search for Key Users and Key Admins groups and add the user.
4. Creating and updating an encryption key.
   IBM Storage Scale 5.1.4 or later supports maximum 65 characters for the Universally Unique Identifier (UUID) of an encryption key. By default, CipherTrust Manager creates keys with 65 characters UUIDs. Complete the following steps to create a key with 65 characters UUID.
   1. In the CipherTrust Manager window, click Keys > Create New Key.
   2. Enter the key name and other information and client on the Create window.
   3. The key ID is displayed. Copy the key ID to use in the IBM Storage Scale encryption policy in Part 3.

   IBM Storage Scale 5.1.3 or earlier supports maximum 60 characters for the Universally Unique Identifier (UUID) of an encryption key. Complete the following steps to create a key with 60 characters UUID:

   1. On the CipherTrust Manager window, click API to open the API Playground.
   2. Click Authenticate. Specify the admin username and password, then click Post. The session is valid for 300 seconds.
   3. On the sidebar, search for Keys, then click Create - Post.
   4. In the body section, specify a key UUID length of 60 characters, for example:

      {
      “name”: “ScaleKey”
      "idSize" : 60
      }

   5. Click POST to create the key.
   6. The key ID is displayed. Copy the key ID to use in the IBM Storage Scale encryption policy in Part 3.
   Updating the key attributes.
   1. On the CipherTrust Manager window, select Keys and click the newly created key.
   2. Ensure that Exportable option is checked.
   3. Expand KEY ACCESS and add the newly created user as the Key Owner.

1. Copy the CA chain, the client certificate, and private key files generated in Part 1, Step 1 from CipherTrust Manager to the IBM Storage Scale node.
2. CipherTrust Manager generates the client private key in the Elliptic Curve (EC) format. IBM Storage Scale 5.1.5 or later supports an EC private key to generate the client keystore. When running IBM Storage Scale 5.1.4 or earlier, convert the EC private key format into the PKCS8 format, for example:

   openssl pkcs8 -topk8 -nocrypt -in EC_privFile -out privFile

3. Create a PKCS#12 keystore to store the certificate and private key of the client in it. Issue the following command in a single line:

   mmgskkm store --cert scaleclient.cert --priv scaleclient.priv --chain CA_chain.pem --label client --pwd clientpassword --out ctmclient.p12

   where:

   --cert certFile

   Specifies the client certificate file that is created in Part 1, Step 2.

   --priv privFile

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

   --label label

   Specifies the label under which the private key is stored in the keystore. Use a common name that was used when you created the client in CipherTrust Manager.

   --pwd pwd

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

   --out keystore

   The file name of the keystore.

   In the following example, the current directory contains the client credentials and the CA chain from Part 1, Step 2:

   mmgskkm store --cert scaleclient.cert --priv scaleclient.priv --chain CA_chain.pem --label client --pwd clientpassword --out ctmclient.p12
   

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

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

1. Create an RKM.conf file and add a remote key management (RKM) stanza to it. The stanza contains the necessary information to communicate with the CipherTrust Manager 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://ctmServer1.ibm.com:5696
         keyStore = /var/mmfs/etc/RKMcerts/ctmClient.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: ctmServer1_ctmClient.

      type

      Always KMIP for the CipherTrust Manager server.

      kmipServerUri

      The DNS name or IP address of the CipherTrust Manager and the CipherTrust Manager SSL port. Multiple kmipServerUri entries can be added for high-availability (HA).

      keyStore

      The path and name of the client keystore from step 3 in part 2.

      passphrase

      The password of the client keystore and client certificate from step 3 in part 2.

      clientCertLabel

      The label of the client certificate in the client keystore from step 3 in part 2.

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 of a 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):

      Note: Make sure to enclose in single quotation marks (') each parameter that you define in the policy, as shown in the next example.

      RULE 'p1' SET POOL 'system' 
      RULE 'Encrypt all files in file system with rule E1'
      SET ENCRYPTION 'E1'
      WHERE NAME LIKE '%'
      RULE 'simpleEncRule' ENCRYPTION 'E1' IS
      ALGO 'DEFAULTNISTSP800131AFAST'
      KEYS('5c62fa7fb9e2e5670f4fb63b18ee2ab73b8c5ea9a5ff206338d2f8025ce9:ctmServer1_ctmClient')
      

      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 CipherTrust Manager window or the API Playground in Part 1.

      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 by issuing 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 by using the mmlspolicy command. Add the new statements to the file and install the contents of the file with the mmchpolicy command.
   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) that corresponds to the matching encryption rule.

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 CipherTrust Manager server.
     • 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 encrypted files are accessible on one node and inaccessible 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.

1. Install multiple CipherTrust Manager servers. To create a high-availability cluster, perform the following steps on the primary CipherTrust Manager server:
   1. Open CipherTrust Manager window, select Admin Settings > Cluster.
   2. Click Manage cluster and select Add cluster.
   3. Enter the primary server’s private and/or public IP addresses and click Save.
   4. To add backup servers to the cluster, click Manage cluster > Add node and specify the backup server information.
   5. Follow the prompt to log in to the backup server and join the cluster.
   6. Repeat steps d and e for each backup server.
   For more information, see CipherTrust Manager Administration Guide.
2. Update the RKM.conf file to list the backup CipherTrust Manager servers under the keyword kmipServerUri2,kmipServerUri3, as shown in the following example:

   ctmServer1_ctmClient {
      type = KMIP
      kmipServerUri = tls://ctmServer1.ibm.com:5696
      kmipServerUri2 = tls://ctmServer2.ibm.com:5696
      kmipServerUri3 = tls://ctmServer3.ibm.com:5696
      keyStore = /var/mmfs/etc/RKMcerts/ctmClient.p12
      passphrase = a_password
      clientCertLabel = a_label
   }