gov.fnal.controls.kerberos
Class KerberosLoginContext

java.lang.Object
  javax.security.auth.login.LoginContext
      gov.fnal.controls.kerberos.KerberosLoginContext

public class KerberosLoginContext

extends javax.security.auth.login.LoginContext

The KerberosLoginContext is the principal class of the Kerberos Module for Java (KMJ). It describes the running application as a single entity of the security infrastructure that can be shared among multiple classes and threads. The class incorporates access to other relevant objects and concepts, such as Subject, Principal, and GSSContext.

The class performs the following three functions:

1. Initialization of the environment,
2. Logging the user in and out,
3. Management of GSS contexts.

As the rule of thumb, the KerberosLoginContext's getInstance() method should be called before any other calls to KMJ are made, because many inner classes of the project use environment variables and temporary files set up in its static initializer.

Here is the list of system variables used in KMJ:

gov.fnal.controls.kerberos.keytab

Name of the keytab file. Should be specified if the principal's credential is stored in a keytab file different from {user.name}/krb5.keytab.

gov.fnal.controls.kerberos.principal

Default principal name. Required only if the authentication is conducted through a keytab file. If not specified, the expected keytab principal is reconstructed from the current user name and the default realm (this assumption will not work for service principals). If there is a credential cache, this property is not required. But if it is set, the value is used as an additional filter for the tickets.

java.security.krb5.conf

Name of the Kerberos configuration file. Set this property only if the default krb5.conf does not exist in kerberos-client.jar, or should not be used. If the ...conf property is not set, the KerberosLoginContext tries to use a local copy of /META-INF/krb5.conf (preferred way). However, if both ...realm and ...kdc properties are set, they take precedence.

java.security.krb5.realm

java.security.krb5.kdc

Kerberos default realm and the key distribution center address. Can be used if no krb5.conf is available. These properties must always come together.

gov.fnal.controls.kerberos.default_realm

An internal property which keeps the default realm name. It it set automatically and should not be changed from applications.

java.security.auth.login.config

Login configuration file URL. It is set automatically during the Module start up and points to the login.conf inside the project's jar file. Typically, should not be changed.

To log the user in and out, the LoginContext's login and logout methods are used. Unlike the generic Java implementation, KMJ is using a fairly complex and operating system-specific way of credential discovery, as specified in its login.conf file. But generally speaking, the login method does not conduct a real login, as it simply reads the Kerberos ticket, possibly forgered, from a cache without any further verification.

The General Security Service (GSS) is used to transfer the local user credentials on a remote host. As the result of this operation, the pair of peers establishes the common security context. This allows two hosts to use some common services, such as encrypted data transfer. Besides that, posession of a GSSContext instance can be used to verify identity of the remote party. KerberosLoginContext implements two pairs of convenient methods for GSS context establishing.

The class also can be used as a standalone utility to test authentication and GSS, on both server and client sides.

Version:

$Revision: 1.11 $

Author:

Andrey Petrov

Field Summary

static byte	F_ANONYMITY GSS option for anonymity.
static byte	F_CONFIDENTIALITY GSS option for confidentiality.
static byte	F_DELEGATION GSS option for delegation.
static byte	F_INTEGRITY GSS option for integrity.
static byte	F_MUTUAL_AUTH GSS option for mutual authentication.
static byte	F_REPLAY_DET GSS option for replay detection.
static byte	F_SEQUENCE_DET GSS option for sequence detection.

Method Summary

org.ietf.jgss.GSSContext	acceptSecContext(java.io.InputStream in, java.io.OutputStream out) Accepts security context on the server.
org.ietf.jgss.GSSContext	acceptSecContext(java.lang.String token) Accepts security context on the server (trivial method).
static KerberosLoginContext	getInstance() Gets shared instance of this class.
javax.security.auth.kerberos.KerberosPrincipal	getPrincipal() Gets the authenticated principal.
org.ietf.jgss.GSSContext	initSecContext(java.io.InputStream in, java.io.OutputStream out, ServiceName serviceName, byte options) Initiates security context on the client.
java.lang.String	initSecContext(ServiceName serviceName) Initiates security context on the client (trivial method).
void	login() Performs the authentication, as specified in login.conf file for the given operating system.
static void	main(java.lang.String[] args) Command line utility.

Methods inherited from class javax.security.auth.login.LoginContext

getSubject, logout

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

F_ANONYMITY

public static final byte F_ANONYMITY

GSS option for anonymity.

Requests that the client's identity not be disclosed to the server.

See Also:

Constant Field Values

F_CONFIDENTIALITY

public static final byte F_CONFIDENTIALITY

GSS option for confidentiality.

Requests that data confidentiality be enabled for the GSSContext's wrap method.

See Also:

Constant Field Values

F_DELEGATION

public static final byte F_DELEGATION

GSS option for delegation.

Requests that the client's credentials be delegated to the server during context establishment

See Also:

Constant Field Values

F_INTEGRITY

public static final byte F_INTEGRITY

GSS option for integrity.

Requests that data integrity be enabled for the GSSContext's wrap and getMIC methods.

See Also:

Constant Field Values

F_MUTUAL_AUTH

public static final byte F_MUTUAL_AUTH

GSS option for mutual authentication.

Requests that mutual authentication be done during context establishment. Automatically assumed if F_CONFIDENTIALITY, F_INTEGRITY, F_REPLAY_DET, or F_SEQUENCE_DET option is set.

See Also:

Constant Field Values

F_REPLAY_DET

public static final byte F_REPLAY_DET

GSS option for replay detection.

Requests that replay detection be enabled for the per-message security services after context establishemnt.

See Also:

Constant Field Values

F_SEQUENCE_DET

public static final byte F_SEQUENCE_DET

GSS option for sequence detection.

Requests that sequence checking be enabled for the per-message security services after context establishemnt.

See Also:

Constant Field Values

Method Detail

main

public static void main(java.lang.String[] args)

Command line utility.

   Usage: KerberosLoginContext
          KerberosLoginContext client <service> <host>[:<port>] [<opt>]*
          KerberosLoginContext server [<port>]

     Authentication-only mode (no keyword):
     The utility authenticates the user or service principal by reading its
     credentials from a ticket cache or a keytab file.

     Client mode:
     The user principal is authenticated, and then its credentials are sent
     to the specified server.
         <service>          Service name
         <host>             Server address
         <port>             Server port, default is 4747
         <opt>              GSS options:
             +|-i           Request/reset integrity
             +|-c           Request/reset confidentiality
             +|-r           Request/reset replay detection
             +|-s           Request/reset sequence detection

     Server mode:
     The server accepts clients' credentials. Use appropriate environment
     variables to set up service principal name, keytab location etc.,
     if needed.
         <port>             Server port, default is 4747
 

Parameters:

args - command line arguments.

getInstance

public static KerberosLoginContext getInstance()

Gets shared instance of this class.

Returns:

shared instance.

login

public void login()
           throws javax.security.auth.login.LoginException

Performs the authentication, as specified in login.conf file for the given operating system.

By authentication we understand either reading the Kerveros ticket from a cache, or obtaining the secret key from a keytab file.

Throws:

javax.security.auth.login.LoginException - if the proper credentials can not be obtained.

getPrincipal

public javax.security.auth.kerberos.KerberosPrincipal getPrincipal()

Gets the authenticated principal.

If the principal is not logged in, returns null.

Returns:

Kerberos principal or null.

initSecContext

public java.lang.String initSecContext(ServiceName serviceName)
                                throws javax.security.auth.login.LoginException,
                                       org.ietf.jgss.GSSException,
                                       java.io.IOException

Initiates security context on the client (trivial method).

This is used for the simple authentication, such as in a web browser. The goal is to verify identity of the client on the server side by possession of the valid GSSContext. All the GSS options are reset, and no common security services are available. GSSContext on the client is immediately discarded. The operation completes after a single transfer of data from the client to the server.

Parameters:

serviceName - the target service name.

Returns:

a piece of data (security token) in BASE64 encoding that needs to be transferred on the server and applied with acceptSecContext(String) method.

Throws:

javax.security.auth.login.LoginException - if login operation failed.

org.ietf.jgss.GSSException - if GSS transaction failed.

java.io.IOException - if streams failed.

See Also:

initSecContext(InputStream,OutputStream,ServiceName,byte)

initSecContext

public org.ietf.jgss.GSSContext initSecContext(java.io.InputStream in,
                                               java.io.OutputStream out,
                                               ServiceName serviceName,
                                               byte options)
                                        throws javax.security.auth.login.LoginException,
                                               org.ietf.jgss.GSSException,
                                               java.io.IOException

Initiates security context on the client.

If the principal is not authenticated in advance, login is attempted. It usually takes 1 to 3 single transfers of data between two parties to complete the trasaction.

Parameters:

in - input stream connected to the server's output.

out - output stream connected to the server's input.

serviceName - the target service name.

options - combination of GSS options.

Returns:

established GSS context.

Throws:

javax.security.auth.login.LoginException - if login operation failed.

org.ietf.jgss.GSSException - if GSS transaction failed.

java.io.IOException - if streams failed.

See Also:

acceptSecContext(InputStream,OutputStream)

acceptSecContext

public org.ietf.jgss.GSSContext acceptSecContext(java.lang.String token)
                                          throws javax.security.auth.login.LoginException,
                                                 org.ietf.jgss.GSSException,
                                                 java.io.IOException

Accepts security context on the server (trivial method).

This is used for the simple authentication, such as in a web browser. The goal is to verify identity of the client on the server side by possession of the valid GSSContext. All the GSS options are reset, and no common security services are available. The operation completes after a single transfer of data from the client to the server.

Parameters:

token - a security token in BASE64 encoding obtained from the client's initSecContext(gov.fnal.controls.kerberos.login.ServiceName) method.

Returns:

established GSS context to verify identity of the client.

Throws:

javax.security.auth.login.LoginException - if login operation failed.

org.ietf.jgss.GSSException - if GSS transaction failed.

java.io.IOException - if streams failed.

See Also:

acceptSecContext(InputStream,OutputStream)

acceptSecContext

public org.ietf.jgss.GSSContext acceptSecContext(java.io.InputStream in,
                                                 java.io.OutputStream out)
                                          throws javax.security.auth.login.LoginException,
                                                 org.ietf.jgss.GSSException,
                                                 java.io.IOException

Accepts security context on the server.

If the principal is not authenticated in advance, login is attempted. It usually takes 1 to 3 single transfers of data between two parties to complete the trasaction.

Parameters:

in - input stream connected to the client's output.

out - output stream connected to the client's input.

Returns:

established GSS context.

Throws:

javax.security.auth.login.LoginException - if login operation failed.

org.ietf.jgss.GSSException - if GSS transaction failed.

java.io.IOException - if streams failed.

See Also:

initSecContext(InputStream,OutputStream,ServiceName,byte)