Source for javax.security.sasl.SaslClient

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