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 EV 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
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.
.jar
files directly with an un-converted PFX file by adding the -storetype pkcs12
flag to the jarsigner
command.- 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.
- Import the PFX into a new keystore with the same password by using the command below. (Replace
MY-CERTIFICATE.p12
andMY-KEYSTORE.jks
with the actual name of your PFX file and the file name you want to give your keystore. Note also that thedestalias
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 be1
, but you can confirm this by running the commandkeytool -list -v -storetype pkcs12 -keystore MY-PFX.P12
and checking the value shown forAlias name
. - 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
- 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 2048-bit RSA key pair. (ReplaceMY-KEYSTORE.jks
with the name you would like the file to have.)keytool -genkeypair -alias codesigning -keyalg RSA -keysize 2048 -keystore MY-KEYSTORE.jks
- 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 organizational unit? [Unknown]: DEPARTMENT 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
- The keystore file has been generated and you’re ready to create a CSR.
Generate CSR
- 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 andMY-CSR.csr
with the name you want to use for the CSR.)keytool -certreq -alias codesigning -file MY-CSR.csr -keystore MY-KEYSTORE.jks
- Enter the password you created when generating the keystore.
Enter keystore password:
- 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
- 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.
- Paste your CSR into the form field and click the Generate Certificate button.
- Click the Download button and save the
.crt
file in the same place you generated your keystore.
Import Certificate into Keystore
- 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
- Enter the keystore password when prompted.
Enter keystore password:
- 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
- Use the following command to add a time-stamped digital signature to a
.jar
file. (Replace/PATH/TO/MY-KEYSTORE.jks
andMY-JAR.jar
with the actual filenames you are using. If you used a different alias when setting up your keystore, substitute it forcodesigning
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 thejarsigner
command. - Enter the keystore password at the prompt.
Enter Passphrase for keystore:
- The file is now signed. You can verify the signature with the following command:
jarsigner -verify -verbose MY-JAR.jar
- If your file was successfully signed, the output of the command should include this line:
s = signature was verified
EV Code Signing with YubiKey
Configuration
Install PKCS#11 Driver and Create eToken.cfg File
Windows
- Install OpenSC by following the instructions in OpenSC’s Windows Quick Start.
- Locate the OpenSC PKCS#11 driver. The default install location is
C:\Program Files\OpenSC Project\OpenSC\pkcs11\opensc-pkcs11.dll
. - 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
- Install OpenSC. If you use Homebrew as a package manager, you can install OpenSC with the following command:
brew install opensc
- Locate the OpenSC PKCS#11 driver. If you installed using Homebrew, the file should be available at
/usr/local/lib/opensc-pkcs11.so
. - 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
- Use the following command to add a time-stamped digital signature to a
.jar
file. (ReplaceMY-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"
- Enter your YubiKey PIN at the passphrase prompt.
Enter Passphrase for keystore:
- The file is now signed. You can verify the signature with the following command:
jarsigner -verify -verbose MY-JAR.jar
- If your file was successfully signed, the output of the command should include this line:
s = signature was verified