Situation
How to use KeyStore Explorer to create a new servletcontainer.bcfks or keystore.bcfks keystore, key pair, and certificate signing request for the Host Access for the Cloud (Reflection ZFE) Session Server.
Resolution
KeyStore Explorer is a GUI replacement for the Java Keytool command line utility. KeyStore Explorer ships with Reflection ZFE and Host Access for the Cloud (formerly called Reflection ZFE). It’s located in the C:\Program Files\Micro Focus\ReflectionZFE\utilities directory for Reflection ZFE and in C:\Program Files\Micro Focus\HACloud\utilities directory for Host Access for the Cloud.
- To start KeyStore Explorer simply double click on the keystore-explorer.bat file in the \utilities directory.
- Once the main screen displays click on the Create a new KeyStore icon.
- Select the BCFKS (Bouncy Castle FIPS Key Store) option for the keystore type and click OK.
- Click on File and then Save to finish creating the new keystore. This is just creating the keystore itself, generating the key pair and certificate signing request will occur later on in the process.
- When saving the keystore you will be prompted to enter a new keystore password. The default keystore password for Host Access for the Cloud and Reflection ZFE is “changeit” without the quotes.
If you choose to use a different password see the Host Access for the Cloud or Reflection ZFE User Guide on “How to change the default Host Access for the Cloud (Reflection ZFE) Key Store Password.”
- After entering in the new keystore password you will be then prompted to save the new keystore to a location and give it a name. For Reflection ZFE the file name should be servletcontainer.bcfks and for Host Access for the Cloud the file name is keystore.bcfks.
- Once the new keystore is saved go to the menu bar click on Tools and select Generate Key Pair from the menu. Take the default settings for the Algorithm and Key Size. Click OK to proceed with creating the new Key Pair.
- In the Generate Key Pair dialog click on the Edit Name button. See the screen shot below with the button circled in red.
- In the Name dialog enter the following information.
- The Common Name is most important as it should be the fully qualified name (FQDN) of the server.
- The remaining options are just labels but it is best practice to enter the proper information.
Click OK when finished.
- Back on the Generate Key Pair Certificate window click on the Add Extensions button on the lower right.
- In the Add certificate Extensions click on the green plus button to add certificate extensions. See the screen shot below with the button circled in red.
- Add the Extension Type of Key Usage and check the box for Critical Extension. Click the OK button to go to the Key Usage Extensions.
- For the Key Usage Extension select Digital Signature and Key Encipherment and click OK.
- Again click on the green plus button and select the extension type of Extended Key Usage from the Extension list. The Critical check box is not needed this time so it can be left unchecked. Click OK to continue.
- Select the Extended Key Usage option of TLS Web Server Authentication and click OK.
- Subject Alternative Names (SANs) are recommended. They can be very useful if you wish to use this same keystore and certificate on multiple servers, or for load balanced environments by including the load balanced name. You can also add IP Address as SANs but this could be a security risk publishing the actual IP Address of the server. While it is possible to simply use the Common Name in the subject field it is encouraged to use the Subject Alternative Name / DNS Name instead.
If the Common Name is used in the subject field it should also be added as Subject Alternative Name / DNS Name. If Subject Alternative Names exist in a certificate most browsers will not read the Common Name of the subject field and you could see hostname verification errors in the TLS handshake process.
Many Certificate Authorities can add SANs during the certificate signing process as well.
- To Add Subject Alternative Names again click on the green plus button and select the extension type of Subject Alternative Name from the Extension list. Click OK to continue.
- Enter the FQDN for the DNS Name and click OK
- Enter the IP Address if desired but it is not necessary. Click OK to continue.
- Click OK once the all SAN entries are complete
- Click the OK button again once all the Certificate Extensions are complete.
- Once the Extensions are complete you will be back at the Generate Keypair window and the certificate Common Name will be displayed in the Generate Key Pair Certificate dialog. See the screen shot below with the CN= circled in red. Again Click OK to continue.
- Click on File in the KeyStore Explorer menu bar and select Save to save recent changes. During the save you will be prompted for the Key Pair Alias name. The alias name must be “servlet-engine” without the quotes. Click OK to continue.
- You will then be prompted to enter the New Key Pair password. This is different from the KeyStore password that was entered at the beginning of this process. This Key Pair password must also be “changeit” without the quotes. Click OK to continue.
- Now that the new keystore and key pair have been created right click on the servlet-engine key pair and select Generate CSR from the menu. This will generate the Certificate Signing Request that will be submitted to the Certificate Authority.
- Browse to the location where you want to save the new Certificate Signing Request and click OK
- You should see the following message once the new CSR is created.
- When the newly signed certificate is returned from the Certificate Authority, again right click on the servlet-engine Key Pair and select Import CA Reply.
- Again if the import was successful you will see the following message.
- Click on File and select Save from the drop down menu to save the certificate reply import and then finally click on File and select Exit from the menu to complete the new servletcontainer.bcfks or keystore.bcfks
On the Reflection ZFE Session server the new servletcontainer.bcfks keystore will go in to the C:\Program Files\Micro Focus\ReflecitonZFE\sessionserver\etc directory. Host Access for the Cloud Session Server keystore.bcfks will go in the C:\Program Files\Micro Focus\HACloud\sessionserver\etc directory.
27. Install and restart –
• Remove or rename the old servletcontainer.bcfks or keystore.bcfks keystore file
• Copy in the new servletcontainer.bcfks or keystore.bcfks keystore to the /etc directory
• Restart the Reflection ZFE Session Server Service or the Host Access for the Cloud Session Server Service for the change to take effect.
• Last but not least re-register the Reflection ZFE Session Server or the Host Access for the Cloud Session Server Service with the Management and Security Server. See the User Guide for either Reflection ZFE or Host Access for the Cloud on how to accomplish this.