libjava/javax/security/sasl/SaslServer.java

   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., 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 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 }