Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD