Entrust Certificate Services. Java Code Signing. User Guide. Date of Issue: December Document issue: 2.0

Entrust Certificate Services

Java Code Signing

User Guide

Date of Issue: December 2014

Document issue: 2.0

Copyright © 2009-2014 Entrust. All rights reserved.

Entrust is a trademark or a registered trademark of Entrust, Inc. in certain countries. All Entrust product names and logos are trademarks or registered trademarks of Entrust, Inc. in certain countries. All other company and product names and logos are trademarks or registered trademarks of their respective owners in certain countries.

This information is subject to change as Entrust reserves the right to, without notice, make changes to its products as progress in engineering or manufacturing methods or circumstances may warrant.

Export and/or import of cryptographic products may be restricted by various regulations in various countries. Export and/or import permits may be required.

Obtaining technical support

For support assistance by telephone call one of the numbers below:

• 1 (866) 267-9297 in North America • 1 (613) 270-2680 outside North America You can also email Customer Support at:

Java Code signing

Signing Java archive files

This guide contains information about signing Java archive (JAR) files. Sections in this guide include:

• “Obtaining and using a code signing certificate”

• “Verifying the authenticity of the software”

Entrust offers customers X.509 certificates to sign JAR files. User guides containing information about:

• Entrust code signing certificates for Windows macros and Visual Basic files • Entrust code signing certificates for Microsoft® Authenticode files

are available from http://www.entrust.net/ssl-resources/whitepapers.htm. Signing your code increases user confidence in its authenticity. Most operating systems include the root certificates of major publicly rooted Certificate authorities in their certificate stores and update the stores periodically. Because Entrust certificates are publicly rooted, the Entrust root certificate should be installed on users’ machines, by default. You should not need to distribute the root certificate to your users if their operating systems are up-to-date.

Obtaining and using a code signing certificate

If you do not have a Java code signing certificate, you must obtain one before you can sign JAR files. To buy and use an Entrust certificate:

• Create a certificate signing request (CSR) as outlined in “Creating a certificate signing request (CSR)”.

• Buy the certificate from Entrust using the Web site mentioned in “Obtaining a certificate from Entrust”.

It takes time to verify the information that you include with your certificate request. Please allow three to five days for Entrust to verify your information. • Import the certificate into your keystore as outlined in “Importing the

certificate into your keystore”.

• If you have not already done so, create a JAR file of your work as outlined in

“Creating JAR files”.

• Sign the file using your certificate as outlined in “Signing a JAR file”.

Required software

Download and install the Java developer’s kit (JDK). The JDK is available free of charge from www.oracle.com.

Creating a certificate signing request (CSR)

To obtain a certificate you must create a certificate signing request using software installed on your computer. The JDK includes the keytool application that can be used to create a CSR.

To be verifiable, each certificate must carry specific information about the entity applying for the certificate. This information is incorporated into the CSR and used by the CA to create the applicant’s certificate.

To create a CSR

1 If you have not already done so, create a keystore using the keytool application from the JDK.

a Open a Command Prompt window.

b Type the following command into the window:

<path to keytool>\keytool -genkey -keyalg rsa -keysize 2048 -alias <friendly_name> -dname

"CN=<name_you_want_to_appear>,O=<company_name>,C=<countr y_code>,E=<your_email_address>" -keystore

Where:

<path to keytool> is the path to the keytool executable in the JDK. -genkey is the generate key option.

-keyalg rsa indicates the rsa algorithm

-keysize 2048 indicates the size of the key in bits

-alias <friendly_name> is the friendly name that are using for your certificate

-dname is the information used to create the distinguished name (DN) -keystore is the name you would like to use for this keystore -storepass is the password of the store

For example:

C:\JDKS\jdk1.6.0_03\bin\keytool -genkey -keyalg rsa -alias MyAlias -dname

"CN=MyName,O=MyCompany,C=CA,E=MyAddress@example.com" -keystore CodeCertStore -storepass P!flW23j

Note: Memorize or securely record the name and password for your keystore.

You will use these passwords in subsequent procedures.

2 Create a certificate signing request (CSR).

a Type the following command into the window:

<path to keytool>\keytool -certreq -alias <friendly_name> -file <filename> -keystore <name_of_keystore>

Attention: For Java keystore the alias names are very important. You can pick

any alias name of your choice but make sure that you use the same alias name when you create the CSR (step 1 b and step 2 a) and later when you install the java code signing certificate in “To import your certificates into your

keystore”step 4. That particular alias will be your private key alias. Make sure that you do not use the private key alias when you import the Root and the Chain certificates.

For example:

C:\JDKS\jdk1.6.0_03\bin\keytool -certreq -alias MyAlias -file certreq1.pem -keystore CodeCertStore

b Enter the keystore password at the prompt.

Keytool creates a file with the specified name (certreq1.pem, in the example) containing a string similar to the following example.

---BEGIN NEW CERTIFICATE REQUEST---MIIBsTCCARoCAQAwcTELMAkGA1UEBhMCQ0ExEDAOBgNVBAgTB09udGFyaW8xDzANBg NVBAcTBk90dGF3YTEUMBIGA1UEChMLZXhhbXBsZS5jb20xFDASBgNVBAsTC0RldmVs b3BtZW50MRMwEQYDVQQDEwpBbGljZSBHcmF5MIGfMA0GCSqGSIb3DQEBAQUAA4GNAD CBiQKBgQCaxmlZnlKq3nZ0VbIsNMwHgdNilnkQlkQTpSzglM3fdUZmF9oRJnYFtBmi gLSXMhoypi4YkOgRLZT5wnnwh1H2UPWpQk3hCNyK0lchNsmTrZKnJEzku24dGXZ/H6 UXlyvGM3bugw+My0/UFeB4J/1DEN/P3Z3QVJ7614Squ+zrawIDAQABoAAwDQYJKoZI hvcNAQEFBQADgYEAdjxeKxzNKQ9LTY+FUXdVv3Lc35jq5Og2O82xhzmYfnYBUkOgOY KiQL+gY2Gm/IkLYceqDfbhBHI6WElmaMtLntbpFXgH9n/C9gLHTbPSQJbGXkU0985i J8O6au4DOPOxegBH+Zflb5mztChzD7+sKVYYI65/XatUtYv3+wIlnKk=

---END NEW CERTIFICATE

REQUEST---This is the string that you will use to obtain a certificate

Obtaining a certificate from Entrust

To obtain a code signing certificate from Entrust, log into the Entrust Web site URL

https://buy.entrust.net/buy. Code signing certificates can only be purchased by customers who have registered for the Entrust Certificate Management Service (CMS). For information about enrolling in the CMS see the Entrust Certificate

Management Service Enrollment Guide. For information about buying and managing code signing certificates see the Entrust Certificate Management Service User Guide. When you retrieve the code signing certificate from the Entrust site, you must also get the root certificate and the chain certificate. These are available from the site by clicking the chain certificate and root certificate tabs respectively and copying them to separate files.

Importing the certificate into your keystore

Attention: Back up your keystore before importing certificates.

Use the keytool application (part of the JDK) to import the three certificates that you downloaded from Entrust into your keystore.

Attention: The order is important. Import the certificates in the order shown in

tis procedure—root certificate, intermediate certificate, then signing certificate.

To import your certificates into your keystore 1 Import the root certificate, issued by Entrust.

Note: This certificate may already exist in your CAcerts store, however you

should re-import the root certificate, even if it already exists. From the command-line, type:

<Path to keytool>\keytool -import -trustcacerts -alias <friendly_name_of_root_certificate> -file

<name_of_root_certificate_file> -keystore <name_of_keystore> Where:

• <Path to keytool> is the location of the keytool executable in the JDK file structure.

• -import specifies that keytool should import the certificate.

• -alias is the friendly name of the certificate. Be sure that the alias used for each certificate is unique.

Attention: Be sure that the alias used for the root and the alias used for the

intermediate certificates are unique. Also, do not use the alias that you used for your private key. Re-using the alias that you used for your private key will damage it.

• -file indicates the certificate being imported.

• -keystore is the name of the keystore that you created in “Creating a certificate signing request (CSR)”.

2 Import the cross chain certificate, issued by Entrust. From the command-line type:

<Path to keytool>\keytool -import -trustcacerts -alias <friendly_name_of_chain_certificate> -file

<name_of_cross_certificate_file> -keystore <name_of_keystore>

3 Before importing the java code signing certificate, you can (optionally) check the contents of your keystore using the command:

keytool -list -v -keystore <name_of_keystore> The contents of the keystore should be displayed.

4 Import the java code signing certificate, issued by Entrust.

<Path to keytool>\keytool -import -alias <alias of your certificate> -file <certificate name> -keystore

<name_of_keystore>

Creating JAR files

Before you can sign a Java applet’s files, you must bundle them into a JAR file. The Java SDK contains a tool for creating JAR bundles. It can be used from the command prompt.

If you are familiar with creating TAR bundles you will find creating a JAR bundle is very similar.

Creating and checking the JAR file

1 Create a directory (or directory and subdirectories—depending on the directory structure you require) for your applet’s files and place them in that location.

2 From the directory (or the top level of the directory structure that you created), run the jar tool. The syntax of the command is:

<path to jar tool>\jar <options> <path to output directory>\<name of jar file>

For example:

<path_to_JDK>\jdk1.6.0_03\bin\jar cvf C:\test.jar Where:

• C:\JDKS\jdk1.6.0_03\bin\ is the location of the jar tool (jar.exe) • cvf stands for:

– create (create file)

– verbose (see all messages from the tool) – file (use the specified filename and location)

Note: For a complete list of options see the man pages for jar.

• C:\test.jar is the name and location that you specify for the resulting JAR file.

The example creates the JAR file C:\test.jar in the location specified.

3 Optionally, verify the newly created JAR file using the jar tool. For example, <path_to_JDK>\jdk1.7.0_17\bin\jar tvf C:\test.jar Where:

• <path_to_JDK>\jdk1.7.0_17\bin\ is the location of the jar tool executable (jar.exe).

• tvf stands for: – test (test file)

– verbose (see all messages from the tool) – file (use the specified filename and location)

Testing ensures that the JAR file has the correct content and structure.

Signing a JAR file

Use the JDK keytool and jarsigner applications to sign your code. These instructions explain how to sign a JAR file.

To sign a JAR file

1 Optionally, check that the keytool application (the JDK application used to sign the applet), can read your keystore.

a Open a command prompt.

b Enter the command:

<path to keytool>\keytool -list -keystore <keystore_Name> For example:

<path_to_JDK>\jdk1.7.0_17\jre\bin\keytool -list -keystore codecertstore

c Enter the password when prompted.

The keytool lists information about entries in your keystore.

2 To sign the JAR file, you need the alias (friendly name) of the key entry that you are using. If you do not know the alias of the key entry use the following procedure.

a To obtain the alias, use keytool’s list and verbose options:

<path to keytool>\keytool -list -keystore <keystore_name> -v

For example:

<path_to_JDK>\jdk1.7.0_17\jre\bin\keytool -list -keystore codecertstore -v

b Enter the password when prompted.

Keytool lists information about the keystore including the alias (friendly name) of the certificates.

3 To sign the JAR file, use the jarsigner tool included in the JDK. Include the timestamp option if you want to timestamp the signature. Enter the following command:

<path_to_jarsigner>\jarsigner -tsa

<keystore_name> <path_to_JAR_file>\<JAR_file_name>.jar <alias_of_cert>

Where:

• <path_to_jarsigner> is the path to the jarsigner tool • -tsa adds the timestamp option

• <URL_of_the_Entrust_timestamping_authority> is the URL of the Entrust timestamp server (RFC3161 compliant)

– to use a SHA1 hash in the timestamp enter the value

http://timestamp.entrust.net/TSS/RFC3161sha1TS

– to use a SHA2 hash in the timestamp enter the value

http://timestamp.entrust.net/TSS/RFC3161sha2TS

• <keystore_name> is the name of the keystore where the certificate is located

• <path_to_JAR_file>\<JAR_file_name>.jar is the path to and name of the jar file being signed

• <alias_of_cert> is the alias you obtained in Step 2. For example:

<path_to_JDK>\jdk1.7.0_17\bin\jarsigner -tsa

http://timestamp.entrust.net/TSS/RFC3161sha1TS -keystore CodeCertStore \work\MyProject\MyApplet.jar MyAlias

a Enter the password when prompted. You have signed a JAR file.

To verify the signature

1 Run Jarsigner tool using the verify switch; for example:

<path_to_JDK>\jdk1.7.0_17\bin>jarsigner -verify -verbose MyApplet.jar

Signing JAR files

When the code is signed, several pieces of information are added to the file. This information is used when the code is downloaded though your browser to authenticate the author of the code and to check for tampering.

The bundle that is used to verify the authenticity of the code is created during two sequences of events.

• A mathematical representation of the code, called a hash, is created and signed.

• The hash and signature are timestamped, hashed (with the timestamp) and signed again.

The timestamp and second signature are applied by a timestamping authority (TSA). Timestamping Authorities are usually maintained by a third party (such as Entrust) that can ensure the validity of the timestamp. The entire sequence takes place as follows:

• The code is passed through a hashing algorithm creating a hash of the file. The hash is an exact numerical representation of the file. The hash is only reproducible using the unaltered file and the hashing algorithm that was used to create the hash. The hash is bundled with the file.

• The hash is signed using the signer’s private key.

– Information identifying the creator of the signature is drawn from the signer’s certificate and incorporated into the signature.

– Information about the CA or CAs that signed the signer’s certificate is drawn from the signer’s certificate and incorporated into the signature. • The signer’s public key is added to the bundle.

• The signature is sent to the timestamping authority (TSA).

– The TSA adds a timestamp to the bundled information and computes a new hash.

– The TSA signs the new hash with its private key creating a new bundle of information.

– The timestamped bundle, original bundle that was sent to the TSA and the time stamp are re-bundled with the original code.

Figure 1: The code-signing process for Java code

JAR signing process

001011 Hash of code Private key Code Code Timestamping Authority Public key Code Certificate

Verifying the authenticity of the software

When the end user’s browser loads the code, it checks the authenticity of the software using the signer’s public key, signature and the hash of the file. If you timestamp the signature, the timestamp is checked using a similar process.

If both the timestamp and the signature are verified successfully, the browser accepts the code as valid. If either the timestamp or signature are not successfully verified, the browser reacts by warning the user or rejecting the code, depending on the level of security being used.

Note: Your end users only need the Entrust Public root certificate to verify the

authenticity of the software you sign. This certificate is usually installed with the operating system (OS) and updated as required by the by the OS manufacturer. You should not need to distribute certificates to your users if their software is up-to-date.

Verifying the timestamp

The following sequence of events is used to verify the timestamp.

• The timestamp is added to the bundled signature information and the combined signature and timestamp are hashed.

• The Timestamping Authority’s public key is applied to the timestamped signature block revealing the hash calculated by the TSA.

• The validity of the TSA’s public key is verified by checking its expiry date and consulting the revocation lists to be sure that it has not been revoked. • The two hashes are compared. If the hashes are equal, the timestamp is

considered to be valid.

Verifying the signature

The signature is verified as follows:

• The original code is passed through a hashing algorithm creating a hash. • The public key of the designer or publisher is extracted from the bundle and

applied to the signature information. Applying the public key reveals the hash that was calculated when the file was signed.

• The expiry date of the public key is checked.

• The public key is checked against the revocation lists to ensure that it is valid. • The two hashes are compared. If the hashes are identical, the signature is

• If the file is considered to be valid it is accepted by the browser. If the file is not considered to be valid the browser takes the security measure

Figure 2: Verifying the authenticity of the code Code ` 001011 Hash from signer’s public key 001011 Hash from signer’s private key

Signer’s Public key

Code Revocation list

Check Timestamp

TSA Public key

Original Hash from TSA’s private key

001011 Revocation list Nov 6 2009 001011 Hash of signature and timestamp Nov 6

20 09 Create hash using

TSA public key

TSA Public key

001011 Hash of signature and timestamp Nov 6 20 09 Check Signature

Create hash using signer’s public key

Signer’s Public key

001011

Hash from signer’s public