Part V : Secure Authentication using SPNEGO Java GSS mechanism (Java SE 6.0)

Exercise 8: Using the Java Generic Security Services (GSS) API with SPNEGO

Goal of this exercise:

Currently the only security mechansim available with Java GSS is "Kerberos". The goal of this exercise is to learn how to use other Java GSS mechanisms, such as SPNEGO, to secure the association. This feature is available from Java SE 6 onwards.

What is SPNEGO?

Java GSS is a framework that can support multiple security mechanisms; a way to negotiate a security mechanism underneath GSS-API is needed. This is available via SPNEGO.

SPNEGO is the Simple and Protected GSS-API Negotiation Mechanism, standardized at IETF in RFC 4178. It's a pseudo-security mechanism used to negotiate an underlying security mechanism. It provides the flexibility for client and server to securely negotiate a common GSS security mechanism.

Microsoft makes heavy use of SPNEGO. SPNEGO can be used to inter-operate with Microsoft Server over HTTP, to support HTTP-based Cross-Platform authentication via the Negotiate Protocol.

What do I need do to use SPNEGO in Java GSS?

Currently when using Java GSS with Kerberos, we specify the Kerberos OID to use Kerberos.

Oid krb5Oid = new Oid("1.2.840.113554.1.2.2");

In order to use SPNEGO, you only need to specify the SPNEGO OID as follows:-

Oid spnegoOid = new Oid("1.3.6.1.5.5.2");

And henceforth use the SPNEGO OID when creating a GSSCredential, GSSContext, etc.

Steps to follow:

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

Code listing for GssSpNegoClient.java.



  1. static class GssSpnegoClientAction 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 spnegoOid = new Oid("1.3.6.1.5.5.2");
  12.     GSSName serverName = manager.createName(serverPrinc, GSSName.NT_HOSTBASED_SERVICE, spnegoOid);

  14.     // Get the context for authentication
  15.     GSSContext context = manager.createContext(serverName, spnegoOid, 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 GssSpNegoClient.java
  2. Read the following code. This is located in src/GssSpNegoServer.java

Code listing for GssSpNegoServer.java.


  1. static class GssSpNegoServerAction 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 spnegoOid = new Oid("1.3.6.1.5.5.2");
  10.     GSSCredential serverCreds = manager.createCredential(null,
  11.       GSSCredential.DEFAULT_LIFETIME, spnegoOid, 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 GssSpNegoServer.java
  2. Launch a new window and start the server. 

    % xterm &
    % java -Djava.security.auth.login.config=jaas-krb5.conf \
           GssSpNegoServer
  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 \
           GssSpNegoClient host j1hol-001

Output for running the GssSpNegoServer 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. SPNEGO Negotiated Mechanism = 1.2.840.113554.1.2.2 Kerberos V5
  5. Context Established!
  6. Client principal is test@J1LABS.EXAMPLE.COM
  7. Server principal is host/j1hol-001@J1LABS.EXAMPLE.COM
  8. Mutual authentication took place!
  9. Received data "Hello There!" of length 12
  10. Confidentiality applied: true
  11. Sending: Hello There! Thu May 06 12:11:15 PDT 2005

Output for running the GssSpNegoClient 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. SPNEGO Negotiated Mechanism = 1.2.840.113554.1.2.2 Kerberos V5
  5. Context Established!
  6. Client principal is test@J1LABS.EXAMPLE.COM
  7. Server principal is host@j1hol-001
  8. Mutual authentication took place!
  9. Sending message: Hello There!
  10. Will read token of size 93
  11. 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 with SPNEGO to negotiate an underlying security mechanism, such as Kerberos, and communicate securely using Kerberos as the underlying authentication system.

Note: Microsoft has implemented certain variations of the SPNEGO protocol, hence to inter-operate with Microsoft, we have added an MS mode via a new system property "sun.security.spnego.msinterop". This property is enabled to "true" by default. To disable it, you need to explicitly set this property to "false". To enable SPNEGO debugging, you can set the system property "sun.security.spnego.debug=true".