Securing Your Java ARchive (JAR) Files

As a standardized development platform, Java has tools that support securing its “distributables.” For Java ARchive (JAR) files, the concept is called JAR signing. Signing a JAR is no different from signing a document; the signature merely verifies that the JAR is valid content and you are aware of what is in it. When publishing an application over the Internet or simply developing applications that can be run in an Internet environment, employing JAR signing can ensure security.

How Does Signing Work?

Signing is a digital method of telling the user of a file that you are the creator or that you are aware of its contents and that they are safe to use. The most important requirement is for a mechanism to indicate that the contents of the file have not changed or been modified. When the user knows that the file is from a trusted source, he or she can rely on it for the features that it offers.

As an example, say you are monitoring the stock market using an online application, maybe an applet. While the applet is just displaying data, you are absolutely fine with it. However, at some point, the applet requests permission to save content and write to your disk. Granting permission for this operation seems risky, because you don’t know what the applet will do to your local file system. You are safe though, because by default applets are controlled by the Java runtime, and not allowed to perform any operation (such as writing a file, modifying contents of files, etc.) on a local system.

However, suppose you want the applet to write to your disk in this case. That brings up the question of credibility; you would provide or grant permissions to the applet to perform activities on the local system if you knew its source. Enter the public and private key infrastructure, which resolves this trust issue. The public key (which, as its name indicates, is available publicly) can verify a signature made by a private key, and a private key can be verified only by a corresponding public key.

But how can you be sure the public key is from a trusted source, as it claims? The verification process closes the loop here. Companies specialize in the verification business and support this requirement. These trustworthy companies award certificates that declare who owns a given public key.

Getting back to JARs, when a JAR is signed, the public key becomes part of it. Anyone who wants to use the JAR can rely on the public key to verify the JAR’s trustworthiness and to be doubly sure that the public key is using a certificate.

To summarize, if your application needs the capability to access resources outside the JVM, sign it. The user can then decide to grant your application the required permission to perform its intended actions.

Signing a JAR and Creating a Key

To sign a JAR file and generate the key, you use the jarsigner and keytool commands, respectively. The following instructions will walk you through using the jarsigner with appropriate syntax to sign a JAR file and using the keytool to generate the key. You will understand more about these commands as you progress.

The steps involved in this exercise are, in short:

1. Generating a key
   
2. Signing the JAR file
   
3. Verifying the signed JAR file

Generating a Key

As previously mentioned, you use the keytool command to generate a key. The following command generates a keystore file. In this case, you will generate the file as mykeystore, which is the value specified for the –keystore option.

keytool -genkey -alias myalias -keystore mykeystore

This command results in a series of questions, which you can answer at your discretion. However, you must remember the answers that you provide. Here is a snapshot of the question set with the answers that I choose to provide.

Enter keystore password:  password

What is your first and last name?

  [Unknown]:  first name

What is the name of your organizational unit?

  [Unknown]:  organization

What is the name of your organization?

  [Unknown]:  organization name

What is the name of your City or Locality?

  [Unknown]:  city name

What is the name of your State or Province?

  [Unknown]:  state name

What is the two-letter country code for this unit?

  [Unknown]:  IN

Is CN=first name, OU=organization, O=organization name, L=city name, ST=state na

me, C=IN correct?

  [no]:  yes

Enter key password for <myalias>

        (RETURN if same as keystore password):

The result of these answers is a keystore file named mykeystore, which is the value for the –keystore option. Notice I did not answered the last question. This allows the system to use the same password that I provided for the keystore.

Key Generation Tip

Manually creating many keystore files with different information can be tedious. Explore the keytool command’s capability to accept a file as input that has the needed information for a command’s arguments. It is a simple function that you can master in a short amount of time. Also, you can provide a different password for <myalias> and observe how it works.

Signing the JAR File

This section uses the MyApplication.jar file from the code download for signing purpose. The arguments in the jarsigner command are self-explanatory, and you will explore the results of providing incorrect values for these arguments.

Case 1

Proper use of the command with the correct values will result in the following output:

jarsigner -keystore mykeystore -storepass password -keypass password MyApplication.jar myalias

Warning: The signer certificate will expire within six months.

Case 2

Here is the command usage and output when the value for the alias is incorrect:

jarsigner -keystore mykeystore -storepass password -keypass passwor MyApplication.jar newalias

jarsigner: Certificate chain not found for: newalias. newalias must reference a valid KeyStore 
key entry containing a private key and corresponding public key certificate chain.

Notice that the value newalias is incorrect, whereas the correct one in this case is myalias (The value is provided during the key-generation process).

Case 3

Here is the command usage and output when the value for the password is incorrect:

jarsigner -keystore mykeystore -storepass password -keypass passwor MyApplication.jar myalias

jarsigner: key associated with myalias not a private key

Here, the value for password is incorrectly spelled as “passwor.” Hence, the system does not allow you to sign the JAR file. The error message is just an indication that the credentials do not match.

Verifying the Signed JAR File

You can use the –verify option in the jarsigner command to verify the integrity of the JAR file.

Case 1

Here is the command to verify the integrity of MyApplication.jar:

jarsigner -verify MyApplication.jar

jar verified.

Warning: This jar contains entries whose signer certificate will expire within six months. 
Re-run with the -verbose and -certs options for more details.

In this example, the result indicates that the JAR is verified. It also has an additional message informing the user that the certificate is expiring shortly. The user should take the appropriate action, perhaps purchase one from an authorized vendor.

Signed JAR Verification Tip

Try using the –validity option in the keytool command and exploring its usages.

Case 2

Here are the commands for verifying the integrity of MyApplication.jar using the –verbose option:

jarsigner -verbose -verify MyApplication.jar

         357 Thu Oct 01 08:00:48 PDT 2009 META-INF/MANIFEST.MF

         435 Thu Oct 01 08:00:48 PDT 2009 META-INF/MYALIAS.SF

        1095 Thu Oct 01 08:00:48 PDT 2009 META-INF/MYALIAS.DSA

           0 Wed Sep 16 15:56:40 PDT 2009 META-INF/

           0 Wed Sep 16 15:55:22 PDT 2009 com/

           0 Wed Sep 16 15:55:22 PDT 2009 com/mycomp/

           0 Wed Sep 16 15:55:22 PDT 2009 com/mycomp/demo/

sm       165 Tue Sep 15 17:39:38 PDT 2009 com/mycomp/demo/MyApplication.java

sm       465 Tue Sep 15 17:40:00 PDT 2009 com/mycomp/demo/MyApplication.class

           0 Wed Sep 16 15:55:22 PDT 2009 demo/

           0 Wed Sep 16 15:55:22 PDT 2009 images/

           0 Wed Sep 16 15:55:22 PDT 2009 lib/

sm        43 Wed Sep 16 15:56:38 PDT 2009 main-class-file
  s = signature was verified

  m = entry is listed in manifest

  k = at least one certificate was found in keystore

  i = at least one certificate was found in identity scope
jar verified.
Warning: This jar contains entries whose signer certificate will expire within six months. 
Re-run with the -verbose and -certs options for more details.

The information displayed is quite comprehensive, but you can use it as desired.

Case 3

Here is the command for verifying an unsigned JAR file:

jarsigner -verify MyApplication.unsigned.jar

jar is unsigned. (signatures missing or not parsable)

The cases covered here are some of the most widely used test cases. Nevertheless, you likely will think of many other cases. Use those to explore some of the other security capabilities of JAR signing.

Code Download

JAR Signing_src

For Further Reading

“jar – The Java Archive Tool” (from java.sun.com)

“keytool – Key and Certificate Management Tool” (from java.sun.com)

About the Author

Sridhar M S is a Java developer from Bangalore, India. He holds a master’s degree in Computer Science.