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 import java.util.Map; 29 import javax.security.auth.callback.CallbackHandler; 30 31 /** 32 * An interface for creating instances of {@code SaslServer}. 33 * A class that implements this interface 34 * must be thread-safe and handle multiple simultaneous 35 * requests. It must also have a public constructor that accepts no 36 * argument. 37 *<p> 38 * This interface is not normally accessed directly by a server, which will use the 39 * {@code Sasl} static methods 40 * instead. However, a particular environment may provide and install a 41 * new or different {@code SaslServerFactory}. 42 * 43 * @since 1.5 44 * 45 * @see SaslServer 46 * @see Sasl 47 * 48 * @author Rosanna Lee 49 * @author Rob Weltman 50 */ 51 public abstract interface SaslServerFactory { 52 /** 53 * Creates a {@code SaslServer} using the parameters supplied. 54 * It returns null 55 * if no {@code SaslServer} can be created using the parameters supplied. 56 * Throws {@code SaslException} if it cannot create a {@code SaslServer} 57 * because of an error. 58 * 59 * @param mechanism The non-null 60 * IANA-registered name of a SASL mechanism. (e.g. "GSSAPI", "CRAM-MD5"). 61 * @param protocol The non-null string name of the protocol for which 62 * the authentication is being performed (e.g., "ldap"). 63 * @param serverName The fully qualified host name of the server to 64 * authenticate to, or null if the server is not bound to any specific host 65 * name. If the mechanism does not allow an unbound server, a 66 * {@code SaslException} will be thrown. 67 * @param props The possibly null set of properties used to select the SASL 68 * mechanism and to configure the authentication exchange of the selected 69 * mechanism. See the {@code Sasl} class for a list of standard properties. 70 * Other, possibly mechanism-specific, properties can be included. 71 * Properties not relevant to the selected mechanism are ignored, 72 * including any map entries with non-String keys. 73 * 74 * @param cbh The possibly null callback handler to used by the SASL 75 * mechanisms to get further information from the application/library 76 * to complete the authentication. For example, a SASL mechanism might 77 * require the authentication ID, password and realm from the caller. 78 * The authentication ID is requested by using a {@code NameCallback}. 79 * The password is requested by using a {@code PasswordCallback}. 80 * The realm is requested by using a {@code RealmChoiceCallback} if there is a list 81 * of realms to choose from, and by using a {@code RealmCallback} if 82 * the realm must be entered. 83 * 84 *@return A possibly null {@code SaslServer} created using the parameters 85 * supplied. If null, this factory cannot produce a {@code SaslServer} 86 * using the parameters supplied. 87 *@exception SaslException If cannot create a {@code SaslServer} because 88 * of an error. 89 */ createSaslServer( String mechanism, String protocol, String serverName, Map<String,?> props, CallbackHandler cbh)90 public abstract SaslServer createSaslServer( 91 String mechanism, 92 String protocol, 93 String serverName, 94 Map<String,?> props, 95 CallbackHandler cbh) throws SaslException; 96 97 /** 98 * Returns an array of names of mechanisms that match the specified 99 * mechanism selection policies. 100 * @param props The possibly null set of properties used to specify the 101 * security policy of the SASL mechanisms. For example, if {@code props} 102 * contains the {@code Sasl.POLICY_NOPLAINTEXT} property with the value 103 * {@code "true"}, then the factory must not return any SASL mechanisms 104 * that are susceptible to simple plain passive attacks. 105 * See the {@code Sasl} class for a complete list of policy properties. 106 * Non-policy related properties, if present in {@code props}, are ignored, 107 * including any map entries with non-String keys. 108 * @return A non-null array containing a IANA-registered SASL mechanism names. 109 */ getMechanismNames(Map<String,?> props)110 public abstract String[] getMechanismNames(Map<String,?> props); 111 } 112