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.

© University of South Australia Getting Started with JCE and JSSE Page 1 of 4
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.

© University of South Australia Getting Started with JCE and JSSE Page 2 of 4
 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.

© University of South Australia Getting Started with JCE and JSSE Page 3 of 4
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

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