Overview of Jar Branding

BBj 13.13 now includes a BBjWebstartBootstrap.jar file signed with a BASIS International Ltd. security certificate. This certificate is part of the latest security solution needed to run Web Start applications. Starting with BBj 13.13, you can now configure the BBj installation and Web Start client startup windows that display the common name from the security certificate to display your company information (branding) instead of BASIS. You achieve this by purchasing your own Java code signing security certificate from a trusted organization and re-signing the BBjWebstartBootstrap.jar file.

Re-signing Prerequisites

Before you can re-sign a BBjWebstartBootstrap.jar file, you must meet two conditions: 1) have a Java Development Kit (JDK) installed on your computer, and 2) own or purchase a code signing certificate.

JDK

Re-signing a .jar file requires two utilities from the Java Development Kit (JDK): jar.exe and jarsigner.exe. If you do not have a JDK installed, the Java 7 JDK can be downloaded from Oracle at  www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html.

Code Signing Certificate

Re-signing a .jar file requires that you own or purchase a code signing certificate and place the certificate in a keystore. The code signing certificate must be purchased from a trusted certificate authority organization and meet the following requirements:

• The certificate must be a code signing certificate. A website certificate will not work for jar file signing.

• The certificate must support Java jar file signing. We recommend asking the Certificate Authority that you are planning to use whether or not their code signing certificates support Java jar file signing if you are not sure.

• The certificate and the private key for it must be stored in a Java JKS keystore file. The Certificate Authority should provide instructions on how to generate the necessary keys and assemble a Java keystore file that contains both the certificate and its private key.
   

Once you have purchased the code signing certificate, follow the instructions from the trusted certificate authority organization to configure the certificate. Be sure to set the certificate’s common name to reflect your organization, since it will appear in place of “BASIS.” Once this is done, place a Java keystore file containing both the purchased certificate and the private key for it on your computer so that it is available during the re-signing process.

Re-signing

To re-sign the BBjWebstartBootstrap.jar file for one BBj installation file, follow these steps:

1. Go to the BASIS download page (www.basis.cloud/bbj-download).

2. Select the product version and package (see Figure 1) to re-sign. To re-sign more than one package, repeat the remaining steps for each package.

Figure 1. Select a product and package to download.

3. Download the BBj<version>.jar file and place it in an empty directory (referred to as the <download dir>). Note: the name of the file depends upon the package selected above.

4. Change directory to the download directory:

cd <download dir>

5. Unpack the BBj installation .jar file in the download directory:

jar xf BBj<version>.jar

6. Create a tmp subdirectory under <download dir>:

mkdir tmp

7. Change directory to the tmp subdirectory:

cd tmp

8. Unpack the BBj installation .jar file in the tmp directory:

jar xvf ..\BBjWebstartBootstrap.jar

9. Remove the BASIS certificate files:

del META-INF\BASISCER.*

10. Remove the old BBjWebstartBootstrap.jar in the download directory:

del ..\BBjWebstartBootstrap.jar

11. Create the new BBjWebstartBootstrap.jar in the download directory:

jar Mcvf ..\BBjWebstartBootstrap.jar *

12. Change directory to the download directory:

cd ..

13. Remove the tmp directory:

rmdir /s /q tmp

14. Sign the new BBjWebstartBootstrap.jar with your certificate:

jarsigner -keystore <keystore file> BBjWebstartBootstrap.jar <alias/key name>

• <keystore file> is the full path and filename for the .jks keystore file holding your certificate and the private key.

• <alias/key name> is the alias name you configured when you purchased the certificate.

15. Remove the old BBj<version>.jar file in the download directory:

del BBj<version>.jar

16. Create the new BBj<version>.jar in the download directory:

jar Mcvf ..\BBj<version>.jar *

The Impact of Re-signing

Re-signing a BBj installation with your security certificate causes security-related appearances of the name “BASIS” to be replaced by your certificate’s common name. Your branding will appear in two places:

1. During BBj installation, when configuring Web Start.

2. At Web Start client startup.

Configuring Web Start During BBj Installation

BBj offers two options for configuring a security certificate during installation. Figure 2 shows an example that displays “BASIS.” Once you have re-signed the BBjWebstartBootstrap.jar file, the selected radio button’s text will change from “Trust BASIS International Ltd. to generate a certificate for Web Start” to “Trust <certificate common name> to generate a certificate for Web Start”. The <certificate common name> will be the common name you configured when you purchased your certificate.

Figure 2. Trust BASIS to generate a certificate.

Web Start Client Startup

The first time a Web Start client runs an application from your BBj application server using a .jnlp file, Web Start will ask for confirmation that the application publisher is trusted. See Figure 3 for an example with BASIS displayed. Once you have re-signed the BBjWebstartBootstrap.jar file, the “Publisher” text will change from “BASIS International Ltd.” to “<certificate common name>”. The <certificate common name> will be the common name you configured when you purchased your certificate.
 

Figure 3. Allow BASIS to install a Certificate Authority Installer.