Part II : Secure Communications using the Java SE 6 Security API

This part shows you how to build applications that perform secure communications. The Java SE 6 platform provides three standard APIs that allow applications to perform secure communications: The Java Generic Security Service (GSS), the Java SASL API, and the Java Secure Socket Extension (JSSE). When building an application, which of these APIs should you use? The answer depends on many factors, including requirements of the protocol or service, deployment infrastructure, and integration with other security services. For example, if you are building an LDAP client library, you would need to use the Java SASL API because use of SASL is part of LDAP's protocol definition. As an other example, if the service supports SSL, then the client application attempting to access the service would need to use JSSE.

Exercise 3: Using the Java Generic Security Service (GSS) API


Goal of this exercise:


The goal of this exercise is to learn how to use the Java GSS API  to perform secure authentication and communication.

Background for this exercise:

The Generic Security Service API provides a uniform C-language interface to access various security services, such as authentication, message integrity, and message confidentiality. The Java GSS API provides the corresponding interface for Java applications.  It allows applications to perform authentication and establish secure communication with the peer. One of the most common security service accessed via the GSS-API and Java GSS-API is Kerberos.

Resources for this Exercise:

  1. The JAAS and Java GSS-API Tutorials
  2. Generic Security Service API Version 2: Java Bindings (RFC 2853)
  3. Java GSS javadocs: org.ietf.jgss.

Overview of this Exercise:

This exercise is a client-server application that demonstrates how to communicate securely using the Java GSS API. The client and server parts first authenticate to Kerberos, as shown in Exercise 1. This stores the credentials in the subject. The application then executes an action that performs Java GSS operations (with Kerberos as the underlying GSS mechanism) inside of a Subject.doAs using the subject. The Java GSS Kerberos mechanism, because it is executing inside the doAs, obtains the Kerberos credentials from the subject, and uses them to authenticate with the peer and to exchange messages securely.

Steps to follow:

  1. Read the following code. This is located in src/GssServer.java.

    This code fragment defines the action to execute after the service principal has authenticated to the KDC. It replaces the MyAction of line 11 of Exercise 1. Note the highlighted lines. The code first creates an instance of GSSManager [line 8], which it uses to obtain its own credentials [line 10-11] and to create an instance of GSSContext [line 18]. It uses this context to perform authentication [the loop between lines 22-34]. Upon completing authentication, it accepts encrypted input from the client and uses the established security context to decrypt the data [line 45]. It then uses the security context to encrypt a reply containing the original input and the date [line 49], and then sends it back to the client.

Code listing for GssServer.java.



  1. static class GssServerAction implements PrivilegedExceptionAction {
  2. ...
  3.   public Object run() throws Exception {
  4.     // Create server socket for accepting connections
  5.     ServerSocket ss = new ServerSocket(localPort);

  7.     // Get own Kerberos credentials for accepting connection
  8.     GSSManager manager = GSSManager.getInstance();
  9.     Oid krb5Oid = new Oid("1.2.840.113554.1.2.2");
  10.     GSSCredential serverCreds = manager.createCredential(null,
  11.       GSSCredential.DEFAULT_LIFETIME, krb5Oid, GSSCredential.ACCEPT_ONLY);

  13.     while (true) {
  14.       Socket socket = ss.accept();
  15.       DataInputStream inStream = new DataInputStream(socket.getInputStream());
  16.       DataOutputStream outStream = new DataOutputStream(socket.getOutputStream());

  18.       GSSContext context = manager.createContext((GSSCredential)serverCreds);

  20.       // Do the context establishment loop
  21.       byte[] token = null;
  22.       while (!context.isEstablished()) {
  23.         // Read token
  24.         token = new byte[inStream.readInt()];
  25.         inStream.readFully(token);

  27.         // Process token
  28.         token = context.acceptSecContext(token, 0, token.length);

  30.         // Send a token to the peer if one was generated by acceptSecContext
  31.         outStream.writeInt(token.length);
  32.         outStream.write(token);
  33.         outStream.flush();
  34.       }

  36.       // Context established!

  38.       // Create MessageProp for use with unwrap (will be set upon return from unwrap)
  39.       MessageProp prop = new MessageProp(0, false);

  41.       // Read token from client
  42.       token = new byte[inStream.readInt()];
  43.       inStream.readFully(token);
  44.       // Unwrap (decrypt) token sent by client
  45.       byte[] input = context.unwrap(token, 0, token.length, prop);
  46.       ...
  47.       // Create new token and send to client
  48.       byte[] reply = ...;
  49.       token = context.wrap(reply, 0, reply.length, prop);

  51.       outStream.writeInt(token.length);
  52.       outStream.write(token);
  53.       outStream.flush();
  54.       context.dispose();
  55.       socket.close();
  56.     }
  57.   }
  58. }

  1. Compile the sample code. 
    
% javac GssServer.java
  2. Read the following code. This is located in src/GssClient.java.

    This code fragment defines the action to execute after the client principal has authenticated to the KDC. It replaces the MyAction of line 11 of Exercise 1. Note the highlighted lines. The code first creates an instance of GSSManager [line 10], which it uses to obtain a principal name for the service that it is going to communicate with [line 12]. It then creates an instance of GSSContext [line 15,16] to perform authentication [the loop between lines 22-33] with the service. Upon completing authentication, it uses the established security context to encrypt a message [line 42] and sends it to the server. It then reads an encrypted message from the server and decodes it using the established security context [line 53].
Code listing for GssClient.java.

  1. static class GssClientAction implements PrivilegedExceptionAction {
  2. ...
  3.   public Object run() throws Exception {
  4.     // Create socket to server
  5.     Socket socket = new Socket(hostName, port);
  6.     DataInputStream inStream = new DataInputStream(socket.getInputStream());
  7.     DataOutputStream outStream = new DataOutputStream(socket.getOutputStream());

  9.     // Get service's principal name
  10.     GSSManager manager = GSSManager.getInstance();
  11.     Oid krb5Oid = new Oid("1.2.840.113554.1.2.2");
  12.     GSSName serverName = manager.createName(serverPrinc, GSSName.NT_HOSTBASED_SERVICE);

  14.     // Get the context for authentication
  15.     GSSContext context = manager.createContext(serverName, krb5Oid, null,
  16.        GSSContext.DEFAULT_LIFETIME);
  17.     context.requestMutualAuth(true); // Request mutual authentication
  18.     context.requestConf(true); // Request confidentiality

  20.     // Do the context establishment loop
  21.     byte[] token = new byte[0];
  22.     while (!context.isEstablished()) {
  23.       token = context.initSecContext(token, 0, token.length);
  24.       outStream.writeInt(token.length);
  25.       outStream.write(token);
  26.       outStream.flush();

  28.       // Check if we're done
  29.       if (!context.isEstablished()) {
  30.         token = new byte[inStream.readInt()];
  31.         inStream.readFully(token);
  32.       }
  33.     }

  35.     // Context established!

  37.     // Create MessageProp for use with unwrap (true means request confidentiality)
  38.     MessageProp prop = new MessageProp(0, true);

  40.     // Create encrypted message and send to server
  41.     byte[] reply = ...;
  42.     token = context.wrap(reply, 0, reply.length, prop);

  44.     outStream.writeInt(token.length);
  45.     outStream.write(token);
  46.     outStream.flush();

  48.     // Read token from server
  49.     token = new byte[inStream.readInt()];
  50.     inStream.readFully(token);

  52.     // Unwrap (decrypt) token sent by server
  53.     byte[] input = context.unwrap(token, 0, token.length, prop);
  54.     ...
  55.     context.dispose();
  56.     socket.close();
  57.     return null;
  58.   }
  59. }

  1. Compile the sample code. 
    % javac GssClient.java
  2. Launch a new window and start the server. 
    % xterm &
% java -Djava.security.auth.login.config=jaas-krb5.conf \
       GssServer
  3. Run the client application. GssClient takes two parameters: the service name and the name of the server that the service is running on. For example, if the service is host running on the machine j1hol-001, you would enter the following. When prompted for the password, enter changeit. 
        
% java -Djava.security.auth.login.config=jaas-krb5.conf \
       GssClient host j1hol-001
  4. Observe the following output in the client and server applications' windows.

Output for running GssServer example.


  1. Authenticated principal: [host/j1hol-001@J1LABS.EXAMPLE.COM]
  2. Waiting for incoming connections...
  3. Got connection from client /129.145.128.102
  4. Context Established!
  5. Client principal is test@J1LABS.EXAMPLE.COM
  6. Server principal is host/j1hol-001@J1LABS.EXAMPLE.COM
  7. Mutual authentication took place!
  8. Received data "Hello There!" of length 12
  9. Confidentiality applied: true
  10. Sending: Hello There! Thu May 06 12:11:15 PDT 2005

Output for running GssClient example.


  1. Kerberos password for test: changeit
  2. Authenticated principal: [test@J1LABS.EXAMPLE.COM]
  3. Connected to address j1hol-001/129.145.128.102
  4. Context Established!
  5. Client principal is test@J1LABS.EXAMPLE.COM
  6. Server principal is host@j1hol-001
  7. Mutual authentication took place!
  8. Sending message: Hello There!
  9. Will read token of size 93
  10. Received message: Hello There! Thu May 06 12:11:15 PDT 2005

Summary:

In this exercise, you learned how to write a client-server application that uses the Java GSS API to authenticate and communicate securely with each other.

Next Steps

  1. Proceed to Exercise 4 to learn how to write a client/server application that uses the Java SASL API to authenticate and communicate securely with each other.
  2. Proceed to Exercise 5 to learn how to write a client/server application that uses the JSSE to authenticate and communicate securely with each other.
  3. Proceed to Exercise 6 to learn how to configure the sample programs that you have just used to achieve single sign-on in a Kerberos environment.

Exercise 4: Using the Java SASL API

Goal of this exercise:

The goal of this exercise is to learn how to use the Java SASL API  to perform secure authentication and communication.

Background for this exercise:

Simple Authentication and Security Layer (SASL) specifies a challenge-response protocol in which data is exchanged between the client and the server for the purposes of authentication and (optional) establishment of a security layer on which to carry on subsequent communications. SASL allows different mechanisms to be used; each such mechanism is identified by a profile that defines the data to be exchanged and a name. SASL is used with connection-based protocols such as LDAPv3 and IMAPv4. SASL is described in RFC 4422.

The Java SASL API defines an API for applications to use SASL in a mechanism-independent way. For example, if you are writing a library for a networking protocol that uses SASL, you can use the Java SASL API to generate the data to be exchanged with the peer. When the library is deployed, you can dynamically configure the mechanisms to use with the library.

In addition to authentication, you can use SASL to negotiate a security layer to be used after authentication. But unlike the GSS-API, the properties of the security layer (such as whether you want integrity or confidentiality) is decided at negotiation time. (the GSS-API allows confidentiality to be turned on or off per message).

Resources for this exercise:

  1. The Java SASL API Programming and Deployment Guide
  2. The Java SASL API javadocs
  3. Simple Authentication and Security Layer (SASL) (RFC 4422)

Overview of this exercise:

This exercise is a client-server application that demonstrates how to communicate securely using the Java SASL API. The client and server parts first authenticate to Kerberos using Exercise 1. This stores the credentials in the subject. The application then executes an action that performs Java SASL API operations (with Kerberos as the underlying SASL mechanism) inside of a Subject.doAs using the subject. The SASL/Kerberos mechanism, because it is executing inside the doAs, obtains the Kerberos credentials from the subject, and uses them to authenticate with the peer and to exchange messages securely.

This example uses a simple protocol implemented by the AppConnection class. This protocol exchanges authentication commands and data commands. Each command consists of a type (e.g., AppConnection.AUTH_CMD), the length of the data to follow, and the data itself. The data is a SASL buffer if it is for authentication or encrypted/integrity-protected application data; it is plain application data otherwise.

Steps to follow:

  1. Read the following code. This is located in src/SaslTestServer.java.

    This code fragment defines the action to execute after the service principal has authenticated to the KDC. It replaces the MyAction of line 11 of Exercise 1. Note the highlighted lines. The server specifies the quality-of-protections that it will support [line 9] and then creates an instance of SaslServer to perform the authentication [line 21]. The challenge-response protocol of SASL is performed in the while loop [lines 33-49], with the server sending challenges to the client and processing the responses from the client. After authentication, the identity of the authenticated client can be obtained via a call to getAuthorizedID() [line 61]. If a security layer was negotiated, the server can exchange data securely with the client [lines 66,70].

Code listing for SaslTestServer.java.


  1. static class SaslServerAction implements PrivilegedExceptionAction {
  2. ...
  3.   public Object run() throws Exception {
  4.     // Create server socket for accepting connections
  5.     ServerSocket ss = new ServerSocket(localPort);

  7.     // Support all quality-of-protection options
  8.     HashMap<String,Object> props = new HashMap<String,Object>();
  9.     props.put(Sasl.QOP, "auth-conf,auth-int,auth");

  11.     while (true) {
  12.       // Create application-level connection to handle request
  13.       Socket socket = ss.accept();
  14.       AppConnection conn = new AppConnection(socket);

  16.       // Normally, the application protocol will negotiate which
  17.       // SASL mechanism to use. In this simplified example, we
  18.       // will always use "GSSAPI" (the name of the mechanism that does Kerberos via GSS-API)

  20.       // Create SaslServer to perform authentication
  21.       SaslServer srv = Sasl.createSaslServer("GSSAPI", service, serviceName, props, cbh);

  23.       if (srv == null) {
  24.         // ... handle error
  25.       }

  27.       // Read the initial response from client
  28.       byte[] response = conn.receive(AppConnection.AUTH_CMD);
  29.       AppConnection.AppReply clientMsg;
  30.       boolean auth = false;

  32.       // Perform authentication
  33.       while (!srv.isComplete()) {
  34.         try
  35.           // Generate challenge based on response
  36.           byte[] challenge = srv.evaluateResponse(response);
  37.           if (srv.isComplete()) {
  38.             conn.send(AppConnection.SUCCESS, challenge);
  39.             auth = true;
  40.           } else {
  41.             clientMsg = conn.send(AppConnection.AUTH_IN_PROGRESS, challenge);
  42.             response = clientMsg.getBytes();
  43.           }
  44.         } catch (SaslException e) {
  45.           // Send failure notification to client
  46.           conn.send(AppConnection.FAILURE, null);
  47.           break;
  48.         }
  49.       }

  51.       // Authentication completed!

  53.       // Check status of authentication
  54.       if (srv.isCompleted() && auth) {
  55.         System.out.println("authorized client is: " + srv.getAuthorizationID());
  56.       } else {
  57.         // Report failure ...
  58.       }

  60.       // Find out whether security layer was negotiated
  61.       String qop = (String) srv.getNegotiatedProperty(Sasl.QOP);
  62.       boolean sl = (qop.equals("auth-conf") || qop.equals("auth-int"));

  64.       // Read and decrypt message from client
  65.       byte[] msg = conn.receive(AppConnection.DATA_CMD);
  66.       byte[] realMsg = (sl ? srv.unwrap(msg, 0, msg.length) : msg);
  67.       ...
  68.       // Create and encrypt message to send to client
  69.       byte[] reply = ...;
  70.       byte[] realReply = (sl ? srv.wrap(reply, 0, reply.length) : reply);
  71.       conn.send(AppConnection.SUCCESS, realReply);
  72.     }
  73.   }
  74. }

  1. Compile the sample code. 
    % javac SaslTestServer.java
  2. Read the following code. This is located in src/SaslTestClient.java. This code fragment defines the action to execute after the client principal has authenticated to the KDC. It replaces the MyAction of line 11 of Exercise 1. Note the highlighted lines. The program first specifies the quality of protection that it wants (in this case, confidentiality) [line 8] and then creates an instance of SaslClient to use for authentication [lines 11-12]. It then checks whether the mechanism has an initial response and if so, gets the response by invoking evaluateChallenge() with an empty byte array [line 20]. It then sends the response to the server to begin the authentication. The challenge-response protocol of SASL is performed in the while loop [lines 24-39], with the client evaluating the challenges that it gets from the server and sending the server the corresponding responses to the challenges. After authentication, the client can proceed to communicate with the server using the negotiated security layer [lines 48,55].

Code listing for SaslTestClient.java.


  1. static class SaslClientAction implements PrivilegedExceptionAction {
  2. ...
  3.   public Object run() throws Exception {
  4.     // Create application-level connection
  5.     AppConnection conn = new AppConnection(serverName, port);

  7.     HashMap<String,Object> props = new HashMap<String,Object>();
  8.     props.put(Sasl.QOP, "auth-conf"); // Request confidentiality

  10.     // Create SaslClient to perform authentication
  11.     SaslClient clnt = Sasl.createSaslClient(
  12.       new String[]{"GSSAPI"}, null, service, serverName, props, cbh);
  13.     if (clnt == null) {
  14.       // ... handle error
  15.     }

  17.     byte[] challenge;

  19.     // Get initial response for authentication
  20.     byte[] response = clnt.hasInitialResponse() ? clnt.evaluateChallenge(EMPTY) : EMPTY;
  21.     AppConnection.AppReply reply = conn.send(AppConnection.AUTH_CMD, response);

  23.     // Repeat until authentication terminates
  24.     while (!clnt.isComplete() &&
  25.       (reply.getStatus() == AppConnection.AUTH_INPROGRESS ||
  26.        reply.getStatus() == AppConnection.SUCCESS))
  27.       // Evaluate challenge to generate response
  28.       challenge = reply.getBytes()
  29.       response = clnt.evaluateChallenge(challenge)

  31.       if (reply.getStatus() == AppConnection.SUCCESS) {
  32.         if (response != null) {
  33.           throw new Exception("Protocol error")
  34.         }
  35.         break;
  36.       }
  37.       // Send response to server and read server's next challenge
  38.       reply = conn.send(AppConnection.AUTH_CMD, response);
  39.     }
  40.     // Authentication completed!
  41.     // Find out whether security layer was negotiated
  42.     String qop = (String) srv.getNegotiatedProperty(Sasl.QOP);
  43.     boolean sl = (qop.equals("auth-conf") || qop.equals("auth-int"));

  45.     byte[] msg = ...;

  47.     // Create and send encrypted data to server
  48.     byte[] encrypted = (sl ? clnt.wrap(msg, 0, msg.length) : msg);
  49.     reply = conn.send(AppConnection.DATA_CMD, encrypted);) {

  51.     ...

  53.     // Read and decrypt data from server
  54.     byte[] encryptedReply = reply.getBytes();
  55.     byte[] clearReply = (sl ? clnt.unwrap(encryptedReply, 0, encryptedReply.length)
  56.       : encryptedReply);
  57.     conn.close();
  58.     return null;
  59.   }
  60. }
  1. Compile the sample code. 
    % javac SaslTestClient.java
  2. Launch a new window and start the server. SaslTestServer takes two parameters: the service name and the name of the server that the service is running on. For example, if the service is host running on the machine j1hol-001, you would enter the following. 
    % xterm &
    % java 
     -Djava.security.auth.login.config=jaas-krb5.conf \
           SaslTestServer host j1hol-001
  3. Run the client application. SaslTestClient takes two parameters: the service name and the name of the server that the service is running on. For example, if the service is host running on the machine j1hol-001, you would enter the following. When prompted for the password, enter changeit. 

    % java -Djava.security.auth.login.config=jaas-krb5.conf \
           SaslTestClient host j1hol-001
  4. Observe the following output in the client and server applications' windows.

Output for running the SaslTestServer example.


  1. Authenticated principal: [host/j1hol-001@J1LABS.EXAMPLE.COM]
  2. Waiting for incoming connections...
  3. Got connection from client /129.145.128.102
  4. Client authenticated; authorized client is: test@J1LABS.EXAMPLE.COM
  5. Negotiated QOP: auth-conf
  6. Received: Hello There!
  7. Sending: Hello There! Fri May 07 15:32:37 PDT 2005
  8. Received data "Hello There!" of length 12

Output for running the SaslTestClient example.


  1. Kerberos password for test: changeit
  2. Authenticated principal: [test@J1LABS.EXAMPLE.COM]
  3. Connected to address j1hol-001/129.145.128.102
  4. Client authenticated.
  5. Negotiated QOP: auth-conf
  6. Sending: Hello There!
  7. Received: Hello There! Fri May 07 15:32:37 PDT 2005
  1. To try the program using different quality-of-protection, change line 8 in SaslTestClient. For example, replace line 8 with the following line to use integrity protection on (no confidentiality). 
    props.put(Sasl.QOP, "auth-int");

Summary:

In this exercise, you learned how to write a client-server application that uses the Java SASL API to authenticate and communicate securely with each other.

Next Steps

  1. Proceed to Exercise 5 to learn how to write a client/server application that uses the JSSE to authenticate and communicate securely with each other.
  2. Proceed to Exercise 6 to learn how to configure the sample programs that you have just used to achieve single sign-on in a Kerberos environment.

Exercise 5: Using the Java Secure Socket Extension with Kerberos

Goal of this exercise:

The goal of this exercise is to learn how to use the JSSE API  to perform secure authentication and communication using Kerberos cipher suites.

Background for this exercise:

Secure Socket Layer (SSL) and Transport Layer Security (TLS) are the most widely used protocols for implementing cryptography on the Internet. TLS is the Internet standard evolved from SSL. SSL/TLS provides application-level protocols (such as HTTP and LDAP) with secure authentication and communication. For example, HTTPS is the resulting protocol of using HTTP over SSL/TLS. SSL/TLS is used not only for standard protocols such as HTTP, it is also widely used when building custom applications using custom protocols that need to communicate securely.

SSL/TLS traditionally used certificate-based authentication and is commonly used for server-authentication. For example, when a Web client such as a browser accesses a secure Web site (server) on behalf of a user, the server sends its certificate to the browser so that the browser can verify the identity of the server. This ensures that the user does not divulge confidential information (such as credit card information) to a bogus server. Recently, a new standard allows the use of Kerberos with TLS. This means instead of using certificate-based authentication, an application can use Kerberos credentials and take advantage of the Kerberos infrastructure in the deployment environment. Using Kerberos cipher suites also provides automatic support for mutual authentication in which the client is also authenticated in addition to the server.

The decision of whether to use Java GSS, Java SASL, or JSSE for a particular application often depends upon several factors, including (the protocols being used by) the services with which the application interacts, the deployment environment (PKI or Kerberos-based), and the application's security requirements. JSSE provides a secure end-to-end channel that takes care of the I/O and transport, while Java GSS and Java SASL provide encryption and integrity-protection on the data, but the application is responsible for transporting the secured data to its peer. Some details about factors for deciding when to use JSSE versus Java GSS are presented in the document, When to use Java GSS vs. JSSE.

Resources for this exercise:

  1. Java Secure Socket Extension (JSSE) Reference Guide
  2. The JSSE javadocs: javax.net and javax.net.ssl
  3. The SSL Protocol version 3.0
  4. The TLS Protocol Version 1.0 (RFC 2246)
  5. Addition of Kerberos Cipher Suites to Transport Layer Security TLS (RFC 2712)
  6. When to use Java GSS vs. JSSE

Overview of this exercise:

This exercise is a client-server application that demonstrates how to communicate securely using the JSSE and Kerberos cipher suites. The client and server parts first authenticate to Kerberos using Exercise 1. This stores the credentials in the subject. The application then executes an action that performs JSSE operations (using a Kerberos cipher suite) inside of a Subject.doAs using the subject. The Kerberos cipher suite implementation, because it is executing inside the doAs, obtains the Kerberos credentials from the subject, and uses them to authenticate with the peer and to exchange messages securely. This example sends newline-terminated messages, encrypted using the negotiated cipher suite and integrity-protected, back and forth between client and server.

According to the standard (RFC 2712) all Kerberos-enabled TLS applications use the same service name, namely, "host". That is why in this exercise, you do not need to explicitly supply the Kerberos service name.

Steps to follow:

  1. Read the following code. This is located in src/JsseServer.java

    This code fragment defines the action to execute after the service principal has authenticated to the KDC. It replaces the MyAction of line 11 of Exercise 1. Note the highlighted lines. The server first creates an SSLServerSocket [lines 5-8]. This is analogous to an application creating a plain ServerSocket except an SSLServerSocket will provide automatic authentication, encryption and decryption, as needed. The server then sets the cipher suites that it wants to use [lines 11-12]. The server then runs in a loop, accepting connections from SSL clients [line 17], and reads and writes from the SSL socket [lines 23, 28]. The server can find out the identities of the owners of socket by invoking the getLocalPrincipal() and getPeerPrincipal() methods [lines 32-33].

Code listing for JsseServer.java.


  1. static class JsseServerAction implements PrivilegedExceptionAction {
  2. ...
  3.   public Object run() throws Exception {
  4.     // Create TLS socket for accepting connections
  5.     SSLServerSocketFactory sslssf =
  6.       (SSLServerSocketFactory) SSLServerSocketFactory.getDefault();
  7.     SSLServerSocket sslServerSocket =
  8.       (SSLServerSocket) sslssf.createServerSocket(localPort);

  10.     // Enable only a Kerberos cipher suite
  11.     String enabledSuites[] = { "TLS_KRB5_WITH_3DES_EDE_CBC_SHA" };
  12.     sslServerSocket.setEnabledCipherSuites(enabledSuites);
  13.     // Should handle exception if enabledSuites is not supported

  15.     while (true) {
  16.       // Create socket to handle request
  17.       SSLSocket sslSocket = (SSLSocket) sslServerSocket.accept();
  18.       BufferedReader in = new BufferedReader(new InputStreamReader(
  19.         sslSocket.getInputStream()));
  20.       BufferedWriter out = new BufferedWriter(new OutputStreamWriter(
  21.         sslSocket.getOutputStream()));

  23.       String inStr = in.readLine();
  24.       // ... use inStr

  26.       // Compose and send reply
  27.       String outStr = inStr + " " + new Date().toString() + "\n";
  28.       out.write(outStr);
  29.       out.flush();

  31.       // Get names of principal at both ends of secure connection
  32.       Principal self = sslSocket.getSession().getLocalPrincipal();
  33.       Principal peer = sslSocket.getSession().getPeerPrincipal();

  35.       sslSocket.close();
  36.     }
  37.   }
  38. }

  1. Compile the sample code. 

    % javac JsseServer.java
  2. Read the following code. This is located in src/JsseClient.java. This code fragment defines the action to execute after the client principal has authenticated to the KDC. It replaces the MyAction of line 11 of Exercise 1. Note the highlighted lines. The client first creates an SSLSocket. The client then sets the cipher suites that it wants to use [lines 11-12]. The client then exchanges messages with the server using the SSLSocket by reading and writing to the socket's input/output streams. The client can find out the identities of the owners of socket by invoking the getLocalPrincipal() and getPeerPrincipal() methods [lines 26-27].

Code listing for JsseClient.java


  1. static class JsseClientAction implements PrivilegedExceptionAction {
  2. ...
  3.   public Object run() throws Exception {
  4.     // Create SSL connection
  5.     SSLSocketFactory sslsf = (SSLSocketFactory) SSLSocketFactory.getDefault();
  6.     SSLSocket sslSocket = (SSLSocket) sslsf.createSocket(server, port);

  8.     // Enable only a Kerberos cipher suite
  9.     String enabledSuites[] = { "TLS_KRB5_WITH_3DES_EDE_CBC_SHA" };
  10.     sslSocket.setEnabledCipherSuites(enabledSuites);
  11.     // Should handle exception if enabledSuites is not supported

  13.     BufferedReader in = new BufferedReader(new InputStreamReader(
  14.       sslSocket.getInputStream()));
  15.     BufferedWriter out = new BufferedWriter(new OutputStreamWriter(
  16.       sslSocket.getOutputStream()));

  18.     String outStr = ...;
  19.     out.write(outStr);
  20.     out.flush();

  22.     String inStr = in.readLine();
  23.     // ... use inStr

  25.     // Get names of principal at both ends of secure connection
  26.     Principal self = sslSocket.getSession().getLocalPrincipal();
  27.     Principal peer = sslSocket.getSession().getPeerPrincipal();

  29.     sslSocket.close();
  30.     return null;
  31.   }
  32. }

  1. Compile the sample code. 
    % javac JsseClient.java
  2. Launch a new window and start the server. JsseServer takes one parameter: the name of the server that the JSSE service is running on. For example, if it is running on the machine j1hol-001, you would enter the following. 
    % xterm &
    % java 
     -Djava.security.auth.login.config=jaas-krb5.conf \
           JsseServer j1hol-001
  3. Run the client application. JsseClient takes one parameter: the name of the server that the JSSE service is running on. For example, if the service is running on the machine j1hol-001, you would enter the following. When prompted for a password, enter changeit. 

    % java -Djava.security.auth.login.config=jaas-krb5.conf \
           JsseClient j1hol-001
  4. Observe the following output in the client and server applications' windows.

Output for running the JsseServer example.


  1. Authenticated principal: [host/j1hol-001@J1LABS.EXAMPLE.COM]
  2. Waiting for incoming connections...
  3. Got connection from client /129.145.128.102
  4. Received: Hello There!
  5. Sending: Hello There! Fri May 07 15:32:37 PDT 2005
  6. Cipher suite in use: TLS_KRB5_WITH_3DES_EDE_CBC_SHA
  7. I am: host/j1hol-001@J1LABS.EXAMPLE.COM
  8. Client is: test@J1LABS.EXAMPLE.COM

Output for running the JsseClient example.


  1. Kerberos password for test: changeit
  2. Authenticated principal: [test@J1LABS.EXAMPLE.COM]
  3. Sending: Hello There!
  4. Received: Hello There! Fri May 07 15:32:37 PDT 2005
  5. Cipher suite in use: TLS_KRB5_WITH_3DES_EDE_CBC_SHA
  6. I am: test@J1LABS.EXAMPLE.COM
  7. Server is: host/j1hol-001@J1LABS.EXAMPLE.COM

Summary:

In this exercise, you learned how to write a client-server application that uses JSSE to authenticate and communicate securely with each other, using Kerberos as the underlying authentication system.

Next Steps

  1. Proceed to Exercise 6 to learn how to configure the sample programs in Exercises 3, 4, and 5 to achieve single sign-on in a Kerberos environment.