1. /*

  2.  * @(#)SaslClient.java	1.14 03/12/19

  3.  *

  4.  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.

  5.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  6.  */

  7. 

  8. package javax.security.sasl;

  9. 

  10. /**

  11.  * Performs SASL authentication as a client.

  12.  *<p>

  13.  * A protocol library such as one for LDAP gets an instance of this

  14.  * class in order to perform authentication defined by a specific SASL

  15.  * mechanism. Invoking methods on the <tt>SaslClient</tt> instance

  16.  * process challenges and create responses according to the SASL

  17.  * mechanism implemented by the <tt>SaslClient</tt>.

  18.  * As the authentication proceeds, the instance

  19.  * encapsulates the state of a SASL client's authentication exchange. 

  20.  *<p>

  21.  * Here's an example of how an LDAP library might use a <tt>SaslClient</tt>.

  22.  * It first gets an instance of a <tt>SaslClient</tt>:

  23.  *<blockquote><pre>

  24.  * SaslClient sc = Sasl.createSaslClient(mechanisms,

  25.  *     authorizationId, protocol, serverName, props, callbackHandler);

  26.  *</pre></blockquote>

  27.  * It can then proceed to use the client for authentication.

  28.  * For example, an LDAP library might use the client as follows:

  29.  *<blockquote><pre>

  30.  * // Get initial response and send to server

  31.  * byte[] response = (sc.hasInitialResponse() ? sc.evaluateChallenge(new byte[0]) :

  32.  *     null);

  33.  * LdapResult res = ldap.sendBindRequest(dn, sc.getName(), response);

  34.  * while (!sc.isComplete() && 

  35.  *     (res.status == SASL_BIND_IN_PROGRESS || res.status == SUCCESS)) {

  36.  *     response = sc.evaluateChallenge(res.getBytes());

  37.  *     if (res.status == SUCCESS) {

  38.  *         // we're done; don't expect to send another BIND

  39.  *         if (response != null) {

  40.  * 	       throw new SaslException(

  41.  * 	           "Protocol error: attempting to send response after completion");

  42.  * 	   }

  43.  *         break;

  44.  *     }

  45.  *     res = ldap.sendBindRequest(dn, sc.getName(), response);

  46.  * }

  47.  * if (sc.isComplete() && res.status == SUCCESS) {

  48.  *    String qop = (String) sc.getNegotiatedProperty(Sasl.QOP);

  49.  *    if (qop != null 

  50.  *        && (qop.equalsIgnoreCase("auth-int") 

  51.  *            || qop.equalsIgnoreCase("auth-conf"))) {

  52.  *

  53.  *      // Use SaslClient.wrap() and SaslClient.unwrap() for future

  54.  *      // communication with server

  55.  *	ldap.in = new SecureInputStream(sc, ldap.in);

  56.  *	ldap.out = new SecureOutputStream(sc, ldap.out);

  57.  *    }

  58.  * }

  59.  *</pre></blockquote>

  60.  *

  61.  * If the mechanism has an initial response, the library invokes

  62.  * <tt>evaluateChallenge()</tt> with an empty

  63.  * challenge and to get initial response.

  64.  * Protocols such as IMAP4, which do not include an initial response with

  65.  * their first authentication command to the server, initiates the

  66.  * authentication without first calling <tt>hasInitialResponse()</tt> 

  67.  * or <tt>evaluateChallenge()</tt>.

  68.  * When the server responds to the command, it sends an initial challenge.

  69.  * For a SASL mechanism in which the client sends data first, the server should

  70.  * have issued a challenge with no data. This will then result in a call

  71.  * (on the client) to <tt>evaluateChallenge()</tt> with an empty challenge.

  72.  *

  73.  * @since 1.5

  74.  *

  75.  * @see Sasl

  76.  * @see SaslClientFactory

  77.  *

  78.  * @author Rosanna Lee

  79.  * @author Rob Weltman

  80.  */

  81. public abstract interface SaslClient {

  82. 

  83.     /**

  84.      * Returns the IANA-registered mechanism name of this SASL client.

  85.      * (e.g. "CRAM-MD5", "GSSAPI").

  86.      * @return A non-null string representing the IANA-registered mechanism name.

  87.      */

  88.     public abstract String getMechanismName();

  89. 

  90.     /**

  91.      * Determines whether this mechanism has an optional initial response.

  92.      * If true, caller should call <tt>evaluateChallenge()</tt> with an

  93.      * empty array to get the initial response.

  94.      *

  95.      * @return true if this mechanism has an initial response.

  96.      */

  97.     public abstract boolean hasInitialResponse();

  98. 

  99.     /**

  100.      * Evaluates the challenge data and generates a response.

  101.      * If a challenge is received from the server during the authentication 

  102.      * process, this method is called to prepare an appropriate next 

  103.      * response to submit to the server.

  104.      *

  105.      * @param challenge The non-null challenge sent from the server.

  106.      * The challenge array may have zero length. 

  107.      *

  108.      * @return The possibly null reponse to send to the server.

  109.      * It is null if the challenge accompanied a "SUCCESS" status and the challenge

  110.      * only contains data for the client to update its state and no response

  111.      * needs to be sent to the server. The response is a zero-length byte 

  112.      * array if the client is to send a response with no data. 

  113.      * @exception SaslException If an error occurred while processing

  114.      * the challenge or generating a response.

  115.      */

  116.     public abstract byte[] evaluateChallenge(byte[] challenge) 

  117. 	throws SaslException;

  118. 

  119.     /**

  120.       * Determines whether the authentication exchange has completed.

  121.       * This method may be called at any time, but typically, it

  122.       * will not be called until the caller has received indication

  123.       * from the server

  124.       * (in a protocol-specific manner) that the exchange has completed. 

  125.       *

  126.       * @return true if the authentication exchange has completed; false otherwise.

  127.       */

  128.     public abstract boolean isComplete();

  129. 

  130.     /**

  131.      * Unwraps a byte array received from the server.

  132.      * This method can be called only after the authentication exchange has

  133.      * completed (i.e., when <tt>isComplete()</tt> returns true) and only if

  134.      * the authentication exchange has negotiated integrity and/or privacy 

  135.      * as the quality of protection; otherwise, an 

  136.      * <tt>IllegalStateException</tt> is thrown.

  137.      *<p>

  138.      * <tt>incoming</tt> is the contents of the SASL buffer as defined in RFC 2222

  139.      * without the leading four octet field that represents the length.

  140.      * <tt>offset</tt> and <tt>len</tt> specify the portion of <tt>incoming</tt>

  141.      * to use.

  142.      *

  143.      * @param incoming A non-null byte array containing the encoded bytes

  144.      * 		      from the server.

  145.      * @param offset The starting position at <tt>incoming</tt> of the bytes to use.

  146.      * @param len The number of bytes from <tt>incoming</tt> to use.

  147.      * @return A non-null byte array containing the decoded bytes.

  148.      * @exception SaslException if <tt>incoming</tt> cannot be successfully 

  149.      * unwrapped.

  150.      * @exception IllegalStateException if the authentication exchange has 

  151.      * not completed, or  if the negotiated quality of protection 

  152.      * has neither integrity nor privacy.

  153.      */

  154.     public abstract byte[] unwrap(byte[] incoming, int offset, int len)

  155. 	throws SaslException;

  156. 

  157.     /**

  158.      * Wraps a byte array to be sent to the server.

  159.      * This method can be called only after the authentication exchange has

  160.      * completed (i.e., when <tt>isComplete()</tt> returns true) and only if

  161.      * the authentication exchange has negotiated integrity and/or privacy 

  162.      * as the quality of protection; otherwise, an 

  163.      * <tt>IllegalStateException</tt> is thrown.

  164.      *<p>

  165.      * The result of this method will make up the contents of the SASL buffer 

  166.      * as defined in RFC 2222 without the leading four octet field that 

  167.      * represents the length.

  168.      * <tt>offset</tt> and <tt>len</tt> specify the portion of <tt>outgoing</tt>

  169.      * to use.

  170.      *

  171.      * @param outgoing A non-null byte array containing the bytes to encode.

  172.      * @param offset The starting position at <tt>outgoing</tt> of the bytes to use.

  173.      * @param len The number of bytes from <tt>outgoing</tt> to use.

  174.      * @return A non-null byte array containing the encoded bytes.

  175.      * @exception SaslException if <tt>outgoing</tt> cannot be successfully 

  176.      * wrapped.

  177.      * @exception IllegalStateException if the authentication exchange has 

  178.      * not completed, or if the negotiated quality of protection 

  179.      * has neither integrity nor privacy.

  180.      */

  181.     public abstract byte[] wrap(byte[] outgoing, int offset, int len) 

  182. 	throws SaslException;

  183. 

  184.     /**

  185.      * Retrieves the negotiated property.

  186.      * This method can be called only after the authentication exchange has

  187.      * completed (i.e., when <tt>isComplete()</tt> returns true); otherwise, an

  188.      * <tt>IllegalStateException</tt> is thrown.

  189.      * 

  190.      * @param propName The non-null property name.

  191.      * @return The value of the negotiated property. If null, the property was

  192.      * not negotiated or is not applicable to this mechanism.

  193.      * @exception IllegalStateException if this authentication exchange 

  194.      * has not completed

  195.      */

  196. 

  197.     public abstract Object getNegotiatedProperty(String propName);

  198. 

  199.      /**

  200.       * Disposes of any system resources or security-sensitive information

  201.       * the SaslClient might be using. Invoking this method invalidates

  202.       * the SaslClient instance. This method is idempotent.

  203.       * @throws SaslException If a problem was encountered while disposing

  204.       * the resources.

  205.       */

  206.     public abstract void dispose() throws SaslException;

  207. }