Regular setup: Using SKLM with a self-signed certificate

Follow the instructions in this subtopic to install and configure the IBM Security Key Lifecycle Manager (SKLM).

1. Install IBM Security Key Lifecycle Manager. For the supported versions, see Preparation for encryption. For the installation, choose a system that the IBM Storage Scale node that you want to configure has direct network access to. For information about installing SKLM, see the Installing and configuring chapter of the SKLM documentation.
2. From the main page of the SKLM web GUI, click Configuration > Key Serving Parameters and select the check box for Keep pending client device communication certificates.
3. Configure SKLM to have the same FIPS 140-2 (FIPS) setting as the IBM Storage Scale cluster.
   Follow these steps:
   1. Determine the FIPS setting of the cluster by entering the following command on the command line:

      mmlsconfig FIPS1402mode

      The command returns yes if the cluster complies with FIPS or no if not.
   2. On the SKLM server system, open the SKLMConfig.properties file.
      Note: The default location of the SKLMConfig.properties file depends on the operating system:

      • On AIX®, Linux®, and similar operating systems the directory is at the following location:

        • For GKLM 4.1.1 or later versions:

          /opt/IBM/WebSphere/Liberty/products/sklm/config/SKLMConfig.properties

        • For GKLM 4.1.0.1 and old supported SKLM versions:

          /opt/IBM/WebSphere/AppServer/products/sklm/config/SKLMConfig.properties
      • On Microsoft Windows, the directory is at the following location:

        • For GKLM 4.1.1 or later versions:

          Drive:\Program Files (x86)\IBM\WebSphere\Liberty\products\sklm\config\SKLMConfig.properties

        • For GKLM 4.1.0.1 and old supported SKLM versions:

          Drive:\Program Files (x86)\IBM\WebSphere\AppServer\products\sklm\config\SKLMConfig.properties
   3. Add or remove the following line from the SKLMConfig.properties file.
      Add the line to configure SKLM to comply with FIPS, or remove it to have SKLM not comply with FIPS.

      fips=on

4. Configure the SKLM server to have the same NIST SP800-131a (NIST) setting as the IBM Storage Scale cluster. Follow these steps:
   1. Determine the NIST setting of the cluster by entering the following command on the command line:

      mmlsconfig nistCompliance

      The command returns SP800-131A if the cluster complies with NIST or off if it is non-compliant.
   2. On the SKLM server system, open the SKLMConfig.properties file. For the location of this file, see the note in Step 3.
   3. Add the following line to configure SKLM to comply with NIST or remove it to configure SKLM not to comply with NIST:

      TransportListener.ssl.protocols=TLSv1.2

5. If the cipher suites are set at any time, SKLM 2.6.0.0 has a known issue that causes server certificates always to be signed with SHA1withRSA. To work around the problem, follow these steps:
   1. While the SKLM server is running, in the SKLMConfig.properties file, add or modify the requireSHA2Signatures property as follows:

      requireSHA2Signatures=true

   2. Do not restart the server.
   3. Generate a new server certificate and set it to be the one in use.
   4. If you restart the server, you must repeat this workaround before you can create a server certificate that is signed other than with SHA1withRSA.

Follow the instructions in this subtopic to create and export a server certificate in SKLM:

1. Create a self-signed server certificate:
   1. On the system where SKLM is running, open the graphical user interface.
   2. Click Configuration > SSL/KMIP.
   3. Click Create self-signed certificate.
   4. Enter the information for the certificate and click OK.
   5. Restart the server to verify that the server can operate with the new certificate.
2. Make a note of the label of the certificate that is in use:
   1. In the SKLM graphical user interface, click Advanced Configuration > Server Certificates.
   2. Select the certificate that is identified as being in use. Click Modify and make a note of the certificate label. You need it in Step 3.
3. Export the certificate through the command-line interface. Follow these steps:
   1. On the SKLM server system, open a command-line window.
   2. Change to the WAS_HOME/bin directory. The location of this directory depends on the operating system:
      • On AIX, Linux, and similar operating systems, the directory is at the following location:

        • For GKLM 4.1.1 and later versions:

          /opt/IBM/WebSphere/Liberty/bin

        • For GKLM 4.1.0.1 and old supported SKLM versions:

          /opt/IBM/WebSphere/AppServer/bin
      • On Microsoft Windows, the directory is at the following location:

        • For GKLM 4.1.1 and later versions:

          drive:\Program Files (x86)\IBM\WebSphere\Liberty\bin

        • For GKLM 4.1.0.1 and old supported SKLM versions:

          drive:\Program Files (x86)\IBM\WebSphere\AppServer\bin
   3. Enter the following command to start the command-line interface to SKLM:
      • On AIX, Linux, and similar operating systems:

        ./wsadmin.sh -username SKLMAdmin -password mypwd -lang jython

      • On Microsoft Windows:

        wsadmin -username SKLMAdmin -password mypwd -lang jython

   4. In the SKLM command line interface, enter the following command:

      print AdminTask.tklmCertList(’[-alias labelSSCert]')

      where:

      labelSSCert

      Specifies the certificate label of the self-signed server certificate. You made a note of the label in Step 2.

      SKLM responds with output like the following example:

      CTGKM0001I Command succeeded.
      uuid = CERTIFICATE-7005029a-831d-405f-af30-4bf0177909de
      alias = server
      key store name = defaultKeyStore
      key state = ACTIVE
      issuer name = CN=server
      subject name = CN=server
      creation date = 13/03/2014 16:27:13 Eastern Daylight Time
      expiration date = 09/03/2015 07:12:30 Eastern Daylight Time
      serial number = 1394363550

   5. Make a note of the UUID of the certificate that is displayed on line 2 of the output. You need it in the next substep and in Part 3.
   6. To export the certificate, from the SKLM command line interface, enter the following command on one line:

      print AdminTask.tklmCertExport(’[-uuid certUUID -format base64 -fileName fileName]’)

      where:

      certUUID

      Specifies the UUID that you made a note of in the previous substep.

      fileName

      Specifies the path and file name of the certificate file in which the server certificate is stored.

      SKLM exports the self-signed server certificate into the specified file.

   7. Close the SKLM command line interface.
   8. Copy the server certificate file to a temporary directory on the IBM Storage Scale node that you are configuring for encryption.
4. In SKLM, create a device group and keys for the IBM Storage Scale cluster:
   1. In the SKLM graphical user interface, click Advanced Configuration > Device Group.
   2. In the Device Group table, click Create.
   3. In the Create Device Group window, follow these steps:
      1. Select the GPFS device family.
      2. Enter an appropriate name, such as GPFS_Tenant0001. The name is case-sensitive.
      3. Make a note of the name. You need it in Part 3 when you create an RKM stanza.
      4. Complete any other fields and click Create.
   4. After SKLM creates the device group, it prompts you to add devices and keys. Do not add any devices or keys. Instead, click Close. Keys are created in the next step.
5. Create keys for the device group.
   1. In the SKLM graphical user interface, in the Key and Device Management table, select the device group that you created in Step 4. In these instructions the device group is named GPFS_Tenant0001.
   2. Click Go to > Manage keys and services.
   3. In the management page for GPFS_Tenant0001, click Add > Key.
   4. Enter the following information:
      • The number of keys to be created
      • The three-letter prefix for key names. The key names are internal SKLM names and are not used for GPFS encryption.
   5. Make a note of the UUID of the key, such as KEY-326a1906-be46-4983-a63e-29f005fb3a15. You need it in Part 3.
   6. In the drop-down list at the bottom of the page, select Hold new certificate requests pending my approval.

1. Create and configure a client keystore. Follow these steps:
   1. Create the following subdirectory to contain the client keystore:

      /var/mmfs/etc/RKMcerts

   2. The following command creates the client keystore, stores a private key and a client certificate in it, and also stores the trusted SKLM server certificate into it. From the command line, enter the following command on one line:

      mmauth gencert --cname clientName --cert serverCertFile --out /var/mmfs/etc/RKMcerts/SKLM.p12 
      --label clientCertLabel --pwd-file passwordFile

      where the parameters are as follows:

      --cname clientName

      The name of the client that is used in the certificate.

      --cert serverCertFile

      The path and file name of the file that contains the SKLM server certificate. You extracted this certificate from SKLM and copied the certificate file to the node in Part 2, Step 3(h).

      --out /var/mmfs/etc/RKMcerts/SKLM.p12

      The path and file name of the client keystore.

      --label clientCertLabel

      The label of the client certificate in the keystore. The label can be 1 - 20 characters in length.

      --pwd-file passwordFile

      The path of a text file that contains the password for the client keystore. The password can be 1 - 20 characters in length.

   Important: Verify that the files in the client keystore directory meet the requirements for security-sensitive files that are listed in the Requirements section at the beginning of this topic.
2. Create an RKM.conf file and add a stanza to it that describes a connection between a local key client, an SKLM device group, and an SKLM key server. Each stanza defines an RKM back end.
   1. Create a text file with the following path and name:

      /var/mmfs/etc/RKM.conf

      Important: Verify that the files in the client keystore directory meet the requirements for security-sensitive files that are listed in the Requirements section at the beginning of this topic.
   2. Add a stanza with the following format:

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

      where the rows of the stanza have the following meaning:

      stanzaName

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

      It is important to ensure that the RKM ID is unique among all RKM stanzas that are configured and no longer than 21 characters in length.

      type

      Always ISKLM.

      kmipServerUri

      The DNS name or IP address of the SKLM server and the KMIP SSL port. You can find this information on the main page of the SKLM graphic user interface. The default port is 5696.

      You can have multiple instances of this line, where the first instance represents the primary key server and each additional instance represents a backup key server. You can have up to five backup key servers. The following example has the primary key server and five backup key servers:

      stanzaName {
         type = ISKLM
         kmipServerUri = tls://raclette.zurich.ibm.com:5696
      
         kmipServerUri2 = tls://raclette.fondue2.ibm.com:5696
         kmipServerUri3 = tls://raclette.fondue3.ibm.com:5696
         kmipServerUri4 = tls://raclette.fondue4.ibm.com:5696
         kmipServerUri5 = tls://raclette.fondue5.ibm.com:5696
         kmipServerUri6 = tls://raclette.fondue6.ibm.com:5696
         keyStore = /var/mmfs/etc/RKMcerts/SKLM.p12
         passphrase = a_password
         clientCertLabel = a_label
         tenantName = GPFS_Tenant0001
      }
      

      If the GPFS daemon cannot get an encryption key from the primary key server, it tries the backup key servers in order.

      For more information, see the subtopics "RKM back ends" and "Adding backup RKM servers in a high-availability configuration" in the topic Preparation for encryption.

      keyStore

      The path and name of the client keystore. You specified this parameter in Step 1.

      passphrase

      The password of the client keystore and client certificate. You specified this parameter in Step 1.

      clientCertLabel

      The label of the client certificate in the client keystore. You specified this parameter in Step 1.

      tenantName

      The name of the SKLM device group. See Part 1: Installing Security Key Lifecycle Manager.

3. Copy the configuration files to the file system manager node:
   Warning: The mmchpolicy command in Step 5 fails if you omit this step. The mmchpolicy command requires the configuration files to be on the file system manager node.
   1. Copy the RKM.conf file from the /var/mmfs/etc directory to the same directory on the file system manager node.
   2. Copy the keystore files that the RKM file references to the same directories on the file system manager node. The recommended location for the keystore files is /var/mmfs/etc/RKMcerts/.
   Important: Verify that the files in the client keystore directory meet the requirements for security-sensitive files that are listed in the Requirements section at the beginning of this topic.
4. To configure other nodes in the cluster for encryption, copy the RKM.conf file and the keystore files to those nodes.
   Copy the files in the same way as you did in Step 3.

   Important: Verify that the files in the client keystore directory meet the requirements for security-sensitive files that are listed in the Requirements section at the beginning of this topic.
5. Install an encryption policy for the cluster:
   Note: You can do this step on any node to which you copied the configuration files.
   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(’KEY-326a1906-be46-4983-a63e-29f005fb3a15:SKLM_srv’)
      

      In the last line of the policy, 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 key that you created in the SKLM graphic user interface in Part 2.

      RkmID

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

   2. Install the policy rule with the mmchpolicy command.
      Trouble: If an encryption policy succeeds on one node but fails on another node in the same cluster, verify that the failing node has the correct client keystore and stanza.

      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.
6. Import the client certificate into the SKLM server:
   1. On the IBM Storage Scale node that you are configuring for encryption, send a KMIP request to SKLM.
      To send a KMIP request, try to create an encrypted file on the node. The attempt fails, but it causes SKLM to put the client certificate in a list of pending certificates in the SKLM key server. The attempt fails because SKLM does not yet trust the client certificate. See the following example:

      # touch /gpfs0/test
      touch: cannot touch `/gpfs0/test’: Permission denied
      # tail -n 2 /var/adm/ras/mmfs.log.latest
      Thu Mar 20 14:00:55.029 2014: [E] Unable to open encrypted file: inode 46088,
      Fileset fs1, File System gpfs0.
      Thu Mar 20 14:00:55.030 2014: [E] Error: key
      ’KEY-326a1906-be46-4983-a63e-29f005fb3a15:SKLM_srv’ could not be fetched (RKM
      reported error -1004).

   2. In the graphical user interface of SKLM, on the main page, click Pending client device communication certificates.
   3. Find the client certificate in the list and click View.
   4. Carefully check that the certificate that you are importing matches the one created in the previous step, then click Accept and Trust.
   5. On the resulting screen, provide a name for the certificate and click Accept and Trust again.
   6. On the node that you are configuring for encryption, try to create an encrypted file as you did in Step (a).
      This time the command succeeds. Enter an mmlsattr command to list the encryption attributes of the new file:

      # touch /gpfs0/test                                                            
      # mmlsattr -n gpfs.Encryption /gpfs0/test                                      
      file name: /gpfs0/test                                                         
      gpfs.Encryption: "EAGC????f?????????????? ??????w?^??>???????????? ?L4??       
      _-???V}f???X????,?G?<sH??0?)??M?????)?KEY-326a1906-be46-4983-a63e-29f005fb3a15?
      sklmsrv?)?KEY-6aaa3451-6a0c-4f2e-9f30-d443ff2ac7db?RKMKMIP3?"                 
      EncPar ’AES:256:XTS:FEK:HMACSHA512’                                            
      type: wrapped FEK WrpPar ’AES:KWRAP’ CmbPar ’XORHMACSHA512’                    
      KEY-326a1906-be46-4983-a63e-29f005fb3a15:sklmsrv                              
      

      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). You created the key in a device group in the SKLM server and included its UUID as part of a key name in the security rule.