Renewing expired server certificates

Follow these instructions to renew expired server certificates for the simplified setup, the regular setup, and certificate chains.

See the following topics for detailed instructions:

Creating a server certificate

The steps for creating a new server certificate to replace one that is expired are similar to the steps for creating an initial server certificate. Follow the instructions in the documentation of your Remote Key Manager (RKM), which must be one of the following products:
  • IBM® Security Key Lifecycle Manager (SKLM)
  • Thales Vormetric Data Security Manager (DSM)
For more information, see Establishing an encryption-enabled environment.

Simplified setup: Trusting a new self-signed SKLM server certificate

These instructions assume that you are using the simplified setup method and that you have created a self-signed SKLM server certificate.
  1. Find the name of the key server object that needs to be updated. To display a list of the available key server objects, issue the following command on the IBM Spectrum Scale command line: 
    mmkeyserv server show
  2. Issue the following command to update the server certificate of the key server object: 
    mmkeyserv server update <serverName>
    The variable <serverName> is the name of the key server object that you want to update.
  3. Enter the SKLMAdmin administrator password when prompted.
  4. Enter yes to trust the SKLM REST certificate.
The key server object is updated with the self-signed server certificate.

Simplified setup: Trusting a new SKLM server certificate chain

These instructions assume that you are using the simplified setup method and you have a certificate chain from a CA. The certificate chain contains a renewed intermediate certificate or a renewed root certificate. For information about obtaining a certificate chain from a CA, see the subtopic Part 2: Configuring SKLM in Simplified setup: Using SKLM with a certificate chain.
  1. Find the name of the key server object that needs to be updated. To display a list of the available key server objects, issue the following command on the IBM Spectrum Scale command line: 
    mmkeyserv server show
  2. Set up the files in the certificate chain by performing the following steps:
    1. Copy the files for the new server certificate chain into the same directory.
    2. Rename each certificate file with the same prefix, followed by a numeral that indicates the order of the certificate in the chain, followed by the file extension .cert. Start the numbering with 0 for the root certificate. For example, if the chain consists of three certificate files and the prefix is sklmChain, rename the files as follows:
      sklmChain0.cert
sklmChain1.cert
sklmChain2.cert

      If the certificate chain contains more than three certificate files, combine the intermediate files into one certificate file, set the numeral in the name of the combined certificate file to 1, and set the numeral in the name of the endpoint certificate file to 2. For example, the certificate chain contains four certificate files: sklmChain0.cert, sklmChain1.cert, sklmChain2.cert, and sklmChain3.cert.

  3. Issue the following command to update the server certificate of the key server object: 
    mmkeyserv server update <serverName> --kmip-cert sklmChain

    The variable <serverName> is the name of the key server object that you want to update.

  4. Enter the SKLMAdmin administrator password when prompted.
  5. Enter yes to trust the certificate chain.

Simplified setup: Trusting a new SKLM WebSphere Application Server certificate

These instructions assume that you are using the simplified setup method with IBM WebSphere® Application Server and SKLM.
  1. The simplified setup communicates with SKLM on both the KMIP port and the REST administration port.
    On the REST port, the server certificate is the one that is configured in WebSphere Application Server. SKLM runs on WebSphere Application Server.
  2. Find the name of the IBM Spectrum Scale key server object that is associated with SKLM on the REST port. To see a list of key server objects, issue the following command: 
    mmkeyserv server show
  3. Issue the following command to update the key server object with the new WebSphere Application Server certificate: 
    mmkeyserv server update <serverName>
    The variable <serverName> is the name of the key server object that you want to update.
  4. Enter the SKLMAdmin administrator password when prompted.
  5. Enter yes to trust the SKLM REST certificate.
The IBM Spectrum Scale client now trusts the new SKLM WebSphere Application Server certificate.

Regular setup: Trusting a new self-signed SKLM server certificate

Follow these instructions if you are using IBM Spectrum Scale v4.1.1 or later. These instructions assume that you are using SKLM and the regular setup method and that you have created a self-signed SKLM server certificate.
  1. Get information about the key client from the /var/mmfs/etc/RKM.conf file:
    1. Open the file and find the RKM stanza for the key client that you want to configure.
    2. Make a note of the following information from the RKM stanza:
      • The password for the client keystore and client certificate, which is specified by the passphrase term. You need this information for Step 2.
      • The path and file name of the client keystore, which is specified by the keyStore term. You need this information for Step 3.
  2. Store the client keystore password from Step 1 into a text file, such as /root/keystore.pwd, that is accessible only by the root user.
  3. Issue the mmsklmconfig command to retrieve the new self-signed SKLM server certificate. This command is available in IBM Spectrum Scale v4.2.1 and later.
    The command connects to the KMIP port, waits for the TLS handshake, and retrieves the certificate that the server presents.
    mmsklmconfig restcert --host <sklmhost> --port <kmipport>
--prefix <sklmChain> --keystore <rkmKeystore>
--keypass <rkmPassfile> --fips <fips> --nist <nist>
    The command specifies the following parameters:
    --host <sklmhost>
    Is the IP address or host name of the RKM server.
    --port <kmipport>
    Is the KMIP port number of the SKLM server. The default value is 5696.
    --prefix <sklmChain>
    Is the path and file name prefix where the server certificate files are to be stored.
    --keystore <rkmKeystore>
    Is the path and file name of the client keystore from Step 1.
    --keypass <rkmPassfile>
    Is the path and file name of the keystore password file from Step 2.
    --fips <fips>
    Indicates whether the IBM Spectrum Scale cluster is using FIPS 140-2-compliant cryptographic modules. Valid values are on or off. Enter the following command to determine the state:
    mmlsconfig FIPS1402mode
    --nist <nist>
    Indicates whether the IBM Spectrum Scale cluster is using encryption that is in compliance with NIST SP800-131A recommendations. Valid values are on or off. Enter the following command to determine the state:
    mmlsconfig nistCompliance
  4. Optional: Display the contents of the retrieved server certificate file and verify that the information matches the information in the new server certificate on the RKM server.
    The mmgskkm command is available in IBM Spectrum Scale v4.2.1 and later. Issue the following command:
    mmgskkm print --cert sklmChain0.cert
    where sklmChain is the path and file name prefix of the certificate files. You specified this prefix in Step 3.
  5. Issue the following command to add the retrieved server certificate to the client keystore:
    The mmgskkm command is available in IBM Spectrum Scale v4.2.1 and later.
    mmgskkm trust --prefix <sklmChain> --out <rkmKeystore> --pwd-file <rkmPassfile> 
--label <serverLabel>
    The command specifies the following parameters:
    --prefix <sklmChain>
    Is the path and file name prefix of the server certificate files. You specified this prefix in Step 3.
    --out <rkmKeystore>
    Is the path and file name of the client keystore from Step 1.
    --pwd-file <rkmPassfile>
    Is the path and file name of the client keystore password file that you created in Step 2.
    --label <serverLabel>
    Is the label under which to store the server certificate in the client keystore.
    Note: The label must be unique in the keystore. In particular, it cannot be the label of the expired server certificate from the SKLM key server.
  6. Copy the updated client keystore file to all the nodes in the IBM Spectrum Scale cluster.
  7. Reload the new client keystore by one of the following methods:
    • On any administration node in the cluster, run the mmchpolicy command to refresh the current policy rules. You do not need to repeat this action on other nodes in the cluster.
    • On each node of the cluster, unmount and mount the file system.
    • In IBM Spectrum Scale v4.2.1 and later, issue the following command on each node of the cluster:
      /usr/lpp/mmfs/bin/tsloadikm run
The IBM Spectrum Scale client now trusts the new self-signed SKLM server certificate.

Trusting a new endpoint server certificate in a server certificate chain

These instructions assume that the certificate chain includes a root certificate that is signed by a certificate authority (CA), zero or more intermediate certificates, and an endpoint certificate.
  1. If only the endpoint certificate expired and was renewed, you do not need to take any further action on the client side.
    This situation occurs, for example, in DSM when you renew an endpoint certificate by running the gencert command.
  2. If an intermediate certificate or the root certificate expired and was renewed, follow the instructions in one of the following two subtopics:

Regular setup: Trusting a new SKLM server certificate chain

These instructions assume that you are using SKLM and the regular setup method and that you have a certificate chain from a CA. The certificate chain contains a renewed intermediate certificate or a renewed root certificate. For information about obtaining a certificate chain from a CA, see the subtopic "Part 2: Configuring SKLM" in Regular setup: Using SKLM with a certificate chain.
  1. Get the path and password of the keystore file of the key client that you are configuring:
    1. Open the /var/mmfs/etc/RKM.conf file and find the RKM stanza of the key client .
    2. Make a note of the following items:
      • The password for the client keystore and client certificate, which is specified by the passphrase term. You need this information for Step 2.
      • The path and file name of the client keystore, which is specified by the keyStore term. You need this information for Step 5.
  2. Store the client keystore password from Step 1 into a text file, such as /root/keystore.pwd, that is accessible only by the root user.
  3. Set up the files in the certificate chain:
    1. Copy the files for the new server certificate chain into the same directory in which the keystore.pwd file is located.
    2. Rename each certificate file with the same prefix, followed by a numeral that indicates the order of the certificate in the chain, followed by the file extension .cert. Start the numbering with 0 for the root certificate. For example, if the chain consists of three certificate files and the prefix is sklmChain, rename the files as follows: 
      sklmChain0.cert
sklmChain1.cert
sklmChain2.cert
      If the certificate chain contains more than three certificate files, combine the intermediate files into one certificate file, set the numeral in the name of the combined certificate file to 1, and set the numeral in the name of the endpoint certificate file to 2. For example, suppose that the certificate chain contains four certificate files: sklmChain0.cert, sklmChain1.cert, sklmChain2.cert, and sklmChain3.cert. Modify the certificate files in the following way:
      • The sklmChain0.cert file needs no changes.
      • Combine sklmChain1.cert and sklmChain2.cert into one file and name it sklmChain1.cert.
      • Rename sklmChain3.cert to sklmChain2.cert.
      Important: If you have not already done so, save the files of the certificate chain to a secure location. Include the root certificate file, any intermediate certificate files, and the endpoint certificate file. Now, when a client certificate expires, you will not need to download the certificate chain from the server again. You can add your local copy of the files in the server certificate chain to the new client keystore. For more information, see Renewing expired client certificates.
  4. Optional: You can verify the server certificate chain by issuing the openssl verify command. The command has the following usage: 
    openssl verify -CAfile <rootCaCert> [-untrusted <intermediateCaCerts>] <endpointCert>
    where:
    -CAfile <rootCaCert>
    Specifies the root certificate file.
    -untrusted <intermediateCaCerts>
    Specifies the file that contains the intermediate certificates. If the chain has more than one intermediate certificate, you must combine them into a single file. If the chain has no intermediate certificates, omit this parameter.
    <endpointCert>
    Specifies the endpoint certificate file.
    For example, if your server certificate chain consists of the three sample files that are listed in Step 3, issue the following command:
    openssl verify -CAfile /root/sklmChain0.cert -untrusted /root/sklmChain1.cert /root/sklmChain2.cert
  5. Issue the following command to add the new SKLM server certificate chain to the keystore.
    The mmgskkm command is available in IBM Spectrum Scale v4.2.1 and later.
    mmgskkm trust --prefix <sklmChain> --out <keystore> --pwd-file <pwd-file> 
--label <serverLabel>
    where:
    --prefix <sklmChain>
    Is the path and file name prefix of the certificate chain files that you set up in Step 3, such as /root/sklmChain.
    --out <keystore>
    Is the path and file name of the client keystore from Step 1.
    --pwd-file <pwd-file>
    Is the path and file name prefix of the keystore password file that you created in Step 2.
    --label <serverLabel>
    Is the label under which to store the server certificate in the client keystore.
    Note: The label must be unique in the keystore. Also, it cannot be the label of the expired server certificate from the SKLM key server.
  6. Copy the updated client keystore to all nodes in the IBM Spectrum Scale cluster.
  7. Reload the new client keystore by one of the following methods:
    • On any administration node in the cluster, run the mmchpolicy command to refresh the current policy rules. You do not need to repeat this action on other nodes in the cluster.
    • On each node of the cluster, unmount and mount the file system.
    • In IBM Spectrum Scale v4.2.1 and later, issue the following command on each node of the cluster:
      /usr/lpp/mmfs/bin/tsloadikm run
The IBM Spectrum Scale client now trusts the new SKLM server certificate chain.

Trusting a new DSM server certificate chain

These instructions assume that you are using DSM and that you have a DSM certificate chain that you renewed by running the security genca command.
  1. Get the path and password of the keystore file of the key client that you are configuring:
    1. Open the /var/mmfs/etc/RKM.conf file and find the RKM stanza of the key client.
    2. Make a note of the following items:
      • The password for the client keystore and client certificate, which is specified by the passphrase term. You need this information for Step 2.
      • The path and file name of the client keystore, which is specified by the keyStore term. You need this information for Step 5.
  2. Store the client keystore password from Step 1 into a text file, such as /root/keystore.pwd, that is accessible only by the root user.
  3. Issue the mmsklmconfig command to retrieve the new self-signed DSM server certificate chain. This command is available in IBM Spectrum Scale v4.2.1 and later.
    The command connects to the KMIP port, waits for the TLS handshake, and retrieves the certificate that the server presents.
    mmsklmconfig restcert --host <dsmhost> --port <dsmport>
--prefix <dsmChain> --keystore <rkmKeystore>
--keypass <rkmPassfile> --fips <fips> --nist <nist>
    The command specifies the following parameters:
    --host <dsmhost>
    Is the IP address or host name of the DSM server.
    --port <dsmport>
    Is the port number of the DSM web GUI. The default value is 8445.
    --prefix <sklmChain>
    Is the path and file name prefix where the server certificate files are to be stored.
    --keystore <rkmKeystore>
    Is the path and file name of the client keystore from Step 1.
    --keypass <rkmPassfile>
    Is the path and file name of the keystore password file from Step 2.
    --fips <fips>
    Indicates whether the IBM Spectrum Scale cluster is using FIPS 140-2-compliant cryptographic modules. Valid values are on or off. Enter the following command to determine the state:
    mmlsconfig FIPS1402mode
    --nist <nist>
    Indicates whether the IBM Spectrum Scale cluster is using encryption that is in compliance with NIST SP800-131A recommendations. Valid values are on or off. Enter the following command to determine the state:
    mmlsconfig nistCompliance
    DSM server certificate chain: The DSM server certificate chain typically consists of two certificates, a DSM internal root CA certificate and an endpoint certificate. The names of certificate files that you retrieve in this step have the following format: the path and file name prefix that you specify in the --prefix parameter, followed by a 0 for the root certificate or a 1 for the endpoint certificate, followed by the suffix .cert. In the following example, the prefix is /root/dsmChain:
    /root/dsmChain0.cert
/root/dsmChain1.cert
  4. Optional: Display the contents of the retrieved server certificate files and verify that the information matches the information in the new server certificate on the DSM server.
    The mmgskkm command is available in IBM Spectrum Scale v4.2.1 and later. Issue the following commands:
    mmgskkm print --cert <dsmChain>0.cert
mmgskkm print --cert <dsmChain>1.cert
    where dsmChain is the path and file name prefix of the certificate files that you retrieved in Step 3.
  5. Issue the following command to add the new DSM server certificate chain to the client keystore.
    The mmgskkm command is available in IBM Spectrum Scale v4.2.1 and later. 
    mmgskkm trust --prefix <dsmChain> --out <rkmKeystore> --pwd-file <rkmPassfile> 
--label <serverLabel>
    The command has the following parameters:
    --prefix <dsmChain>
    Is the path and file name prefix of the certificate chain files that you retrieved in Step 3, such as /root/dsmChain.
    --out <rkmKeystore>
    Is the path and file name of the client keystore from Step 1.
    --pwd-file <rkmPassfile>
    Is the path and file name prefix of the keystore password file that you created in Step 2.
    --label <serverLabel>
    Is the label under which to store the server certificate in the client keystore.
    Note: The label must be unique in the keystore. Also, it cannot be the label of the expired server certificate from the DSM key server.
  6. Copy the updated client keystore to all nodes in the IBM Spectrum Scale cluster.
  7. Reload the new client keystore by one of the following methods:
    • On any administration node in the cluster, run the mmchpolicy command to refresh the current policy rules. You do not need to repeat this action on other nodes in the cluster.
    • On each node of the cluster, unmount and mount the file system
    • In IBM Spectrum Scale v4.2.1 and later, issue the following command on each node of the cluster:
      /usr/lpp/mmfs/bin/tsloadikm run
The IBM Spectrum Scale client now trusts the new self-signed DSM server certificate.