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