Getting Started With JSSE and JCE

© University of South Australia Getting Started with JCE and JSSE Page 1 of 4

Getting started with JSSE and JCE

Sun JSSE is the Java Secure Socket Extension and provides SSL capabilities to Java programs.

Sun JCE is the Java Cryptography Extension and supplies encryption, authentication and related functions.

Setting Up your PC

Ensure that you have Java 1.4 or later installed. No other installation is necessary.

Much of the work described below is done from the command line (Linux, Unix or Windows). I have used Unix, but there should be little difference if you are using Windows.

SSL1

This is a test to show that you have everything in place to be able to use SSL from within a Java program.

Create and compile the following program, adapted from [4]: import java.io.*; import java.net.*; public class SSL1 { public static void main(String [] arstring) { try { Object inStream = new java.net.URL("https://" + arstring[0] + "/").getContent(); BufferedReader in = new BufferedReader( new InputStreamReader( (InputStream) inStream )

); String line; while ( (line = in.readLine()) != null ) System.out.println( line ); } catch (Exception exception) { exception.printStackTrace(); } finally { System.out.flush(); } } }

Run it: java SSL1 some_https_server >out.html

where some_https_server is any convenient SSL server for this test, eg java SSL1 www.linkedin.com >out.html

This should make an https: connection with the server and write out the page returned from the server.

You can get trace/debugging information out of SSL by adding a system property -Djavax.net.debug=..., eg: java -Djavax.net.debug=ssl SSL1 some_https_server > trace.txt

SSL client-server

This is a client-server example using the SSL protocol to secure the connection.

Step 1: create server keystore

To allow programs to communicate using SSL, a server certificate is needed.


The SSL protocol uses public key certificates to authenticate the server. Normally, a server certificate is obtained from a recognised certificate authority such as Verisign, which signs the certificate to show that it is genuine. The server owning this certificate sends the certificate to the client as part of the SSL protocol setup, and the client verifies that the certificate is genuine by checking that it was correctly signed.

In addition, the SSL client checks that the server is really the owner of the certificate. Whereas the certificate is public information which anyone can read and verify, the server (and only the server, unless there has been a security breach) also has the private key corresponding to the public key in its certificate. The client sends the server a challenge (random value) which the server must sign with its private key and return to the client. The client verifies this signature using the server’s public key extracted from the certificate: if this verifies, then it proves that the server has the private key and the client assumes that it is talking to the correct server.

For this assignment, we are going to simplify this process a little. We will use a “self-signed certificate”, meaning that the server certificate has not been signed by an independent certificate authority. This certificate, together with the private key, is stored in the server’s keystore, where it is protected by a password. The same certificate, but without the private key, is stored in the client’s truststore, also protected by a password. What this means is that the client will only be able to connect to a server which has the private key for the server certificate.

To create the server certificate and private key, use the keytool –genkey command as follows: mkdir server cd server keytool -genkey -alias serverkey -keyalg RSA -keysize 1024 -keystore serverKeystore -validity 365

and answer the questions. Make sure you remember the password. Notice that we have put the server’s keystore into its own directory, keeping it away from the client. Do the same thing with the server’s other data files.

Check the result using keytool -list -v -keystore serverKeystore

Step 2: create client truststore cd .. mkdir client cd client keytool -export -alias serverkey -file server.cer -keystore ../server/serverKeystore keytool -import -alias servercert -file server.cer -keystore clientTruststore rm server.cer

After creating a client directory, we first export the certificate (without private key) into a file, and then import that into a new store, the client’s truststore. The password for the client’s truststore should not be the same as the password for the server’s keystore.

Check the result using keytool -list -v -keystore clientTruststore. Compare the output with the listing of the server’s keystore and note that the fingerprints are the same so it is the same certificate, but this is a trusted certificate entry, not a key entry, indicating that there is no private key included.

Step 3: create and run echo programs

This step checks that the results of Steps 1 and 2 are correct, by running a simple client-server.

Download SSLEchoClient.java and SSLEchoServer.java from the website. You should put them into the client and server directories created previously. Compile them, and run as follows:

Server cd server java -Djavax.net.ssl.keyStore=serverKeystore -Djavax.net.ssl.keyStorePassword=serverpassword

SSLEchoServer 7777

This starts the server listening on port 7777 (use whatever port you like). Note that we have to give the server’s password on the command line; this is obviously insecure; although there are ways around this, we won’t use them for this assignment.


Client

Do this in a separate terminal window: cd client java -Djavax.net.ssl.trustStore=clientTruststore -Djavax.net.ssl.trustStorePassword=clientpassword

SSLEchoClient localhost 7777

This connects to the server on port 7777 and asks you for input, which it sends to the server and then prints the server’s response. Quit using an end-of-file character (CTRL/D in Unix, CTRL/Z in Windows), or a . on a line by itself.

You can also run the server and client on separate computers, as long as you copy the necessary files, and access is not prevented by a firewall. Just replace localhost by the name of the computer running the server.

Now you have reached this stage, you have a keystore and truststore that can also be used for your Conference assignment submission.

JCE

Create and compile the following program, extracted from [1]. import javax.crypto.*; public class JCE1 { public static void main( String[] args ) { try { KeyGenerator keygen = KeyGenerator.getInstance("AES"); SecretKey aesKey = keygen.generateKey(); Cipher aesCipher; // Create the cipher aesCipher = Cipher.getInstance("AES/ECB/PKCS5Padding"); // Initialize the cipher for encryption aesCipher.init(Cipher.ENCRYPT_MODE, aesKey); // Our cleartext byte[] cleartext = "This is just an example".getBytes(); // Encrypt the cleartext byte[] ciphertext = aesCipher.doFinal(cleartext); // Initialize the same cipher for decryption aesCipher.init(Cipher.DECRYPT_MODE, aesKey); // Decrypt the ciphertext byte[] cleartext1 = aesCipher.doFinal(ciphertext); System.out.println( new String( cleartext )); System.out.println( new String( cleartext1 )); // Should be same } catch ( Exception ex ) { ex.printStackTrace(); } finally { System.out.flush(); } } }

Run it: java JCE1

In due course it should produce two lines of identical output. If not, check your configuration carefully.


Where to from here?

JSSE

Reference [4] provides a client and server example similar to the echo server and client above.. Another client/server tutorial can be found in Dr. Dobb’s Journal [5]. You should also make yourself familiar with the JSSE Reference Guide [2], and keep available for reference the API documentation [3].

JCE

Make yourself familiar with the Java Cryptography Architecture Specification [1], and keep available for reference the corresponding API javadocs [3].

References and Documentation

1. Sun Microsystems, Java Cryptography Architecture (JCA) Reference Guide, http://java.sun.com/javase/6/docs/technotes/guides/security/crypto/CryptoSpec.html

2. Sun Microsystems, JSSE Reference Guide, http://java.sun.com/javase/6/docs/technotes/guides/security/jsse/JSSERefGuide.html

3. Sun Microsystems, Javadocs for javax.crypto, javax.net.ssl, java.security, java.security.cert, java.security.interfaces, java.security.spec (part of standard Javadocs), http://java.sun.com/javase/6/docs/api/

4. Todd Sunsted, Build Secure Network Applications with SSL and the JSSE API, http://www.javaworld.com/javaworld/jw-05-2001/jw-0511-howto.html

5. Kirby W. Angell, The Java Secure Socket Extensions - Authenticating and Encrypting Connections, Dr. Dobb's Journal, Feb 2001, http://www.ddj.com/184404478

6. Sun Microsystems, Security Home Page, java.sun.com/security/index.html

Chris Steketee, 6th May 2009

Documents

Getting Started With JSSE and JCE