Simplified setup: Using SKLM with a self-signed certificate

Learn how to configure IBM® Security Key Lifecycle Manager (SKLM) in the simplified setup when you use a self-signed server certificate rather than a certificate chain from a certificate authority (CA).

This topic describes the simplified method for setting up encryption with SKLM as the key server and with a self-signed certificate on the KMIP port of the RKM server. For more information about the simplified setup, see the topic Preparation for encryption.

Note: IBM Storage Scale supports IBM Security Guardium Key Lifecycle Manager (GKLM) 4.1.0.1 (IF01), 4.1.1, or later. The older versions of GKLM are referred to as IBM Security Lifecycle Manager or SKLM in the documentation. The configuration information is the same for both GKLM and SKLM.

If your deployment scenario uses a chain of certificates from a certificate authority rather than a self-signed certificate, see one of the following topics:

The simplified setup with SKLM requires IBM Storage Scale Advanced Edition, IBM Storage Scale Data Management Edition, or IBM Storage Scale Developer Edition or IBM Storage Scale Erasure Code Edition 4.2.1 or later and a supported version of SKLM. For more information, see Preparation for encryption.

Note: If you are using SKLM 2.7 or later, see the topic Configuring encryption with SKLM 2.7 or later.

Requirements:

The following requirements must be met on every IBM Storage Scale node that participates in encryption:

The node must have direct network access to the system where the key server is installed.
The security-sensitive files that are created during the configuration process must have the following characteristics:
- They must be regular files that are owned by the root user.
- The group ownership must be changed to root group.
- They must be readable and writable only by the user (mode '0600'). See the following examples:
```
-rw-------. 1 root root 2454 Mar 20 10:32 /var/mmfs/ssl/keyServ/RKM.conf
drw-------. 2 root root 4096 Mar 20 11:15 /var/mmfs/ssl/keyServ/
-rw-------. 1 root root 3988 Mar 20 11:15 /var/mmfs/ssl/keyServ/keystore_name.p12
```
  Note: In the simplified setup, the mmkeyserv command sets the permission bits automatically.
These security-sensitive files include the following files:
- The RKM.conf file. For more information about this file, see The RKM.conf file and the RKM stanza.
- The files in the client keystore directory, which include the keystore file, the public and private key files for the client, and possibly other files. For more information about these files, see The client keystore directory and its files.
  Note: In the simplified setup, the mmkeyserv command automatically creates and distributes the RKM.conf files and the files in the client keystore directory to every node in the cluster. The files are located in the following directory on each node:
```
 /var/mmfs/ssl/keyServ
```
CAUTION:
- Take appropriate precautions to ensure that the security-sensitive files are not lost or corrupted. IBM Storage Scale does not manage or replicate the files.
- Ensure that the passphrase for the client certificate file is not leaked through other means, such as the shell history.
Client keystore files 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.

The setup procedure is greatly simplified by the use of the mmkeyserv command, which automates many of the tasks that must be done manually in the regular setup:

Creating and configuring client credentials.
Creating a device group and master encryption keys in the RKM server.
Creating and updating RKM.conf configuration files.
Retrieving server certificates from the RKM server and storing them in client keystores.
Propagating configuration information and client credentials to every node in the cluster.

See the following subtopics for instructions:

Part 1: Installing and configuring SKLM
Part 2: Configuring the cluster for encryption
Part 3: Adding a node to the cluster

Part 1: Installing and configuring SKLM

Follow the instructions in this subtopic to install and configure SKLM on the RKM server.

Install SKLM. For more information, see Preparation for encryption.
For information about installing SKLM, see the Installing chapter of the SKLM documentation.
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.
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 issuing the following command:
```
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. Find the following line in the SKLMConfig.properties file:
```
fips=on
```
  or
```
fips=off
```
  If the line is not present in the file, then add it. Set the value to on to configure SKLM to comply with FIPS, or set it to off to configure SKLM not to comply with FIPS.
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 issuing the following command:
```
mmlsconfig nistCompliance
```
  The command returns SP800-131A if the cluster complies with NIST or off if not.
2. On the SKLM server system, open the SKLMConfig.properties file. For the location of this file, see the note in Step 3.
3. Find the line in the SKLMConfig.properties file that begins with the following phrase:
```
TransportListener.ssl.protocols=
```
  If the line is not present in the file, then add it. To configure SKLM to comply with NIST, set the value as it is shown below:
```
TransportListener.ssl.protocols=TLSv1.2
```
  To configure SKLM not to comply with NIST, set the value as it is shown below:
```
TransportListener.ssl.protocols=SSL_TLS
```
Configure IBM WebSphere® Application Server so that it has the same NIST setting as the IBM Storage Scale cluster.
See the topic Transitioning WebSphere Application Server to the SP800-131 security standard in the volume WebSphere Application Server Network Deployment in the WebSphere Application Server online documentation.
- WebSphere Application Server can be configured to run SP800-131 in a transition mode or a strict mode. The strict mode is recommended.
- When NIST is enabled, make sure that WebSphere Application Server certificate size is at least 2048 bytes and is signed with SHA256withRSA as described in the preceding link.
If the cipher suites were 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, 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.
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.

Part 2: Configuring the cluster for encryption

Gather the following information:

The logon password of the SKLMAdmin administrator
The certificate chain of the SKLM server (optional)

The following table provides a high-level overview of the configuration process. The steps in the table correspond to the steps in the procedure that begins immediately after the table.

Table 1. Configuring the cluster for encryption in the simplified setup
Step	Actions
1	Verify the direct network connection between the IBM Storage Scale node and the SKLM server.
2	Add the SKLM key server to the configuration.
3	Add a tenant to the key server.
4	Create a key client.
5	Register the key client to the tenant.
6	Create a master encryption key in the tenant.
7	Set up an encryption policy in the cluster.
8	Test the encryption policy.

Verify that the IBM Storage Scale node that you are working from has a direct network connection to the RKM server.

Add the RKM server to the encryption configuration:

Use the mmkeyserv server add command to add the SKLM server to the encryption configuration. Depending on how SKLM is configured, you might also need to specify a port number for connecting with SKLM:
- If SKLM is configured to use its default REST port for communications with its clients, you do not need to specify a port number when you add the server. Issue a command like the following one:
```
mmkeyserv server add ServerName
```
  where:
  - ServerName is the host name or IP address of the SKLM key server that you want to add.
  When no port number is specified, IBM Storage Scale automatically tries to connect with SKLM through the default REST port number of each of the supported versions of SKLM serially, starting with the earliest version, until it finds a successful connection with SKLM.
  Note: The default REST port number depends on the version of SKLM that is installed on the RKM server. For more information, see Firewall recommendations for IBM SKLM.
- If SKLM is not configured to use its default REST port number, you must specify the correct port number when you add the server. Issue a command like the following one:
```
mmkeyserv server add ServerName --port RestPortNumber
```
  where:
  - ServerName is the host name or IP address of the SKLM key server that you want to add.
  - RestPortNumber is the port number that SKLM uses to connect with its clients.
  If you do not specify a port number or if you specify an incorrect port number, IBM Storage Scale fails to connect with SKLM and displays an error message. For more information see the description of the --port parameter in mmkeyserv command.

Respond to the prompts from the mmkeyserv server add command. See the example output and prompts in the figure that follows:

Enter the SKLM administrator password when prompted.
To view the certificate chain of the SKLM server, enter view when prompted.
Verify that the certificates that are displayed have the same contents as the certificates in the chain that you downloaded from SKLM.
Enter yes to trust the certificates or no to reject them.

If you trust the certificates, the command adds the RKM server to the encryption configuration. In the following listing, key server keyserver01 is added:

Figure 1. Example listing for mmkeyserv server add

# mmkeyserv server add keyserver01
Enter password for the key server keyserver01:
The security certificate(s) from keyserver01.gpfs.net must be accepted to continue.  View the
certificate(s) to determine whether you want to trust the certifying authority.
Do you want to view or trust the certificate(s)? (view/yes/no) view

Serial number:          01022a8adf20f3
SHA-256 digest:         2ca4a48a3038f37d430162be8827d91eb584e98f5b3809047ef4a1c72e15fc4c
Signature:              7f0312e7be18efd72c9d8f37dbb832724859ba4bb5827c230e2161473e0753b367ed49d
993505bd23858541475de8e021e0930725abbd3d25b71edc8fc3de20b7c2db5cd4e865f41c7c410c1d710acf222e1c4
5189108e40568ddcbeb21094264da60a1d96711015a7951eb2655363309d790ab44ee7b26adf8385e2c210b8268c5ae
de5f82f268554a6fc22ece6efeee2a6264706e71416a0dbe8c39ceacd86054d7cc34dda4fffea4605c037d321290556
10821af85dd9819a4d7e4baa70c51addcda720d33bc9f8bbde6d292c028b2f525a0275ebea968c26f8f0c4b604719ae
3b04e71ed7a8188cd6adf68764374b29c91df3d101a941bf8b7189485ad72
Signature algorithm:    SHA256WithRSASignature
Key size:               2048
Issuer:                 C=US, O=IBM, OU=SKLMNode, SKLMCell, Root Certificate, CN=c40bbc1xn3.gpfs.net
Subject:                C=US, O=IBM, OU=SKLMNode, SKLMCell, CN=c40bbc1xn3.gpfs.net

Serial number:          01022a24475466
SHA-256 digest:         077c3b53c5046aa893b760c11cca3a993efbc729479771e03791f9ed4f716879
Signature:              227b5befe89f2e55ef628da6b50db1ab842095a54e1505655e3d95fee753a7f7554868a
a79b294c503dc34562cf69c2a20128796758838968565c0812c4aedbb0543d396646a269c02bf4c5ce5acba4409a10e
ffbd47ca38ce492698e2dcdc8390b9ae3f4a47c23ee3045ff0145218668f35a63edac68201789ed0db6e5c170f5c6db
49769f0b4c9a5f208746e4342294c447793ed087fa0ac762588faf420febeb3fca411e4e725bd46476e1f9f44759a69
6573af5dbbc9553218c7083c80440f2e542bf56cc5cc18156cce05efd6c2e5fea2b886c5c1e262c10af18b13ccf38c3
533ba025b97bbe62f271545b2ab5c1f50c1dca45ce504dfcfc257362e9b43
Signature algorithm:    SHA256WithRSASignature
Key size:               2048
Issuer:                 C=US, O=IBM, OU=SKLMNode, SKLMCell, Root Certificate, CN=c40bbc1xn3.gpfs.net
Subject:                C=US, O=IBM, OU=SKLMNode, SKLMCell, Root Certificate, CN=c40bbc1xn3.gpfs.net

Do you trust the certificate(s) above? (yes/no) yes

Issue the mmkeyserv server show command to verify that the key server is added. The following listing shows that keyserver01 is created:

# mmkeyserv server show
keyserver01
    Type:                         ISKLM
    Hostname:                     keyserver01.gpfs.net
    User ID:                      SKLMAdmin
    REST port:                    9080
    Label:                        1_keyserver01
    NIST:                         on
    FIPS1402:                     off
    Backup Key Servers:
    Distribute:                   yes
    Retrieval Timeout:            120
    Retrieval Retry:              3
    Retrieval Interval:           10000
    REST Certificate Expiration:  2033-05-18 17:01:24 (-0400)
    KMIP Certificate Expiration:  2021-05-22 22:24:54 (-0400)

Issue the mmkeyserv tenant add command to add a tenant to the key server. The command creates the tenant on the SKLM server if it does not exist.
A tenant is an entity on the SKLM server that can contain encryption keys and certificates. SKLM uses the term device group instead of tenant.
1. Issue the following command to add tenant devG1 to key server keyserver01. Enter the SKLM administrator password when prompted:
```
# mmkeyserv tenant add devG1 --server keyserver01
Enter password for the key server keyserver01:
```
2. Issue the mmkeyserv tenant show command to verify that the tenant is added. The following listing shows that tenant devG1 is added to keyserver01:
```
# mmkeyserv tenant show
devG1
    Key Server:      keyserver01.gpfs.net
    Registered Client:  (none)
```
Issue the mmkeyserv client create command to create a key client. A key client can request master encryption keys from a tenant after it is registered to the tenant. The command creates a client keystore on the node from which the command is issued and puts into the keystore a set of client credentials and the certificate chain of the SKLM server. The command then copies the keystore to all the nodes in the cluster. The keystore is stored in the following directory on each node of the cluster:
```
/var/mmfs/ssl/keyServ
```
1. Issue the following command to create key client c1Client1 for key server keyserver01. Enter the SKLM administrator password and a passphrase for the new keystore when prompted:
```
# mmkeyserv client create c1Client1 --server keyserver01
Enter password for the key server keyserver01:
Create a pass phrase for keystore:
Confirm your pass phrase:
```
  Alternatively, issue the following command to create key client c1Client1 for key server keyserver01 using a user-provided, CA-signed certificate. The client certificate file is client1CertFile.cert, the client's key file is client1PrivFile.pem, and the CA chain file is CACertChain.pem. Enter the SKLM administrator password and a passphrase for the new keystore when prompted:
```
# mmkeyserv client create c1Client1 --server keyserver01 -cert client1CertFile.cert 
 --priv client1PrivFile.pem --ca-chain CACertChain.pem
Enter password for the key server keyserver01:
Create a pass phrase for keystore:
Confirm your pass phrase:
```
  There are three elements to using external certificates:
  - A CA-signed certificate file, which certifies the client's identity.
  - A private key file that matches the client's certificate.
  - The certificate chain of the CA that signed the client certificate.
  All these elements must be provided to the mmkeyserv command to establish trust in the client's identity and to use it to create a secure connection with the SKLM server. The certificates must be in PEM-encoded x509 format, and the content of the private key file must be PEM-encoded and unencrypted.
  The CA certificate chain can be used either as individual files, one file for each CA certificate in the chain, or as a chain file that contains all the CA certificates:
  - To create a chain file, concatenate all the CA certificates from the certificate authority into a single file. The file must begin with the CA root certificate, continue with the intermediate CA certificates in the order in which they are used, and end with the CA certificate that signed the client certificate.
  - To use the CA certificates as individual files, copy them to a temporary location and rename each file using 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.
  In the following example, the chain consists of a CA root certificate file and two intermediate CA certificate files. The full path prefix is /tmp/CA/certfiles:
  CA root certificate /tmp/CA/certfiles.0.cert
  
  First intermediate CA root certificate: /tmp/CA/certfiles.1.cert
  
  Second intermediate CA root certificate: /tmp/CA/certfiles.2.cert
  
  Issue the following command to create key client c1Client1 for key server keyserver01:
```
# mmkeyserv client create c1Client1 --server keyserver01 --cert client1CertFile.cert --priv client1PrivFile.pem --ca-cert /tmp/CA/certfiles
Enter password for the key server keyserver01:
Create a pass phrase for keystore:
Confirm your pass phrase:
```
2. Issue the mmkeyserv client show command to verify that the key client is created. The Certificate Type attribute is set to user-provided if the client was created with a CA-signed certificate or to system-generated if the client was created with a self-signed certificate that was generated by IBM Storage Scale.
  In the following example, the output shows that key client c1Client1 was created for remote key server keyserver01.gpfs.net and that the client certificate is a system-generated, self-signed certificate:
```
# mmkeyserv client show
c1Client1
  Label: c1Client1
  Key Server: keyserver01.gpfs.net
  Tenants: (none)
  Certificate Expiration: 2023-03-11 00:01:03 (-0500)
  Certificate Type:        system-generated
```
  In the following example, the output shows that key client c1Client1 was created with a user-provided, CA-signed certificate:
```
# mmkeyserv client show
c1Client1
  Label: c1Client1
  Key Server: keyserver01.gpfs.net
  Tenants: (none)
  Certificate Expiration: 2023-03-11 00:01:03 (-0500)
  Certificate Type:        user-provided
```
Issue the mmkeyserv client register command to register the key client with the tenant:
You must provide a remote key management (RKM) ID as an input for this command. The RKM ID will become the identifier field of a new RKM stanza that describes the connection between this key client, this tenant, and this key server. For more information about the RKM stanza, see The RKM.conf file and the RKM stanza.

It is a good practice to use a format like the following one to ensure that the RKM ID is unique:
```
keyServerName_tenantName
```
For example, the RKM ID for the key server and the tenant in these instructions is keyserver01_devG1.
1. Issue the following command to register key client c1Client1with tenant devG1 under RKM ID keyserver01_devG1. Enter the requested information when prompted:
```
# mmkeyserv client register c1Client1 --tenant devG1 --rkm-id keyserver01_devG1
Enter password for the key server:

mmkeyserv: [I] Client currently does not have access to the key.  Continue the registration
    process ...
mmkeyserv: Successfully accepted client certificate
```
2. Issue the command mmkeyserv tenant show to verify that the key client is known to the tenant.
  The following listing shows that tenant devG1 lists c1Client1 as a registered client:
```
mmkeyserv tenant show
devG1
    Key Server:      keyserver01.gpfs.net
    Registered Client:  c1Client1
```
3. You can also issue the command mmkeyserv client show to verify that the tenant is known to the client.
  The following listing shows that client c1Client1 is registered with tenant devG1:
```
# mmkeyserv client show
c1Client1
    Label:                   c1Client1
    Key Server:              keyserver01.gpfs.net
    Tenants:                 devG1
    Certificate Expiration:  2023-03-11 00:01:03 (-0500)
```
4. To see the contents of the RKM stanza, issue the mmkeyserv rkm show command.
  In the following listing, notice that the RKM ID of the stanza is keyserver01_devG1, the string that was specified in Step 5(a):
```
# mmkeyserv rkm show
keyserver01_devG1 {
type = ISKLM
kmipServerUri = tls://192.0.2.59:5696
keyStore = /var/mmfs/ssl/keyServ/serverKmip.1_keyserver01.c1Client1.1.p12
passphrase = pw4c1Client1
clientCertLabel = c1Client1
tenantName = devG1
}
```
5. You can also see the RKM stanza by displaying the contents of the RKM.conf file on the node:
```
# cat /var/mmfs/ssl/keyServ/RKM.conf
keyserver01_devG1 {
  type = ISKLM
  kmipServerUri = tls://192.0.2.59:5696
  keyStore = /var/mmfs/ssl/keyServ/serverKmip.1_keyserver01.c1Client1.1.p12
  passphrase = pw4c1Client1
  clientCertLabel = c1Client1
  tenantName = devG1
}
```
Issue the mmkeyserv key create command to create a master encryption key in the tenant. The following command creates a master encryption key in tenant devG1 of server keyserver01.gpfs.net.
The command displays the UUID of the encryption key (not the key value itself) at line 3 of the listing:
```
# mmkeyserv key create --server keyserver01.gpfs.net --tenant devG1
Enter password for the key server keyserver01.gpfs.net:
KEY-d4e83148-e827-4f54-8e5b-5e1b5cc66de1
```
Set up an encryption policy on the node.
1. Create a file management policy that instructs GPFS to do the encryption tasks that you want.
  The following example policy 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-d4e83148-e827-4f54-8e5b-5e1b5cc66de1:keyserver01_devG1')
```
  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 Step 6.
  
  RkmID
  
  Specifies the RKM ID that you specified in Step 5(a).
2. Issue the mmchpolicy command to install the rule.
  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.
  1. Issue the following command to install the policy rules in file enc.pol for file system c1FileSystem1:
```
# mmchpolicy c1FileSystem1 /tmp/enc.pol
Validated policy `enc.pol': Parsed 3 policy rules.
Policy `enc.pol' installed and broadcast to all nodes.
```
  2. You can list the new encryption policy with the following command:
```
# mmlspolicy c1FileSystem1 -L
```

Test the new encryption policy:

Create a file in the file system c1FileSystem1:
```
# echo 'Hello World!' >/c1FilesSystem1/hw.enc
```
The policy engine detects the new file, encrypts it, and wraps the file encryption key in a master encryption key.

To verify that the file hw.enc is encrypted, issue the following command to display the encryption attribute of the file.

The output shows that the file is encrypted:

# mmlsattr -n gpfs.Encryption /c1Filesystem1/hw.enc
file name:          /c1Filesystem1/hw.enc
gpfs.Encryption:    "EAGC????.?????????????? ??????h????????????????? ?u?~?}????????????t??lN??
'k???*?3??C???#?)?KEY-ef07b465-cfa5-4476-9f63-544e4b3cc119?NewGlobal11?"
EncPar 'AES:256:XTS:FEK:HMACSHA512'
    type: wrapped FEK  WrpPar 'AES:KWRAP'  CmbPar 'XORHMACSHA512'
        KEY-d4e83148-e827-4f54-8e5b-5e1b5cc66de1:keyserver01_devG1

Part 3: Adding a node to the cluster

When you add a node to a cluster that is configured for encryption by the simplified setup, the cluster automatically detects the new node and copies the encryption configuration to it. For other requirements, see the Requirements section earlier in this topic.