Source for javax.security.sasl.SaslServer

   1: /* SasServer.java
   2:    Copyright (C) 2003, 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 server.</p>
  43:  *
  44:  * <p>A server such as an LDAP server gets an instance of this class in order to
  45:  * perform authentication defined by a specific SASL mechanism. Invoking methods
  46:  * on the <code>SaslServer</code> instance generates challenges corresponding to
  47:  * the SASL mechanism implemented by the <code>SaslServer</code> instance. As
  48:  * the authentication proceeds, the instance encapsulates the state of a SASL
  49:  * server's authentication exchange.</p>
  50:  *
  51:  * <p>Here's an example of how an LDAP server might use a <code>SaslServer</code>
  52:  * instance. It first gets an instance of a <code>SaslServer</code> for the SASL
  53:  * mechanism requested by the client:</p>
  54:  *
  55:  * <pre>
  56:  *SaslServer ss =
  57:  *      Sasl.createSaslServer(mechanism, "ldap", myFQDN, props, callbackHandler);
  58:  * </pre>
  59:  *
  60:  * <p>It can then proceed to use the server for authentication. For example,
  61:  * suppose the LDAP server received an LDAP BIND request containing the name of
  62:  * the SASL mechanism and an (optional) initial response. It then might use the
  63:  * server as follows:</p>
  64:  *
  65:  * <pre>
  66:  *while (!ss.isComplete()) {
  67:  *   try {
  68:  *      byte[] challenge = ss.evaluateResponse(response);
  69:  *      if (ss.isComplete()) {
  70:  *         status = ldap.sendBindResponse(mechanism, challenge, SUCCESS);
  71:  *      } else {
  72:  *         status = ldap.sendBindResponse(mechanism, challenge, SASL_BIND_IN_PROGRESS);
  73:  *         response = ldap.readBindRequest();
  74:  *      }
  75:  *   } catch (SaslException x) {
  76:  *      status = ldap.sendErrorResponse(x);
  77:  *      break;
  78:  *   }
  79:  *}
  80:  *if (ss.isComplete() && (status == SUCCESS)) {
  81:  *   String qop = (String) sc.getNegotiatedProperty(Sasl.QOP);
  82:  *   if (qop != null
  83:  *         && (qop.equalsIgnoreCase("auth-int")
  84:  *            || qop.equalsIgnoreCase("auth-conf"))) {
  85:  *      // Use SaslServer.wrap() and SaslServer.unwrap() for future
  86:  *      // communication with client
  87:  *      ldap.in = new SecureInputStream(ss, ldap.in);
  88:  *      ldap.out = new SecureOutputStream(ss, ldap.out);
  89:  *   }
  90:  *}
  91:  * </pre>
  92:  *
  93:  * @see Sasl
  94:  * @see SaslServerFactory
  95:  */
  96: public interface SaslServer
  97: {
  98: 
  99:   /**
 100:    * Returns the IANA-registered mechanism name of this SASL server (e.g.
 101:    * "CRAM-MD5", "GSSAPI").
 102:    *
 103:    * @return a non-null string representing the IANA-registered mechanism name.
 104:    */
 105:   String getMechanismName();
 106: 
 107:   /**
 108:    * Evaluates the response data and generates a challenge. If a response is
 109:    * received from the client during the authentication process, this method is
 110:    * called to prepare an appropriate next challenge to submit to the client.
 111:    * The challenge is <code>null</code> if the authentication has succeeded and
 112:    * no more challenge data is to be sent to the client. It is non-null if the
 113:    * authentication must be continued by sending a challenge to the client, or
 114:    * if the authentication has succeeded but challenge data needs to be
 115:    * processed by the client. {@link #isComplete()} should be called after each
 116:    * call to <code>evaluateResponse()</code>,to determine if any further
 117:    * response is needed from the client.
 118:    *
 119:    * @param response the non-null (but possibly empty) response sent by the
 120:    * client.
 121:    * @return the possibly <code>null</code> challenge to send to the client.
 122:    * It is <code>null</code> if the authentication has succeeded and there is
 123:    * no more challenge data to be sent to the client.
 124:    * @throws SaslException if an error occurred while processing the response
 125:    * or generating a challenge.
 126:    */
 127:   byte[] evaluateResponse(byte[] response) throws SaslException;
 128: 
 129:   /**
 130:    * Determines if the authentication exchange has completed. This method is
 131:    * typically called after each invocation of {@link #evaluateResponse(byte[])}
 132:    * to determine whether the authentication has completed successfully or
 133:    * should be continued.
 134:    *
 135:    * @return <code>true</code> if the authentication exchange has completed;
 136:    * <code>false</code> otherwise.
 137:    */
 138:   boolean isComplete();
 139: 
 140:   /**
 141:    * Reports the authorization ID in effect for the client of this session This
 142:    * method can only be called if {@link #isComplete()} returns <code>true</code>.
 143:    *
 144:    * @return the authorization ID of the client.
 145:    * @throws IllegalStateException if this authentication session has not
 146:    * completed.
 147:    */
 148:   String getAuthorizationID();
 149: 
 150:   /**
 151:    * <p>Unwraps a byte array received from the client. This method can be called
 152:    * only after the authentication exchange has completed (i.e., when
 153:    * {@link #isComplete()} returns <code>true</code>) and only if the
 154:    * authentication exchange has negotiated integrity and/or privacy as the
 155:    * quality of protection; otherwise, an {@link IllegalStateException} is
 156:    * thrown.</p>
 157:    *
 158:    * <p><code>incoming</code> is the contents of the SASL buffer as defined in
 159:    * RFC 2222 without the leading four octet field that represents the length.
 160:    * <code>offset</code> and <code>len</code> specify the portion of incoming
 161:    * to use.</p>
 162:    *
 163:    * @param incoming a non-null byte array containing the encoded bytes from
 164:    * the client.
 165:    * @param offset the starting position at <code>incoming</code> of the bytes
 166:    * to use.
 167:    * @param len the number of bytes from <code>incoming</code> to use.
 168:    * @return a non-null byte array containing the decoded bytes.
 169:    * @throws SaslException if <code>incoming</code> cannot be successfully
 170:    * unwrapped.
 171:    * @throws IllegalStateException if the authentication exchange has not
 172:    * completed, or if the negotiated quality of protection has neither
 173:    * integrity nor privacy.
 174:    */
 175:   byte[] unwrap(byte[] incoming, int offset, int len) throws SaslException;
 176: 
 177:   /**
 178:    * <p>Wraps a byte array to be sent to the client. This method can be called
 179:    * only after the authentication exchange has completed (i.e., when
 180:    * {@link #isComplete()} returns <code>true</code>) and only if the
 181:    * authentication exchange has negotiated integrity and/or privacy as the
 182:    * quality of protection; otherwise, an {@link IllegalStateException} is
 183:    * thrown.</p>
 184:    *
 185:    * <p>The result of this method will make up the contents of the SASL buffer
 186:    * as defined in RFC 2222 without the leading four octet field that
 187:    * represents the length. <code>offset</code> and <code>len</code> specify
 188:    * the portion of <code>outgoing</code> to use.
 189:    *
 190:    * @param outgoing a non-null byte array containing the bytes to encode.
 191:    * @param offset the starting position at <code>outgoing</code> of the bytes
 192:    * to use.
 193:    * @param len the number of bytes from <code>outgoing</code> to use.
 194:    * @return a non-null byte array containing the encoded bytes.
 195:    * @throws SaslException if <code>outgoing</code> cannot be successfully
 196:    * wrapped.
 197:    * @throws IllegalStateException if the authentication exchange has not
 198:    * completed, or if the negotiated quality of protection has neither
 199:    * integrity nor privacy.
 200:    */
 201:   byte[] wrap(byte[] outgoing, int offset, int len) throws SaslException;
 202: 
 203:   /**
 204:    * Retrieves the negotiated property. This method can be called only after
 205:    * the authentication exchange has completed (i.e., when
 206:    * {@link #isComplete()} returns <code>true</code>); otherwise, an
 207:    * {@link IllegalStateException} is thrown.
 208:    *
 209:    * @return the value of the negotiated property. If <code>null</code>, the
 210:    * property was not negotiated or is not applicable to this mechanism.
 211:    * @throws IllegalStateException if this authentication exchange has not
 212:    * completed.
 213:    */
 214:   Object getNegotiatedProperty(String propName) throws SaslException;
 215: 
 216:   /**
 217:    * Disposes of any system resources or security-sensitive information the
 218:    * <code>SaslServer</code> might be using. Invoking this method invalidates
 219:    * the <code>SaslServer</code> instance. This method is idempotent.
 220:    *
 221:    * @throws SaslException if a problem was encountered while disposing of the
 222:    * resources.
 223:    */
 224:   void dispose() throws SaslException;
 225: }