Note that the information in this article applies to BoKS 6.7, 7.0 and 7.1. It does not apply to BoKS 7.2, where certificate management has changed.


Summary

Once the BoKS Root CA is going to expire, a new Root CA must be created.
After the BoKS Root CA renewal, the certificates issued by BoKS Root CA used by WSI to communicate with BoKS (BCCASD on the Master) are no longer valid. They must also be updated to work correctly.

The connection between the WSI server and each BoKS Master (BCCASD) is protected by client-side SSL, where the server-side certificate is the Master's host certificate, and the client-side certificate is the WSI server's certificate, issued by the same CA in the corresponding BoKS Master.

Once the Master's host certificate is changed when updating certificates for WSI, you have to update the certificates for BoKS Control Center (BCC) as well to make them continue to work.

Procedure

There are different BoKS domains defined in WSI. Take one of them for example here. The same operations need to be done for all the BoKS domains defined in WSI.

  1. Create a new BoKS root CA in BCC
    1. Go to Domain > Certificates > Create root CA.
    2. Input the parameters including "Country", "Common Name (CN)", "CA password", "RSA key length", "VC lifespan" and so on.

      If you select "Save CA password", the CA password is saved to a file. The file is located in $BOKS_data/sso_creds/ca_creds/keypkgs/*.pin. Later you can use it as a parameter when you renew the host virtual card using the script mkhostvc.sh.

    3. Check on the BoKS Master that a new BoKS Root CA is created.

      The SKI (Subject Key Identifier) data can be used to identify which is the new and which is the old certificate.

      To list BoKS CAs with SKI data on the Master:

       BoKS # cacreds list -v    
      Subject name : "CN=Admin Root CA,O=abcd,C=SE"
      Issuer name : "CN=Admin Root CA,O=abcd,C=SE"
      AuthorityKeyIdentifier: "************************************5eb0"
      SubjectKeyIdentifier : "************************************5eb0"
      Subject name : "CN=Admin Root CA,O=abcd,C=SE"
      Issuer name : "CN=Admin Root CA,O=abcd,C=SE"
      AuthorityKeyIdentifier: "************************************2d9b"
      SubjectKeyIdentifier : "************************************2d9b"

      You can also list the detailed information of one of them using the command below:

       BoKS # cacreds get -n 
      "CN=Admin Root CA,O=abcd,C=SE" -s "************************************2d9b" -a -v
  2. Replace the host virtual card for the Master
    1. Save the certificate data in the host virtual card on the Master before updating.

      In the result of the commands below, the AKI (Authority Key Identifier) data matches the SKI data from the old BoKS root CA, which means it is issued by the old BoKS Root CA.

      BoKS # usrcreds get -k <vcname>  -c > /tmp/master.cert
          BoKS # certinfo -c /tmp/master.cert
      	...
          Extensions:
                  subjectKeyIdentifier:
                          ************************************2ae1
                  authorityKeyIdentifier:
                          ************************************5eb0
          ...

      The vcname parameter in the command usrcreds is the virtual card name. Here it should be the host virtual card name for the BoKS Master, which is created with the IP address of the BoKS Master by default. Refer to the manpages for commands usrcreds and certinfo.

    2. Create a new host virtual card for the Master using the script mkhostvc.sh on the Master.
      #./mkhostvc.sh -h $(hostname) -n 'CN=Admin Root CA,O=abcd,C=SE' -p $BOKS_data/sso_creds/ca_creds/keypkgs/'CN=Admin Root CA,O=abcd,C=SE'*.pin -c $(hostname).your.domain -v 10 -o

      Here the *.pin file is the saved password file if you selected "Save CA password" when you created the new Root CA in step 1.

      Refer to these two KB articles about where to obtain the script mkhostvc.sh and the manpage on how to use it.

    3. Check that the AKI data within the host virtual card for the Master has changed.
      BoKS # usrcreds get -k <vcname>  -c > /tmp/master.new.cert
          BoKS # certinfo -c /tmp/master.new.cert
      	...
          Extensions:
                  subjectKeyIdentifier:
                          ************************************3kr8
                  authorityKeyIdentifier:
                          ************************************2d9b
          ...

      This time the AKI data listed here should match the SKI data from the new BoKS Root CA, which means the host virtual card has been replaced with the new certificate issued from the new BoKS Root CA.

  3. Replace the host virtual card for the WSI server on the Master according to the same steps.
     #./mkhostvc.sh -h $(hostname) -n 'CN=Admin Root CA,O=abcd,C=SE' 
    -p $BOKS_data/sso_creds/ca_creds/keypkgs/'CN=Admin Root CA,O=abcd,C=SE'*.pin -c $(FQDN hostname) -v 5 -o
  4. Update the java keystore files on the WSI server as follows.
    1. Find out the keystore file related to the current BoKS domain that had updated the host virtual card in previous steps.

      The keystore file name is defined as "keystore:" for each domain in domain.yaml, located at /etc/opt/mds/domain.yaml by default. The keystore files for different BoKS domains are located at /etc/opt/mds/certificates/ by default.

    2. Save certificate data used in the keystore file before updating.

      From the AKI data there, you can tell that the certificate is issued by the old BoKS Root CA. The command below can list registered certificates in a java keystore file.

      /opt/mds/jre/bin/keytool -list -v -keystore /etc/opt/mds/certificates/<domain1>.jks
    3. Run bccgethostcert on the Master to export the host certificate for the WSI server, and copy the two output files to the WSI server.
      BoKS # bccgethostcert <hostname>
      <hostname>/<ip> already has a virtual card, extracting it...
      PKCS#12 file password :
      Retype PKCS#12 file password :
      PKCS#12 file created: <hostname>.p12
      CA certificate file created: <hostname>-ca.pem
      BoKS #
    4. Back up the old domain keystore file on the WSI server.
      #mv /etc/opt/mds/certificates/<domain1>.jks /etc/opt/mds/certificates/<domain1>.jks.bak
    5. Run createtrust.sh to update the certificates in the keystore file on the WSI server.
      #/opt/mds/lib/createtrust.sh -c ca-chain.out -h <hostname>.p12 -j /etc/opt/mds/certificates/<domain1>.jks [-p "keystore-password"] [-P "p12-password"]

      Here the ca-chain.out is the output *.pem file from bccgethostcert, while the <hostname> .p12 is the output *.p12 file from bccgethostcert previously.

    6. Change the owner and group for the new keystore file created in the last step.

      Use the same user and group that were used for the old keystore file.

      #ls -l /etc/opt/mds/certificates/.jks.bak	
      -rw------- 1 wsipuser wsipusergroup 2365 Sep 28 17:06 .jks.bak
      #chown wsipuser:wsipusergroup /etc/opt/mds/certificates/.jks

      Refer to the KB article below for more details:

  5. Reboot BoKS on the Master, to load the new host certificate in BCCASD.
    BoKS # Boot -k; 
    BoKS # Boot
  6. Reboot the WSI server, to load the new host certificate in WSI.
    /etc/init.d/mds stop
    /etc/init.d/mds start
  7. Check that the WSI server works correctly.
    # /opt/mds/sbin/calldomain.sh -u idmuser
    Password for idmuser:
    Calling domain <domain1>...
    Successfully called getDomainParameters function for domain <domain1>
  8. Follow the same steps to update the java keystore file for BCCPS.

    When you reboot BoKS after the Master's host virtual card has been replaced, BCCASD loads the new host certificate. Then BCC does not work correctly anymore with the old host certificate from BoKS Master registered in the Java keystore file. Therefore you must update the Java keystore file for BCCPS. The keystore file used by BCCPS is defined as "TrustFile" in the bcc.properties file, located at /etc/opt/bccps/bcc.properties by default.

    If BCCPS is installed on another host instead of the Master, you need to replace the host virtual card first according to the operations in step 2. And finally, check that BCC is working correctly.

    Refer to the KB article below for more details.

    How to: Check certificates used by BCC and the Master admin server interface, boks_bccasd

    Notes:

    1. The steps in this article are verified for BoKS 6.7, 7.0 and 7.1.
    2. In step 1, create the new BoKS Root CA with the same DN name as the old one.
    3. In step 2, if you reboot BoKS on the Master, and then test /opt/mds/sbin/calldomain.sh -d user on the WSI server, it would fail, since BCCASD loads the new host certificate after rebooting.
    4. In step 2, use the hostcreds command instead of usrcreds to export host certificate information if using BoKS 7.1 and later.

      #For BoKS 7.0 and earlier#

      usrcreds get -k <vcname> -c > /tmp/cert

      #For BoKS 7.1 and later#

      hostcreds get -h <hostname> -c > /tmp/cert
    5. In step 4, when running the bccgethostcert command you will be prompted to enter a password for the PKCS#12 file. It is important to enter the same password as used for the Java Keystore file.

      The keystore password is available on the WSI server in the file /etc/opt/mds/config.yaml:

      certstorepwd: "password".

      Later in the createtrust.sh command, you are prompted for the keystore password and the PKCS#12 password if you don't provide them via the -p and -P options.


Still have questions? We can help. Submit a case to Technical Support.

Last Modified On: January 11, 2019