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

• Introduction to JAAS and Java GSS-API Tutorials
• Generic Security Service API Version 2: Java Bindings (RFC 2853)
• Java GSS JavaDoc API documentation: 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: Using the JAAS API. 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 a Subject.callAs using the subject. The Java GSS Kerberos mechanism, because it is executing inside the callAs, 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 GssServer.java code.

   This code fragment defines the action to execute after the service principal has authenticated to the KDC. It replaces the MyAction in Exercise 1: Using the JAAS API. The code first creates an instance of GSSManager, which it uses to obtain its own credentials and to create an instance of GSSContext. It uses this context to perform authentication. Upon completing authentication, it accepts encrypted input from the client and uses the established security context to decrypt the data. It then uses the security context to encrypt a reply containing the original input and the date, and then sends it back to the client.

2. Compile the sample code.

3. Read the GssClient.java code.

   This code fragment defines the action to execute after the client principal has authenticated to the KDC. It replaces the MyAction in Exercise 1: Using the JAAS API. The code first creates an instance of GSSManager, which it uses to obtain a principal name for the service that it is going to communicate with. It then creates an instance of GSSContext to perform authentication with the service. Upon completing authentication, it uses the established security context to encrypt a message, and sends it to the server. It then reads an encrypted message from the server and decodes it using the established security context.

4. Compile the sample code.

5. Launch a new window and start the server:

   % java -Djava.security.auth.login.config=jaas-krb5.conf GssServer

6. 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:

   % java -Djava.security.auth.login.config=jaas-krb5.conf GssClient host j1hol-001

   When prompted for the password, enter change_it.

7. Observe the following output in the respective client and server applications' windows.

   Output for running GssServer example:

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

   Output for running GssClient example:

   Kerberos password for test: change_it
   Authenticated principal: [test@J1LABS.EXAMPLE.COM]
   Connected to address j1hol-001/192.0.2.102
   Context Established!
   Client principal is test@J1LABS.EXAMPLE.COM
   Server principal is host@j1hol-001
   Mutual authentication took place!
   Sending message: Hello There!
   Will read token of size 93
   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: Using the Java SASL API 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: Deploying for Single Sign-On to learn how to configure the sample programs that you have just used to achieve single sign-on in a Kerberos environment.

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

• Java SASL API Programming and Deployment Guide
•  javax.security.sasl
• 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: Using the JAAS API. 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 a Subject.callAs using the subject. The SASL/Kerberos mechanism, because it is executing inside the callAs, 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 SaslTestServer.java sample code.

   This code fragment defines the action to execute after the service principal has authenticated to the KDC. It replaces the MyAction in Exercise 1: Using the JAAS API. The server specifies the quality of protections (QOP) that it will support and then creates an instance of SaslServer to perform the authentication. The challenge-response protocol of SASL is performed in the while loop, 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 the getAuthorizedID() method. If a security layer was negotiated, the server can exchange data securely with the client.

2. Compile the sample code.

3. Read the SaslTestClient.java sample code.

   This code fragment defines the action to execute after the client principal has authenticated to the KDC. It replaces the MyAction in Exercise 1: Using the JAAS API. The program first specifies the quality of protections that it wants (in this case, confidentiality) and then creates an instance of SaslClient to use for authentication. It then checks whether the mechanism has an initial response and if so, gets the response by invoking the evaluateChallenge() method with an empty byte array. It then sends the response to the server to begin the authentication. The challenge-response protocol of SASL is performed in the while loop, 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.

4. Compile the sample code.

5. 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:

   % java -Djava.security.auth.login.config=jaas-krb5.conf SaslTestServer host j1hol-001

6. 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:

   % java -Djava.security.auth.login.config=jaas-krb5.conf SaslTestClient host j1hol-001

   Provide a secure password.

7. Observe the following output in the respective client and server applications' windows.

   Output for running the SaslTestServer example:

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

   Output for running the SaslTestClient example (password will be replaced by the password that you provided):

   Kerberos password for test: password
   Authenticated principal: [test@J1LABS.EXAMPLE.COM]
   Connected to address j1hol-001/192.0.2.102
   Client authenticated.
   Negotiated QOP: auth-conf
   Sending: Hello There!
   Received: Hello There! Fri May 07 15:32:37 PDT 2005

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

Proceed to Exercise 5: Deploying for Single Sign-On to learn how to configure the sample programs that you have just used to achieve single sign-on in a Kerberos environment.