libjava/javax/security/sasl/SaslClient.java

   1 /* SaslClient.java
   2    Copyright (C) 2003, Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpathis 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 Classpathis 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  * @version $Revision: 1.1 $
 106  */
 107 public interface SaslClient
 108 {
 109
 110   /**
 111    * Returns the IANA-registered mechanism name of this SASL client. (e.g.
 112    * "CRAM-MD5", "GSSAPI").
 113    *
 114    * @return a non-null string representing the IANA-registered mechanism name.
 115    */
 116   String getMechanismName();
 117
 118   /**
 119    * Determines if this mechanism has an optional initial response. If
 120    * <code>true</code>, caller should call {@link #evaluateChallenge(byte[])}
 121    * with an empty array to get the initial response.
 122    *
 123    * @return <code>true</code> if this mechanism has an initial response.
 124    */
 125   boolean hasInitialResponse();
 126
 127   /**
 128    * Evaluates the challenge data and generates a response. If a challenge is
 129    * received from the server during the authentication process, this method is
 130    * called to prepare an appropriate next response to submit to the server.
 131    *
 132    * @param challenge the non-null challenge sent from the server. The
 133    * challenge array may have zero length.
 134    * @return the possibly <code>null</code> reponse to send to the server. It
 135    * is <code>null</code> if the challenge accompanied a "SUCCESS" status and
 136    * the challenge only contains data for the client to update its state and no
 137    * response needs to be sent to the server. The response is a zero-length
 138    * byte array if the client is to send a response with no data.
 139    * @throws SaslException if an error occurred while processing the challenge
 140    * or generating a response.
 141    */
 142   byte[] evaluateChallenge(byte[] challenge) throws SaslException;
 143
 144   /**
 145    * Determines if the authentication exchange has completed. This method may
 146    * be called at any time, but typically, it will not be called until the
 147    * caller has received indication from the server (in a protocol-specific
 148    * manner) that the exchange has completed.
 149    *
 150    * @return <code>true</code> if the authentication exchange has completed;
 151    * <code>false</code> otherwise.
 152    */
 153   boolean isComplete();
 154
 155   /**
 156    * <p>Unwraps a byte array received from the server. This method can be
 157    * called only after the authentication exchange has completed (i.e., when
 158    * {@link #isComplete()} returns <code>true</code>) and only if the
 159    * authentication exchange has negotiated integrity and/or privacy as the
 160    * quality of protection; otherwise, an {@link IllegalStateException} is
 161    * thrown.</p>
 162    *
 163    * <p><code>incoming</code> is the contents of the SASL buffer as defined in
 164    * RFC 2222 without the leading four octet field that represents the length.
 165    * <code>offset</code> and <code>len</code> specify the portion of incoming
 166    * to use.</p>
 167    *
 168    * @param incoming a non-null byte array containing the encoded bytes from
 169    * the server.
 170    * @param offset the starting position at <code>incoming</code> of the bytes
 171    * to use.
 172    * @param len the number of bytes from <code>incoming</code> to use.
 173    * @return a non-null byte array containing the decoded bytes.
 174    * @throws SaslException if <code>incoming</code> cannot be successfully
 175    * unwrapped.
 176    * @throws IllegalStateException if the authentication exchange has not
 177    * completed, or if the negotiated quality of protection has neither
 178    * integrity nor privacy.
 179    */
 180   byte[] unwrap(byte[] incoming, int offset, int len) throws SaslException;
 181
 182   /**
 183    * <p>Wraps a byte array to be sent to the server. This method can be called
 184    * only after the authentication exchange has completed (i.e., when
 185    * {@link #isComplete()} returns <code>true</code>) and only if the
 186    * authentication exchange has negotiated integrity and/or privacy as the
 187    * quality of protection; otherwise, an {@link IllegalStateException} is
 188    * thrown.</p>
 189    *
 190    * <p>The result of this method will make up the contents of the SASL buffer
 191    * as defined in RFC 2222 without the leading four octet field that
 192    * represents the length. <code>offset</code> and <code>len</code> specify
 193    * the portion of <code>outgoing</code> to use.</p>
 194    *
 195    * @param outgoing a non-null byte array containing the bytes to encode.
 196    * @param offset the starting position at <code>outgoing</code> of the bytes
 197    * to use.
 198    * @param len the number of bytes from <code>outgoing</code> to use.
 199    * @return a non-null byte array containing the encoded bytes.
 200    * @throws SaslException if <code>outgoing</code> cannot be successfully
 201    * wrapped.
 202    * @throws IllegalStateException if the authentication exchange has not
 203    * completed, or if the negotiated quality of protection has neither
 204    * integrity nor privacy.
 205    */
 206   byte[] wrap(byte[] outgoing, int offset, int len) throws SaslException;
 207
 208   /**
 209    * Retrieves the negotiated property. This method can be called only after
 210    * the authentication exchange has completed (i.e., when {@link #isComplete()}
 211    * returns <code>true</code>); otherwise, an {@link IllegalStateException} is
 212    * thrown.
 213    *
 214    * @param propName the non-null property name.
 215    * @return the value of the negotiated property. If <code>null</code>, the
 216    * property was not negotiated or is not applicable to this mechanism.
 217    * @throws IllegalStateException if this authentication exchange has not
 218    * completed.
 219    */
 220   Object getNegotiatedProperty(String propName) throws SaslException;
 221
 222   /**
 223    * Disposes of any system resources or security-sensitive information the
 224    * <code>SaslClient</code> might be using. Invoking this method invalidates
 225    * the <code>SaslClient</code> instance. This method is idempotent.
 226    *
 227    * @throws SaslException if a problem was encountered while disposing of the
 228    * resources.
 229    */
 230   void dispose() throws SaslException;
 231 }