Internet Draft Rob Weltman
Netscape Communications Corp.
Rosanna Lee
draft-weltman-java-sasl-02.txt Sun Microsystems
Rob Earhart
Carnegie Mellon
June 4, 1999
The Java SASL Application Program Interface
Status of this Memo
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Task Force
(IETF), its areas, and its working groups. Note that other groups
may also distribute working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six
months and may be updated, replaced, or obsoleted by other documents
at any time. It is inappropriate to use Internet Drafts as
reference material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
Abstract
This document defines a client-side and a server-side Java language
interface for using the Simple Authentication and Security Layer
(SASL) mechanisms for adding authentication support to connection-
based protocols. The interface promotes sharing of SASL mechanism
drivers and security layers between applications using different
protocols. It complements but does not replace [SASL], which defines
and exemplifies use of the SASL protocol in a language-independent
way.
Expires 12/99 [Page 1]
JAVA SASL API June 1999
1 Overview of the SASL classes..........................5
1.1 Interfaces .......................................5
1.2 Classes .......................................5
2 Overview of SASL API Use..............................6
3 The java SASL classes.................................7
3.1 public class Sasl.....................................7
3.1.1 createSaslClient.................................7
3.1.2 setSaslClientFactory.............................9
3.1.3 createSaslServer.................................9
3.1.4 setSaslServerFactory............................10
3.2 public interface SaslClient..........................11
3.2.1 createInitialResponse...........................11
3.2.2 evaluateChallenge...............................11
3.2.3 isComplete......................................11
3.2.4 getSecurityLayer................................11
3.2.5 getMechanismName................................12
3.3 public interface SaslClientFactory...................12
3.3.1 createSaslClient................................12
3.3.2 getMechanismNames...............................13
3.4 public interface SaslServer..........................13
3.4.1 evaluateResponse................................13
3.4.2 isComplete......................................14
3.4.3 getSecurityLayer................................14
3.4.4 getMechanismName................................14
3.4.5 getAuthorizationID..............................14
3.5 public interface SaslServerFactory...................15
3.5.1 createSaslServer................................15
3.5.2 getMechanismNames...............................16
3.6 public class SaslException...........................16
3.6.1 Constructors....................................16
3.6.2 getException....................................17
3.6.3 printStackTrace.................................17
3.7 public interface SecurityLayer.......................17
3.7.1 encode......................................17
3.7.2 decode......................................18
4 Security Considerations..............................19
5 Bibliography ......................................19
6 Authors' Addresses...................................19
7 Acknowledgements.....................................19
8 Appendix A - Sample java LDAP program using SASL.....20
9 Appendix B - Changes from java-sasl-01.txt...........24
Expires 12/99 [Page 2]
JAVA SASL API June 1999
Introduction
See [SASL], section 3, for an introduction to and overview of the
SASL framework for authentication and negotiation of a security
layer. The following presents an outline of the concepts.
--------------- ------------------- -----------------
| Application |-----| Protocol Driver |------| MD5 |
--------------- ------------------- | -----------------
|
| -----------------
|--| Kerberos v5 |
| -----------------
|
| -----------------
|--| PKCS-11 |
| -----------------
|
|
|
| - - - - - - - - -
|--| xxxYYYxxx |
- - - - - - - - -
An application chooses a Protocol Driver specific to the protocol it
wants to use, and specifies one or more acceptable mechanisms. The
Protocol Driver controls the socket, and knows the format/packaging
of bytes sent down and received from the socket, but does not know
how to authenticate or to encrypt/ decrypt the bytes. It uses one of
the Mechanism Drivers to help it perform authentication. The
Protocol Driver examines each byte string received from the server
during the authentication in a protocol-specific way to determine if
the authentication process has been completed. If not, the byte
string is passed to the Mechanism Driver to be interpreted as a
server challenge; the Mechanism Driver returns an appropriate
response, which the Protocol Driver can encode in a protocol-
specific way and return to the server.
If the Protocol Driver concludes from the byte string received from
the server that authentication is complete, it may query the
Mechanism Driver if it considers the authentication process
complete, in order to thwart early completion messages inserted by
an intruder.
On completed authentication, the Protocol Driver may receive from
the Mechanism Driver a Security Layer object. From this point on,
any data exchanged throught the socket is passed to the Security
Layer object for encoding/decoding.
A complication here is that some authentication methods may require
additional user/application input. That means that a Mechanism
Driver may need to call up to an application during the
authentication process. To satisfy this requirement, the application
Expires 12/99 [Page 3]
JAVA SASL API June 1999
can supply a javax.security.auth.callback.CallbackHandler instance
[JAAS] that can be used by the Mechanism Driver to prompt the user
for additional input.
Protocol Drivers are protocol-dependent, and may be built in to a
protocol package or an application. There is a generalized framework
for registering and finding Mechanism Drivers. The framework uses a
factory to produce an appropriate Mechanism Driver. The factory may
be preconfigured, explicitly specified by the caller, specified as a
list of packages by the caller, or be identified based on a list of
packages in the System properties.
The Mechanism Drivers are protocol-independent, and don't deal
directly with network connections, just byte arrays, so they can be
implemented in a generalizable way for all protocols.
A Security Layer Driver typically inherits a state object from the
Mechanism Driver, where parameters and resolutions reached during
authentication have been stored.
Different Mechanism Drivers may require different parameters to
carry out the authentication process. This is handled by passing a
java.util.Hashtable object as an argument to instantiation methods.
In the following discussion, 'client' refers to the client-side
protocol driver that is using the SASL mechanism while 'server'
refers to the server-side protocol driver that is using the SASL
mechanism.
In the Java SASL environment, the SaslClient interface represents
the client's view of the Mechanism Driver, while the SaslServer
interface represents the server's view.
--------------- ---------------
| Application |--+ +--| Server |
--------------- | | ---------------
| |
------------------- -------------------
| Protocol Driver |--+ <- - - - -> +--| Protocol Driver |
------------------- | | -------------------
| |
------------------- -------------------
| SaslClient | | SaslServer |
------------------- -------------------
| |
----------------- | | -----------------
| MD5 |----| |---| MD5 |
----------------- | | -----------------
| |
----------------- | | -----------------
| Kerberos v5 |----| |---| Kerberos v5 |
----------------- | | -----------------
| |
----------------- | | -----------------
Expires 12/99 [Page 4]
JAVA SASL API June 1999
| PKCS-11 |----| |---| PKCS-11 |
----------------- | | -----------------
| |
- - - - - - - - - | | - - - - - - - - -
| xxxYYYxxx |----+ +---| xxxYYYxxx |
- - - - - - - - - - - - - - - - - -
A client using the Java SASL API may communicate with any server
implementing the SASL protocol, and a server may use the API to
process authentication requests from any client using the SASL
protocol. It is not required that both sides use the same language
bindings.
1 Overview of the SASL classes
1.1 Interfaces
SaslClient Performs SASL authentication as a
client.
SaslClientFactory An interface for creating instances of
SaslClient. It is not normally accessed
directly by a client, which will use the
Sasl static methods instead. However, a
particular environment may provide and
install a new or different
SaslClientFactory.
SaslServer Performs SASL authentication as a
server.
SaslServerFactory An interface for creating instances of
SaslServer. It is not normally accessed
directly by a server, which will use the
Sasl static methods instead. However, a
particular environment may provide and
install a new or different
SaslServerFactory.
SecurityLayer An interface for encoding and decoding
data.
1.2 Classes
Sasl A static class for creating SASL clients
and servers. It transparently locates
and uses any available
SaslClientFactory/SaslServerFactory
instances.
Expires 12/99 [Page 5]
JAVA SASL API June 1999
SaslException Exception thrown on errors and failures
in the authentication process.
2 Overview of SASL API Use
An application generally uses the SASL API as follows:
- Pass a list of acceptable or known Mechanisms to
Sasl.createSaslClient. The method returns an object
implementing SaslClient on success.
- Create an object implementing the client authentication
callback interfaces, which can provide credentials when
required by the SaslClient.
- Have the SaslClient object begin the authentication process by
providing an initial server response, if the protocol supports
an initial response.
- Responses/challenges are exchanged with the server. If a
response indicates authentication has completed, SaslClient is
queried for validation, and a SecurityLayer object may be
obtained from it. If not, the SaslClient is queried for an
appropriate next response to the server. This continues until
authentication has completed.
- For the rest of the session, messages to the server are encoded
first by the Security Layer (if one has been provided by
SaslClient), and messages from the server are decoded by it
before processing in the application.
A server generally uses the SASL API as follows:
- It receives a request from the client requesting authentication
for a particular SASL mechanism, accompanied by an optional
an initial response.
- It processes the initial response and generates a challenge
specific for the SASL mechanism to be sent back to the client
if the response is processed successfully. If the response is
not processed successfully, it sends an error to the client and
terminates the authentication session.
- Responses/challenges are exchanged with the client. If the
server cannot successful process a response, the server sends
an error to the client and terminates the authentication. If
the server has completed the authentication and has no more
challenges to send, it sends a success indication to the
client.
- If the authentication has completed successfully, the server
extracts the authorization ID of the client from the SaslServer
Expires 12/99 [Page 6]
JAVA SASL API June 1999
instance (if appropriate) to be used for subsequent access
control checks.
- For the rest of the session, messages to and from the client
are encoded and decoded by the Security Layer, if one has been
provided by SaslServer.
The following sections describe the SASL classes in more detail.
3 The Java SASL classes
3.1 public class Sasl
A class capable of providing a SaslClient or SaslServer.
3.1.1 createSaslClient
public static SaslClient
createSaslClient(String[] mechanisms,
String authorizationID,
String protocol,
String serverName,
Hashtable props,
javax.security.auth.callback.CallbackHandler cbh)
throws SaslException
Creates a SaslClient using the parameters supplied. It returns null
if no SaslClient can be created using the parameters supplied.
Throws SaslException if it cannot create a SaslClient because of an
error.
The algorithm for selection is as follows:
1.If a factory has been installed via setSaslClientFactory(), try
it first. If non-null answer produced, return it.
2.Use the packages listed in the javax.security.sasl.client.pkgs
property from props to load in a factory and try to create a
SaslClient, by looking for a class named ClientFactory. Repeat
this for each package on the list until a non-null answer is
produced. If non-null answer produced, return it.
3.Repeat previous step using the javax.security.sasl.client.pkgs
System property.
4.If no non-null answer produced, return null.
Parameters are:
mechanisms The non-null list of mechanism names to try. Each
is the IANA-registered name of a SASL mechanism.
(e.g. "GSSAPI", "CRAM-MD5").
Expires 12/99 [Page 7]
JAVA SASL API June 1999
authorizationIDThe possibly null protocol-dependent
identification to be used for authorization, e.g.
user name or distinguished name. When the SASL
authentication completes successfully, the entity
named by authorizationId is granted access. If
null, access is granted to a protocol-dependent
default (for example, in LDAP this is the DN in
the bind request).
protocol The non-null string name of the protocol for
which the authentication is being performed, e.g
"pop", "ldap".
serverName The non-null fully qualified host name of the
server to authenticate to.
props The possibly null additional configuration
properties for the session, e.g.
javax.security.sasl.encryption.minimum Minimum key length;
default "0" (no
session
protection). "1"
means integrity
protection only.
javax.security.sasl.encryption.maximum Maximum key length;
default "256".
javax.security.sasl.server.authentication "true" if
server must
authenticate to
client; default
"false".
javax.security.sasl.ip.local IP address in
dotted decimal
format, for
kerberos v4; no
default.
javax.security.sasl.ip.remote IP address in
dotted decimal
format, for
kerberos v4; no
default.
javax.security.sasl.maxbuffer Maximum size of
security layer
frames; default "0"
(client will
not use the
security layer).
Expires 12/99 [Page 8]
JAVA SASL API June 1999
javax.security.sasl.client.pkgs A space-separated
list of package
names to use when
locating a
SaslClientFactory.
cbh The possibly null callback handler to used by the
SASL mechanisms to get further information from
the application/library to complete the
authentication. For example, a SASL mechanism
might require the authentication ID and password
from the caller. The authentication ID may be
requested with a NameCallback, and the password
with a PasswordCallback.
3.1.2 setSaslClientFactory
public static void
setSaslClientFactory(SaslClientFactory fac)
Sets the default SaslClientFactory to use. This method sets fac to
be the default factory. It can only be called with a non-null value
once per VM. If a factory has been set already, this method throws
IllegalStateException.
Parameters are:
fac The possibly null factory to set. If null, it
doesn't do anything.
3.1.3 createSaslServer
public static SaslServer
createSaslServer(String mechanism,
String protocol,
String serverName,
Hashtable props,
javax.security.auth.callback.CallbackHandler cbh)
throws SaslException
This method creates a SaslServer for the specified mechanism. It
returns null if no SaslServer can be created for the specified
mechanism.
The algorithm for selection is as follows:
1.If a factory has been installed via setSaslServerFactory(), try
it first. If non-null answer produced, return it.
2.Use the packages listed in the javax.security.sasl.server.pkgs
property in props, if present, to load in a factory and try to
create a SaslServer, by looking for a class named
Expires 12/99 [Page 9]
JAVA SASL API June 1999
ServerFactory. Repeat this for each package on the list until a
non-null answer is produced. If non-null answer produced,
return it.
3.Use the packages listed in the javax.security.sasl.server.pkgs
System property to load in a factory and try to create a
SaslServer. Repeat this for each package on the list until a
non-null answer is produced. If non-null answer produced,
return it.
4.If no non-null answer produced, return null.
Parameters are:
mechanism A non-null IANA-registered name of a SASL
mechanism (e.g. "GSSAPI", "CRAM-MD5").
protocol The non-null string name of the protocol for
which the authentication is being performed, e.g
"pop", "ldap".
serverName The non-null fully qualified host name of the
server to authenticate to.
props The possibly null properties to be used by the
SASL mechanisms to configure the authentication
exchange. See Sasl.createSaslClient for examples
of properties.
cbh The possibly null callback handler to used by the
SASL mechanisms to get further information from
the application/library to complete the
authentication. For example, a SASL mechanism
might require the authentication ID and password
from the caller. The authentication ID may be
requested with a NameCallback, and the password
with a PasswordCallback.
3.1.4 setSaslServerFactory
public static void
setSaslServerFactory(SaslServerFactory fac)
Sets the default SaslServerFactory to use. This method sets fac to
be the default factory. It can only be called with a non-null value
once per VM. If a factory has been set already, this method throws
IllegalStateException.
Parameters are:
fac The possibly null factory to set. If null, it
doesn't do anything.
Expires 12/99 [Page 10]
JAVA SASL API June 1999
3.2 public interface SaslClient
An object implementing this interface can negotiate authentication
using one of the IANA-registered mechanisms.
3.2.1 createInitialResponse
public byte[]
createInitialResponse() throws SaslException
This method prepares a byte array to use for the initial response to
start the authentication process. A SaslException is thrown if the
driver cannot initiate authentication. The return value may be
null, indicating there is no initial response to send to the server.
3.2.2 evaluateChallenge
public byte[]
evaluateChallenge(byte[] challenge)
throws SaslException
If a challenge is received from the server during the authentication
process, this method is called to prepare an appropriate next
response to submit to the server. The response is null if the
challenge accompanied a "SUCCESS" status and the challenge only
contains data for the client to update its state and no response
needs to be sent to the server. A SaslException is thrown if an
error occurred while processing the challenge or generating a
response.
Parameters are:
challenge The non-null challenge received from the server.
3.2.3 isComplete
public boolean
isComplete()
This method may be called at any time to determine if the
authentication process is finished. Typically, the protocol driver
will not do this until it has received something from the server
which indicates (in a protocol-specific manner) that the process has
completed.
3.2.4 getSecurityLayer
public SecurityLayer
getSecurityLayer() throws SaslException
Expires 12/99 [Page 11]
JAVA SASL API June 1999
Once authentication is complete, this method may be called to obtain
an object capable of encoding/decoding data content for the rest of
the session. An exception is thrown if authentication is not yet
complete. It may return null if the mechanism does not define a
security layer, or if none was negotiated.
3.2.5 getMechanismName
public String
getMechanismName()
Report the IANA-registered name of the mechanism used by this
client, e.g. "GSSAPI" or "CRAM-MD5".
3.3 public interface SaslClientFactory
An object implementing this interface can provide a SaslClient.
Implementations must be thread-safe and handle multiple simultaneous
requests.
3.3.1 createSaslClient
public SaslClient
createSaslClient(String[] mechanisms,
String authorizationID,
String protocol,
String serverName,
Hashtable props,
javax.security.auth.callback.CallbackHandler cbh)
throws SaslException
Creates a SaslClient using the parameters supplied. It returns null
if no SaslClient can be created using the parameters supplied.
Throws SaslException if it cannot create a SaslClient because of an
error.
Returns a possibly null SaslClient created using the parameters
supplied. If null, this factory cannot produce a SaslClient using
the parameters supplied.
Parameters are:
mechanisms The non-null list of mechanism names to try. Each
is the IANA-registered name of a SASL mechanism.
(e.g. "GSSAPI", "CRAM-MD5").
authorizationID The possibly null protocol-dependent
identification to be used for authorization, e.g.
user name or distinguished name. When the SASL
authentication completes successfully, the entity
Expires 12/99 [Page 12]
JAVA SASL API June 1999
named by authorizationId is granted access. If
null, access is granted to a protocol-dependent
default (for example, in LDAP this is the DN in
the bind request).
protocol The non-null string name of the protocol for
which the authentication is being performed, e.g
"pop", "ldap".
serverName The non-null fully qualified host name of the
server to authenticate to.
props The possibly null properties to be used by the
SASL mechanisms to configure the authentication
exchange. See Sasl.createSaslClient for examples
of properties.
cbh The possibly null callback handler to used by the
SASL mechanisms to get further information from
the application/library to complete the
authentication. For example, a SASL mechanism
might require the authentication ID and password
from the caller. The authentication ID may be
requested with a NameCallback, and the password
with a PasswordCallback.
3.3.2 getMechanismNames
public String[]
getMechanismNames()
Returns a non-null array of names of mechanisms supported by this
factory.
3.4 public interface SaslServer
An object implementing this interface can negotiate authentication
using one of the IANA-registered mechanisms.
3.4.1 evaluateResponse
public byte[]
evaluateResponse(byte[] response)
throws SaslException
If a response is received from the client during the authentication
process, this method is called to prepare an appropriate next
challenge to submit to the client. The challenge is null if the
authentication has succeeded and no more challenge data is to be
sent to the client. It is non-null if the authentication must be
Expires 12/99 [Page 13]
JAVA SASL API June 1999
continued by sending a challenge to the client, or if the
authentication has succeeded but challenge data needs to be
processed by the client. A SaslException is thrown if an error
occurred while processing the response or generating a challenge.
isComplete() should be called after each call to evaluateResponse(),
to determine if any further response is needed from the client. The
protocol driver will send an indication (in a protocol-specific
manner) as to whether the authentication has succeeded, failed, or
should be continued, and any accompanying challenge data.
Parameters are:
response Non-null response received from client.
3.4.2 isComplete
public boolean
isComplete()
This method may be called at any time to determine if the
authentication process is finished. This method is typically called
after each invocation of evaluateResponse() to determine whether the
authentication has completed successfully or should be continued.
3.4.3 getSecurityLayer
public SecurityLayer
getSecurityLayer() throws SaslException
Once authentication is complete, this method may be called to obtain
an object capable of encoding/decoding data content for the rest of
the session. An exception is thrown if authentication is not yet
complete. It may return null if the mechanism does not define a
security layer, or if none was negotiated.
3.4.4 getMechanismName
public String
getMechanismName()
Returns the non-null IANA-registered name of the mechanism used by
this server, e.g. "GSSAPI" or "CRAM-MD5".
3.4.5 getAuthorizationID
public String
getAuthorizationID()
Report the authorization ID in effect for the client of this
session. If null, a protocol-dependent default is assumed.
Expires 12/99 [Page 14]
JAVA SASL API June 1999
3.5 public interface SaslServerFactory
An object implementing this interface can provide a SaslServer.
Implementations must be thread-safe and handle multiple simultaneous
requests.
3.5.1 createSaslServer
public SaslServer
createSaslServer(String mechanism,
String protocol,
String serverName,
Hashtable props,
javax.security.auth.callback.CallbackHandler cbh)
throws SaslException
Creates a SaslServer using the mechanism supplied. It returns null
if no SaslClient can be created using the parameters supplied.
Throws SaslException if it cannot create a SaslClient because of an
error.
Returns a possibly null SaslServer which supports the specified
mechanism. If null, this factory cannot produce a SaslServer for the
specified mechanism.
Parameters are:
mechanism The non-null IANA-registered name of a SASL
mechanism (e.g. "GSSAPI", "CRAM-MD5").
protocol The non-null string name of the protocol for
which the authentication is being performed, e.g
"pop", "ldap".
serverName The non-null fully qualified host name of the
server.
props The possibly null properties to be used by the
SASL mechanisms to configure the authentication
exchange. See Sasl.createSaslClient for examples
of properties.
cbh The possibly null callback handler to used by the
SASL mechanisms to get further information from
the application/library to complete the
authentication. For example, a SASL mechanism
might require the authentication ID and password
from the caller. The authentication ID may be
requested with a NameCallback, and the password
with a PasswordCallback.
Expires 12/99 [Page 15]
JAVA SASL API June 1999
3.5.2 getMechanismNames
public String[]
getMechanismNames()
Returns a non-null array of names of mechanisms supported by this
factory.
3.6 public class SaslException
extends IOException
Exception thrown on errors and failures in authentication.
3.6.1 Constructors
public SaslException()
Constructs a new instance of SaslException. The root exception and
the detailed message are null.
public SaslException(String message)
Constructs a default exception with a detailed message and no root
exception.
public SaslException(String messag,
Throwable ex)
Constructs a new instance of SaslException with a detailed message
and a root exception. For example, a SaslException might result from
a problem with the callback handler, which might throw a
NoSuchCallbackException if it does not support the requested
callback, or throw an IOException if it had problems obtaining data
for the callback. The SaslException's root exception would be then
be the exception thrown by the callback handler.
Parameters are:
message Possibly null additional detail about the
exception.
ex A possibly null root exception that caused this
exception.
Expires 12/99 [Page 16]
JAVA SASL API June 1999
3.6.2 getException
public Throwable
getException()
Returns the possibly null root exception that caused this exception.
3.6.3 printStackTrace
public void
printStackTrace()
Prints this exception's stack trace to System.err. If this
exception has a root exception, the stack trace of the root
exception is printed to System.err instead.
public void
printStackTrace(PrintStream ps)
Prints this exception's stack trace to a print stream. If this
exception has a root exception, the stack trace of the root
exception is printed to the print stream instead.
public void
printStackTrace(PrintWriter pw)
Prints this exception's stack trace to a print writer. If this
exception has a root exception, the stack trace of the root
exception is printed to the print writer instead.
Parameters are:
ps The non-null print stream to which to print.
pw The non-null print writer to which to print.
3.7 public interface SecurityLayer
An object implementing this interface translates buffers back and
forth during a session, after the authentication process has
completed, to provide a security layer. The security layer may
provide data integrity and/or session privacy.
3.7.1 encode
public byte[]
encode(byte[] inVals, int offset, int count) throws SASLException
Take a protocol-dependent byte array and encode it (encrypt, for
example) for sending to the server.
Expires 12/99 [Page 17]
JAVA SASL API June 1999
Parameters are:
inVals A request to be encoded before sending to the
server.
offset The inclusive starting offset in the byte array
inVals to use. 0 <= offset < inVals.length.
count The number of bytes in inVals to use.
0 <= count < inVals.length-offset.
3.7.2 decode
public byte[]
decode(byte[] outVals, int offset, int count) throws SASLException
Take an encoded byte array received from the server and decode it.
Parameters are:
outVals A response received from the server, to be
decoded.
offset The inclusive starting offset in the byte array
outVals to use. 0 <= offset < outVals.length.
count The number of bytes in outVals to use.
0 <= count < outVals.length-offset.
Expires 12/99 [Page 18]
JAVA SASL API June 1999
4 Security Considerations
When SASL authentication is performed over unsecured connections, it
is possible for an active attacker to spoof the server's protocol-
specific indication that authentication is complete. Clients should
protect against this attack by verifying the completion of
authentication with the mechanism driver by calling the driver's
isComplete() method.
Additional security considerations are discussed in [SASL].
5 Bibliography
[JAAS] Java Software, Sun Microsystems, Inc., "Java Authentication
and Authorization Service," http://java.sun.com/security/jaas,
March 1999.
[SASL] J. Myers, "Simple Authentication and Security Layer (SASL)",
RFC 2222, October 1997
6 Authors' Addresses
Rob Weltman
Netscape Communications Corp.
501 E. Middlefield Rd.
Mail Stop MV-029
Mountain View, CA 94043-4042
USA
Email: rweltman@netscape.com
Rosanna Lee
Sun Microsystems
Mail Stop UCUP02-206
901 San Antonio Road
Palo Alto, CA 94303
USA
Email: rosanna.lee@eng.sun.com
Rob Earhart
Carnegie Mellon
5000 Forbes Ave.
Pittsburgh, PA 15213-3890
USA
Email: earhart@cmu.edu
7 Acknowledgements
Scott Seligman of Sun Microsystems, Inc. contributed to the
architecture and API proposed in this document.
Expires 12/99 [Page 19]
JAVA SASL API June 1999
8 Appendix A - Sample java LDAP program using SASL
/****************************************************************
It might look like this in LDAP. The Protocol Driver is
implemented as part of the authenticate method of
LDAPConnection.
****************************************************************/
public class LDAPConnection {
public void authenticate( String dn,
String[] mechs,
Hashtable props,
CallbackHandler cbh )
throws SaslException {
// Create SASL client to use for authentication
SaslClient saslClnt = Sasl.createSaslClient(
mechs, dn, "ldap", getHost(), props, cbh);
if (saslClnt == null) {
throw new SaslException("SASL client not available");
}
String mechName = saslClnt.getMechanismName();
byte[] response = saslClnt.createInitialResponse();
// Create a bind request message, including the initial
// response (if any), and send it off
LDAPSASLBindResponse msg =
writeRequest( new LDAPSASLBindRequest( dn, mechName,
response ) );
// Get the server challenge
LDAPSASLBindResponse msg = (LDAPSASLBindResponse)readResponse();
// Authentication done?
while (!saslClnt.isComplete() &&
msg.getStatus() == LDAP_SASL_BIND_IN_PROGRESS) {
// No, get an appropriate next response and send it off
byte[] challenge = msg.getChallenge();
response = saslClnt.evaluateChallenge( challenge );
// May be a success message with no further challenge
if ( response != null ) {
// Wrap the response in another bind request and
// send it off
writeRequest( new LDAPSASLBindRequest( dn,
mechName, response ) );
msg = (LDAPSASLBindResponse)readResponse();
}
}
// Make sure authentication REALLY is complete
if ( !driver.isComplete() ) {
/* Authentication session hijacked! */
throw new SaslException( "SASL session hijacked!" );
}
// Get the negotiated security layer, if any
Expires 12/99 [Page 20]
JAVA SASL API June 1999
security = saslClnt.getSecurityLayer();
}
Expires 12/99 [Page 21]
JAVA SASL API June 1999
/****************************************************************
This might be in an application
****************************************************************/
/**
* A sample callback handler. This implementation is created by
* using the input that it will return. Other implementations are
* typically more sophisticated and might prompt the user on demand
* in order to satisfy the callbacks.
*/
class SimpleCallbackHandler implements CallbackHandler {
private char[] passwd;
private String authenticationID;
SimpleCallbackHandler(String principal, Object cred)
throws IOException {
authenticationID = principal;
if (cred instanceof String) {
passwd = ((String)cred).toCharArray();
} else if (cred instanceof char[]) {
passwd = (char[])((char[])cred).clone();
} else if (cred instanceof byte[]) {
// PasswordCallback expects char[]; assume UTF-8
// encoding
String orig = new String((byte[])cred, "UTF8");
passwd = orig.toCharArray();
} else {
throw new IOException("Unsupported password format: " +
cred);
}
}
public void invokeCallback(Callback[] callbacks)
throws java.io.IOException, UnsupportedCallbackException {
for (int i = 0; i < callbacks.length; i++) {
if (callbacks[i] instanceof NameCallback) {
((NameCallback)callbacks[i]).setName(
authenticationID);
} else if (callbacks[i] instanceof PasswordCallback) {
((PasswordCallback)callbacks[i]).setPassword(
passwd);
} else {
throw new
UnsupportedCallbackException(callbacks[i]);
}
}
}
}
Expires 12/99 [Page 22]
JAVA SASL API June 1999
/***************************************************************
And so the application code to do authentication
***************************************************************/
// Set up all SASL parameters; some may have reasonable defaults
Hashtable props = new Hashtable();
props.add("javax.security.sasl.encryption.minimum", "40");
props.add("javax.security.sasl.encryption.maximum", "128");
props.add("javax.security.sasl.server_authentication", "true");
props.add("javax.security.sasl.maxbuffer", "4096");
// The following two for kerberos v4, only
//props.add("javax.security.sasl.ip.local", "192.68.1.10");
//props.add("javax.security.sasl.ip.remote", "192.68.1.50");
// What we want to authenticate as
String dn = "cn=Directory Manager";
// Create an object for possible use by the authentication
// process
SimpleCallbackHandler cbh = new SimpleCallbackHandler();
try {
// Note: cbh methods may be called during authentication
// Note: "connection" includes the SASL Protocol Driver
// functionality, and it will internally manage a Mechanism
// Driver for GSSAPI, and then a Security Layer object for
// data translation
String[] mechNames = { "GSSAPI" };
connection.authenticate( dn, mechNames, props, cbh );
} catch ( SaslException e ) {
// Abort, return, maybe try some other authentication
}
// Okay. From here on, everything goes through security, but the
// methods have the same signatures as if we were not using SASL
Expires 12/99 [Page 23]
JAVA SASL API June 1999
9 Appendix B - Changes from draft-weltman-java-sasl-01.txt
The class hierarchy defined in this document is entirely different
from that defined in the previous document.
For callback handling, the newly released
javax.security.auth.callback package is used.
Expires 12/99 [Page 24]