GNU Classpath (0.18) | ||
Frames | No Frames |
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: }
GNU Classpath (0.18) |