Sasl.java revision 0
0N/A * Copyright 1999-2006 Sun Microsystems, Inc. All Rights Reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 0N/A * published by the Free Software Foundation. Sun designates this 0N/A * particular file as subject to the "Classpath" exception as provided 0N/A * by Sun in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 0N/A * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, 0N/A * CA 95054 USA or visit www.sun.com if you need additional information or 0N/A * have any questions. 0N/A * A static class for creating SASL clients and servers. 0N/A * This class defines the policy of how to locate, load, and instantiate 0N/A * SASL clients and servers. 0N/A * For example, an application or library gets a SASL client by doing 0N/A * SaslClient sc = Sasl.createSaslClient(mechanisms, 0N/A * authorizationId, protocol, serverName, props, callbackHandler); 0N/A *</pre></blockquote> 0N/A * It can then proceed to use the instance to create an authentication connection. 0N/A * Similarly, a server gets a SASL server by using code that looks as follows: 0N/A * SaslServer ss = Sasl.createSaslServer(mechanism, 0N/A * protocol, serverName, props, callbackHandler); 0N/A *</pre></blockquote> 0N/A * @author Rosanna Lee 0N/A * @author Rob Weltman 0N/A // Cannot create one of these 0N/A * The name of a property that specifies the quality-of-protection to use. 0N/A * The property contains a comma-separated, ordered list 0N/A * of quality-of-protection values that the 0N/A * client or server is willing to support. A qop value is one of 0N/A * <li><tt>"auth"</tt> - authentication only</li> 0N/A * <li><tt>"auth-int"</tt> - authentication plus integrity protection</li> 0N/A * <li><tt>"auth-conf"</tt> - authentication plus integrity and confidentiality 0N/A * The order of the list specifies the preference order of the client or 0N/A * server. If this property is absent, the default qop is <tt>"auth"</tt>. 0N/A * The value of this constant is <tt>"javax.security.sasl.qop"</tt>. 0N/A * The name of a property that specifies the cipher strength to use. 0N/A * The property contains a comma-separated, ordered list 0N/A * of cipher strength values that 0N/A * the client or server is willing to support. A strength value is one of 0N/A * <li><tt>"low"</tt></li> 0N/A * <li><tt>"medium"</tt></li> 0N/A * <li><tt>"high"</tt></li> 0N/A * The order of the list specifies the preference order of the client or 0N/A * server. An implementation should allow configuration of the meaning 0N/A * of these values. An application may use the Java Cryptography 0N/A * Extension (JCE) with JCE-aware mechanisms to control the selection of 0N/A * cipher suites that match the strength values. 0N/A * If this property is absent, the default strength is 0N/A * <tt>"high,medium,low"</tt>. 0N/A * The value of this constant is <tt>"javax.security.sasl.strength"</tt>. 0N/A * The name of a property that specifies whether the 0N/A * server must authenticate to the client. The property contains 0N/A * <tt>"true"</tt> if the server must 0N/A * authenticate the to client; <tt>"false"</tt> otherwise. 0N/A * The default is <tt>"false"</tt>. 0N/A * <br>The value of this constant is 0N/A * <tt>"javax.security.sasl.server.authentication"</tt>. 0N/A "javax.security.sasl.server.authentication";
0N/A * The name of a property that specifies the maximum size of the receive 0N/A * buffer in bytes of <tt>SaslClient</tt>/<tt>SaslServer</tt>. 0N/A * The property contains the string representation of an integer. 0N/A * <br>If this property is absent, the default size 0N/A * is defined by the mechanism. 0N/A * <br>The value of this constant is <tt>"javax.security.sasl.maxbuffer"</tt>. 0N/A * The name of a property that specifies the maximum size of the raw send 0N/A * buffer in bytes of <tt>SaslClient</tt>/<tt>SaslServer</tt>. 0N/A * The property contains the string representation of an integer. 0N/A * The value of this property is negotiated between the client and server 0N/A * during the authentication exchange. 0N/A * <br>The value of this constant is <tt>"javax.security.sasl.rawsendsize"</tt>. 0N/A * The name of a property that specifies whether to reuse previously 0N/A * authenticated session information. The property contains "true" if the 0N/A * mechanism implementation may attempt to reuse previously authenticated 0N/A * session information; it contains "false" if the implementation must 0N/A * not reuse previously authenticated session information. A setting of 0N/A * "true" serves only as a hint: it does not necessarily entail actual 0N/A * reuse because reuse might not be possible due to a number of reasons, 0N/A * including, but not limited to, lack of mechanism support for reuse, 0N/A * expiration of reusable information, and the peer's refusal to support 0N/A * The property's default value is "false". The value of this constant 0N/A * is "javax.security.sasl.reuse". 0N/A * Note that all other parameters and properties required to create a 0N/A * this property has been supplied. That is, you cannot supply any less 0N/A * information in anticipation of reuse. 0N/A * Mechanism implementations that support reuse might allow customization 0N/A * of its implementation, for factors such as cache size, timeouts, and 0N/A * criteria for reuseability. Such customizations are 0N/A * implementation-dependent. 0N/A * The name of a property that specifies 0N/A * whether mechanisms susceptible to simple plain passive attacks (e.g., 0N/A * "PLAIN") are not permitted. The property 0N/A * contains <tt>"true"</tt> if such mechanisms are not permitted; 0N/A * <tt>"false"</tt> if such mechanisms are permitted. 0N/A * The default is <tt>"false"</tt>. 0N/A * <br>The value of this constant is 0N/A * <tt>"javax.security.sasl.policy.noplaintext"</tt>. 0N/A "javax.security.sasl.policy.noplaintext";
0N/A * The name of a property that specifies whether 0N/A * mechanisms susceptible to active (non-dictionary) attacks 0N/A * are not permitted. 0N/A * The property contains <tt>"true"</tt> 0N/A * if mechanisms susceptible to active attacks 0N/A * are not permitted; <tt>"false"</tt> if such mechanisms are permitted. 0N/A * The default is <tt>"false"</tt>. 0N/A * <br>The value of this constant is 0N/A * <tt>"javax.security.sasl.policy.noactive"</tt>. 0N/A "javax.security.sasl.policy.noactive";
0N/A * The name of a property that specifies whether 0N/A * mechanisms susceptible to passive dictionary attacks are not permitted. 0N/A * The property contains <tt>"true"</tt> 0N/A * if mechanisms susceptible to dictionary attacks are not permitted; 0N/A * <tt>"false"</tt> if such mechanisms are permitted. 0N/A * The default is <tt>"false"</tt>. 0N/A * The value of this constant is 0N/A * <tt>"javax.security.sasl.policy.nodictionary"</tt>. 0N/A "javax.security.sasl.policy.nodictionary";
0N/A * The name of a property that specifies whether mechanisms that accept 0N/A * anonymous login are not permitted. The property contains <tt>"true"</tt> 0N/A * if mechanisms that accept anonymous login are not permitted; 0N/A * if such mechanisms are permitted. The default is <tt>"false"</tt>. 0N/A * The value of this constant is 0N/A * <tt>"javax.security.sasl.policy.noanonymous"</tt>. 0N/A "javax.security.sasl.policy.noanonymous";
0N/A * The name of a property that specifies whether mechanisms that implement 0N/A * forward secrecy between sessions are required. Forward secrecy 0N/A * means that breaking into one session will not automatically 0N/A * provide information for breaking into future sessions. 0N/A * contains <tt>"true"</tt> if mechanisms that implement forward secrecy 0N/A * between sessions are required; <tt>"false"</tt> if such mechanisms 0N/A * are not required. The default is <tt>"false"</tt>. 0N/A * The value of this constant is 0N/A * <tt>"javax.security.sasl.policy.forward"</tt>. 0N/A "javax.security.sasl.policy.forward";
0N/A * The name of a property that specifies whether 0N/A * mechanisms that pass client credentials are required. The property 0N/A * contains <tt>"true"</tt> if mechanisms that pass 0N/A * client credentials are required; <tt>"false"</tt> 0N/A * if such mechanisms are not required. The default is <tt>"false"</tt>. 0N/A * The value of this constant is 0N/A * <tt>"javax.security.sasl.policy.credentials"</tt>. 0N/A "javax.security.sasl.policy.credentials";
0N/A * The name of a property that specifies the credentials to use. 0N/A * The property contains a mechanism-specific Java credential object. 0N/A * Mechanism implementations may examine the value of this property 0N/A * to determine whether it is a class that they support. 0N/A * The property may be used to supply credentials to a mechanism that 0N/A * supports delegated authentication. 0N/A * The value of this constant is 0N/A * <tt>"javax.security.sasl.credentials"</tt>. 0N/A * Creates a <tt>SaslClient</tt> using the parameters supplied. 0N/A * This method uses the 0N/A * "Java Cryptography Architecture API Specification & Reference", for 0N/A * locating and selecting a <tt>SaslClient</tt> implementation. 0N/A * obtains an ordered list of <tt>SaslClientFactory</tt> instances from 0N/A * the registered security providers for the "SaslClientFactory" service 0N/A * and the specified SASL mechanism(s). It then invokes 0N/A * <tt>createSaslClient()</tt> on each factory instance on the list 0N/A * until one produces a non-null <tt>SaslClient</tt> instance. It returns 0N/A * the non-null <tt>SaslClient</tt> instance, or null if the search fails 0N/A * to produce a non-null <tt>SaslClient</tt> instance. 0N/A * A security provider for SaslClientFactory registers with the 0N/A * JCA Security Provider Framework keys of the form <br> 0N/A * <tt>SaslClientFactory.<em>mechanism_name</em></tt> 0N/A * and values that are class names of implementations of 0N/A * <tt>javax.security.sasl.SaslClientFactory</tt>. 0N/A * For example, a provider that contains a factory class, 0N/A * <tt>com.wiz.sasl.digest.ClientFactory</tt>, that supports the 0N/A * "DIGEST-MD5" mechanism would register the following entry with the JCA: 0N/A * <tt>SaslClientFactory.DIGEST-MD5 com.wiz.sasl.digest.ClientFactory</tt> 0N/A * "Java Cryptography Architecture API Specification & Reference" 0N/A * for information about how to install and configure security service 0N/A * @param mechanisms The non-null list of mechanism names to try. Each is the 0N/A * IANA-registered name of a SASL mechanism. (e.g. "GSSAPI", "CRAM-MD5"). 0N/A * @param authorizationId The possibly null protocol-dependent 0N/A * identification to be used for authorization. 0N/A * If null or empty, the server derives an authorization 0N/A * ID from the client's authentication credentials. 0N/A * When the SASL authentication completes successfully, 0N/A * the specified entity is granted access. 0N/A * @param protocol The non-null string name of the protocol for which 0N/A * the authentication is being performed (e.g., "ldap"). 0N/A * @param serverName The non-null fully-qualified host name of the server 0N/A * to authenticate to. 0N/A * @param props The possibly null set of properties used to 0N/A * select the SASL mechanism and to configure the authentication 0N/A * exchange of the selected mechanism. 0N/A * For example, if <tt>props</tt> contains the 0N/A * <code>Sasl.POLICY_NOPLAINTEXT</code> property with the value 0N/A * <tt>"true"</tt>, then the selected 0N/A * SASL mechanism must not be susceptible to simple plain passive attacks. 0N/A * In addition to the standard properties declared in this class, 0N/A * other, possibly mechanism-specific, properties can be included. 0N/A * Properties not relevant to the selected mechanism are ignored, 0N/A * including any map entries with non-String keys. 0N/A * @param cbh The possibly null callback handler to used by the SASL 0N/A * to complete the authentication. For example, a SASL mechanism might 0N/A * require the authentication ID, password and realm from the caller. 0N/A * The authentication ID is requested by using a <tt>NameCallback</tt>. 0N/A * The password is requested by using a <tt>PasswordCallback</tt>. 0N/A * The realm is requested by using a <tt>RealmChoiceCallback</tt> if there is a list 0N/A * of realms to choose from, and by using a <tt>RealmCallback</tt> if 0N/A * the realm must be entered. 0N/A *@return A possibly null <tt>SaslClient</tt> created using the parameters 0N/A * supplied. If null, cannot find a <tt>SaslClientFactory</tt> 0N/A * that will produce one. 0N/A *@exception SaslException If cannot create a <tt>SaslClient</tt> because 0N/A "Mechanism name cannot be null");
0N/A * Load the implementation class with the same class loader 0N/A * that was used to load the provider. 0N/A * In order to get the class loader of a class, the 0N/A * caller's class loader must be the same as or an ancestor of 0N/A * the class loader being returned. Otherwise, the caller must 0N/A * have "getClassLoader" permission, or a SecurityException 0N/A * Creates a <tt>SaslServer</tt> for the specified mechanism. 0N/A * This method uses the 0N/A * "Java Cryptography Architecture API Specification & Reference", for 0N/A * locating and selecting a <tt>SaslServer</tt> implementation. 0N/A * obtains an ordered list of <tt>SaslServerFactory</tt> instances from 0N/A * the registered security providers for the "SaslServerFactory" service 0N/A * and the specified mechanism. It then invokes 0N/A * <tt>createSaslServer()</tt> on each factory instance on the list 0N/A * until one produces a non-null <tt>SaslServer</tt> instance. It returns 0N/A * the non-null <tt>SaslServer</tt> instance, or null if the search fails 0N/A * to produce a non-null <tt>SaslServer</tt> instance. 0N/A * A security provider for SaslServerFactory registers with the 0N/A * JCA Security Provider Framework keys of the form <br> 0N/A * <tt>SaslServerFactory.<em>mechanism_name</em></tt> 0N/A * and values that are class names of implementations of 0N/A * <tt>javax.security.sasl.SaslServerFactory</tt>. 0N/A * For example, a provider that contains a factory class, 0N/A * <tt>com.wiz.sasl.digest.ServerFactory</tt>, that supports the 0N/A * "DIGEST-MD5" mechanism would register the following entry with the JCA: 0N/A * <tt>SaslServerFactory.DIGEST-MD5 com.wiz.sasl.digest.ServerFactory</tt> 0N/A * "Java Cryptography Architecture API Specification & Reference" 0N/A * for information about how to install and configure security 0N/A * service providers. 0N/A * @param mechanism The non-null mechanism name. It must be an 0N/A * IANA-registered name of a SASL mechanism. (e.g. "GSSAPI", "CRAM-MD5"). 0N/A * @param protocol The non-null string name of the protocol for which 0N/A * the authentication is being performed (e.g., "ldap"). 0N/A * @param serverName The non-null fully qualified host name of the server. 0N/A * @param props The possibly null set of properties used to 0N/A * select the SASL mechanism and to configure the authentication 0N/A * exchange of the selected mechanism. 0N/A * For example, if <tt>props</tt> contains the 0N/A * <code>Sasl.POLICY_NOPLAINTEXT</code> property with the value 0N/A * <tt>"true"</tt>, then the selected 0N/A * SASL mechanism must not be susceptible to simple plain passive attacks. 0N/A * In addition to the standard properties declared in this class, 0N/A * other, possibly mechanism-specific, properties can be included. 0N/A * Properties not relevant to the selected mechanism are ignored, 0N/A * including any map entries with non-String keys. 0N/A * @param cbh The possibly null callback handler to used by the SASL 0N/A * to complete the authentication. For example, a SASL mechanism might 0N/A * require the authentication ID, password and realm from the caller. 0N/A * The authentication ID is requested by using a <tt>NameCallback</tt>. 0N/A * The password is requested by using a <tt>PasswordCallback</tt>. 0N/A * The realm is requested by using a <tt>RealmChoiceCallback</tt> if there is a list 0N/A * of realms to choose from, and by using a <tt>RealmCallback</tt> if 0N/A * the realm must be entered. 0N/A *@return A possibly null <tt>SaslServer</tt> created using the parameters 0N/A * supplied. If null, cannot find a <tt>SaslServerFactory</tt> 0N/A * that will produce one. 0N/A *@exception SaslException If cannot create a <tt>SaslServer</tt> because 0N/A * Gets an enumeration of known factories for producing <tt>SaslClient</tt>. 0N/A * This method uses the same algorithm for locating factories as 0N/A * <tt>createSaslClient()</tt>. 0N/A * @return A non-null enumeration of known factories for producing 0N/A * <tt>SaslClient</tt>. 0N/A * @see #createSaslClient 0N/A * Gets an enumeration of known factories for producing <tt>SaslServer</tt>. 0N/A * This method uses the same algorithm for locating factories as 0N/A * <tt>createSaslServer()</tt>. 0N/A * @return A non-null enumeration of known factories for producing 0N/A * <tt>SaslServer</tt>. 0N/A * @see #createSaslServer 0N/A // Check the keys for each provider. 0N/A // We should skip the currentKey if it contains a 0N/A // whitespace. The reason is: such an entry in the 0N/A // provider property contains attributes for the 0N/A // implementation of an algorithm. We are only interested 0N/A // in entries which lead to the implementation