Subject: Submission: draft-weltman-java-sasl-03.txt

From: [email-masked] (Rob Weltman)
Date: Wed, 01 Mar 2000 08:00:42 -0800

Network Working Group                                        Rob Weltman
INTERNET-DRAFT                             Netscape Communications Corp.
                                                             Rosanna Lee
                                                        Sun Microsystems
                                                             March, 2000

              The Java SASL Application Program Interface
                     draft-weltman-java-sasl-03.txt

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 September 2000                                        [Page 1]

JAVA SASL API                                              March, 2000

1.    Introduction....................................................3
2.    Overview of the SASL classes....................................5
2.1   Interfaces.....................................................5
2.2   Classes........................................................6
3.    Overview of SASL API Use........................................6
4.    The Java SASL classes...........................................7
4.1   public class Sasl..............................................7
4.1.1    createSaslClient............................................7
4.1.2    setSaslClientFactory........................................9
4.1.3    createSaslServer...........................................10
4.1.4    setSaslServerFactory.......................................11
4.2   public interface SaslClient...................................11
4.2.1    evaluateChallenge..........................................12
4.2.2    hasInitialResponse.........................................12
4.2.3    isComplete.................................................12
4.2.4    getInputStream.............................................13
4.2.5    getOutputStream............................................13
4.2.6    getMechanismName...........................................13
4.3   public interface SaslClientFactory............................14
4.3.1    createSaslClient...........................................14
4.3.2    getMechanismNames..........................................15
4.4   public interface SaslServer...................................15
4.4.1    evaluateResponse...........................................15
4.4.2    isComplete.................................................16
4.4.3    getInputStream.............................................16
4.4.4    getOutputStream............................................16
4.4.5    getMechanismName...........................................17
4.4.6    getAuthorizationID.........................................17
4.5   public interface SaslServerFactory............................17
4.5.1    createSaslServer...........................................17
4.5.2    getMechanismNames..........................................18
4.6   public class SaslException extends IOException................19
4.6.1    Constructors...............................................19
4.6.2    getException...............................................19
4.6.3    printStackTrace............................................20
5.    Security Considerations........................................20
6.    Copyright......................................................20
7.    Bibliography...................................................21
8.    Author's Addresses.............................................21
9.    Acknowledgements...............................................21
10.   Changes from draft-weltman-java-sasl-02.txt....................22
10.1  SecurityLayer.................................................22
10.2  SaslClient....................................................22
10.3  SaslClient and SaslServer.....................................22
11.   Appendix A - Sample Java LDAP program using SASL...............23

Expires September 2000                                         [Page 2

JAVA SASL API                                              March, 2000

1. 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 input and output streams that encapsulate the
   negotiated security layer. From this point on, any data exchanged
   through the socket is passed to these input and output streams.

   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
   can supply a javax.security.auth.callback.CallbackHandler instance

Expires September 2000                                         [Page 3

JAVA SASL API                                              March, 2000

   [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.

   The negotiated security layer is encapsulated in input and output
   streams, which typically inherit 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.

Expires September 2000                                         [Page 4

JAVA SASL API                                              March, 2000

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

2. Overview of the SASL classes

2.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

Expires September 2000                                         [Page 5

JAVA SASL API                                              March, 2000

                               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.

2.2 Classes

   Sasl                        A static class for creating SASL clients
                               and servers. It transparently locates
                               and uses any available
                               SaslClientFactory/SaslServerFactory
                               instances.

   SaslException               Exception thrown on errors and failures
                               in the authentication process.

3. 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 input and output streams that
        encapsulate the negotiated security layer may be obtained from
        it. If not, the SaslClient is queried for an appropriate next

Expires September 2000                                         [Page 6

JAVA SASL API                                              March, 2000

        response to the server. This continues until authentication has
        completed.

   -    For the rest of the session, messages to the server are written
        to the output stream which encodes the data (if a security
        layer has been negotiated), and  messages from the server are
        read from the input stream which decodes the data 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
        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
        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 using the input and output streams that
        encapsulate the negotiated security layer (if any).

      The following sections describe the SASL classes in more detail.

4. The Java SASL classes

4.1 public class Sasl

A class capable of providing a SaslClient or SaslServer.

4.1.1 createSaslClient

   public static SaslClient

Expires September 2000                                         [Page 7

JAVA SASL API                                              March, 2000

   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").

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

Expires September 2000                                         [Page 8

JAVA SASL API                                              March, 2000

                                                     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
                                                     receive buffer
                                                     in bytes of
                                                     SaslClient;
                                                     default "4096".

             javax.security.sasl.client.pkgs         A |-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.

4.1.2 setSaslClientFactory

   public static void

Expires September 2000                                         [Page 9

JAVA SASL API                                              March, 2000

   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.

4.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 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".

Expires September 2000                                        [Page 10

JAVA SASL API                                              March, 2000

      serverName     The non-null fully qualified host name of the
                    server.

      props          The possibly null properties to be used by the SASL
                    mechanism to configure the authentication exchange,
                    e.g.

             javax.security.sasl.maxbuffer           Maximum size of
                                                     receive buffer
                                                     in bytes of
                                                     SaslServer;
                                                     default "4096".

             javax.security.sasl.server.pkgs         A |-separated
                                                     list of package
                                                     names to use when
                                                     locating a
                                                     SaslServerFactory.

                     See Sasl.createSaslClient for examples of
                    additional properties.

      cbh            The possibly null callback handler to used by the
                    SASL mechanism 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.

4.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.

4.2 public interface SaslClient

Expires September 2000                                        [Page 11

JAVA SASL API                                              March, 2000

An object implementing this interface can negotiate authentication using
one of the IANA-registered mechanisms.

4.2.1 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. The response is a zero-length byte
   array if the client is to send a response with no data. A
   SaslException is thrown if an error occurred while processing the
   challenge or generating a response. The challenge array may have zero
   length.

   Parameters are:

      challenge      The non-null challenge received from the server.

4.2.2 hasInitialResponse

   public boolean hasInitialResponse()

   Determines whether this mechanism has an optional initial response.
   If true, caller should call evaluateChallenge() with an empty array
   to get the initial response.

4.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.

Expires September 2000                                        [Page 12

JAVA SASL API                                              March, 2000

4.2.4 getInputStream

   public InputStream
   getInputStream(InputStream source)
                  throws IOException

   Retrieves an input stream for the session. It may return the same
   stream that is passed in, if no processing is to be done by the
   client. This method can only be called if isComplete() returns true.

   The octets from the resulting input stream must have already gone
   through any integrity checking or other processing applied to the
   data from "source," as negotiated through the authentication session.

   From the mechanism provider's perspective, if a security layer has
   been negotiated, 'source' is expected to contain SASL buffers, as
   defined in RFC 2222. Four octets in network byte order in the front
   of each buffer identify the length of the buffer. The provider is
   responsible for performing any integrity checking or other processing
   on the buffer before returning the data as a stream of octets. For
   example, the protocol driver's request for a single octet from the
   stream might result in an entire SASL buffer being read and processed
   before that single octet can be returned.

   Parameters are:

      source    The original input stream for reading from the server.

4.2.5 getOutputStream

   public OutputStream
   getOutputStream(OutputStream dest)
                   throws IOException

   Retrieves an output stream for the session. It may return the same
   stream that is passed in, if no processing is to be done by the
   client. This method can only be called if isComplete() returns true.

   When writing octets to the resulting stream, if a security layer has
   been negotiated, each piece of data written (by a single invocation
   of write()) will be encapsulated as a SASL buffer, as defined in RFC
   2222, and then written to the underlying 'dest' output stream.

   From the mechanism provider's perspective, the data from each
   invocation of write() should be processed separately, resulting in
   the transmission of a single SASL buffer whose first four octets in
   network byte order denote the length of the buffer to the underlying
   'dest' output stream.

   Parameters are:

Expires September 2000                                        [Page 13

JAVA SASL API                                              March, 2000

      dest      The original output stream for writing to the server.

4.2.6 getMechanismName

   public String
   getMechanismName()

   Reports the IANA-registered name of the mechanism used by this
   client, e.g. "GSSAPI" or "CRAM-MD5".

4.3 public interface SaslClientFactory

An object implementing this interface can provide a SaslClient.
Implementations must be thread-safe and handle multiple simultaneous
requests.

4.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
                      named by authorizationId is granted access. If

Expires September 2000                                        [Page 14

JAVA SASL API                                              March, 2000

                      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.

4.3.2 getMechanismNames

   public String[]
   getMechanismNames()

   Returns a non-null array of names of mechanisms supported by this
   factory.

4.4 public interface SaslServer

An object implementing this interface can negotiate authentication using
one of the IANA-registered mechanisms.

4.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

Expires September 2000                                        [Page 15

JAVA SASL API                                              March, 2000

   to the client. It is non-null if the authentication must be 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.

4.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.

4.4.3 getInputStream

   public InputStream
   getInputStream(InputStream source)
                  throws IOException

   Retrieves an input stream for the session. It may return the same
   stream that is passed in, if no processing is to be done by the
   server. This method can only be called if isComplete() returns true.

   The octets from the resulting input stream must have already gone
   through any integrity checking or other processing applied to the
   data from "source," as negotiated through the authentication session.

   From the mechanism provider's perspective, if a security layer has
   been negotiated, 'source' is expected to contain SASL buffers, as
   defined in RFC 2222. Four octets in network byte order in the front
   of each buffer identify the length of the buffer. The provider is
   responsible for performing any integrity checking or other processing
   on the buffer before returning the data as a stream of octets. For
   example, the protocol driver's request for a single octet from the
   stream might result in an entire SASL buffer being read and processed
   before that single octet can be returned.

Expires September 2000                                        [Page 16

JAVA SASL API                                              March, 2000

   Parameters are:

      source    The original input stream for reading from the client.

4.4.4 getOutputStream

   public OutputStream
   getOutputStream(OutputStream dest)
                   throws IOException

   Retrieves an output stream for the session. It may return the same
   stream that is passed in, if no processing is to be done by the
   server. This method can only be called if isComplete() returns true.

   When writing octets to the resulting stream, if a security layer has
   been negotiated, each piece of data written (by a single invocation
   of write()) will be encapsulated as a SASL buffer, as defined in RFC
   2222, and then written to the underlying 'dest' output stream.

   From the mechanism provider's perspective, the data from each
   invocation of write() should be processed separately, resulting in
   the transmission of a single SASL buffer whose first four octets in
   network byte order denote the length of the buffer to the underlying
   'dest' output stream.

   Parameters are:

      dest      The original output stream for writing to the client.

4.4.5 getMechanismName

   public String
   getMechanismName()

   Returns the non-null IANA-registered name of the mechanism used by
   this server, e.g. "GSSAPI" or "CRAM-MD5".

4.4.6 getAuthorizationID

   public String
   getAuthorizationID() throws SaslException

   Reports the authorization ID in effect for the client of this
   session. If null, a protocol-dependent default is assumed. Can only
   be called if isComplete() returns true; throws SaslException if
   called before authentication completes.

Expires September 2000                                        [Page 17

JAVA SASL API                                              March, 2000

4.5 public interface SaslServerFactory

An object implementing this interface can provide a SaslServer.
Implementations must be thread-safe and handle multiple simultaneous
requests.

4.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 SaslServer can be created using the parameters supplied. Throws
   SaslException if it cannot create a SaslServer 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
                    mechanism to configure the authentication exchange.
                    See Sasl.createSaslServer for examples of
                    properties.

      cbh            The possibly null callback handler to used by the
                    SASL mechanism 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 September 2000                                        [Page 18

JAVA SASL API                                              March, 2000

4.5.2 getMechanismNames

   public String[]
   getMechanismNames()

   Returns a non-null array of names of mechanisms supported by this
   factory.

4.6 public class SaslException extends IOException

Exception thrown on errors and failures in authentication.

4.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 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 September 2000                                        [Page 19

JAVA SASL API                                              March, 2000

4.6.2 getException

   public Throwable
   getException()

   Returns the possibly null root exception that caused this exception.

4.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.

5. 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].

Expires September 2000                                        [Page 20

JAVA SASL API                                              March, 2000

6. Copyright

   Copyright (C) The Internet Society (2000). All Rights Reserved.

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works.  However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the  purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than
   English.

   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.

   This document and the information contained herein is provided on an
   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

7. Bibliography

   [JAAS] Java Software, Sun Microsystems, Inc., "Java Authentication
        and Authorization Service, "http://java.sun.com/security/jaas,
        Jan 2000.

   [SASL] J. Myers, "Simple Authentication and Security Layer (SASL)",
        RFC 2222, October 1997

8. Author's Addresses

   Rob Weltman
   Netscape Communications Corp.
   MV-068
   501 E. Middlefield Rd.
   Mountain View, CA 94043
   USA
   +1 650 937-3301
   [email-masked]

Expires September 2000                                        [Page 21

JAVA SASL API                                              March, 2000

   Rosanna Lee
   Sun Microsystems
   Mail Stop UCUP02-206
   901 San Antonio Road
   Palo Alto, CA  94303
   USA
   Email: [email-masked]

9. Acknowledgements

   Rob Earhart, then of Carnegie Mellon University, was a coauthor of
   the preceding draft.

   Scott Seligman of Sun Microsystems, Inc. contributed to the
   architecture and API proposed in this document.

10. Changes from draft-weltman-java-sasl-02.txt

10.1 SecurityLayer

   The SecurityLayer interface was removed.

10.2 SaslClient

   createInitialResponse() was removed. evaluateChallenge() accepts an
   empty challenge and can return an initial response.
   hasInitialResponse() was added to determine if the mechanism allows
   for an initial client response.

10.3 SaslClient and SaslServer

   getSecurityLayer() was replaced with getInputStream() and
   getOutputStream().

   Package names are |-delimited, not space-delimited, in the pkgs
   properties.

Expires September 2000                                        [Page 22

JAVA SASL API                                              March, 2000

11. 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 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();

           // Get initial response, if any
           byte[] response = (saslClnt.hasInitialResponse() ?
                              saslClnt.evaluateChallenge(new byte[0]) :
                              null);

           // Create a bind request message, including the initial
           // response (if any), and send it off
           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 ||
                   msg.getStatus() == LDAP_SUCCESS)) {

               // No, process challenge to get an appropriate next
               // response
               byte[] challenge = msg.getChallenge();
               response = saslClnt.evaluateChallenge( challenge );

               // May be a success message with no further response
               if ( msg.getStatus() == LDAP_SUCCESS) {
                   if ( response != null ) {
                       // Protocol error; supposed to be done already

Expires September 2000                                        [Page 23

JAVA SASL API                                              March, 2000

                       throw new SaslException("Protocol error in " +
                                               "SASL session");
                   }
                   break; // done
               }

               // 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 ( !saslClnt.isComplete() ) {
               // Authentication session hijacked!
               throw new SaslException( "SASL session hijacked!" );
           }

           // Get input and output stream processes, if any
           InputStream is = saslClnt.getInputStream(getInputStream());
           OutputStream os =
                            saslClnt.getOutputStream(getOutputStream());
       }

Expires September 2000                                        [Page 24