1. /*

  2.  * @(#)SaslServer.java	1.13 04/02/03

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

  12.  *<p>

  13.  * A server such an LDAP server gets an instance of this

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

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

  16.  * generates challenges according to the SASL

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

  18.  * As the authentication proceeds, the instance

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

  20.  *<p>

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

  22.  * It first gets an instance of a <tt>SaslServer</tt> for the SASL mechanism

  23.  * requested by the client:

  24.  *<blockquote><pre>

  25.  * SaslServer ss = Sasl.createSaslServer(mechanism,

  26.  *     "ldap", myFQDN, props, callbackHandler);

  27.  *</pre></blockquote>

  28.  * It can then proceed to use the server for authentication.

  29.  * For example, suppose the LDAP server received an LDAP BIND request

  30.  * containing the name of the SASL mechanism and an (optional) initial

  31.  * response. It then might use the server as follows:

  32.  *<blockquote><pre>

  33.  * while (!ss.isComplete()) {

  34.  *     try {

  35.  *         byte[] challenge = ss.evaluateResponse(response);

  36.  *         if (ss.isComplete()) {

  37.  *             status = ldap.sendBindResponse(mechanism, challenge, SUCCESS);

  38.  *         } else {

  39.  *             status = ldap.sendBindResponse(mechanism, challenge, 

  40. 	           SASL_BIND_IN_PROGRESS);

  41.  *             response = ldap.readBindRequest();

  42.  *         }

  43.  *     } catch (SaslException e) {

  44.  * 	    status = ldap.sendErrorResponse(e);

  45.  * 	    break;

  46.  *     }

  47.  * }

  48.  * if (ss.isComplete() && status == SUCCESS) {

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

  50.  *    if (qop != null 

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

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

  53.  *

  54.  *      // Use SaslServer.wrap() and SaslServer.unwrap() for future

  55.  *      // communication with client

  56.  *	ldap.in = new SecureInputStream(ss, ldap.in);

  57.  *	ldap.out = new SecureOutputStream(ss, ldap.out);

  58.  *    }

  59.  * }

  60.  *</pre></blockquote>

  61.  *

  62.  * @since 1.5

  63.  *

  64.  * @see Sasl

  65.  * @see SaslServerFactory

  66.  *

  67.  * @author Rosanna Lee

  68.  * @author Rob Weltman

  69.  */

  70. public abstract interface SaslServer {

  71. 

  72.     /**

  73.      * Returns the IANA-registered mechanism name of this SASL server.

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

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

  76.      */

  77.     public abstract String getMechanismName();

  78. 

  79.     /**

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

  81.      *

  82.      * If a response is received from the client during the authentication 

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

  84.      * challenge to submit to the client. The challenge is null if the 

  85.      * authentication has succeeded and no more challenge data is to be sent 

  86.      * to the client. It is non-null if the authentication must be continued 

  87.      * by sending a challenge to the client, or if the authentication has 

  88.      * succeeded but challenge data needs to be processed by the client. 

  89.      * <tt>isComplete()</tt> should be called 

  90.      * after each call to <tt>evaluateResponse()</tt>,to determine if any further 

  91.      * response is needed from the client. 

  92.      *

  93.      * @param response The non-null (but possibly empty) response sent

  94.      * by the client.

  95.      *

  96.      * @return The possibly null challenge to send to the client.

  97.      * It is null if the authentication has succeeded and there is

  98.      * no more challenge data to be sent to the client.

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

  100.      * the response or generating a challenge.

  101.      */

  102.     public abstract byte[] evaluateResponse(byte[] response) 

  103. 	throws SaslException;

  104. 

  105.     /**

  106.       * Determines whether the authentication exchange has completed.

  107.       * This method is typically called after each invocation of 

  108.       * <tt>evaluateResponse()</tt> to determine whether the 

  109.       * authentication has completed successfully or should be continued. 

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

  111.       */

  112.     public abstract boolean isComplete();

  113. 

  114.     /**

  115.      * Reports the authorization ID in effect for the client of this

  116.      * session. 

  117.      * This method can only be called if isComplete() returns true. 

  118.      * @return The authorization ID of the client.

  119.      * @exception IllegalStateException if this authentication session has not completed

  120.      */

  121.     public String getAuthorizationID();

  122. 	

  123.     /**

  124.      * Unwraps a byte array received from the client.

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

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

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

  128.      * as the quality of protection; otherwise, 

  129.      * an <tt>IllegalStateException</tt> is thrown.

  130.      *<p>

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

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

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

  134.      * to use.

  135.      *

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

  137.      * 		      from the client.

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

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

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

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

  142.      * unwrapped.

  143.      * @exception IllegalStateException if the authentication exchange has 

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

  145.      * has neither integrity nor privacy

  146.      */

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

  148. 	throws SaslException;

  149. 

  150.     /**

  151.      * Wraps a byte array to be sent to the client.

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

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

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

  155.      * as the quality of protection; otherwise, a <tt>SaslException</tt> is thrown.

  156.      *<p>

  157.      * The result of this method

  158.      * will make up the contents of the SASL buffer as defined in RFC 2222

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

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

  161.      * to use.

  162.      *

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

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

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

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

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

  168.      * wrapped.

  169.      * @exception IllegalStateException if the authentication exchange has 

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

  171.      * neither integrity nor privacy.

  172.      */

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

  174. 	throws SaslException;

  175. 

  176.     /**

  177.      * Retrieves the negotiated property.

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

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

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

  181.      * 

  182.      * @param propName the property

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

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

  185.      * @exception IllegalStateException if this authentication exchange has not completed

  186.      */

  187. 

  188.     public abstract Object getNegotiatedProperty(String propName);

  189. 

  190.      /**

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

  192.       * the SaslServer might be using. Invoking this method invalidates

  193.       * the SaslServer instance. This method is idempotent.

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

  195.       * the resources.

  196.       */

  197.     public abstract void dispose() throws SaslException;

  198. }