src/java.security.sasl/share/classes/javax/security/sasl/SaslServer.java
changeset 47216 71c04702a3d5
parent 25859 3317bb8137f4
equal deleted inserted replaced
47215:4ebc2e2fb97c 47216:71c04702a3d5
       
     1 /*
       
     2  * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
       
     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
       
     4  *
       
     5  * This code is free software; you can redistribute it and/or modify it
       
     6  * under the terms of the GNU General Public License version 2 only, as
       
     7  * published by the Free Software Foundation.  Oracle designates this
       
     8  * particular file as subject to the "Classpath" exception as provided
       
     9  * by Oracle in the LICENSE file that accompanied this code.
       
    10  *
       
    11  * This code is distributed in the hope that it will be useful, but WITHOUT
       
    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
       
    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
       
    14  * version 2 for more details (a copy is included in the LICENSE file that
       
    15  * accompanied this code).
       
    16  *
       
    17  * You should have received a copy of the GNU General Public License version
       
    18  * 2 along with this work; if not, write to the Free Software Foundation,
       
    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
       
    20  *
       
    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
       
    22  * or visit www.oracle.com if you need additional information or have any
       
    23  * questions.
       
    24  */
       
    25 
       
    26 package javax.security.sasl;
       
    27 
       
    28 /**
       
    29  * Performs SASL authentication as a server.
       
    30  *<p>
       
    31  * A server such an LDAP server gets an instance of this
       
    32  * class in order to perform authentication defined by a specific SASL
       
    33  * mechanism. Invoking methods on the {@code SaslServer} instance
       
    34  * generates challenges according to the SASL
       
    35  * mechanism implemented by the {@code SaslServer}.
       
    36  * As the authentication proceeds, the instance
       
    37  * encapsulates the state of a SASL server's authentication exchange.
       
    38  *<p>
       
    39  * Here's an example of how an LDAP server might use a {@code SaslServer}.
       
    40  * It first gets an instance of a {@code SaslServer} for the SASL mechanism
       
    41  * requested by the client:
       
    42  *<blockquote><pre>
       
    43  * SaslServer ss = Sasl.createSaslServer(mechanism,
       
    44  *     "ldap", myFQDN, props, callbackHandler);
       
    45  *</pre></blockquote>
       
    46  * It can then proceed to use the server for authentication.
       
    47  * For example, suppose the LDAP server received an LDAP BIND request
       
    48  * containing the name of the SASL mechanism and an (optional) initial
       
    49  * response. It then might use the server as follows:
       
    50  *<blockquote><pre>{@code
       
    51  * while (!ss.isComplete()) {
       
    52  *     try {
       
    53  *         byte[] challenge = ss.evaluateResponse(response);
       
    54  *         if (ss.isComplete()) {
       
    55  *             status = ldap.sendBindResponse(mechanism, challenge, SUCCESS);
       
    56  *         } else {
       
    57  *             status = ldap.sendBindResponse(mechanism, challenge,
       
    58                    SASL_BIND_IN_PROGRESS);
       
    59  *             response = ldap.readBindRequest();
       
    60  *         }
       
    61  *     } catch (SaslException e) {
       
    62  *          status = ldap.sendErrorResponse(e);
       
    63  *          break;
       
    64  *     }
       
    65  * }
       
    66  * if (ss.isComplete() && status == SUCCESS) {
       
    67  *    String qop = (String) sc.getNegotiatedProperty(Sasl.QOP);
       
    68  *    if (qop != null
       
    69  *        && (qop.equalsIgnoreCase("auth-int")
       
    70  *            || qop.equalsIgnoreCase("auth-conf"))) {
       
    71  *
       
    72  *      // Use SaslServer.wrap() and SaslServer.unwrap() for future
       
    73  *      // communication with client
       
    74  *      ldap.in = new SecureInputStream(ss, ldap.in);
       
    75  *      ldap.out = new SecureOutputStream(ss, ldap.out);
       
    76  *    }
       
    77  * }
       
    78  *}</pre></blockquote>
       
    79  *
       
    80  * @since 1.5
       
    81  *
       
    82  * @see Sasl
       
    83  * @see SaslServerFactory
       
    84  *
       
    85  * @author Rosanna Lee
       
    86  * @author Rob Weltman
       
    87  */
       
    88 public abstract interface SaslServer {
       
    89 
       
    90     /**
       
    91      * Returns the IANA-registered mechanism name of this SASL server.
       
    92      * (e.g. "CRAM-MD5", "GSSAPI").
       
    93      * @return A non-null string representing the IANA-registered mechanism name.
       
    94      */
       
    95     public abstract String getMechanismName();
       
    96 
       
    97     /**
       
    98      * Evaluates the response data and generates a challenge.
       
    99      *
       
   100      * If a response is received from the client during the authentication
       
   101      * process, this method is called to prepare an appropriate next
       
   102      * challenge to submit to the client. The challenge is null if the
       
   103      * authentication has succeeded and no more challenge data is to be sent
       
   104      * to the client. It is non-null if the authentication must be continued
       
   105      * by sending a challenge to the client, or if the authentication has
       
   106      * succeeded but challenge data needs to be processed by the client.
       
   107      * {@code isComplete()} should be called
       
   108      * after each call to {@code evaluateResponse()},to determine if any further
       
   109      * response is needed from the client.
       
   110      *
       
   111      * @param response The non-null (but possibly empty) response sent
       
   112      * by the client.
       
   113      *
       
   114      * @return The possibly null challenge to send to the client.
       
   115      * It is null if the authentication has succeeded and there is
       
   116      * no more challenge data to be sent to the client.
       
   117      * @exception SaslException If an error occurred while processing
       
   118      * the response or generating a challenge.
       
   119      */
       
   120     public abstract byte[] evaluateResponse(byte[] response)
       
   121         throws SaslException;
       
   122 
       
   123     /**
       
   124       * Determines whether the authentication exchange has completed.
       
   125       * This method is typically called after each invocation of
       
   126       * {@code evaluateResponse()} to determine whether the
       
   127       * authentication has completed successfully or should be continued.
       
   128       * @return true if the authentication exchange has completed; false otherwise.
       
   129       */
       
   130     public abstract boolean isComplete();
       
   131 
       
   132     /**
       
   133      * Reports the authorization ID in effect for the client of this
       
   134      * session.
       
   135      * This method can only be called if isComplete() returns true.
       
   136      * @return The authorization ID of the client.
       
   137      * @exception IllegalStateException if this authentication session has not completed
       
   138      */
       
   139     public String getAuthorizationID();
       
   140 
       
   141     /**
       
   142      * Unwraps a byte array received from the client.
       
   143      * This method can be called only after the authentication exchange has
       
   144      * completed (i.e., when {@code isComplete()} returns true) and only if
       
   145      * the authentication exchange has negotiated integrity and/or privacy
       
   146      * as the quality of protection; otherwise,
       
   147      * an {@code IllegalStateException} is thrown.
       
   148      *<p>
       
   149      * {@code incoming} is the contents of the SASL buffer as defined in RFC 2222
       
   150      * without the leading four octet field that represents the length.
       
   151      * {@code offset} and {@code len} specify the portion of {@code incoming}
       
   152      * to use.
       
   153      *
       
   154      * @param incoming A non-null byte array containing the encoded bytes
       
   155      *                from the client.
       
   156      * @param offset The starting position at {@code incoming} of the bytes to use.
       
   157      * @param len The number of bytes from {@code incoming} to use.
       
   158      * @return A non-null byte array containing the decoded bytes.
       
   159      * @exception SaslException if {@code incoming} cannot be successfully
       
   160      * unwrapped.
       
   161      * @exception IllegalStateException if the authentication exchange has
       
   162      * not completed, or if the negotiated quality of protection
       
   163      * has neither integrity nor privacy
       
   164      */
       
   165     public abstract byte[] unwrap(byte[] incoming, int offset, int len)
       
   166         throws SaslException;
       
   167 
       
   168     /**
       
   169      * Wraps a byte array to be sent to the client.
       
   170      * This method can be called only after the authentication exchange has
       
   171      * completed (i.e., when {@code isComplete()} returns true) and only if
       
   172      * the authentication exchange has negotiated integrity and/or privacy
       
   173      * as the quality of protection; otherwise, a {@code SaslException} is thrown.
       
   174      *<p>
       
   175      * The result of this method
       
   176      * will make up the contents of the SASL buffer as defined in RFC 2222
       
   177      * without the leading four octet field that represents the length.
       
   178      * {@code offset} and {@code len} specify the portion of {@code outgoing}
       
   179      * to use.
       
   180      *
       
   181      * @param outgoing A non-null byte array containing the bytes to encode.
       
   182      * @param offset The starting position at {@code outgoing} of the bytes to use.
       
   183      * @param len The number of bytes from {@code outgoing} to use.
       
   184      * @return A non-null byte array containing the encoded bytes.
       
   185      * @exception SaslException if {@code outgoing} cannot be successfully
       
   186      * wrapped.
       
   187      * @exception IllegalStateException if the authentication exchange has
       
   188      * not completed, or if the negotiated quality of protection has
       
   189      * neither integrity nor privacy.
       
   190      */
       
   191     public abstract byte[] wrap(byte[] outgoing, int offset, int len)
       
   192         throws SaslException;
       
   193 
       
   194     /**
       
   195      * Retrieves the negotiated property.
       
   196      * This method can be called only after the authentication exchange has
       
   197      * completed (i.e., when {@code isComplete()} returns true); otherwise, an
       
   198      * {@code IllegalStateException} is thrown.
       
   199      * <p>
       
   200      * The {@link Sasl} class includes several well-known property names
       
   201      * (For example, {@link Sasl#QOP}). A SASL provider can support other
       
   202      * properties which are specific to the vendor and/or a mechanism.
       
   203      *
       
   204      * @param propName the property
       
   205      * @return The value of the negotiated property. If null, the property was
       
   206      * not negotiated or is not applicable to this mechanism.
       
   207      * @exception IllegalStateException if this authentication exchange has not completed
       
   208      */
       
   209 
       
   210     public abstract Object getNegotiatedProperty(String propName);
       
   211 
       
   212      /**
       
   213       * Disposes of any system resources or security-sensitive information
       
   214       * the SaslServer might be using. Invoking this method invalidates
       
   215       * the SaslServer instance. This method is idempotent.
       
   216       * @throws SaslException If a problem was encountered while disposing
       
   217       * the resources.
       
   218       */
       
   219     public abstract void dispose() throws SaslException;
       
   220 }