com.dstc.security.kerberos
Class Kerberos

java.lang.Object
  |
  +--com.dstc.security.kerberos.Kerberos

public class Kerberos
extends Object

This is the main class and point of entry to the kerberos package, providing Kerberos-level services to both Kerberos clients and servers.

Both high-level and low-level operations are supported. High-level operations are methods for making ticket requests to a KDC (Key Distribution Centre), and a method which returns a GSSManager managing GSS-API level calls. Low-level operations are mainly methods for generating and processing Kerberos messages. They are defined and exposed here so that customized versions of the higher-level methods can be built, if necessary. Most Kerberos applications will only need to call the high-level methods. Familiarity with RFC 1510 is a requirement to use the low-level API.

The high-level ticket requesting methods are for a Kerberos user (as opposed to Kerberos service) and are (variants of) requestInitialTicket(), requestTicketGrantingTicket(), and requestServiceTicket(). An initial ticket is a ticket obtained from the Authentication Service (AS). A special case of an initial ticket is a ticket granting ticket (TGT), which is a ticket for the Ticket Granting Service (TGS) to issue service tickets. Service tickets can also be directly obtained from the AS, as initial tickets.

An instance of Kerberos can be obtained in two ways: either by supplying a KerberosContext to getInstance(), or by calling getInstance() with no arguments, in which case a default KerberosContext is used in conjunction with a number of system properties. The second method is mainly for the benefit of the mechanism-independent GSS-API getInstance() factory method in GSSManager, which GSS-API enabled applications which care about mechanism-portability should write to.

Example usage:

    // Suppose we are a Kerberos user registered in a certain Kerberos
    // realm, and we want to obtain a TGT and subsequently make GSS-API
    // calls as a context initiator 

    String userName = ....
    String realm = ....
    PrincipalName principal = new PrincipalName(userName);
    InetAddress kdc = ....

    // Set up a KerberosContext ...
    KerberosContext context = new KerberosContext(realm, principal, kdc);
    
    // .... with an MIT-compatible file credential cache
    context.setCredentialStore(new FileCredentialStore("/tmp/ccache"));

    // Get a Kerberos instance for this context
    Kerberos kerberos = Kerberos.getInstance(context);

    // Get our Kerberos key in prepartion for decrypting a KDC response
    // assuming we know its key value. This will be slightly different
    // if we know the password form of the key
    KerberosKey key = KerberosKey.getInstance(DES_CBC_MD5, keyBytes);
   
    // Request a TGT with default KDCOptions
    KDCOptions kdcOptions = new KDCOptions();
    Credential cred = kerberos.requestTicketGrantingTicket(key, kdcOptions);

    // Store Credential in CredentialStore
    kerberos.getContext().getCredentialStore().put(cred);

    // With a TGT in the CredentialStore we are ready for GSSAPI ...

    // So obtain a GSSManager ...
    org.ietf.jgss.GSSManager gss = kerberos.getGSSManager();

    // ... and make GSS API calls
    ......

 

See Also:
KerberosContext, Credential, KeyTab, CredentialStore, GSSManager

Field Summary
static int CKSUM_CRC32
          Checksum type CRC32 (0x01)
static int CKSUM_DES_MAC
          Checksum type des-mac (0x04)
static int CKSUM_MD4
          Checksum type rsa-md4 (0x02)
static int CKSUM_MD5
          Checksum type rsa-md5 (0x07)
static int DES_CBC_CRC
          Encryption type des-cbc-crc (0x01)
static int DES_CBC_MD4
          Encryption type des-cbc-md4 (0x02)
static int DES_CBC_MD5
          Encryption type des-cbc-md5 (0x03)
 
Method Summary
static APReq createApplicationRequest(Credential cred, APOptions apOpts, int seqNum, Checksum cksum, EncryptionKey subKey)
          Creates and returns an APReq to hand over to a Kerberized application, using a supplied Credential and request options.
static APRep createApplicationResponse(EncryptionKey key, Date cTime, int cusec, int seqNum, EncryptionKey subKey)
          Creates and returns an APRep in response to a successful application request with a given Kerberos encryption key.
 KrbASReq createKrbASReq(PrincipalName sName, KDCOptions options, InetAddress[] adds, Date validFrom, Date validTill, PaData[] padatas)
          Creates and returns a KrbASReq in order to send to a KDC.
static KrbCred createKrbCred(EncryptionKey key, Credential[] creds)
          Creates a KrbCred message with an EncryptionKey and a list of Credentials to forward.
static KrbError createKrbError(int errorCode, String server)
          Creates a KrbError message with an error code, and the server name.
static KrbError createKrbError(int errorCode, String realm, PrincipalName sName)
          Creates a KrbError message with an error code, and the realm and server principal name
 KrbTGSReq createKrbTGSReq(Credential cred, PrincipalName sName, String realm, KDCOptions options, Date validFrom, Date validTill, InetAddress[] adds, Ticket addTicket, AuthorizationDataElement[] authData)
          Creates and returns a KrbTGSReq in order to send to a KDC.
static APReq decryptApplicationRequest(EncryptionKey key, APReq apReq)
          Decrypts a supplied APReq with a given Kerberos encryption key and returns a decrypted APReq.
static APRep decryptApplicationResponse(EncryptionKey key, APRep apRep)
          Decrypts a supplied APRep with a given Kerberos encryption key and returns a decrypted APRep
static KrbCred decryptKrbCred(EncryptionKey key, KrbCred cred)
          Decrypts a supplied KrbCred with a given Kerberos encryption key and returns a decrypted KrbCred
static Ticket decryptTicket(EncryptionKey key, Ticket ticket)
          Decrypts a supplied Ticket with a given Kerberos encryption key and returns a decrypted Ticket
 KerberosContext getContext()
          Returns the KerberosContext for this Kerberos instance
 GSSManager getGSSManager()
          Returns the GSSManager for this Kerberos instance.
static Kerberos getInstance()
          Returns a Kerberos instance for a KerberosContext which is constructed from defaults and from information passed through system properties.
static Kerberos getInstance(KerberosContext context)
          Returns a Kerberos instance for a given KerberosContext
 KrbASRep getKrbASRepFromKDC(KrbASReq req, EncryptionKey key)
          Sends the supplied KrbASReq to the configured KDC, processes the reply and returns it as a KrbASRep, if successful.
 KrbTGSRep getKrbTGSRepFromKDC(KrbTGSReq req)
          Sends the supplied KrbTGSReq to the configured KDC, processes the reply and returns it as a KrbTGSRep, if successful.
static KerberosMessage getMessage(byte[] encoded)
          Returns a KerberosMessage from its ASN.1 DER encoding.
 Credential processKrbASRep(KrbASRep rep, EncryptionKey key)
          Processes (decrypts with the supplied EncryptionKey) a KrbASRep obtained from a KDC and returns a Credential.
 Credential processKrbTGSRep(KrbTGSRep rep, EncryptionKey key)
          Processes (decrypts with the supplied EncryptionKey) a KrbTGSRep obtained from a KDC and returns a Credential.
 Credential requestInitialTicket(EncryptionKey key, PrincipalName sName, KDCOptions options, Date validFrom, Date validTill, InetAddress[] adds, PaData[] padatas)
          Requests from the KDC an initial ticket (may be TGT or service ticket) for the supplied target principal with supplied request options, validity dates (may be null, in which case defaults apply), addresses for which the ticket is to be valid (may be null, in which case it's all the local addresses), pre-authentication data (may be null), together with an encryption key to decrypt the KDC response.
 Credential requestServiceTicket(Credential cred, PrincipalName sName, String serverRealm, KDCOptions options)
          Requests from the KDC a service ticket with a Credential (containing a suitable TGT) for a service with given name and realm, and given request options and, if successful, returns a Credential (containing the service ticket).
 Credential requestServiceTicket(Credential cred, PrincipalName sName, String serverRealm, KDCOptions options, Date validFrom, Date validTill, Ticket addTicket, AuthorizationDataElement[] authData)
          Requests from the KDC a service ticket with a Credential (containing a suitable TGT) for a service with given name and realm, given request options, validity dates (may be null, in which case defaults apply), additional tickets (may be null) and authorization data (may be null) and, if successful, returns a Credential (containing the service ticket).
 Credential requestTicketGrantingTicket(EncryptionKey key, KDCOptions options)
          Requests from the KDC a TGT with supplied request options, together with an encryption key to decrypt the KDC response.
 Credential requestTicketGrantingTicket(EncryptionKey key, KDCOptions options, Date validFrom, Date validTill, InetAddress[] adds, PaData[] padatas)
          Requests from the KDC a TGT with supplied request options, validity dates (may be null, in which case defaults apply), addresses for which the ticket is to be valid (may be null, in which case it's all the local addresses), pre-authentication data (may be null), together with an encryption key to decrypt the KDC response.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DES_CBC_CRC

public static final int DES_CBC_CRC
Encryption type des-cbc-crc (0x01)

DES_CBC_MD4

public static final int DES_CBC_MD4
Encryption type des-cbc-md4 (0x02)

DES_CBC_MD5

public static final int DES_CBC_MD5
Encryption type des-cbc-md5 (0x03)

CKSUM_CRC32

public static final int CKSUM_CRC32
Checksum type CRC32 (0x01)

CKSUM_MD4

public static final int CKSUM_MD4
Checksum type rsa-md4 (0x02)

CKSUM_DES_MAC

public static final int CKSUM_DES_MAC
Checksum type des-mac (0x04)

CKSUM_MD5

public static final int CKSUM_MD5
Checksum type rsa-md5 (0x07)
Method Detail

getInstance

public static Kerberos getInstance()
Returns a Kerberos instance for a KerberosContext which is constructed from defaults and from information passed through system properties.

This factory method is for the benefit of applications which "access" the kerberos library through the GSSAPI call org.ietf.jgss.GSSManager.getInstance(). It is only valid for GSSAPI context initiators with a FileCredentialStore and context acceptors with a FileKeyTab (the standard MIT Kerberos scenario). Applications with different needs should instead use the alternative and more flexible factory method Kerberos.getInstance(KerberosContext).

Five system properties are consulted:

  1. A jcsi.kerberos.principal property for the principal
  2. A jcsi.kerberos.realm property for the realm
  3. A jcsi.kerberos.KDChost property for the KDC host
  4. A jcsi.kerberos.ccache property for the location of the FileCredentialStore
  5. A jcsi.kerberos.keytab property for the location of the FileKeyTab

If jcsi.kerberos.principal is not set, the standard property java.user will be used in its place. If either jcsi.kerberos.realm or jcsi.kerberos.kdcHost is null, a RuntimeException will be thrown. Likewise if both the fourth and fifth properties are null.


getInstance

public static Kerberos getInstance(KerberosContext context)
Returns a Kerberos instance for a given KerberosContext

getContext

public KerberosContext getContext()
Returns the KerberosContext for this Kerberos instance

getGSSManager

public GSSManager getGSSManager()
Returns the GSSManager for this Kerberos instance.

Note. Calling org.ietf.jgss.GSSManager.getInstance() is equivalent to calling Kerberos.getInstance().getGSSManager()


createKrbASReq

public KrbASReq createKrbASReq(PrincipalName sName,
                               KDCOptions options,
                               InetAddress[] adds,
                               Date validFrom,
                               Date validTill,
                               PaData[] padatas)
                        throws KerberosException
Creates and returns a KrbASReq in order to send to a KDC. The request will have the supplied KDCOptions and PaDatas set and will be for use from the specified addresses.

Note. Clients requiring authentication to a KDC do not normally need to handle KrbASReq directly. The requestInitialTicket() methods are recommended instead. This method exists to allow a developer to create a customized version of requestInitialTicket().


createKrbTGSReq

public KrbTGSReq createKrbTGSReq(Credential cred,
                                 PrincipalName sName,
                                 String realm,
                                 KDCOptions options,
                                 Date validFrom,
                                 Date validTill,
                                 InetAddress[] adds,
                                 Ticket addTicket,
                                 AuthorizationDataElement[] authData)
                          throws KerberosException
Creates and returns a KrbTGSReq in order to send to a KDC. The request will have the supplied KDCOptions set and will be for a service Ticket to use for the principal with specified PrincipalName and realm.

Note. Clients requiring a service Ticket from a KDC do not normally need to handle KrbTGSReq directly. The requestServiceTicket() methods are recommended instead. This method exists to allow a developer to create a customized version of requestServiceTicket().


processKrbASRep

public Credential processKrbASRep(KrbASRep rep,
                                  EncryptionKey key)
                           throws KerberosException
Processes (decrypts with the supplied EncryptionKey) a KrbASRep obtained from a KDC and returns a Credential.

This method can handle password salts transparently. More specifically, if the KrbASRep has a PaData of type PaData.PA_PW_SALT (indicating a non-standard mix-in string for password-to-key conversion), and the supplied EncryptionKey is of type KerberosKey with a non-null getMixInString(), then updateMixIn() with the value specified in the PaData will be called on the KerberosKey before it is used to decrypt KrbASRep. Otherwise the passed-in EncryptionKey is used as is.

Note. Clients requiring an initial Ticket from a KDC do not normally need to handle KrbASRep directly. The requestInitialTicket() methods should be used, if possible. This method exists to allow a developer to create a customized version of requestInitialTicket().


processKrbTGSRep

public Credential processKrbTGSRep(KrbTGSRep rep,
                                   EncryptionKey key)
                            throws KerberosException
Processes (decrypts with the supplied EncryptionKey) a KrbTGSRep obtained from a KDC and returns a Credential.

Note. Clients requiring a service Ticket from a KDC do not normally need to handle KrbTGSRep directly. The requestServiceTicket() methods should be used, if possible. This method exists to allow a developer to create a customized version of requestServiceTicket().


requestTicketGrantingTicket

public Credential requestTicketGrantingTicket(EncryptionKey key,
                                              KDCOptions options)
                                       throws KerberosException,
                                              IOException
Requests from the KDC a TGT with supplied request options, together with an encryption key to decrypt the KDC response. If successful, the TGT is returned as a Credential

requestTicketGrantingTicket

public Credential requestTicketGrantingTicket(EncryptionKey key,
                                              KDCOptions options,
                                              Date validFrom,
                                              Date validTill,
                                              InetAddress[] adds,
                                              PaData[] padatas)
                                       throws KerberosException,
                                              IOException
Requests from the KDC a TGT with supplied request options, validity dates (may be null, in which case defaults apply), addresses for which the ticket is to be valid (may be null, in which case it's all the local addresses), pre-authentication data (may be null), together with an encryption key to decrypt the KDC response. If successful, the TGT is returned as a Credential

requestInitialTicket

public Credential requestInitialTicket(EncryptionKey key,
                                       PrincipalName sName,
                                       KDCOptions options,
                                       Date validFrom,
                                       Date validTill,
                                       InetAddress[] adds,
                                       PaData[] padatas)
                                throws KerberosException,
                                       IOException
Requests from the KDC an initial ticket (may be TGT or service ticket) for the supplied target principal with supplied request options, validity dates (may be null, in which case defaults apply), addresses for which the ticket is to be valid (may be null, in which case it's all the local addresses), pre-authentication data (may be null), together with an encryption key to decrypt the KDC response. If successful, the TGT is returned as a Credential

getKrbASRepFromKDC

public KrbASRep getKrbASRepFromKDC(KrbASReq req,
                                   EncryptionKey key)
                            throws KerberosException,
                                   IOException
Sends the supplied KrbASReq to the configured KDC, processes the reply and returns it as a KrbASRep, if successful. If the KDC sends a KrbError message indicating a failure condition, a KerberosError exception is thrown.

If the KerberosError is one indicating pre-authentication required, a second request will be sent transparently with an PaEncTimestamp generated with the supplied EncryptionKey appended to the original KrbASReq. If this results in another KrbError from the KDC, a KerberosError exception will be thrown with the corresponding error code.

Note. Applications do not normally need to handle KrbASReq directly. The requestInitialTicket() methods should be sufficient for most users. This method exists to allow a developer to create a customized version of requestInitialTicket().


requestServiceTicket

public Credential requestServiceTicket(Credential cred,
                                       PrincipalName sName,
                                       String serverRealm,
                                       KDCOptions options)
                                throws KerberosException,
                                       IOException
Requests from the KDC a service ticket with a Credential (containing a suitable TGT) for a service with given name and realm, and given request options and, if successful, returns a Credential (containing the service ticket).

requestServiceTicket

public Credential requestServiceTicket(Credential cred,
                                       PrincipalName sName,
                                       String serverRealm,
                                       KDCOptions options,
                                       Date validFrom,
                                       Date validTill,
                                       Ticket addTicket,
                                       AuthorizationDataElement[] authData)
                                throws KerberosException,
                                       IOException
Requests from the KDC a service ticket with a Credential (containing a suitable TGT) for a service with given name and realm, given request options, validity dates (may be null, in which case defaults apply), additional tickets (may be null) and authorization data (may be null) and, if successful, returns a Credential (containing the service ticket).

getKrbTGSRepFromKDC

public KrbTGSRep getKrbTGSRepFromKDC(KrbTGSReq req)
                              throws KerberosException,
                                     IOException
Sends the supplied KrbTGSReq to the configured KDC, processes the reply and returns it as a KrbTGSRep, if successful. If the KDC sends a KrbError message indicating a failure condition, a KerberosError exception is thrown.

Note. Applications do not normally need to handle KrbTGSReq directly. The requestServiceTicket() methods should be sufficient for most users. This method exists to allow a developer to create a customized version of requestServiceTicket().


createApplicationRequest

public static APReq createApplicationRequest(Credential cred,
                                             APOptions apOpts,
                                             int seqNum,
                                             Checksum cksum,
                                             EncryptionKey subKey)
                                      throws KerberosException
Creates and returns an APReq to hand over to a Kerberized application, using a supplied Credential and request options. The supplied Credential should have a Ticket valid for the target application.

Note. Applications do not normally need to handle APReq directly. Equivalent ways of dealing with this are available through the GSSAPI (context initiation), which is the recommended practice.


decryptApplicationRequest

public static APReq decryptApplicationRequest(EncryptionKey key,
                                              APReq apReq)
                                       throws KerberosException
Decrypts a supplied APReq with a given Kerberos encryption key and returns a decrypted APReq.

Note. Applications do not normally need to handle APReq directly. Equivalent ways of dealing with this are available through the GSSAPI (context acceptance), which is the recommended practice.


createApplicationResponse

public static APRep createApplicationResponse(EncryptionKey key,
                                              Date cTime,
                                              int cusec,
                                              int seqNum,
                                              EncryptionKey subKey)
                                       throws KerberosException
Creates and returns an APRep in response to a successful application request with a given Kerberos encryption key.

Note. Applications do not normally need to handle APRep directly. Equivalent ways of dealing with this are available through the GSSAPI (context acceptance), which is the recommended practice.


decryptApplicationResponse

public static APRep decryptApplicationResponse(EncryptionKey key,
                                               APRep apRep)
                                        throws KerberosException
Decrypts a supplied APRep with a given Kerberos encryption key and returns a decrypted APRep

Note. Applications do not normally need to handle APRep directly. Equivalent ways of dealing with this are available through the GSSAPI (context initiation), which is the recommended practice.


decryptTicket

public static Ticket decryptTicket(EncryptionKey key,
                                   Ticket ticket)
                            throws KerberosException
Decrypts a supplied Ticket with a given Kerberos encryption key and returns a decrypted Ticket

Note. Applications do not normally need to handle Tickets directly. Equivalent ways of dealing with this are available through the GSSAPI (context acceptance), which is the recommended practice.


createKrbCred

public static KrbCred createKrbCred(EncryptionKey key,
                                    Credential[] creds)
                             throws KerberosException
Creates a KrbCred message with an EncryptionKey and a list of Credentials to forward.

Note. Applications do not normally need to call this low-level method directly. Equivalent ways of dealing with this are available through the GSSAPI (context acceptance), which is the recommended practice.


decryptKrbCred

public static KrbCred decryptKrbCred(EncryptionKey key,
                                     KrbCred cred)
                              throws KerberosException
Decrypts a supplied KrbCred with a given Kerberos encryption key and returns a decrypted KrbCred

Note. Applications do not normally need to handle KrbCred directly. Equivalent ways of dealing with this are available through the GSSAPI (context acceptance), which is the recommended practice.


createKrbError

public static KrbError createKrbError(int errorCode,
                                      String server)
                               throws KerberosException
Creates a KrbError message with an error code, and the server name.

Note. Applications do not normally need to call this low-level method.


createKrbError

public static KrbError createKrbError(int errorCode,
                                      String realm,
                                      PrincipalName sName)
                               throws KerberosException
Creates a KrbError message with an error code, and the realm and server principal name

Note. Applications do not normally need to call this low-level method.


getMessage

public static KerberosMessage getMessage(byte[] encoded)
                                  throws KerberosException
Returns a KerberosMessage from its ASN.1 DER encoding. This is a utility method not normally of relevance to application developers