Configuration

Step 1: Create a Server Keystore

In this step, you’ll use either your own self-signed certificate or a certificate from a valid certificate authority. 

Self-Signed Certificates

Execute the following at the command prompt:

keytool -genkeypair -alias jetty -keyalg RSA -sigalg SHA256WithRSA -keysize 2048 -validity 3700 -keystore server_keystore.jks

You will be asked to make up a password and enter it twice.  You will need that password for subsequent steps. Follow the rest of the command line prompts to provide additional information for the certificate that will be used to build the distinguished name (DN) such as company, country, etc.

Buying a Certificate from a Certificate Authority

If you are planning to buy a certificate from a certificate authority, you will need to create a Java keystore file that contains a self-signed certificate, generate a certificate request to send to a certificate authority, and import the final certificate that was supplied by the certificate authority into the Java keystore file.  Note that importing the final certificate into the Java keystore file replaces the self-signed certificate with the one that was supplied by the certificate authority.  Also note that the final certificate must be imported into the same Java keystore file that was used to generate the certificate request in order to have a usable Java keystore file.

Generate a Self-Signed Certificates for a Certificate Request

Execute the following at the command prompt:

keytool -genkeypair -alias jetty -keyalg RSA -sigalg SHA256WithRSA -keysize 2048 -validity 3700 -keystore server_keystore.jks

You will be asked to make up a password and enter it twice.  You will need that password for subsequent steps. Follow the rest of the command line prompts to provide additional information for the certificate that will be used to build the distinguished name (DN) such as company, country, etc.

Generate a Certificate Request File to Send to a Certificate Authority

keytool -certreq -keystore server_keystore.jks -alias jetty -sigalg SHA256WithRSA -file certificate_request.req

The certificate_request.req file contains the certificate request information and public encryption key to send to a certificate authority during the purchasing process.  Note that certificate_request.req is an ascii file that can be viewed with a text editor and can be cut and pasted into a certificate authority’s website.  Do not misplace or lose the server_keystore.jks file and password as that file contains the private encryption key that you will need when the certificate authority issues a certificate.  If the certificate authority asks what type of web browser you are planning to use, say Jetty or Java.

When a certificate authority issues a certificate, use this command to import it into the server_keystore.jks file.  If the certificate authority supplied the certificate in more than one format, use the p7b file which should be in the PKCS7 format.  A file in the PKCS7 format is preferred as that type of file usually contains both the certificate and the certificate chain.

keytool -importcert -trustcacerts -alias jetty -keystore server_keystore.jks -file <theCertificate.p7b>

If you get a “keytool error: java.lang.Exception: Failed to establish chain from reply” error, this usually indicates that the certificate file that was supplied by the certificate authority does not contain the certificate chain.  This type of problem can be corrected by manually generating a .p7b file that contains both the certificate and the certificate chain.  Here are two ways to do this:

Method 1: If you have access to a computer that runs Microsoft Windows, you can use a built in certificate export wizard to generate a .p7b file.  To do this, open the file that you received from the certificate authority by double clicking on it.  If the file contains a certificate, this will bring up a certificate window.  If the certificate window shows an icon with a red x and a note stating that this certificate is not trusted, the certificate wizard will not be able to generate a usable .p7b file.  If the certificate window looks ok in that no red x is shown, do the following:  Select the “Details” tab.  Press the “Copy to File…” button.  Select the PKCS #7 (.P7B) radio button.  Check the “Include all certificates in the certification path if possible” checkbox.  Press “Next” and make up a name for a new file.  These steps will cause Windows to generate a .p7b file that contains the certificate and the required intermediate certificates that the Windows certificate wizard obtained from various databases.

Method 2: If you have the OpenSSL command line tool installed and the certificate authority supplied the certificate chain in a separate file, you can use OpenSSL to generate a .p7b by using this command: openssl crl2pkcs7 -nocrl -certfile <theCertificate.crt> -certfile <certificateChain.pem> -out <theCertificate.p7b>

Make sure to place the keystore file (server_keystore.jks in our example) somewhere secure. NOTE: BASIS does not recommend including it in the BBj cfg directory. The reason is that it is quite common for BASIS Support to request the contents of your cfg directory and even when it’s a known entity like BASIS, you should never unnecessarily share a secret key or certificate with anyone.

Step 2: Create the Client Public Key Keystore

In order for clients to connect to the Secure Thin Client server, they will need to have the public key available to them. The client should have a client keystore that contains the public key. To create this keystore, execute the following at the command prompt. Make sure references to any files include the appropriate path if necessary:

keytool -exportcert -rfc -alias jetty -keystore server_keystore.jks -file temp.crt

keytool -importcert -alias jetty -noprompt -file temp.crt -keystore client_keystore.jks -storepass password

rm temp.crt (or del temp.crt on Windows)

Step 3: Add the Server Keystore and Client Keystore to the BBj Secure Thin Client Server Configuration

Configure the Server Keystore

1. Use the BBj Enterprise Manager, navigate to BBjServices->Servers
2. Select the Thin Client (SSL) server from the list.
3. Ensure the “Start” checkbox is selected.
4. Provide the full path to the location of the server_keystore.jks file in the “Keystore” field.
5. Provide the password that you made up in step 1.

When the Secure Thin Client Server is enabled, the assumption is that security is of utmost concern so you will also need to disable the standard Thin Client server:

1. Select the Thin Client server from the server list.
2. Uncheck the “Start” checkbox.

Configure the Client Keystore

In order for desktop apps to function properly, they also require access to the client_keystore.jks. Even if you are not currently using desktop app deployment, BASIS recommends configuring this section to ensure a seamless process should that change in the future. 

1. Place the client_keystore.jks file created in step 2 in the <bbj home>/jetty/appdeployment/ssl
2. Using the Enterprise Manager, select the Thin Client (SSL) server from the list.
3. Provide the -storepass password that you provided in step 2 (we used “password” as our example) in the “Client Keystore Password” field. Note that this password can be simple and known to anyone since the client keystore file only contains the public key.

Once all of your changes are made, make sure to Save the changes and restart BBjServices.

Step 4: Copy the Client Public Key Keystore to Client Machines

Step 2 creates a client_keystore.jks file. This keystore contains only the public key and can be distributed and used by BBj Thin Client applications to connect to the Secure Thin Client server using an encrypted connection. Clients will need this file and the password used when creating the file. NOTE: The password can be simple and known to anyone since this keystore only contains the public key.

Running a Secure Thin Client Connection

To connect to your secure server, ensure that you have a copy of the client_keystore.jks file on the client machine and execute the following command line from the BBj bin directory:

bbj -RHmyserver -SC –keystore=/path/to/client_keystore.jks –-keypass=password

For Desktop Apps, the Secure TC Connection must be set to “true”.  This option is found in EM under Web->Applications->App Name settings->Web App Only.

Appendix

If you have an existing https SSL certificate for an Apache-based web server in the OpenSSL PEM based file formats, you can import it into a Java keystore file for use with BBj.  This process requires that you have openssl installed.  You can use these commands to create a server_keystore.jks keystore file for use with BBj:

Import the Private Key and Certificate Into a PKCS12 File

openssl pkcs12 -export -in <existingCertificate.crt> -inkey <existingPrivateKey.key> -certfile <existingCertificateChain.pem> -name jetty -passout pass:temppassword -out temp.p12

Convert the PKCS12 File to a Java Keystore

keytool -importkeystore -srckeystore temp.p12 -srcstoretype pkcs12 -srcstorepass temppassword -alias jetty -destkeystore server_keystore.jks

You will be asked to make up a password and enter it twice.  You will need that password in order to use the keystore file.

Delete the Temporary File

rm temp.p12