libjava/javax/security/sasl/SaslClient.java

   1 /* SaslClient.java --
   2    Copyright (C) 2003, 2004 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package javax.security.sasl;
  40
  41 /**
  42  * <p>Performs SASL authentication as a client.</p>
  43  *
  44  * <p>A protocol library such as one for LDAP gets an instance of this class in
  45  * order to perform authentication defined by a specific SASL mechanism.
  46  * Invoking methods on the <code>SaslClient</code> instance process challenges
  47  * and create responses according to the SASL mechanism implemented by the
  48  * <code>SaslClient</code>. As the authentication proceeds, the instance
  49  * encapsulates the state of a SASL client's authentication exchange.</p>
  50  *
  51  * <p>Here's an example of how an LDAP library might use a <code>SaslClient</code>.
  52  * It first gets an instance of a SaslClient:</p>
  53  * <pre>
  54  *SaslClient sc =
  55  *      Sasl.createSaslClient(mechanisms, authorizationID, protocol,
  56  *                            serverName, props, callbackHandler);
  57  * </pre>
  58  *
  59  * <p>It can then proceed to use the client for authentication. For example, an
  60  * LDAP library might use the client as follows:</p>
  61  * <pre>
  62  * // Get initial response and send to server
  63  *byte[] response = sc.hasInitialResponse()
  64  *      ? sc.evaluateChallenge(new byte[0]) : null;
  65  *LdapResult res = ldap.sendBindRequest(dn, sc.getName(), response);
  66  *while (!sc.isComplete()
  67  *       && ((res.status == SASL_BIND_IN_PROGRESS) || (res.status == SUCCESS))) {
  68  *   response = sc.evaluateChallenge( res.getBytes() );
  69  *   if (res.status == SUCCESS) {
  70  *      // we're done; don't expect to send another BIND
  71  *      if ( response != null ) {
  72  *         throw new SaslException(
  73  *               "Protocol error: attempting to send response after completion");
  74  *      }
  75  *      break;
  76  *   }
  77  *   res = ldap.sendBindRequest(dn, sc.getName(), response);
  78  *}
  79  *if (sc.isComplete() && (res.status == SUCCESS) ) {
  80  *   String qop = (String)sc.getNegotiatedProperty(Sasl.QOP);
  81  *   if ((qop != null)
  82  *         && (qop.equalsIgnoreCase("auth-int")
  83  *            || qop.equalsIgnoreCase("auth-conf"))) {
  84  *      // Use SaslClient.wrap() and SaslClient.unwrap() for future
  85  *      // communication with server
  86  *      ldap.in = new SecureInputStream(sc, ldap.in);
  87  *      ldap.out = new SecureOutputStream(sc, ldap.out);
  88  *   }
  89  *}
  90  * </pre>
  91  *
  92  * <p>If the mechanism has an initial response, the library invokes
  93  * {@link #evaluateChallenge(byte[])} with an empty challenge to get the initial
  94  * response. Protocols such as IMAP4, which do not include an initial response
  95  * with their first authentication command to the server, initiate the
  96  * authentication without first calling {@link #hasInitialResponse()} or
  97  * {@link #evaluateChallenge(byte[])}. When the server responds to the command,
  98  * it sends an initial challenge. For a SASL mechanism in which the client sends
  99  * data first, the server should have issued a challenge with no data. This will
 100  * then result in a call (on the client) to {@link #evaluateChallenge(byte[])}
 101  * with an empty challenge.</p>
 102  *
 103  * @see Sasl
 104  * @see SaslClientFactory
 105  */
 106 public interface SaslClient
 107 {
 108
 109   /**
 110    * Returns the IANA-registered mechanism name of this SASL client. (e.g.
 111    * "CRAM-MD5", "GSSAPI").
 112    *
 113    * @return a non-null string representing the IANA-registered mechanism name.
 114    */
 115   String getMechanismName();
 116
 117   /**
 118    * Determines if this mechanism has an optional initial response. If
 119    * <code>true</code>, caller should call {@link #evaluateChallenge(byte[])}
 120    * with an empty array to get the initial response.
 121    *
 122    * @return <code>true</code> if this mechanism has an initial response.
 123    */
 124   boolean hasInitialResponse();
 125
 126   /**
 127    * Evaluates the challenge data and generates a response. If a challenge is
 128    * received from the server during the authentication process, this method is
 129    * called to prepare an appropriate next response to submit to the server.
 130    *
 131    * @param challenge the non-null challenge sent from the server. The
 132    * challenge array may have zero length.
 133    * @return the possibly <code>null</code> reponse to send to the server. It
 134    * is <code>null</code> if the challenge accompanied a "SUCCESS" status and
 135    * the challenge only contains data for the client to update its state and no
 136    * response needs to be sent to the server. The response is a zero-length
 137    * byte array if the client is to send a response with no data.
 138    * @throws SaslException if an error occurred while processing the challenge
 139    * or generating a response.
 140    */
 141   byte[] evaluateChallenge(byte[] challenge) throws SaslException;
 142
 143   /**
 144    * Determines if the authentication exchange has completed. This method may
 145    * be called at any time, but typically, it will not be called until the
 146    * caller has received indication from the server (in a protocol-specific
 147    * manner) that the exchange has completed.
 148    *
 149    * @return <code>true</code> if the authentication exchange has completed;
 150    * <code>false</code> otherwise.
 151    */
 152   boolean isComplete();
 153
 154   /**
 155    * <p>Unwraps a byte array received from the server. This method can be
 156    * called only after the authentication exchange has completed (i.e., when
 157    * {@link #isComplete()} returns <code>true</code>) and only if the
 158    * authentication exchange has negotiated integrity and/or privacy as the
 159    * quality of protection; otherwise, an {@link IllegalStateException} is
 160    * thrown.</p>
 161    *
 162    * <p><code>incoming</code> is the contents of the SASL buffer as defined in
 163    * RFC 2222 without the leading four octet field that represents the length.
 164    * <code>offset</code> and <code>len</code> specify the portion of incoming
 165    * to use.</p>
 166    *
 167    * @param incoming a non-null byte array containing the encoded bytes from
 168    * the server.
 169    * @param offset the starting position at <code>incoming</code> of the bytes
 170    * to use.
 171    * @param len the number of bytes from <code>incoming</code> to use.
 172    * @return a non-null byte array containing the decoded bytes.
 173    * @throws SaslException if <code>incoming</code> cannot be successfully
 174    * unwrapped.
 175    * @throws IllegalStateException if the authentication exchange has not
 176    * completed, or if the negotiated quality of protection has neither
 177    * integrity nor privacy.
 178    */
 179   byte[] unwrap(byte[] incoming, int offset, int len) throws SaslException;
 180
 181   /**
 182    * <p>Wraps a byte array to be sent to the server. This method can be called
 183    * only after the authentication exchange has completed (i.e., when
 184    * {@link #isComplete()} returns <code>true</code>) and only if the
 185    * authentication exchange has negotiated integrity and/or privacy as the
 186    * quality of protection; otherwise, an {@link IllegalStateException} is
 187    * thrown.</p>
 188    *
 189    * <p>The result of this method will make up the contents of the SASL buffer
 190    * as defined in RFC 2222 without the leading four octet field that
 191    * represents the length. <code>offset</code> and <code>len</code> specify
 192    * the portion of <code>outgoing</code> to use.</p>
 193    *
 194    * @param outgoing a non-null byte array containing the bytes to encode.
 195    * @param offset the starting position at <code>outgoing</code> of the bytes
 196    * to use.
 197    * @param len the number of bytes from <code>outgoing</code> to use.
 198    * @return a non-null byte array containing the encoded bytes.
 199    * @throws SaslException if <code>outgoing</code> cannot be successfully
 200    * wrapped.
 201    * @throws IllegalStateException if the authentication exchange has not
 202    * completed, or if the negotiated quality of protection has neither
 203    * integrity nor privacy.
 204    */
 205   byte[] wrap(byte[] outgoing, int offset, int len) throws SaslException;
 206
 207   /**
 208    * Retrieves the negotiated property. This method can be called only after
 209    * the authentication exchange has completed (i.e., when {@link #isComplete()}
 210    * returns <code>true</code>); otherwise, an {@link IllegalStateException} is
 211    * thrown.
 212    *
 213    * @param propName the non-null property name.
 214    * @return the value of the negotiated property. If <code>null</code>, the
 215    * property was not negotiated or is not applicable to this mechanism.
 216    * @throws IllegalStateException if this authentication exchange has not
 217    * completed.
 218    */
 219   Object getNegotiatedProperty(String propName) throws SaslException;
 220
 221   /**
 222    * Disposes of any system resources or security-sensitive information the
 223    * <code>SaslClient</code> might be using. Invoking this method invalidates
 224    * the <code>SaslClient</code> instance. This method is idempotent.
 225    *
 226    * @throws SaslException if a problem was encountered while disposing of the
 227    * resources.
 228    */
 229   void dispose() throws SaslException;
 230 }