Skip to content

Server Certificate Management

When users log on to Gateway Administrator or the Reflection Identity Manager, the connection is made using HTTPS and the browser requires server authentication. By default, the Reflection Gateway servers send a self-signed security certificate to the browser for this purpose. (A self-signed certificate is signed by the same entity that it certifies.) The browser checks the digital signature in this certificate against its list of trusted Certificate Authorities (CAs). With the default certificates, you see a certificate warning, because the signer of the certificate is not in your browser's list of trusted CAs.

The procedures in this section describe options for managing these server certificates.

Replace the Default Server Certificate

To be able to start the Identity Manager and Gateway Administrator without seeing certificate warning messages, you can replace each of these self-signed certificates with a certificate from a well-known Certificate Authority (CA).

To replace self-signed certificates create a PKCS#12, or JKS keystore and migrate the file (.p12, .pfx, or .jks) to BCKFS. Server certificates must be stored in a FIPS compliant BCFKS keystore. Refer to the following procedures for details.

Install a Server Certificate in a PKCS#12 File

Install a Server Certificate in a Java Keystore

Install a New Server Certificate: PKCS#12 File

Use this procedure to replace the default Transfer Server or Gateway Administrator server certificate with a CA-signed certificate contained within a PKCS#12 file.

Before you begin

Obtain a PKCS#12 file (.p12 or .pfx) that includes your private key and a certificate signed by a Certificate Authority (CA).

PKCS#7 can be used to sign and/or encrypt messages. It can also be used to store certificates and to disseminate certificates (for instance as a response to a PKCS#10 message). Files in this format typically use a *.p7b extension. PKCS#10 is used for certificate requests to a Certificate Authority (CA). PKCS#12 is used for storage and transportation of certificates and associated private keys. Files in this format typically use a .pfx or .p12 extension.

Note

  • The certificates that authenticate Reflection Gateway servers must use FIPS-compliant cryptography. You should request a FIPS-compliant certificate from your Certificate Authority. DSA keys used in the certificate must be either 1024, 2048, or 3072 bits. RSA keys must be either 2048 or 3072 bits.

  • The PKCS#12 store must also use FIPS-compliant cryptography. If you have a PKCS#12 package that contains a FIPS-compliant private key, but the store encryption is not FIPS-compliant, the server will fail to start. To resolve this, you can re-encrypt the PKCS#12 file or import the file into a Java keystore.

  • The PKCS#12 store and the private key must be protected with the same password.

To replace the default server certificate with a certificate in a PKCS#12 file (.p12 or .pfx)

  1. Move the PKCS#12 file to the folder that holds the default Reflection Gateway keystore (or to any secure location on your server). The default keystore locations are:

    <install path>\TransferServer\etc\

    <install path>\GatewayAdministrator\etc\

    Caution

    Do not delete any of the existing certificates or keystore files in these locations. The server certificates located here are required for communication between Reflection Gateway components.

  2. Locate the container.properties file in the location below for the server you are updating.

    <install path>\TransferServer\conf\container.properties

    <install path>\GatewayAdministrator\conf\container.properties

  3. Open container.properties in a text editor. (You must be a Windows administrator to be able to edit this file.) Remove the comment character (#) from the following lines. Edit these lines to specify a PKCS12 package and enter your certificate name and password. For example:

    servletengine.ssl.keystore=../etc/myserver_cert.p12
servletengine.ssl.keystoretype=PKCS12
servletengine.ssl.keystorepassword=mypassword

    Note

    The path to the keystore must be specified using either forward slashes or escaped backslashes. For example: C:/pathto/keystore or C:\pathto\keystore

  4. Restart the server you are configuring. See Start and Stop the Reflection Transfer Server and Start and Stop the Reflection Gateway Administrator Service.

  5. If you replaced the Gateway Administrator certificate after using the default certificate, you will need to update server authentication configuration:

  6. Confirm that you can log on to the Identity Manager or Gateway Administrator.

    If you can't log in, or if you continue to see a certificate warning message, see Troubleshooting Server Certificate Setup.

Note

If you are using a load-balancing proxy to ensure high availability of Reflection Gateway services, you will need to configure duplicate server systems after making these changes. For details, see Ensuring High Availability of Reflection Gateway Services .

Install a New Server Certificate: Java Keystore

Use this procedure to replace the default Transfer Server or Gateway Administrator server certificate with a CA-signed certificate contained within a Java keystore.

Before you begin

Obtain a Java keystore (*.bcfks) file that contains your private key and a certificate signed by a Certificate Authority (CA). You can use the following procedures to create your keystore using the Java keytool utility.

To replace the default server certificate with a certificate in a Java keystore

  1. Move the new Java keystore to the folder that holds the default keystore (or to any secure location on your server). The default keystore locations are:

    <install path>\TransferServer\etc\

    <install path>\GatewayAdministrator\etc\

    Caution

    Do not delete any of the existing certificates or keystore files in these locations. The server certificates located here are required for communication between Reflection Gateway components.

  2. Locate the container.properties file in the location below for the server you are updating.

    <install path>\TransferServer\conf\container.properties

    <install path>\GatewayAdministrator\conf\container.properties

  3. Open container.properties in a text editor (running as an administrator). Remove the comment character (#) from the following lines and edit them to point to your keystore and specify your keystore password. For example:

    servletengine.ssl.keystore=../etc/newkeystore.jks
servletengine.ssl.keystorepassword=mypassword

    Note

    The path to the keystore must be specified using forward slashes or escaped backslashes. For example: C:/pathto/keystore or C:\pathto\keystore

  4. Run the new migrate_keystore.bat file.

  5. Open container.properties in a text editor and edit the following lines:

    servletengine.ssl.keystore=../etc/migrated.bcfks
servletengine.ssl.keystoretype=BCFKS

  6. Restart the server you are configuring. See Start and Stop the Reflection Transfer Server and Start and Stop the Reflection Gateway Administrator Service.

  7. If you replaced the Gateway Administrator certificate, you must repeat the Activate and verify action on the Reflection Secure Shell Proxy. This reestablishes the connection to the Gateway Administrator using the new certificate.

  8. Confirm that you can log on to the Identity Manager or Gateway Administrator. If you can't log in, or if you continue to see a certificate warning message, see Troubleshooting Server Certificate Setup.

Note

If you are using a load-balancing proxy to ensure high availability of Reflection Gateway services, you will need to configure duplicate server systems after making these changes. For details, see Ensuring High Availability of Reflection Gateway Services ,

Configure Your Browser to Trust a Self-Signed Certificate

If you use the default Reflection Gateway certificates, you will see a certificate warning when you connect to the Gateway Administrator and the Identity Manager. You can use the following procedures to remove these warnings without modifying the server certificates.

Note

The procedures below are appropriate for testing. They may also be appropriate if only a small number of users access Gateway Administrator. However, before you deploy the Identity Manager to end users, or provide administrative access to a larger number of users. you should configure Reflection Gateway to use certificates signed by a well-known Certificate Authority. (See Replace the Default Server Certificate.) With the updated certificates in place, the following procedures are not necessary.

To add an untrusted certificate to the Internet Explorer trusted root store

  1. When you see a warning that the security certificate was not issued by a trusted certificate authority, select Continue to this website.

    This connects you to the web page and displays a certificate error alert in the address bar.

  2. Click the certificate error alert to view the Certificate Error message.

  3. In the Certificate Error message, click View Certificates.

  4. On the certificate General tab, click Install Certificate.

    Note

    If the Install Certificate button is not visible, you need to modify your browser's security settings. Go to Tools > Internet Options > Security, then clear Enable Protected Mode. You can restore this setting after you install the certificate.

  5. In the Install Certificate Wizard, select Place all certificates in the following store.

  6. Click Browse and select Trusted Root Certification Authorities, then continue through the remaining steps to install the certificate.

To add an exception for an untrusted certificate in Firefox

  1. When you see a warning that the connection is untrusted, click Advanced.

  2. Click Add Exception.

  3. Leave Permanently store this exception selected and click Confirm Security Exception.

To add an untrusted certificate to the trusted root store from Chrome

  1. When you see a message saying your connection is not private, click Advanced, then click the Proceed to link log in.

  2. Save the presented certificate to a file. To do this:

    • Click the View site information icon (a padlock) in the address bar:

    • Click Certificate Information.

    • On the Details tab, click Copy to File and save the file using defaults.

  3. Locate and double-click the certificate file you just saved.

  4. On the certificate General tab, click Install Certificate.

  5. In the Install Certificate Wizard, select Place all certificates in the following store.

  6. Click Browse and select Trusted Root Certification Authorities, then continue through the remaining steps to install the certificate.

Migrate PKCS#12 or JCEKS keystores to BCFKS keystores

You can use an installed script called migrated_keystore.bat to convert your PKCS#12 or JCEKS keystores to BCFKS keystores.

This script examines the container.properties to find custom keystores that have been added and automatically converts them to BCFKS.

Important

You need to know the password that protects this file.

Before you Begin

  1. Open a command window.

  2. Run the following two commands to place Java in the default path:

    set JAVA_HOME="c:\Program Files\Common Files\Micro Focus\ServerJDK\1.8.0_151"
set PATH=%JAVA_HOME%\bin;%PATH%

To re-encrypt a PKCS#12 file using a FIPS-approved algorithm

  1. On the computer running the Reflection Transfer Server, open a command window running as an administrator.

  2. Navigate to TransferServer\bin in the Reflection Gateway installation folder. The default location is:

    C:\Program Files\Micro Focus\ReflectionGateway\Gateway\TransferServer\bin

  3. Run the migrated_keystore.bat batch file.

  4. Modify the container.properties and update the following settings:

    servletengine.ssl.keystore=..\etc\migrated.bcfks
servletengine.ssl.keystoretype=BCFKS

    Note

    If these passwords don't match, the server will not be able to use the keystore.

Using the Keytool Utility to Manage Keystores

The Java keytool utility is a command-line tool that can be used to manage keys and certificates. Depending on how you obtain certificates, you can use one or more of these procedures to manage your Reflection Gateway certificates. For more complete documentation, refer to the keytool documentation.

In this section:

Run the Keytool Utility

The keytool utility is a key and certificate management tool that is installed with the Java JRE.

  1. Open a Command Prompt window running as an administrator.

  2. Navigate to the folder that contains keytool.exe or add this folder to your path. (Confirm the actual Server JDK version for your installation.) For example:

    SET PATH=%PATH%;C:\Program Files\Common Files\Micro Focus\ServerJDK\<version>\bin

  3. To review the available options, enter the following:

    keytool -help

Generate a Key Pair and Create a Keystore

This procedure uses the Java keytool utility to generate a key and save it to a Java keystore.

Note

  • The CA you use might have specific options required for creating an HTTPS certificate. Review the instructions provided by the CA before creating your key pair.

  • DSA keys used in Reflection Gateway server certificates must be 1024, 2048, or 3072 bits. RSA keys must be either 2048 or 3072 bits.

  1. Use the -genkeypairoption to generate a key and save it to a Java keystore (newkeystore.bckfs in this example). The example shown here prompts you to enter values for items that make up the distinguished name (DN) in the certificate. See the example below to enter these values directly on the command line.

    keytool -genkeypair -providername BCFIPS -providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider -providerpath ../bc-fips-1.0.1.jar -alias rgateway -keyalg RSA -keysize 2048 -keystore newkeystore.bcfks -validity 365 -storetype BCFKS –storepass “<password>”

  2. The keytool prompts you to enter a password and values for the items that make up the distinguished name (DN) in the certificate (name = CN, organizational unit = OU, organization = O, city or locality = L, state or province = S, two letter country code = C). The generated DN will use the value "Unknown" for any fields you don't specify.

    • When you are prompted with "What is your first and last name?\"

      You must enter the DNS name that is used to access the Reflection Gateway server (for example gateway.mycompany.com). This value is used as the CN (Common Name) in the certificate. If the CN in a certificate doesn\'t match the actual DNS name used to access the server, you will see a certificate warning when you connect to the server.

    • When you are prompted with \"What is the two-letter country code for this unit?\"

      You must enter a valid two-letter country code (for example US).

  3. When you are prompted for a password for the alias, press Enter to use the same password you used for the keystore.

An alternate option to responding to prompts is to specify the DN value on the command line using the -dname option. For example:

keytool -genkeypair -providername BCFIPS -providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider -providerpath ../bc-fips-1.0.1.jar  -dname "CN=gateway.mycompany.com, O=My Company, C=US" -alias rgateway -keyalg RSA -keysize 2048 -keystore newkeystore.bcfks -validity 365  -storetype  BCFKS.

Create and Submit a Certificate Signing Request

This procedure uses the Java keytool utility to create a Certificate Signing Request (CSR) from an existing keystore.

Before you begin

To create and submit a Certificate Signing Request

  1. Use the -certreq option to generate a certificate request. This generates a Certificate Signing Request, using the PKCS#10 format. For example:

    keytool -v -certreq -alias gateway -providername BCFIPS -providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider -providerpath ../bc-fips-1.0.1.jar  -keystore newkeystore.bcfks -file cert_request.csr -ext ExtendedkeyUsage=serverAuth -storetype BCFKS

  2. Enter your keystore password when prompted.

  3. You will see a message saying that the certificate request has been saved to the file you specified (cert_request.csr in this example).

  4. Submit this CSR to your CA. You will need the contents of the CSR file. Open the file in a text editor. The contents should include a header and footer with encoded data between them. When you submit the request, copy the entire file, including the BEGINand END lines.

    -----BEGIN CERTIFICATE REQUEST-----


    -----END CERTIFICATE REQUEST-----

Import Certificates from a p7b package into your Java Keystore

The Certification Authority may provide you with a PKCS#7 package (*.p7b) that contains the full chain of certificates required to authenticate your server (the CA-signed server certificate, intermediate certificates, and the CA root certificate). This procedure uses Java keytool command to import the certificates from the p7b file into your Java keystore.

Note

If you have individual certificates not contained within a p7b package do not use this procedure. You will need to import each certificate separately. See the procedure described in Import Individual Certificates into your Keystore.

Before you begin

  • Obtain a PKCS#7 package (*.p7b) from the Certification Authority that contains the CA-signed server certificate, intermediate certificates, and the CA root certificate.

  • You need to know the keystore name, password, and alias you used when you created the keystore.

To import certificates contained within a p7b file

  • Add the certificates from the PKCS#7 file (FullChainOfCerts.p7b in this example) to the Java keystore. The alias in this command needs to match the alias you specified when you generated your key pair. For example:
    keytool -importcert -alias rgateway -trustcacerts -file FullChainOfCerts.p7b -providername BCFIPS -providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider -providerpath ../bc-fips-1.0.1.jar -keystore newkeystore.bcfks –storetype  BCFKS

Import Individual Certificates into your Keystore

Use this procedure if certificates (the CA-signed server certificate, intermediate certificates, and the CA root certificate) are obtained as individual certificates instead of in a single PKCS#7 (*.p7b) file. This procedure uses a series of Java keytool commands to import these certificates into an existing keystore. Use the order of import as shown in the procedure: import the root CA first, then any required intermediate certificates, and finally, the CA-signed server certificate.

Note

If your certificate was provided within a p7b package, you do not need to import each certificate separately. Instead, use the procedure described in Import Certificates from a p7b package into your Java Keystore.

  • Obtain a server certificate for your server signed by a Certificate Authority.

  • Obtain the trusted root CA certificate for the Certificate Authority and any required intermediate certificates.

  • You need to know the keystore name, password, and alias you used when you created the keystore.

To import certificates into your Java keystore

  1. Add the root CA certificate (CAcert.cer in this example) to the Java keystore that you generated when you created your private key (newkeystore.jks in this example). Use a new alias (root in this example). For example:

    keytool -importcert -alias root -file CAcert.cer -providername BCFIPS -providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider -providerpath ../bc-fips-1.0.1.jar  -keystore newkeystore.bcfks – storetype  BCFKS.

  2. Add each required intermediate certificate (IntermediateCAcert.cer in this example) to the Java keystore:

    keytool -importcert -alias intermediate -trustcacerts -file IntermediateCAcert.cer -providername BCFIPS -providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider -providerpath ../bc-fips-1.0.1.jar  -keystore newkeystore.bcfks –storetype BCFKS

  3. Add the CA-signed server certificate (EndEntitycert.cer in this example) to the Java keystore. The alias in this command needs to match the alias you specified when you generated your key pair. For example:

    keytool -importcert -alias rgateway -trustcacerts -file EndEntitycert.cer -providername BCFIPS -providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider -providerpath ../bc-fips-1.0.1.jar  -keystore newkeystore.bcfks –storetype  BCFKS

Import a PKCS#12 File into a Java Keystore

This procedure uses the Java keytool utility to create a Java keystore from a PKCS#12 file.

  • You need a PKCS#12 (*.p12 or *.pfx) file containing your CA-signed Reflection Gateway server certificate and private key.

  • You need to know the password that protects this file.

To import a PKCS#12 file into a Java keystore

  • Use the -importkeystore option to create a Java keystore (newkeystore.jks in this example). For example:

    keytool -importkeystore -v -srckeystore cert_file.p12 -srcstoretype PKCS12 -providername BCFIPS -providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider -providerpath ../bc-fips-1.0.1.jar  -destkeystore newkeystore.bcfks -deststoretype  BCFKS.

    Note

    The keystore type you specify for deststoretype must match the type specified for servletengine.ssl.keystoretype in the server's container.propertiesfile. BCFKS is specified by default, and is recommended because it uses a stronger encryption for protecting the private key.

  • Enter passwords when prompted using the same password for destination keystore and source keystore.

    Note

    If these passwords don't match, the server will not be able to use the Java keystore and the browser will not be able to launch the application.