SPNEGO Provider Read Me

 

This document only provides information specified to SPNEGO provider. For information regarding JGSS framework and usage, please consult JGSS user guide or developer guide.

 

·        Introduction

 

SPNEGO stands for Simple and Protected GSS-API Negotiation Mechanism as specified in RFC 2478 (http://www.ietf.org/rfc/rfc2478.txt?number=2478). Information access or information exchange over the network may require authentication of remote parties’ identities and certain level of protection of the data flow. Different parties may support different security mechanisms. SPNEGO provides the means for two remote parities to determine whether they share same security mechanisms, negotiate different options within the mechanisms, identify the mechanism used for authentication and data protection, then set up a security context between them.

 

·        Installation and Configuration

 

The binary is ibmspnego.jar. It has been tested on IBM JDK1.3 and 1.4.0 platform. To install the jar file, put it under{java.home}\lib\ext directory, or in your specific classpath. In {java.home}\lib\security\java.security file, add the IBMSPNEGO to your security provider list, for example, security.provider.6=com.ibm.security.jgss.mech.spnego.IBMSPNEGO.

 

Since it is the provider of JGSS, you also need to install the IBM JGSS package on your machine. Please follow JGSS instruction for installation.

 

·        How to Use SPNEGO

 

SPNEGO provider is totally transparent to the application developers. Callers do not need to be aware of the negotiation tokens. No additional APIs are exposed to users. All users need to do is to specify SPNEGO mechanism type in normal GSS API calls.

 

The following pieces of code show how to initiate GSS context that can negotiate a desired mechanism.  For more information on how to program with GSS APIs to establish the security context and do message exchange with remote service, please consult JGSS documentations.

 

GSSManager manager = GSSManager.getInstance();

GSSName initiator = manager.createName("NT_USER_Name",    

                                        GSSName.NT_USER_NAME);

            //creates SPNEGO credential      

GSSCredential credential = manager.createCredential(initiator.canonicalize(spnegoMechOid),

                               GSSCredential.INDEFINITE_LIFETIME,

                               spnegoMechOid,

                               GSSCredential.INITIATE_ONLY);

//adds Kerberos specific credential element to the credential. Now Kerberos becomes the first preferred mechanism in the negotiation list.

credential.add(initiator.canonicalize(krb5MechOid),

               GSSCredential.INDEFINITE_LIFETIME,

               GSSCredential.INDEFINITE_LIFETIME, 

               krb5MechOid,

               GSSCredential.INITIATE_ONLY);

//adds GSSUP specific credential element to the credential. Now GSSUP becomes the second mechanism candidate in the negotiation list.

credential.add(initiator.canonicalize(gssupMechOid),

               GSSCredential.INDEFINITE_LIFETIME,

               GSSCredential.INDEFINITE_LIFETIME, 

               gssupMechOid,

               GSSCredential.INITIATE_ONLY);   

      GSSName service = manager.createName("NT_HOST_Service",

                                           GSSName.NT_HOSTBASED_SERVICE);

GSSContext context = manager.createContext(service,

                                           spnegoMechOid,

                                                 Credential,

                                                 GSSContext.INDEFINITE_LIFETIME);                                                 

 

·        About the Implementation

 

This section is provided for those who are interested to know more inside the SPNEGO provider package.

 

SPNEGO is implemented as a pluggable provider under IBM's JGSS framework to support the mechanism represented by the object identifier iso.org.dod.internet.security.mechanism.spnego (1.3.6.1.5.5.2). It supports the service provider interface as defined in com.ibm.security.jgss.spi package. It provides an implementation of MechanismFactory engine class to support generation of SPNEGO specific GSSName element, GSSCredential element, and SPNEGO mechanism context.

 

·        SPNEGOName

 

The "IBMSPNEGO" provider supplies an implementation of the GSSName element that can be created under GSSManager engine class for SPNEGO mechanism. This GSSName has 1.3.6.1.5.5.2 as mechanism, and accepts any legal name type. In current implementation, GSSManager.getNamesForMech(Oid) returns a null value to indicate any name types are acceptable (since we cannot list all potentially legal name types).

 

·        SPNEGOCredential

 

The "IBMSPNEGO" provider supplies an implementation of the GSSCredential element. The creation of SPNEGO credential element itself does not involve any credential acquisition underneath. If the name of the principal for whom this credential is to be acquired is not specified, a default name will be used.

 

·        SPNEGOContext

 

GSSContext element for SPNEGO mechanism is implemented to carry on the negotiation and provides security services that are available for the selected mechanism after the negotiation is successfully completed. Detailed negotiation procedure is described in RFC 2478.

 

The "IBMSPNEGO" provider implementation considers network connection setup as a critical performance characteristic. To avoid extra round trip, the preferred mechanism's initial security token is always piggybacked in the negotiation's initial token for the initiator. The initial security token is wrapped up based on corresponding mechanism's credential that has been acquired. If such credential is not specified by the caller, the default credential, which in IBM JGSS is Kerberos v5 mechanism specific credential, will be pulled out.

 

The policy by which the target selects a security mechanism is that the target would always choose the first mechanism in the initiator's list based on whether the credential for that mechanism is available.

 

To provide GSS-API caller the ability to reduce the set of mechanisms from supported mechanisms for negotiation, two APIs are added to GSSContext interface - setNegMechs(Oid[], GSSCredential), and getNegMechs(GSSCredential). They are introduced in RFC 2478. See RFC 2478 appendix A for more information. Users can limit the set of mechanisms for negotiation by calling setNegMechs() on both initiator side and target side. If users do not specify it at the application level, the full set of mechanism types available on the system is used, and the mechanism specific credential element will be acquired before negotiation start.

 

Currently, org.ietf.jgss.GSSContext does not support setNegMechs() and getNegMechs() in order to remain compatibility with Sun JDK’s GSSContext class. These two APIs are supported by IBM JGSS framework in GSSContext implementation class. It is recommended that you always invoke the common public APIs (those in org.ietf.jgss package) in your application. But if you really do want to control the set of mechanisms that are negotiable, com.ibm.security.jgss.GSSContextImpl  class provides you with this capability.