Java Code Signing Guide

This guide will get you started signing your Java code with either an OV/IV or EV code signing certificate from SSL.com. These instructions assume that the Java Development Kit (JDK) is installed on your computer and that the keytool and jarsigner commands are included in your PATH. The Yubikey code signing instructions assume that your certificate is installed in slot 9a of a YubiKey FIPS token, as they are shipped by SSL.com.

If you don’t have a code signing certificate yet and are not sure which type you need, please read this FAQ.

OV/IV Code Signing (only for OV/IV certificates issued before June 1, 2023)

Configuration

Method 1: Generate CSR and PFX File in Browser

The simplest method for getting started quickly with Java code signing is to generate a CSR and PFX file when retrieving your certificate from SSL.com and install it in a new Java keystore.

1. Follow the steps shown in Ordering and Retrieving Code Signing Certificates to order your certificate and download a PFX file with your certificate and private key.
2. Import the PFX into a new keystore with the same password by using the command below. (Replace MY-CERTIFICATE.p12 and MY-KEYSTORE.jks with the actual name of your PFX file and the file name you want to give your keystore. Note also that the destalias is arbitrary and you may use another alias value if desired.)

   keytool -importkeystore -srckeystore MY-PFX.p12 -srcstoretype pkcs12 -srcalias 1 -destkeystore MY-KEYSTORE.jks -deststoretype JKS -destalias codesigning

   Note: The value for -srcalias for the PFX file downloaded from SSL.com should normally be 1, but you can confirm this by running the command keytool -list -v -storetype pkcs12 -keystore MY-PFX.P12 and checking the value shown for Alias name.
3. You will be prompted for a password for the destination keystore, and then for the source keystore password (the password you entered when creating the PFX). You may also see a warning message beginning with Warning: The JKS keystore uses a proprietary format. You may safely ignore this message.

Method 2: Generate Key Pair and CSR with Java

If you prefer to generate your Key Pair and CSR with Java, follow the steps in this section. The process is the same one that is used to create a CSR for an SSL/TLS certificate in Java.

Create Keystore and Key Pair

1. First, we’ll create a keystore and public/private key pair. Java uses files with the extension .jks (Java KeyStore) to store certificates and cryptographic keys. Enter the following command to generate a keystore and 3072-bit RSA key pair. (Replace MY-KEYSTORE.jks with the name you would like the file to have.)

   keytool -genkeypair -alias codesigning -keyalg RSA -keysize 3072 -keystore MY-KEYSTORE.jks

2. You will be presented with a series of prompts. First, create and verify a password for the keystore, then enter and verify the information requested. (Replace the values shown in all-caps with your own information.)

   Enter keystore password:  
   Re-enter new password: 
   What is your first and last name?
     [Unknown]:  FIRSTNAME LASTNAME
   What is the name of your organization?
     [Unknown]:  COMPANY
   What is the name of your City or Locality?
     [Unknown]:  CITY
   What is the name of your State or Province?
     [Unknown]:  STATE
   What is the two-letter country code for this unit?
     [Unknown]:  US
   Is CN=FIRSTNAME LASTNAME, OU=DEPARTMENT, O=COMPANY, L=CITY, ST=STATE, C=US correct?
     [no]:  yes

3. The keystore file has been generated and you’re ready to create a CSR.

Generate CSR

1. Enter the following command to generate a CSR from the keystore we just created. (Replace MY-KEYSTORE.jks with the value you used when creating the keystore and MY-CSR.csr with the name you want to use for the CSR.)

   keytool -certreq -alias codesigning -file MY-CSR.csr -keystore MY-KEYSTORE.jks

2. Enter the password you created when generating the keystore.

   Enter keystore password:

3. The CSR has been created. If you are ready to order your certificate from SSL.com, open the file in a text editor to copy and paste into the CSR field when ordering. The contents of the file will look something like the example shown below:

   -----BEGIN NEW CERTIFICATE REQUEST-----
   MIIC5TCCAc0CAQAwcDELMAkGA1UEBhMCVVMxDjAMBgNVBAgTBVNUQVRFMQ0wCwYD
   VQQHEwRDSVRZMRAwDgYDVQQKEwdDT01QQU5ZMRMwEQYDVQQLEwpERVBBUlRNRU5U
   MRswGQYDVQQDExJGSVJTVE5BTUUgTEFTVE5BTUUwggEiMA0GCSqGSIb3DQEBAQUA
   A4IBDwAwggEKAoIBAQCrRyk8VLs1THls+vfz0YtMJ3qYYl4c5c499d1YSbfQHa6L
   kIYhKTxvgdtbD+ePDigKB40CpeuMp5Yu8R6g2YIVBpGMrejAZYAmrzs6tfjpelh0
   ocSDwYr7H8qQ9jq6MfZTu6J7EjS5RMODB6MVq1usKg3H866xbi6lqAtcktEF+zlM
   4FW9Tm3H/DW2G7EnTjlMPzgaXNIU7lLar7YAWPJgv83NV8lQNCDW4lFlZLWBU95r
   YkJ4gfWUFUyPc+AiGbsyDdrVjPvF5yaebnFDrwheFaWeTTigSfLY688G7bpA8VvE
   lKioCl8nlJlc9HOBNKKdhs4qEtF0BwSE8tOgbkWPAgMBAAGgMDAuBgkqhkiG9w0B
   CQ4xITAfMB0GA1UdDgQWBBTmVpJp824krUaJKrQNhsSbVjJA1jANBgkqhkiG9w0B
   AQsFAAOCAQEALlux89RkXyHN4PQqQHbShSeTTWLURII+F+OSK9N1RS5l8V7AMcRM
   wvOkPP7JBRCKiaFGTW+5vcLQNnWRqQZMe0I4E0jzhL2gGsdChPIJy9Jwgn3Rzxmw
   8V0lBY1SHQ9LKgSK0jIer3PQhXHDJlE2g2Dx8nJ4WJk7l2OTF9Kkly9hg8MOQdeg
   VIcs3HLsVI9Cwd6UHRT6ruKL3+bRgEcb6qj+qcrKHkzN7KXbOEznd10nAm87wENS
   mTb012ZFMlpUDvPNAHQgoGJ6slA+pIoH1fvrkosjql7R/H7Q+onm37Qa6d9L2ZqM
   MhgNpNWVwI0UBU4Xy4p9oUCJnvHhQ7U+3w==
   -----END NEW CERTIFICATE REQUEST-----

Order and Retrieve Certificate

1. Follow the steps shown in Ordering and Retrieving Code Signing Certificates through step 24. Rather than immediately clicking the Generate Certificate button, check the box labeled I have my own CSR.
   
2. Paste your CSR into the form field and click the Generate Certificate button.
   
3. Click the Download button and save the .crt file in the same place you generated your keystore.
   

Import Certificate into Keystore

1. Use the following command to import the certificate into your Java keystore file. (Replace MY-CERTIFICATE.crt and MY-KEYSTORE.jks with the actual filenames.)

   keytool -importcert -file MY-CERTIFICATE.crt -keystore MY-KEYSTORE.jks -trustcacerts -alias codesigning

2. Enter the keystore password when prompted.

   Enter keystore password:  

3. Your certificate is installed in the keystore and you are ready to start signing files.

   Certificate reply was installed in keystore

Sign Files with Jarsigner

1. Use the following command to add a time-stamped digital signature to a .jar file. (Replace /PATH/TO/MY-KEYSTORE.jks and MY-JAR.jar with the actual filenames you are using. If you used a different alias when setting up your keystore, substitute it for codesigning in the command.)

   jarsigner -tsa http://ts.ssl.com -keystore MY-KEYSTORE.jks MY-JAR.jar codesigning

   Note: It is also possible to sign your .jar files directly with an un-converted PFX file by adding the -storetype pkcs12 flag to the jarsigner command.
   
   
   Note: By default, SSL.com supports timestamps from ECDSA keys.
   
   If you encounter this error: The timestamp certificate does not meet a minimum public key length requirement, you should contact your software vendor to permit timestamps from ECDSA keys.
   
   If there is no way for your software vendor to allow for the normal endpoint to be used, you can use this legacy endpoint http://ts.ssl.com/legacy to get a timestamp from an RSA Timestamping Unit.
2. Enter the keystore password at the prompt.

   Enter Passphrase for keystore: 

3. The file is now signed. You can verify the signature with the following command:

   jarsigner -verify -verbose MY-JAR.jar

4. If your file was successfully signed, the output of the command should include this line:

   s = signature was verified
   

IV, OV, and EV Code Signing with YubiKey

Configuration

Install PKCS#11 Driver and Create eToken.cfg File

Windows

1. Install OpenSC by following the instructions in OpenSC’s Windows Quick Start.
2. Locate the OpenSC PKCS#11 driver. The default install location is C:\Program Files\OpenSC Project\OpenSC\pkcs11\opensc-pkcs11.dll.
3. Create a configuration file and save it in a convenient location (like your home directory). The filename is arbitrary, but in this guide we will use yubikey-pkcs11-java.cfg. The file should contain the following information:

   name = OpenSC-PKCS11
   description = SunPKCS11 via OpenSC
   library = C:\Program Files\OpenSC Project\OpenSC\pkcs11\opensc-pkcs11.dll
   slotListIndex = 0

macOS

1. Install OpenSC. If you use Homebrew as a package manager, you can install OpenSC with the following command:

   brew install opensc

2. Locate the OpenSC PKCS#11 driver. If you installed using Homebrew, the file should be available at /usr/local/lib/opensc-pkcs11.so.
3. Create a configuration file and save it in a convenient location (like your home directory). The filename is arbitrary, but in this guide we will use yubikey-pkcs11-java.cfg. The file should contain the following information:

   name = OpenSC-PKCS11
   description = SunPKCS11 via OpenSC
   library = /usr/local/lib/opensc-pkcs11.so
   slotListIndex = 0

Sign Files with Jarsigner

1. Use the following command to add a time-stamped digital signature to a .jar file. (Replace MY-JAR.jar with the actual filename you are using.)

   jarsigner -tsa http://ts.ssl.com -providerClass sun.security.pkcs11.SunPKCS11 -providerArg yubikey-pkcs11-java.cfg -keystore NONE -storetype PKCS11 MY-JAR.jar "Certificate for PIV Authentication"

2. Enter your YubiKey PIN at the passphrase prompt.

   Enter Passphrase for keystore: 

3. The file is now signed. You can verify the signature with the following command:

   jarsigner -verify -verbose MY-JAR.jar

4. If your file was successfully signed, the output of the command should include this line:

   s = signature was verified