Back to index...

	/*
	* Copyright (c) 1999, 2019, Oracle and/or its affiliates. All rights reserved.
	* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
	*
	* This code is free software; you can redistribute it and/or modify it
	* under the terms of the GNU General Public License version 2 only, as
	* published by the Free Software Foundation. Oracle designates this
	* particular file as subject to the "Classpath" exception as provided
	* by Oracle in the LICENSE file that accompanied this code.
	*
	* This code is distributed in the hope that it will be useful, but WITHOUT
	* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
	* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
	* version 2 for more details (a copy is included in the LICENSE file that
	* accompanied this code).
	*
	* You should have received a copy of the GNU General Public License version
	* 2 along with this work; if not, write to the Free Software Foundation,
	* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
	*
	* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
	* or visit www.oracle.com if you need additional information or have any
	* questions.
	*/

	package javax.security.sasl;

	import javax.security.auth.callback.CallbackHandler;
	import java.security.AccessController;
	import java.security.PrivilegedAction;
	import java.util.ArrayList;
	import java.util.Enumeration;
	import java.util.Iterator;
	import java.util.List;
	import java.util.Map;
	import java.util.Set;
	import java.util.HashSet;
	import java.util.Collections;
	import java.security.Provider;
	import java.security.Security;
	import java.util.logging.Level;
	import java.util.logging.Logger;

	/**
	* A static class for creating SASL clients and servers.
	*<p>
	* This class defines the policy of how to locate, load, and instantiate
	* SASL clients and servers.
	*<p>
	* For example, an application or library gets a SASL client by doing
	* something like:
	*<blockquote><pre>
	* SaslClient sc = Sasl.createSaslClient(mechanisms,
	* authorizationId, protocol, serverName, props, callbackHandler);
	*</pre></blockquote>
	* It can then proceed to use the instance to create an authentication connection.
	*<p>
	* Similarly, a server gets a SASL server by using code that looks as follows:
	*<blockquote><pre>
	* SaslServer ss = Sasl.createSaslServer(mechanism,
	* protocol, serverName, props, callbackHandler);
	*</pre></blockquote>
	*
	* @since 1.5
	*
	* @author Rosanna Lee
	* @author Rob Weltman
	*/
	public class Sasl {

	private static List<String> disabledMechanisms = new ArrayList<>();

	static {
	String prop = AccessController.doPrivileged(
	(PrivilegedAction<String>)
	() -> Security.getProperty("jdk.sasl.disabledMechanisms"));

	if (prop != null) {
	for (String s : prop.split("\\s,\\s")) {
	if (!s.isEmpty()) {
	disabledMechanisms.add(s);
	}
	}
	}
	}

	private static final String SASL_LOGGER_NAME = "javax.security.sasl";

	/**
	* Logger for debug messages
	*/
	private static final Logger logger = Logger.getLogger(SASL_LOGGER_NAME);

	// Cannot create one of these
	private Sasl() {
	}

	/**
	* The name of a property that specifies the quality-of-protection to use.
	* The property contains a comma-separated, ordered list
	* of quality-of-protection values that the
	* client or server is willing to support. A qop value is one of
	* <ul>
	* <li>{@code "auth"} - authentication only</li>
	* <li>{@code "auth-int"} - authentication plus integrity protection</li>
	* <li>{@code "auth-conf"} - authentication plus integrity and confidentiality
	* protection</li>
	* </ul>
	*
	* The order of the list specifies the preference order of the client or
	* server. If this property is absent, the default qop is {@code "auth"}.
	* The value of this constant is {@code "javax.security.sasl.qop"}.
	*/
	public static final String QOP = "javax.security.sasl.qop";

	/**
	* The name of a property that specifies the cipher strength to use.
	* The property contains a comma-separated, ordered list
	* of cipher strength values that
	* the client or server is willing to support. A strength value is one of
	* <ul>
	* <li>{@code "low"}</li>
	* <li>{@code "medium"}</li>
	* <li>{@code "high"}</li>
	* </ul>
	* The order of the list specifies the preference order of the client or
	* server. An implementation should allow configuration of the meaning
	* of these values. An application may use the Java Cryptography
	* Extension (JCE) with JCE-aware mechanisms to control the selection of
	* cipher suites that match the strength values.
	* <BR>
	* If this property is absent, the default strength is
	* {@code "high,medium,low"}.
	* The value of this constant is {@code "javax.security.sasl.strength"}.
	*/
	public static final String STRENGTH = "javax.security.sasl.strength";

	/**
	* The name of a property that specifies whether the
	* server must authenticate to the client. The property contains
	* {@code "true"} if the server must
	* authenticate the to client; {@code "false"} otherwise.
	* The default is {@code "false"}.
	* <br>The value of this constant is
	* {@code "javax.security.sasl.server.authentication"}.
	*/
	public static final String SERVER_AUTH =
	"javax.security.sasl.server.authentication";

	/**
	* The name of a property that specifies the bound server name for
	* an unbound server. A server is created as an unbound server by setting
	* the {@code serverName} argument in {@link #createSaslServer} as null.
	* The property contains the bound host name after the authentication
	* exchange has completed. It is only available on the server side.
	* <br>The value of this constant is
	* {@code "javax.security.sasl.bound.server.name"}.
	*/
	public static final String BOUND_SERVER_NAME =
	"javax.security.sasl.bound.server.name";

	/**
	* The name of a property that specifies the maximum size of the receive
	* buffer in bytes of {@code SaslClient}/{@code SaslServer}.
	* The property contains the string representation of an integer.
	* <br>If this property is absent, the default size
	* is defined by the mechanism.
	* <br>The value of this constant is {@code "javax.security.sasl.maxbuffer"}.
	*/
	public static final String MAX_BUFFER = "javax.security.sasl.maxbuffer";

	/**
	* The name of a property that specifies the maximum size of the raw send
	* buffer in bytes of {@code SaslClient}/{@code SaslServer}.
	* The property contains the string representation of an integer.
	* The value of this property is negotiated between the client and server
	* during the authentication exchange.
	* <br>The value of this constant is {@code "javax.security.sasl.rawsendsize"}.
	*/
	public static final String RAW_SEND_SIZE = "javax.security.sasl.rawsendsize";

	/**
	* The name of a property that specifies whether to reuse previously
	* authenticated session information. The property contains "true" if the
	* mechanism implementation may attempt to reuse previously authenticated
	* session information; it contains "false" if the implementation must
	* not reuse previously authenticated session information. A setting of
	* "true" serves only as a hint: it does not necessarily entail actual
	* reuse because reuse might not be possible due to a number of reasons,
	* including, but not limited to, lack of mechanism support for reuse,
	* expiration of reusable information, and the peer's refusal to support
	* reuse.
	*
	* The property's default value is "false". The value of this constant
	* is "javax.security.sasl.reuse".
	*
	* Note that all other parameters and properties required to create a
	* SASL client/server instance must be provided regardless of whether
	* this property has been supplied. That is, you cannot supply any less
	* information in anticipation of reuse.
	*
	* Mechanism implementations that support reuse might allow customization
	* of its implementation, for factors such as cache size, timeouts, and
	* criteria for reusability. Such customizations are
	* implementation-dependent.
	*/
	public static final String REUSE = "javax.security.sasl.reuse";

	/**
	* The name of a property that specifies
	* whether mechanisms susceptible to simple plain passive attacks (e.g.,
	* "PLAIN") are not permitted. The property
	* contains {@code "true"} if such mechanisms are not permitted;
	* {@code "false"} if such mechanisms are permitted.
	* The default is {@code "false"}.
	* <br>The value of this constant is
	* {@code "javax.security.sasl.policy.noplaintext"}.
	*/
	public static final String POLICY_NOPLAINTEXT =
	"javax.security.sasl.policy.noplaintext";

	/**
	* The name of a property that specifies whether
	* mechanisms susceptible to active (non-dictionary) attacks
	* are not permitted.
	* The property contains {@code "true"}
	* if mechanisms susceptible to active attacks
	* are not permitted; {@code "false"} if such mechanisms are permitted.
	* The default is {@code "false"}.
	* <br>The value of this constant is
	* {@code "javax.security.sasl.policy.noactive"}.
	*/
	public static final String POLICY_NOACTIVE =
	"javax.security.sasl.policy.noactive";

	/**
	* The name of a property that specifies whether
	* mechanisms susceptible to passive dictionary attacks are not permitted.
	* The property contains {@code "true"}
	* if mechanisms susceptible to dictionary attacks are not permitted;
	* {@code "false"} if such mechanisms are permitted.
	* The default is {@code "false"}.
	*<br>
	* The value of this constant is
	* {@code "javax.security.sasl.policy.nodictionary"}.
	*/
	public static final String POLICY_NODICTIONARY =
	"javax.security.sasl.policy.nodictionary";

	/**
	* The name of a property that specifies whether mechanisms that accept
	* anonymous login are not permitted. The property contains {@code "true"}
	* if mechanisms that accept anonymous login are not permitted;
	* {@code "false"}
	* if such mechanisms are permitted. The default is {@code "false"}.
	*<br>
	* The value of this constant is
	* {@code "javax.security.sasl.policy.noanonymous"}.
	*/
	public static final String POLICY_NOANONYMOUS =
	"javax.security.sasl.policy.noanonymous";

	/**
	* The name of a property that specifies whether mechanisms that implement
	* forward secrecy between sessions are required. Forward secrecy
	* means that breaking into one session will not automatically
	* provide information for breaking into future sessions.
	* The property
	* contains {@code "true"} if mechanisms that implement forward secrecy
	* between sessions are required; {@code "false"} if such mechanisms
	* are not required. The default is {@code "false"}.
	*<br>
	* The value of this constant is
	* {@code "javax.security.sasl.policy.forward"}.
	*/
	public static final String POLICY_FORWARD_SECRECY =
	"javax.security.sasl.policy.forward";

	/**
	* The name of a property that specifies whether
	* mechanisms that pass client credentials are required. The property
	* contains {@code "true"} if mechanisms that pass
	* client credentials are required; {@code "false"}
	* if such mechanisms are not required. The default is {@code "false"}.
	*<br>
	* The value of this constant is
	* {@code "javax.security.sasl.policy.credentials"}.
	*/
	public static final String POLICY_PASS_CREDENTIALS =
	"javax.security.sasl.policy.credentials";

	/**
	* The name of a property that specifies the credentials to use.
	* The property contains a mechanism-specific Java credential object.
	* Mechanism implementations may examine the value of this property
	* to determine whether it is a class that they support.
	* The property may be used to supply credentials to a mechanism that
	* supports delegated authentication.
	*<br>
	* The value of this constant is
	* {@code "javax.security.sasl.credentials"}.
	*/
	public static final String CREDENTIALS = "javax.security.sasl.credentials";

	/**
	* Creates a {@code SaslClient} using the parameters supplied.
	*
	* This method uses the
	<a href="{@docRoot}/../technotes/guides/security/crypto/CryptoSpec.html#Provider">JCA Security Provider Framework</a>, described in the
	* "Java Cryptography Architecture API Specification & Reference", for
	* locating and selecting a {@code SaslClient} implementation.
	*
	* First, it
	* obtains an ordered list of {@code SaslClientFactory} instances from
	* the registered security providers for the "SaslClientFactory" service
	* and the specified SASL mechanism(s). It then invokes
	* {@code createSaslClient()} on each factory instance on the list
	* until one produces a non-null {@code SaslClient} instance. It returns
	* the non-null {@code SaslClient} instance, or null if the search fails
	* to produce a non-null {@code SaslClient} instance.
	*<p>
	* A security provider for SaslClientFactory registers with the
	* JCA Security Provider Framework keys of the form <br>
	* {@code SaslClientFactory.}<em>{@code mechanism_name}</em>
	* <br>
	* and values that are class names of implementations of
	* {@code javax.security.sasl.SaslClientFactory}.
	*
	* For example, a provider that contains a factory class,
	* {@code com.wiz.sasl.digest.ClientFactory}, that supports the
	* "DIGEST-MD5" mechanism would register the following entry with the JCA:
	* {@code SaslClientFactory.DIGEST-MD5 com.wiz.sasl.digest.ClientFactory}
	*<p>
	* See the
	* "Java Cryptography Architecture API Specification & Reference"
	* for information about how to install and configure security service
	* providers.
	* <p>
	* If a mechanism is listed in the {@code jdk.sasl.disabledMechanisms}
	* security property, it will be ignored and won't be negotiated.
	*
	* @param mechanisms The non-null list of mechanism names to try. Each is the
	* IANA-registered name of a SASL mechanism. (e.g. "GSSAPI", "CRAM-MD5").
	* @param authorizationId The possibly null protocol-dependent
	* identification to be used for authorization.
	* If null or empty, the server derives an authorization
	* ID from the client's authentication credentials.
	* When the SASL authentication completes successfully,
	* the specified entity is granted access.
	*
	* @param protocol The non-null string name of the protocol for which
	* the authentication is being performed (e.g., "ldap").
	*
	* @param serverName The non-null fully-qualified host name of the server
	* to authenticate to.
	*
	* @param props The possibly null set of properties used to
	* select the SASL mechanism and to configure the authentication
	* exchange of the selected mechanism.
	* For example, if {@code props} contains the
	* {@code Sasl.POLICY_NOPLAINTEXT} property with the value
	* {@code "true"}, then the selected
	* SASL mechanism must not be susceptible to simple plain passive attacks.
	* In addition to the standard properties declared in this class,
	* other, possibly mechanism-specific, properties can be included.
	* Properties not relevant to the selected mechanism are ignored,
	* including any map entries with non-String keys.
	*
	* @param cbh The possibly null callback handler to used by the SASL
	* mechanisms to get further information from the application/library
	* to complete the authentication. For example, a SASL mechanism might
	* require the authentication ID, password and realm from the caller.
	* The authentication ID is requested by using a {@code NameCallback}.
	* The password is requested by using a {@code PasswordCallback}.
	* The realm is requested by using a {@code RealmChoiceCallback} if there is a list
	* of realms to choose from, and by using a {@code RealmCallback} if
	* the realm must be entered.
	*
	*@return A possibly null {@code SaslClient} created using the parameters
	* supplied. If null, cannot find a {@code SaslClientFactory}
	* that will produce one.
	*@exception SaslException If cannot create a {@code SaslClient} because
	* of an error.
	*/
	public static SaslClient createSaslClient(
	String[] mechanisms,
	String authorizationId,
	String protocol,
	String serverName,
	Map<String,?> props,
	CallbackHandler cbh) throws SaslException {

	SaslClient mech = null;
	SaslClientFactory fac;
	String className;
	String mechName;

	for (int i = 0; i < mechanisms.length; i++) {
	if ((mechName=mechanisms[i]) == null) {
	throw new NullPointerException(
	"Mechanism name cannot be null");
	} else if (mechName.length() == 0) {
	continue;
	} else if (isDisabled(mechName)) {
	logger.log(Level.FINE,
	"Disabled " + mechName + " mechanism ignored");
	continue;
	}
	String mechFilter = "SaslClientFactory." + mechName;
	Provider[] provs = Security.getProviders(mechFilter);
	for (int j = 0; provs != null && j < provs.length; j++) {
	className = provs[j].getProperty(mechFilter);
	if (className == null) {
	// Case is ignored
	continue;
	}

	fac = (SaslClientFactory) loadFactory(provs[j], className);
	if (fac != null) {
	mech = fac.createSaslClient(
	new String[]{mechanisms[i]}, authorizationId,
	protocol, serverName, props, cbh);
	if (mech != null) {
	return mech;
	}
	}
	}
	}

	return null;
	}

	private static Object loadFactory(Provider p, String className)
	throws SaslException {
	try {
	/*
	* Load the implementation class with the same class loader
	* that was used to load the provider.
	* In order to get the class loader of a class, the
	* caller's class loader must be the same as or an ancestor of
	* the class loader being returned. Otherwise, the caller must
	* have "getClassLoader" permission, or a SecurityException
	* will be thrown.
	*/
	ClassLoader cl = p.getClass().getClassLoader();
	Class<?> implClass;
	implClass = Class.forName(className, true, cl);
	return implClass.newInstance();
	} catch (ClassNotFoundException e) {
	throw new SaslException("Cannot load class " + className, e);
	} catch (InstantiationException e) {
	throw new SaslException("Cannot instantiate class " + className, e);
	} catch (IllegalAccessException e) {
	throw new SaslException("Cannot access class " + className, e);
	} catch (SecurityException e) {
	throw new SaslException("Cannot access class " + className, e);
	}
	}


	/**
	* Creates a {@code SaslServer} for the specified mechanism.
	*
	* This method uses the
	<a href="{@docRoot}/../technotes/guides/security/crypto/CryptoSpec.html#Provider">JCA Security Provider Framework</a>,
	* described in the
	* "Java Cryptography Architecture API Specification & Reference", for
	* locating and selecting a {@code SaslServer} implementation.
	*
	* First, it
	* obtains an ordered list of {@code SaslServerFactory} instances from
	* the registered security providers for the "SaslServerFactory" service
	* and the specified mechanism. It then invokes
	* {@code createSaslServer()} on each factory instance on the list
	* until one produces a non-null {@code SaslServer} instance. It returns
	* the non-null {@code SaslServer} instance, or null if the search fails
	* to produce a non-null {@code SaslServer} instance.
	*<p>
	* A security provider for SaslServerFactory registers with the
	* JCA Security Provider Framework keys of the form <br>
	* {@code SaslServerFactory.}<em>{@code mechanism_name}</em>
	* <br>
	* and values that are class names of implementations of
	* {@code javax.security.sasl.SaslServerFactory}.
	*
	* For example, a provider that contains a factory class,
	* {@code com.wiz.sasl.digest.ServerFactory}, that supports the
	* "DIGEST-MD5" mechanism would register the following entry with the JCA:
	* {@code SaslServerFactory.DIGEST-MD5 com.wiz.sasl.digest.ServerFactory}
	*<p>
	* See the
	* "Java Cryptography Architecture API Specification & Reference"
	* for information about how to install and configure security
	* service providers.
	* <p>
	* If {@code mechanism} is listed in the {@code jdk.sasl.disabledMechanisms}
	* security property, it will be ignored and this method returns {@code null}.
	*
	* @param mechanism The non-null mechanism name. It must be an
	* IANA-registered name of a SASL mechanism. (e.g. "GSSAPI", "CRAM-MD5").
	* @param protocol The non-null string name of the protocol for which
	* the authentication is being performed (e.g., "ldap").
	* @param serverName The fully qualified host name of the server, or null
	* if the server is not bound to any specific host name. If the mechanism
	* does not allow an unbound server, a {@code SaslException} will
	* be thrown.
	* @param props The possibly null set of properties used to
	* select the SASL mechanism and to configure the authentication
	* exchange of the selected mechanism.
	* For example, if {@code props} contains the
	* {@code Sasl.POLICY_NOPLAINTEXT} property with the value
	* {@code "true"}, then the selected
	* SASL mechanism must not be susceptible to simple plain passive attacks.
	* In addition to the standard properties declared in this class,
	* other, possibly mechanism-specific, properties can be included.
	* Properties not relevant to the selected mechanism are ignored,
	* including any map entries with non-String keys.
	*
	* @param cbh The possibly null callback handler to used by the SASL
	* mechanisms to get further information from the application/library
	* to complete the authentication. For example, a SASL mechanism might
	* require the authentication ID, password and realm from the caller.
	* The authentication ID is requested by using a {@code NameCallback}.
	* The password is requested by using a {@code PasswordCallback}.
	* The realm is requested by using a {@code RealmChoiceCallback} if there is a list
	* of realms to choose from, and by using a {@code RealmCallback} if
	* the realm must be entered.
	*
	*@return A possibly null {@code SaslServer} created using the parameters
	* supplied. If null, cannot find a {@code SaslServerFactory}
	* that will produce one.
	*@exception SaslException If cannot create a {@code SaslServer} because
	* of an error.
	**/
	public static SaslServer
	createSaslServer(String mechanism,
	String protocol,
	String serverName,
	Map<String,?> props,
	javax.security.auth.callback.CallbackHandler cbh)
	throws SaslException {

	SaslServer mech = null;
	SaslServerFactory fac;
	String className;

	if (mechanism == null) {
	throw new NullPointerException("Mechanism name cannot be null");
	} else if (mechanism.length() == 0) {
	return null;
	} else if (isDisabled(mechanism)) {
	logger.log(Level.FINE,
	"Disabled " + mechanism + " mechanism ignored");
	return null;
	}

	String mechFilter = "SaslServerFactory." + mechanism;
	Provider[] provs = Security.getProviders(mechFilter);
	for (int j = 0; provs != null && j < provs.length; j++) {
	className = provs[j].getProperty(mechFilter);
	if (className == null) {
	throw new SaslException("Provider does not support " +
	mechFilter);
	}
	fac = (SaslServerFactory) loadFactory(provs[j], className);
	if (fac != null) {
	mech = fac.createSaslServer(
	mechanism, protocol, serverName, props, cbh);
	if (mech != null) {
	return mech;
	}
	}
	}

	return null;
	}

	/**
	* Gets an enumeration of known factories for producing {@code SaslClient}.
	* This method uses the same algorithm for locating factories as
	* {@code createSaslClient()}.
	* @return A non-null enumeration of known factories for producing
	* {@code SaslClient}.
	* @see #createSaslClient
	*/
	public static Enumeration<SaslClientFactory> getSaslClientFactories() {
	Set<Object> facs = getFactories("SaslClientFactory");
	final Iterator<Object> iter = facs.iterator();
	return new Enumeration<SaslClientFactory>() {
	public boolean hasMoreElements() {
	return iter.hasNext();
	}
	public SaslClientFactory nextElement() {
	return (SaslClientFactory)iter.next();
	}
	};
	}

	/**
	* Gets an enumeration of known factories for producing {@code SaslServer}.
	* This method uses the same algorithm for locating factories as
	* {@code createSaslServer()}.
	* @return A non-null enumeration of known factories for producing
	* {@code SaslServer}.
	* @see #createSaslServer
	*/
	public static Enumeration<SaslServerFactory> getSaslServerFactories() {
	Set<Object> facs = getFactories("SaslServerFactory");
	final Iterator<Object> iter = facs.iterator();
	return new Enumeration<SaslServerFactory>() {
	public boolean hasMoreElements() {
	return iter.hasNext();
	}
	public SaslServerFactory nextElement() {
	return (SaslServerFactory)iter.next();
	}
	};
	}

	private static Set<Object> getFactories(String serviceName) {
	HashSet<Object> result = new HashSet<Object>();

	if ((serviceName == null) \|\| (serviceName.length() == 0) \|\|
	(serviceName.endsWith("."))) {
	return result;
	}


	Provider[] providers = Security.getProviders();
	HashSet<String> classes = new HashSet<String>();
	Object fac;

	for (int i = 0; i < providers.length; i++) {
	classes.clear();

	// Check the keys for each provider.
	for (Enumeration<Object> e = providers[i].keys(); e.hasMoreElements(); ) {
	String currentKey = (String)e.nextElement();
	if (currentKey.startsWith(serviceName)) {
	// We should skip the currentKey if it contains a
	// whitespace. The reason is: such an entry in the
	// provider property contains attributes for the
	// implementation of an algorithm. We are only interested
	// in entries which lead to the implementation
	// classes.
	if (currentKey.indexOf(" ") < 0) {
	String className = providers[i].getProperty(currentKey);
	if (!classes.contains(className)) {
	classes.add(className);
	try {
	fac = loadFactory(providers[i], className);
	if (fac != null) {
	result.add(fac);
	}
	}catch (Exception ignore) {
	}
	}
	}
	}
	}
	}
	return Collections.unmodifiableSet(result);
	}

	private static boolean isDisabled(String name) {
	return disabledMechanisms.contains(name);
	}
	}

Back to index...