Using javakey

Contents

1. Summary
2. Steps for creating and signing a JAR file, short version
3. Steps for creating and signing a JAR file, longwinded version
4. Example certificate directive file
5. Example signing directive file
6. javakey help
7. jar help

Summary

A JAR file is an archive of files; JAR stands for "Java ARchive." JAR is defined to be ZIP+manifest, where ZIP is the standard archiving format. JAR includes a manifest file, which stores meta-information about the contents of the archive.

The manifest is defined by the manifest spec at http://java.sun.com/products/jdk/1.1/docs/guide/jar/manifest.html.

A Signed JAR file includes at least one signature file, in addition to the manifest file. There is one signature file per signer.

For example, if you have a set of 3 files that make up an applet, then the signed JAR file for the applet will be one file. That one file contains 5 files:

• the original 3 files that make up the applet
• the manifest file
• the signature file

Steps for creating and signing a JAR file, short version

1. Set up path

   	% setenv PATH ~/java/bin:$PATH
   

2. Create an identity.

   	% javakey -cs "duke" true
   

3. Generate DSA key pair for the identity.

   	% javakey -gk "duke" DSA 512 duke_pub duke_priv
   

4. Generate certificate

   Create a cert_directive file (See example, below)

   	% javakey -gc cert_directive
   

5. Create a jar file (syntax is like tar.)

   	% jar cf demo.jar PhoneServlet.class
   

6. Sign the jar file

   Create a sign_directive file (See example, below)

   	% javakey -gs sign_directive demo.jar
   

   The signed jar file will be written to a file named "demo.jar.sig."

   Rename this file so that it has the suffix .jar, so that it can be read and unjar-ed by the applet classloader. By default, the jar tool doesn't overwrite your original jar file.

   	% mv demo.jar.sig demo.jar
   

7. Getting more info

   Online quick help

   	% javakey -h
   
   	% jar
   

   Looking inside the identity database

   	% javakey -ld
   	% javakey -li "duke"
   
   

   Looking inside a JAR file

   	% jar tvf demo.jar
   

Steps for creating and signing a JAR file, longwinded version

1. Make sure you have the JDK 1.1 bin on your search path. You can download JDK 1.1 from http://java.sun.com/products/jdk/1.1.

   	% setenv PATH ~java/bin:$PATH
   

2. Create an identity.

   	% javakey -cs "duke" true
   

   This "identity" is the unique name for the signer. The identity lives in the identity database for the JDK that you are using. For JDK 1.1, this is found in /home/userid/identitydb.obj.

   You can modify the location of the identity database, identitydb.obj, by adding the following system property to the $DISTRIB/lib/security/java.security properties file. $DISTRIB refers to the path name of the directory where JDK 1.1 is installed. Read the policy recommendations section, for information on how to set up and maintain an identity database for your organization.

   	     identity.database=/yourSecureDirectory/identitydb.obj
   

3. Generate DSA key pair for the identity.

   	% javakey -gk "duke" DSA 512 duke_pub duke_priv
   

   You need to tell javakey

   • the unique name of the signer. In this case, "duke"
   • the name of the algorithm you want to use. In JDK 1.1, javakey only supports DSA.
   • the size of the key you want to use. In this case, we're using 512.

   Optionally, you can choose to save a copy of the public key and the private key in files on your local disk. In this example, "duke_pub" is the name of the file where the public key half of the DSA key pair is stored. "duke_priv" is the name of the file where the private key half of the DSA key pair is stored.

   Private keys should be guarded with the utmost caution. They must be stored on secured areas of the local file system and not exposed. The private key is used to sign the file. The public key is used to verify the signature.

   Cryptographic algorithms that use public-private key pairs are known as "public key algorithms." The key pair used for an algorithm is particular to that algorithm. That is, DSA key pairs can only be used with the DSA algorithm, and RSA key paris can only be used with the RSA algorithm.

   DSA stands for "Digital Signature Algorithm." It is the algorithm used by DSS, "Digital Signature Standard", a government standard developed by NIST and the NSA.

   RSA is the name of a popular algorithm used for encryption and also for signing. RSA is the initials of the three inventors, Rivest, Shamir, Adleman. The RSA algorithm is patented and the patent is held by RSA DSI (RSA Data Security Inc.) JDK 1.1 provides an implementation for DSA but not for RSA, due to the patent situation.

   Key pairs can also be used to encrypt files, when they are used with a matching encryption algorithm. A DSA key pair can only be used for signing. An RSA key pair can be used either for signing or for encryption.

   This is an oversimplification. For more details on signing and cryptography, refer to "Applied Cryptography" by Bruce Schneier.

4. Generate a certificate

   	% javakey -gc cert_directive
   

   First, create a cert_directive file. Some important arguments for creating a certificate are described in the cert_directive file. Make a copy of the cert_directive file, and modify it.

   The arguments are described as name/value pairs in a Java properties file.

   The arguments you need to specify are

   • the unique name of the issuer of the certificate
   • the unique number of the certificate
   • the unique name of the subject
   • the components of the X.500 name for the subject
   • "time to live" for the certificate - start date and end date
   • serial number
   • the name of the file where the certificate will be stored

   If you don't specify a file to store the certificate, then it exists only in the identitydb.obj database. Once the cert_directive file is set up, use javakey to create the certificate:

   	% javakey -gc cert_directive
   

5. Create a JAR file.

   	% jar cf demo.jar PhoneServlet.class
   

   The tool for creating JAR files is named jar. It is distributed with JDK 1.1 Its syntax is very similar to the syntax for tar, the "tape archive" utility that is widely used in unix. Type

   	% jar
   

   on a command line by itself to see the arguments it expects.

   	puffin% jar
   	Usage: jar {ctx}[vfm] [jar-file] [manifest-file] files ...
   	Options:
   	  -c  create new archive
   	  -t  list table of contents for archive
   	  -x  extract named (or all) files from archive
   	  -v  generate verbose output on standard error
   	  -f  specify archive file name
   	  -m  include manifest information from specified manifest file
   	If any file is a directory then it is processed recursively.
   	puffin% 
   

6. Sign the JAR file using sign_directive file

   	% javakey -gs sign_directive demo.jar
   

   Important arguments used to sign the JAR file are provided in the sign_directive file. As with the certificate directive file, these are stored as name/value pairs for a Java properties file.

   Copy the sign_directive file and modify it. You need to specify four arguments

   • the unique identity of the signer
   • the unique number of the certificate
   • the certificate chaining depth
   • the name to give to the signature file

   Currently, chaining certificates is not supported, so the third argument always is set to zero, in JDK 1.1:

   	chain=0
   

   The signed jar file will be written to a file named "demo.jar.sig."

   Rename this file so that it has the suffix .jar, so that it can be read and unjar-ed by the applet classloader. By default, the jar tool doesn't overwrite your original jar file.

   	% mv demo.jar.sig demo.jar
   

7. Getting more info about what's on your system

   	% javakey -li duke
   

   prints out detailed information about the identity "duke." It will tell you that duke has a key pair and a certificate, for example, stored in your identity database (the identitydb.obj file)

   	% javakey -ld
   

   prints out detailed information about the entire identity database.

   	% jar tvf demo.jar
   

   list the contents of a jar file.

   	% jar xvf demo.jar
   

   un-jars the JAR file. The manifest file is ascii format, and readable.

Example certificate directive file

#
# 96/11/11 	@(#)cert_directive	1.3
# 

#
# This is a sample certificate directive file. 
#

# the id of the signer

issuer.name=duke

# the cert to use for the signing (this is where it gets it DN)

issuer.cert=1

# the id of the subject

subject.name=duke

# the components of the X500 name for the subject

subject.real.name=Marianne Mueller
subject.org.unit=JavaSoft 
subject.org=Sun MicroSystems
subject.country=US

# Various parameters: start and end date for validity and expiration
# of the certificate. Serial number. FIle to which to output the
# certificate (optional).

start.date=10 Dec 1996
end.date=1 Sept 1997
serial.number=1001
out.file=duke.x509

Example signing directive file

#
# 96/09/22  @(#)sigdir	1.1
# 

#
# Jar signing directive. This is the directive file used by javakey to 
# sign a jar file.
#

# Which signer to use. This must be in the system's database.

signer=duke


# Cert number to use for this signer. This determines which
# certificate will be included in the PKCS7 block. This is mandatory
# and is 1 based.  

cert=1


# Cert chain depth of a chain of certificate to include. This is
# currently not supported.

chain=0


# The name to give to the signature file and associated signature
# block.  (i.e. DUKESIGN.SF and DUKESIGN.DSA). This must be 8
# characters or less.

signature.file=dukeSig

javakey help

See also the javakey man page.

% javakey
javakey
        l       list of the identities in the database.
        c       create an new identity.
        r       remove an identity from the database.
        i       import a public key, a key pair, etc.
        g       generate a key pair, a certificate, etc.
        d       display a certficate.
 
for more information, see documentation.

The options are:

• list (l option):

  no argument

  list all identities in succint form.

  i <identity>

  list an identity in detail.

  d

  detail: list all identities in detail.

• create (c option):

  no arguments <name> {trusted}

  create a new identity.

  s <name> {trusted}

  create a new signer.

• remove (r option):

  <name>

  the name of the identity to remove

• import (i option): (<id> is the identity for which the import is done.)

  k <id> <pub>

  import a public key from a file.

  kp <id> <pub> <priv>

  import a key pair from two files.

  c <id> <cert>

  import a certificate from a file.

• generate (g option):

  k <id> <alg> <mod>

  generate a key pair.

  c <certdir>

  generate a certificate.

  s <sigdir> <file>

  generate a signature.

• display (d option):
  c <cert>
  display a certificate.

jar help

See also the jar man page.

puffin% jar
Usage: jar {ctx}[vfm] [jar-file] [manifest-file] files ...
Options:
  -c  create new archive
  -t  list table of contents for archive
  -x  extract named (or all) files from archive
  -v  generate verbose output on standard error
  -f  specify archive file name
  -m  include manifest information from specified manifest file
If any file is a directory then it is processed recursively.
puffin% 

---

Last modified: 09/28/99


java-security@sun.com