| Frames | No Frames |
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: }