This section describes how one performs the actions of generating key pairs and self-signed certificates, signing client code, importing and exporting certificates, and finally relaxing security on a client.
This section was specifically written with JDK1.2.x’s keytool in mind, so users of JDK1.1.x will have to research their javakey program instead.
Note: This document was written for users of Windows NT. By creating directories similar to those mentioned, a Windows 9x or UNIX/Linux user should also be able to execute the steps.
Generating a Key Pair and a Self-Signed Certificate
We start off by generating a key pair. After you have logged in and
set everything up, open a DOS Prompt window. Remember to set the
path and classpath accordingly. Now change the active directory to
your ‘home directory’, which is the directory bearing your login name in
the C:\WinNT\Profiles\ directory.
cd\Winnt\Profiles\<YourLoginName>
Now use keytool to generate a key. The first parameter
tells keytool that we are generating a key. The second parameter
(-alias Peter) creates the key for a user using the alias Peter.
Note that you could, and probably should, substitute your own alias here.
keytool -genkey -alias Peter
You should first be prompted to assign a password for your keystore (a database of keys). Note that the keytool program does not substitute asterisks, or any other character, for the characters in your password, so make sure no one is peeking over your shoulder! The password must have more than 5 characters in it. Thereafter, answer all the questions regarding name, place, organisation, etc., and enter ‘y’ if the information is correct. Here is an example run of the program:
C:\>keytool -genkey -alias Peter
Enter keystore password: apples
What is your first and last name?
[Unknown]: Peter Pumpkineater
What is the name of your organizational unit?
[Unknown]: Computer Science Department
What is the name of your organization?
[Unknown]: University of Pretoria
What is the name of your City or Locality?
[Unknown]: Pretoria
What is the name of your State or Province?
[Unknown]: Gauteng
What is the two-letter country code for this unit?
[Unknown]: ZA
Is <CN=Peter Pumpkineater, OU=Computer Science Department, O=University
of Pretoria,
L=Pretoria, ST=Gauteng, C=ZA> correct?
[no]: y
Enter key password for <Peter>
(RETURN if same as keystore
password):
The key password will be used to access the keystore entry containing that key, in this case the key for Peter.
You can now check your keystore. You will have a file called .keystore in your home directory. Type:
keytool -list
Enter the keystore password. The display should be something like this:
Keystore type: jks
Keystore provider: SUN
Your keystore contains 1 entries:
peter, Tue Apr 18 21:14:01 GMT+02:00 2000, keyEntry,
Certificate fingerprint (MD5): BC:77:E9:C6:F5:F3:37:65:62:1B:03:89:E2:2E:5B:76
Note the keystore type (jks) and the certificate fingerprint(yours may
differ with the one shown above). You will need these to insure your
code is trusted by another system.
Signing Your Client Code
Create a JAR file containing all the code the client will need.
To do this, change the directory to where your class files are stored,
and enter the following command:
jar cvf MyJar.jar *.class
where MyJar.jar is the name of the JAR file created. You can
now delete all the class files (to prevent confusion of the applet browser).
Note that you can delete the main applet class, as the browser will load
it from the JAR in any case. Remember to add the archive=”MyJar.jar”
parameter to the applet tag in your HTML documents. To view the content
of the Jar file type:
jar tf Write.jar
Now we need to sign the JAR file, so that the code inside is trustable,
as it were. To do this, we use the jarsigner utility, as well as
the key we generated in the first step.
jarsigner MyJar.jar Peter
Provide the keystore password and the alias password you provided earlier.
This time, when you list the contents of the JAR file, you should see
the files Peter.SF and Peter.DSA, which were added by the jarsigner utility
(the name Peter will obviously differ from keystore to keystore).
Now move the JAR file to your home directory.
Importing and Exporting Certificates
You need to export your certificate so that a potential client will be able to import the certificate into their own keystore. This, in essence, is how the client expresses trust for you. Note that this certificate is self-signed, whereas real life applications would make use of a proper Certificate Authority and a Certificate Signing Request (VeriSign is an example of a CA).
Use keytool to export a copy of your certificate:
keytool –export –alias Peter –file Peter.cer
The third parameter tells keytool where to save the certificate.
Normally, importing a certificate will take place on a completely different machine. However, for the purposes of demonstration, you can do it on your own machine. To do this, you must delete the key entry for Peter:
keytool -delete –alias Peter
In the outside world, a client would have been supplied with the certificate file, which he imports into his keystore, and then verifies that the fingerprint on the certificate corresponds to the one he was supplied with by you (telephonically, probably).
Now, to import the certificate type:
keytool –import -alias Peter –file Peter.cer
When asked, say yes to trust the certificate. Now list the content
on the keystore. Note that Peter is now a trustedCertEntry.
Relaxing Security on the Client
This you would normally do if your applet was receiving security exceptions when trying to do elementary things like writing to files and such (hackers wouldn’t do this, of course!). For this discussion, there are two permission we want to grant (relax the security of). The first is to get rid of the yellow warning banner, and then the write protection.
To do this we run the GUI policytool:
policytool
Ignore any error messages you may receive after doing this.
On the menu bar, select Edit and choose the option Change Keystore. Now specify the URL location of the keystore like this:
file://C:/WinNT/Profiles/<YourLoginName>/.keystore
Enter the keystore type as jks (from the keystore at the beginning, remember). Now click ‘Ok’.
Next, click on the button ‘Add Policy Entry’. Leave the CodeBase text field blank. This indicates that we want to assign a policy to all the files signed by a specific person. In the SignedBy text field, type in the alias of the imported trustedCertificateEntry, which is Peter in our example. Click on ‘Add Permission’. Now, in the Permissions listbox, select AWTPermission. In the TargetName listbox select showWindowWithoutWarningBanner. Leave the SignedBy field blank. Click ‘Ok’. To add the file write permission, click on ‘Add Pemission’ again. Select FilePermission from the Permissions list box. Type in the name of the file you want to grant the permissions for in the TargetName field. Select the actions you want permission granted for in the Actions field (probably write, or read, write, delete, execute), and click on ‘Ok’. When you’ve finished, click on ‘Done’. You will now see that your code is “SignedBy Peter” in the message box.
Choose to save the file from the File menu, and name it peter.jp (This is the policy file name). Now exit policytool. At the command prompt type in:
appletviewer –J-Djava.security.policy=peter.jp <YourHTMLFilename>
The file write operation should now work.