/* * @(#)Sasl.java 1.9 01/01/25 * * Copyright 1999-2000 Sun Microsystems, Inc. All Rights Reserved. * * This software is the proprietary information of Sun Microsystems, Inc. * Use is subject to license terms. */ package com.sun.security.sasl.preview; import java.util.Hashtable; import java.util.StringTokenizer; import java.util.Enumeration; import javax.security.auth.callback.CallbackHandler; /** * A static class for creating SASL clients and servers. *

* This class defines the policy of how to locate, load, and instantiate * SASL clients and servers. *

* For example, an application or library gets a SASL client by doing * something like: *

 * SaslClient sc = Sasl.createSaslClient(mechanisms,
 *     authorizationId, protocol, serverName, props, callbackHandler);
 *
* It can then proceed to use the instance to create an authentication connection. *

* Similarly, a server gets a SASL server by using code that looks as follows: *

 * SaslServer ss = Sasl.createSaslServer(mechanism,
 *     protocol, serverName, props, callbackHandler);
 *
* * IMPLEMENTATION NOTE FOR THE JAVA 2 PLATFORM: *
To use the create methods, * the caller needs the following permissions: * * To use the set factory methods, the caller needs the following permissions: * * * @author Rosanna Lee * @author Rob Weltman */ public class Sasl { private static SaslClientFactory clientFactory = null; private static SaslServerFactory serverFactory = null; // Cannot create one of these private Sasl() { } /** * The name of the property that specifies the SaslClientFactorys * to use. The property contains a list of client package names, * separated by * '|'. Each package contains a class named ClientFactory that * implements the SaslClientFactory interface. * Its value is "javax.security.sasl.client.pkgs". */ public static final String CLIENT_PKGS = "javax.security.sasl.client.pkgs"; /** * The name of the property that specifies the SaslServerFactorys * to use. * The property contains a list of server package names, * separated by * '|'. Each package contains a class named ServerFactory that * implements the SaslServerFactory interface. * Its value is "javax.security.sasl.server.pkgs". */ public static final String SERVER_PKGS = "javax.security.sasl.server.pkgs"; /** * 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 * * * The order of the list specifies the preference order of the client or * server. If this property is absent, the default qop is "auth". * The value of this constant is "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 * * 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. *
* If this property is absent, the default strength is * "high,medium,low". * The value of this constant is "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 * "true" if the server must * authenticate the to client; "false" otherwise. * The default is "false". *
The value of this constant is * "javax.security.sasl.server.authentication". */ public static final String SERVER_AUTH = "javax.security.sasl.server.authentication"; /** * The name of a property that specifies the maximum size of the receive * buffer in bytes of SaslClient/SaslServer. * The property contains the string representation of an integer. *
If this property is absent, the default size * is defined by the mechanism. *
The value of this constant is "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 SaslClient/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. *
The value of this constant is "javax.security.sasl.rawsendsize". */ public static final String RAW_SEND_SIZE = "javax.security.sasl.rawsendsize"; /** * The name of a property that specifies * whether mechanisms susceptible to simple plain passive attacks (e.g., * "PLAIN") are permitted. The property * contains "true" if such mechanisms are not permitted; * "false" if such mechanisms are permitted. * The default is "false". *
The value of this constant is * "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 permitted. The property contains "true" * if mechanisms susceptible to active attacks * are not permitted; "false" if such mechanisms are permitted. * The default is "false". *
The value of this constant is * "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 dictionary attacks are permitted. * The property contains "true" * if mechanisms susceptible to dictionary attacks are not permitted; * "false" if such mechanisms are permitted. * The default is "false". *
* The value of this constant is * "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 permitted. The property contains "true" * if mechanisms that accept anonymous login are not permitted; * "false" * if such mechanisms are permitted. The default is "false". *
* The value of this constant is * "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 * forward secrecy between sessions are required. The property * contains "true" if mechanisms that forward secrecy * between sessions are required; "false" if such mechanisms * are not required. The default is "false". *
* The value of this constant is * "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 "true" if mechanisms that pass * client credentials are required; "false" * if such mechanisms are not required. The default is "false". *
* The value of this constant is * "javax.security.sasl.policy.credentials". */ public static final String POLICY_PASS_CREDENTIALS = "javax.security.sasl.policy.credentials"; /** * Creates a SaslClient using the parameters supplied. * The algorithm for selecting a SaslClient is as follows. *
    *
  1. If a factory has been installed via setSaslClientFactory(), *invoke createSaslClient() on it. *If the method invocation returns a non-null SaslClient *instance, return the SaslClient instance; otherwise continue. * *
  2. Create a list of fully qualified class names * using the package names listed in the CLIENT_PKGS * ("javax.security.sasl.client.pkgs") * property in props and the class name, ClientFactory. * Each class named on this list names a SaslClientFactory * implementation. Starting with the first class on the list, * create an instance of SaslClientFactory using the class's * public no-argument constructor and * invoke createSaslClient() on it. If the method invocation * returns a non-null SaslClient instance, return it; * otherwise repeat using the next class on the list until a non-null * SaslClient is produced or the list exhausted. * *
  3. Repeat previous step using the CLIENT_PKGS * ("javax.security.sasl.client.pkgs") System property instead * of the property in props. * *
  4. As per the Java 2, Standard Edition, v 1.3 service provider guidelines, * check for the existence of one of more files named * META-INF/services/com.sun.security.sasl.preview.SaslClientFactory in * the classpath and installed JAR files. * Each file lists the fully qualified * class names of the factories (i.e., implementations of * SaslClientFactory) found in the JAR or classpath. * Construct a complete list of fully qualified class names using these * files and repeat Step 2 using this list. * If there are more than one of these files, the order in * which they are processed is undefined. *
  5. If no non-null SaslClient instance is produced, return null. *
* * @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 authorization ID to use. When * the SASL authentication completes successfully, the entity named * by authorizationId 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 string name of the server to which * we are creating an authenticated connection. * * @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 props contains the * Sasl.POLICY_NOPLAINTEXT property with the value * "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. * * @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 NameCallback. * The password is requested by using a PasswordCallback. * The realm is requested by using a RealmChoiceCallback if there is a list * of realms to choose from, and by using a RealmCallback if * the realm must be entered. * *@return A possibly null SaslClient created using the parameters * supplied. If null, cannot find a SaslClientFactory * that will produce one. *@exception SaslException If cannot create a SaslClient because * of an error. * @see #CLIENT_PKGS */ public static SaslClient createSaslClient( String[] mechanisms, String authorizationId, String protocol, String serverName, Hashtable props, CallbackHandler cbh) throws SaslException { SaslClient mech = null; Enumeration enum = getSaslClientFactories(props); SaslClientFactory fac; while (mech == null && enum.hasMoreElements()) { fac = (SaslClientFactory)enum.nextElement(); mech = fac.createSaslClient(mechanisms, authorizationId, protocol, serverName, props, cbh); } return mech; } /** * Gets an enumeration of known factories for producing SaslClient. * This method uses the same sources for locating factories as * createSaslClient(). * @param props A possible null set of properties that may * contain the Sasl.CLIENT_PKGS property. * @return An enumeration of known factories for producing * SaslClient. * @see #createSaslClient */ public static Enumeration getSaslClientFactories(Hashtable props) { // %%% Get merged list of factories from // 1. setSaslServerFactory // 2. CLIENT_PKGS prop from props // 3. CLIENT_PKGS system properties // 4. META-INF/services/javax.security.sasl.SaslClientFactory return new MergedEnumeration(clientFactory, CLIENT_PKGS, 0, "ClientFactory", SaslClientFactory.class, props); } /** * Sets the default SaslClientFactory to use. * This method sets fac to be the default factory. * It can only be called with a non-null value once per VM. * If a factory has been set already, this method throws * IllegalStateException. * @param fac The possibly null factory to set. If null, doesn't do anything. * @exception IllegalStateException If factory already set. * @exception SecurityException If a security manager exists and the * caller does not have permission to * get the security manager or set a factory. */ /*On the Java 2 platform, * the required permissions are * java.lang.RuntimePermission("getSecurityManager"), * java.lang.RuntimePermission("setFactory"). */ public static void setSaslClientFactory(SaslClientFactory fac) { if (clientFactory != null) { throw new IllegalStateException ( "SaslClientFactory already defined"); } SecurityManager security = System.getSecurityManager(); if (security != null) { security.checkSetFactory(); } clientFactory = fac; } /** * Creates a SaslServer for the specified mechanism. It * returns null if no SaslServer can be created * for the specified mechanism. *

* The algorithm for selecting a SaslServer is as follows. *

    *
  1. If a factory has been installed via setSaslServerFactory(), *invoke createSaslServer() on it. *If the method invocation returns a non-null SaslServer *instance, return the SaslServer instance; otherwise continue. * *
  2. Create a list of fully qualified class names * using the package names listed in the SERVER_PKGS * ("javax.security.sasl.server.pkgs") * property in props and the class name, ServerFactory. * Each class named on this list names a SaslServerFactory * implementation. Starting with the first class on the list, * create an instance of SaslServerFactory using the class's * public no-argument constructor and * invoke createSaslServer() on it. If the method invocation * returns a non-null SaslServer instance, return it; * otherwise repeat using the next class on the list until a non-null * SaslServer is produced or the list exhausted. * *
  3. Repeat previous step using the SERVER_PKGS * ("javax.security.sasl.server.pkgs") System property instead * of the property in props. * *
  4. As per the Java 2, Standard Edition, v 1.3 service provider guidelines, * check for the existence of one of more files named * META-INF/services/com.sun.security.sasl.preview.SaslServerFactory * in the classpath and installed JAR files. * Each file lists the fully qualified * class names of the factories (i.e., implementations of * SaslServerFactory). * Construct a complete list of fully qualified class names using these * files and repeat Step 2 using this list. * If there are more than one of these files, the order in * which they are processed is undefined. *
  5. If no non-null SaslServer instance is produced, return 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 non-null string name of the server. * @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 props contains the * Sasl.POLICY_NOPLAINTEXT property with the value * "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. * * @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 NameCallback. * The password is requested by using a PasswordCallback. * The realm is requested by using a RealmChoiceCallback if there is a list * of realms to choose from, and by using a RealmCallback if * the realm must be entered. * *@return A possibly null SaslServer created using the parameters * supplied. If null, cannot find a SaslServerFactory * that will produce one. *@exception SaslException If cannot create a SaslServer because * of an error. * @see #SERVER_PKGS **/ public static SaslServer createSaslServer(String mechanism, String protocol, String serverName, Hashtable props, javax.security.auth.callback.CallbackHandler cbh) throws SaslException { SaslServer mech = null; Enumeration enum = getSaslServerFactories(props); SaslServerFactory fac; while (mech == null && enum.hasMoreElements()) { fac = (SaslServerFactory)enum.nextElement(); mech = fac.createSaslServer(mechanism, protocol, serverName, props, cbh); } return mech; } /** * Gets an enumeration of known factories for producing SaslServer. * This method uses the same sources for locating factories as * createSaslServer(). * @param props A possible null set of properties that may * contain the Sasl.SERVER_PKGS property. * @return An enumeration of known factories for producing * SaslServer. * @see #createSaslServer */ public static Enumeration getSaslServerFactories(Hashtable props) { // %%% Get merged list of factories from // 1. setSaslServerFactory // 2. SERVER_PKGS prop from props // 3. SERVER_PKGS system properties // 4. META-INF/services/javax.security.sasl.SaslClientFactory return new MergedEnumeration(serverFactory, SERVER_PKGS, 1, "ServerFactory", SaslServerFactory.class, props); } /** * Sets the default SaslServerFactory to use. * This method sets fac to be the default factory. * It can only be called with a non-null value once per VM. * If a factory has been set already, this method throws * IllegalStateException. * * @param fac The possibly null factory to set. If null, doesn't do anything. * @exception IllegalStateException If factory already set. * @exception SecurityException If a security manager exists and * the caller does not have permission to * get the security manager or set a factory. */ /* On the Java 2 platform, * the required permissions are * java.lang.RuntimePermission("getSecurityManager"), * java.lang.RuntimePermission("setFactory"). */ public static void setSaslServerFactory(SaslServerFactory fac) { if (serverFactory != null) { throw new IllegalStateException ( "SaslServerFactory already defined"); } SecurityManager security = System.getSecurityManager(); if (security != null) { security.checkSetFactory(); } serverFactory = fac; } }