archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-27 14:54:52 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8187443: Forest Consolidation: Move files to unified layout

Browse source 
Reviewed-by: darcy, ihse
This commit is contained in:
Erik Joelsson 2017-09-12 19:03:39 +02:00
parent 270fe13182
commit 3789983e89
56923 changed files with 3 additions and 15727 deletions
Download patch file Download diff file Expand all files Collapse all files

83
src/java.security.sasl/share/classes/javax/security/sasl/AuthenticationException.java Normal file
View file

@ -0,0 +1,83 @@
/*
* Copyright (c) 2003, 2013, 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;
/**
* This exception is thrown by a SASL mechanism implementation
* to indicate that the SASL
* exchange has failed due to reasons related to authentication, such as
* an invalid identity, passphrase, or key.
* <p>
* Note that the lack of an AuthenticationException does not mean that
* the failure was not due to an authentication error. A SASL mechanism
* implementation might throw the more general SaslException instead of
* AuthenticationException if it is unable to determine the nature
* of the failure, or if does not want to disclose the nature of
* the failure, for example, due to security reasons.
*
* @since 1.5
*
* @author Rosanna Lee
* @author Rob Weltman
*/
public class AuthenticationException extends SaslException {
/**
* Constructs a new instance of {@code AuthenticationException}.
* The root exception and the detailed message are null.
*/
public AuthenticationException () {
super();
}
/**
* Constructs a new instance of {@code AuthenticationException}
* with a detailed message.
* The root exception is null.
* @param detail A possibly null string containing details of the exception.
*
* @see java.lang.Throwable#getMessage
*/
public AuthenticationException (String detail) {
super(detail);
}
/**
* Constructs a new instance of {@code AuthenticationException} with a detailed message
* and a root exception.
*
* @param detail A possibly null string containing details of the exception.
* @param ex A possibly null root exception that caused this exception.
*
* @see java.lang.Throwable#getMessage
* @see #getCause
*/
public AuthenticationException (String detail, Throwable ex) {
super(detail, ex);
}
/** Use serialVersionUID from JSR 28 RI for interoperability */
private static final long serialVersionUID = -3579708765071815007L;
}

145
src/java.security.sasl/share/classes/javax/security/sasl/AuthorizeCallback.java Normal file
View file

@ -0,0 +1,145 @@
/*
* Copyright (c) 2000, 2013, 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.Callback;
/**
* This callback is used by {@code SaslServer} to determine whether
* one entity (identified by an authenticated authentication id)
* can act on
* behalf of another entity (identified by an authorization id).
*
* @since 1.5
*
* @author Rosanna Lee
* @author Rob Weltman
*/
public class AuthorizeCallback implements Callback, java.io.Serializable {
/**
* The (authenticated) authentication id to check.
* @serial
*/
private String authenticationID;
/**
* The authorization id to check.
* @serial
*/
private String authorizationID;
/**
* The id of the authorized entity. If null, the id of
* the authorized entity is authorizationID.
* @serial
*/
private String authorizedID;
/**
* A flag indicating whether the authentication id is allowed to
* act on behalf of the authorization id.
* @serial
*/
private boolean authorized;
/**
* Constructs an instance of {@code AuthorizeCallback}.
*
* @param authnID The (authenticated) authentication id.
* @param authzID The authorization id.
*/
public AuthorizeCallback(String authnID, String authzID) {
authenticationID = authnID;
authorizationID = authzID;
}
/**
* Returns the authentication id to check.
* @return The authentication id to check.
*/
public String getAuthenticationID() {
return authenticationID;
}
/**
* Returns the authorization id to check.
* @return The authentication id to check.
*/
public String getAuthorizationID() {
return authorizationID;
}
/**
* Determines whether the authentication id is allowed to
* act on behalf of the authorization id.
*
* @return {@code true} if authorization is allowed; {@code false} otherwise
* @see #setAuthorized(boolean)
* @see #getAuthorizedID()
*/
public boolean isAuthorized() {
return authorized;
}
/**
* Sets whether the authorization is allowed.
* @param ok {@code true} if authorization is allowed; {@code false} otherwise
* @see #isAuthorized
* @see #setAuthorizedID(java.lang.String)
*/
public void setAuthorized(boolean ok) {
authorized = ok;
}
/**
* Returns the id of the authorized user.
* @return The id of the authorized user. {@code null} means the
* authorization failed.
* @see #setAuthorized(boolean)
* @see #setAuthorizedID(java.lang.String)
*/
public String getAuthorizedID() {
if (!authorized) {
return null;
}
return (authorizedID == null) ? authorizationID : authorizedID;
}
/**
* Sets the id of the authorized entity. Called by handler only when the id
* is different from getAuthorizationID(). For example, the id
* might need to be canonicalized for the environment in which it
* will be used.
* @param id The id of the authorized user.
* @see #setAuthorized(boolean)
* @see #getAuthorizedID
*/
public void setAuthorizedID(String id) {
authorizedID = id;
}
private static final long serialVersionUID = -2353344186490470805L;
}

67
src/java.security.sasl/share/classes/javax/security/sasl/RealmCallback.java Normal file
View file

@ -0,0 +1,67 @@
/*
* Copyright (c) 2000, 2013, 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.TextInputCallback;
/**
* This callback is used by {@code SaslClient} and {@code SaslServer}
* to retrieve realm information.
*
* @since 1.5
*
* @author Rosanna Lee
* @author Rob Weltman
*/
public class RealmCallback extends TextInputCallback {
/**
* Constructs a {@code RealmCallback} with a prompt.
*
* @param prompt The non-null prompt to use to request the realm information.
* @throws IllegalArgumentException If {@code prompt} is null or
* the empty string.
*/
public RealmCallback(String prompt) {
super(prompt);
}
/**
* Constructs a {@code RealmCallback} with a prompt and default
* realm information.
*
* @param prompt The non-null prompt to use to request the realm information.
* @param defaultRealmInfo The non-null default realm information to use.
* @throws IllegalArgumentException If {@code prompt} is null or
* the empty string,
* or if {@code defaultRealm} is empty or null.
*/
public RealmCallback(String prompt, String defaultRealmInfo) {
super(prompt, defaultRealmInfo);
}
private static final long serialVersionUID = -4342673378785456908L;
}

62
src/java.security.sasl/share/classes/javax/security/sasl/RealmChoiceCallback.java Normal file
View file

@ -0,0 +1,62 @@
/*
* Copyright (c) 2000, 2013, 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.ChoiceCallback;
/**
* This callback is used by {@code SaslClient} and {@code SaslServer}
* to obtain a realm given a list of realm choices.
*
* @since 1.5
*
* @author Rosanna Lee
* @author Rob Weltman
*/
public class RealmChoiceCallback extends ChoiceCallback {
/**
* Constructs a {@code RealmChoiceCallback} with a prompt, a list of
* choices and a default choice.
*
* @param prompt the non-null prompt to use to request the realm.
* @param choices the non-null list of realms to choose from.
* @param defaultChoice the choice to be used as the default choice
* when the list of choices is displayed. It is an index into
* the {@code choices} array.
* @param multiple true if multiple choices allowed; false otherwise
* @throws IllegalArgumentException If {@code prompt} is null or the empty string,
* if {@code choices} has a length of 0, if any element from
* {@code choices} is null or empty, or if {@code defaultChoice}
* does not fall within the array boundary of {@code choices}
*/
public RealmChoiceCallback(String prompt, String[]choices,
int defaultChoice, boolean multiple) {
super(prompt, choices, defaultChoice, multiple);
}
private static final long serialVersionUID = -8588141348846281332L;
}

619
src/java.security.sasl/share/classes/javax/security/sasl/Sasl.java Normal file
View file

@ -0,0 +1,619 @@
/*
* Copyright (c) 1999, 2017, 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.util.Enumeration;
import java.util.Iterator;
import java.util.Map;
import java.util.Set;
import java.util.HashSet;
import java.util.Collections;
import java.security.InvalidParameterException;
import java.security.NoSuchAlgorithmException;
import java.security.Provider;
import java.security.Provider.Service;
import java.security.Security;
/**
* 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 {
// 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
* {@extLink security_guide_jca JCA Security Provider Framework},
* described in the
* "Java Cryptography Architecture (JCA) Reference Guide", 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 &amp; Reference"
* for information about how to install and configure security service
* providers.
*
* @implNote
* The JDK Reference Implementation additionally uses the
* {@code jdk.security.provider.preferred}
* {@link Security#getProperty(String) Security} property to determine
* the preferred provider order for the specified algorithm. This
* may be different than the order of providers returned by
* {@link Security#getProviders() Security.getProviders()}.
*
* @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;
Service service;
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;
}
String type = "SaslClientFactory";
Provider[] provs = Security.getProviders(type + "." + mechName);
if (provs != null) {
for (Provider p : provs) {
service = p.getService(type, mechName);
if (service == null) {
// no such service exists
continue;
}
fac = (SaslClientFactory) loadFactory(service);
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(Service service)
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.
*/
return service.newInstance(null);
} catch (InvalidParameterException | NoSuchAlgorithmException e) {
throw new SaslException("Cannot instantiate service " + service, e);
}
}
/**
* Creates a {@code SaslServer} for the specified mechanism.
*
* This method uses the
* {@extLink security_guide_jca JCA Security Provider Framework},
* described in the
* "Java Cryptography Architecture (JCA) Reference Guide", for
* locating and selecting a {@code SaslClient} 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 &amp; Reference"
* for information about how to install and configure security
* service providers.
*
* @implNote
* The JDK Reference Implementation additionally uses the
* {@code jdk.security.provider.preferred}
* {@link Security#getProperty(String) Security} property to determine
* the preferred provider order for the specified algorithm. This
* may be different than the order of providers returned by
* {@link Security#getProviders() Security.getProviders()}.
*
* @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;
Service service;
if (mechanism == null) {
throw new NullPointerException("Mechanism name cannot be null");
} else if (mechanism.length() == 0) {
return null;
}
String type = "SaslServerFactory";
Provider[] provs = Security.getProviders(type + "." + mechanism);
if (provs != null) {
for (Provider p : provs) {
service = p.getService(type, mechanism);
if (service == null) {
throw new SaslException("Provider does not support " +
mechanism + " " + type);
}
fac = (SaslServerFactory) loadFactory(service);
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[] provs = Security.getProviders();
Object fac;
for (Provider p : provs) {
Iterator<Service> iter = p.getServices().iterator();
while (iter.hasNext()) {
Service s = iter.next();
if (s.getType().equals(serviceName)) {
try {
fac = loadFactory(s);
if (fac != null) {
result.add(fac);
}
} catch (Exception ignore) {
}
}
}
}
return Collections.unmodifiableSet(result);
}
}

229
src/java.security.sasl/share/classes/javax/security/sasl/SaslClient.java Normal file
View file

@ -0,0 +1,229 @@
/*
* Copyright (c) 1999, 2013, 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;
/**
* Performs SASL authentication as a client.
*<p>
* A protocol library such as one for LDAP gets an instance of this
* class in order to perform authentication defined by a specific SASL
* mechanism. Invoking methods on the {@code SaslClient} instance
* process challenges and create responses according to the SASL
* mechanism implemented by the {@code SaslClient}.
* As the authentication proceeds, the instance
* encapsulates the state of a SASL client's authentication exchange.
*<p>
* Here's an example of how an LDAP library might use a {@code SaslClient}.
* It first gets an instance of a {@code SaslClient}:
*<blockquote><pre>{@code
* SaslClient sc = Sasl.createSaslClient(mechanisms,
* authorizationId, protocol, serverName, props, callbackHandler);
*}</pre></blockquote>
* It can then proceed to use the client for authentication.
* For example, an LDAP library might use the client as follows:
*<blockquote><pre>{@code
* // Get initial response and send to server
* byte[] response = (sc.hasInitialResponse() ? sc.evaluateChallenge(new byte[0]) :
* null);
* LdapResult res = ldap.sendBindRequest(dn, sc.getName(), response);
* while (!sc.isComplete() &&
* (res.status == SASL_BIND_IN_PROGRESS || res.status == SUCCESS)) {
* response = sc.evaluateChallenge(res.getBytes());
* if (res.status == SUCCESS) {
* // we're done; don't expect to send another BIND
* if (response != null) {
* throw new SaslException(
* "Protocol error: attempting to send response after completion");
* }
* break;
* }
* res = ldap.sendBindRequest(dn, sc.getName(), response);
* }
* if (sc.isComplete() && res.status == SUCCESS) {
* String qop = (String) sc.getNegotiatedProperty(Sasl.QOP);
* if (qop != null
* && (qop.equalsIgnoreCase("auth-int")
* || qop.equalsIgnoreCase("auth-conf"))) {
*
* // Use SaslClient.wrap() and SaslClient.unwrap() for future
* // communication with server
* ldap.in = new SecureInputStream(sc, ldap.in);
* ldap.out = new SecureOutputStream(sc, ldap.out);
* }
* }
*}</pre></blockquote>
*
* If the mechanism has an initial response, the library invokes
* {@code evaluateChallenge()} with an empty
* challenge and to get initial response.
* Protocols such as IMAP4, which do not include an initial response with
* their first authentication command to the server, initiates the
* authentication without first calling {@code hasInitialResponse()}
* or {@code evaluateChallenge()}.
* When the server responds to the command, it sends an initial challenge.
* For a SASL mechanism in which the client sends data first, the server should
* have issued a challenge with no data. This will then result in a call
* (on the client) to {@code evaluateChallenge()} with an empty challenge.
*
* @since 1.5
*
* @see Sasl
* @see SaslClientFactory
*
* @author Rosanna Lee
* @author Rob Weltman
*/
public abstract interface SaslClient {
/**
* Returns the IANA-registered mechanism name of this SASL client.
* (e.g. "CRAM-MD5", "GSSAPI").
* @return A non-null string representing the IANA-registered mechanism name.
*/
public abstract String getMechanismName();
/**
* Determines whether this mechanism has an optional initial response.
* If true, caller should call {@code evaluateChallenge()} with an
* empty array to get the initial response.
*
* @return true if this mechanism has an initial response.
*/
public abstract boolean hasInitialResponse();
/**
* Evaluates the challenge data and generates a response.
* If a challenge is received from the server during the authentication
* process, this method is called to prepare an appropriate next
* response to submit to the server.
*
* @param challenge The non-null challenge sent from the server.
* The challenge array may have zero length.
*
* @return The possibly null response to send to the server.
* It is null if the challenge accompanied a "SUCCESS" status and the challenge
* only contains data for the client to update its state and no response
* needs to be sent to the server. The response is a zero-length byte
* array if the client is to send a response with no data.
* @exception SaslException If an error occurred while processing
* the challenge or generating a response.
*/
public abstract byte[] evaluateChallenge(byte[] challenge)
throws SaslException;
/**
* Determines whether the authentication exchange has completed.
* This method may be called at any time, but typically, it
* will not be called until the caller has received indication
* from the server
* (in a protocol-specific manner) that the exchange has completed.
*
* @return true if the authentication exchange has completed; false otherwise.
*/
public abstract boolean isComplete();
/**
* Unwraps a byte array received from the server.
* This method can be called only after the authentication exchange has
* completed (i.e., when {@code isComplete()} returns true) and only if
* the authentication exchange has negotiated integrity and/or privacy
* as the quality of protection; otherwise, an
* {@code IllegalStateException} is thrown.
*<p>
* {@code incoming} is the contents of the SASL buffer as defined in RFC 2222
* without the leading four octet field that represents the length.
* {@code offset} and {@code len} specify the portion of {@code incoming}
* to use.
*
* @param incoming A non-null byte array containing the encoded bytes
* from the server.
* @param offset The starting position at {@code incoming} of the bytes to use.
* @param len The number of bytes from {@code incoming} to use.
* @return A non-null byte array containing the decoded bytes.
* @exception SaslException if {@code incoming} cannot be successfully
* unwrapped.
* @exception IllegalStateException if the authentication exchange has
* not completed, or if the negotiated quality of protection
* has neither integrity nor privacy.
*/
public abstract byte[] unwrap(byte[] incoming, int offset, int len)
throws SaslException;
/**
* Wraps a byte array to be sent to the server.
* This method can be called only after the authentication exchange has
* completed (i.e., when {@code isComplete()} returns true) and only if
* the authentication exchange has negotiated integrity and/or privacy
* as the quality of protection; otherwise, an
* {@code IllegalStateException} is thrown.
*<p>
* The result of this method will make up the contents of the SASL buffer
* as defined in RFC 2222 without the leading four octet field that
* represents the length.
* {@code offset} and {@code len} specify the portion of {@code outgoing}
* to use.
*
* @param outgoing A non-null byte array containing the bytes to encode.
* @param offset The starting position at {@code outgoing} of the bytes to use.
* @param len The number of bytes from {@code outgoing} to use.
* @return A non-null byte array containing the encoded bytes.
* @exception SaslException if {@code outgoing} cannot be successfully
* wrapped.
* @exception IllegalStateException if the authentication exchange has
* not completed, or if the negotiated quality of protection
* has neither integrity nor privacy.
*/
public abstract byte[] wrap(byte[] outgoing, int offset, int len)
throws SaslException;
/**
* Retrieves the negotiated property.
* This method can be called only after the authentication exchange has
* completed (i.e., when {@code isComplete()} returns true); otherwise, an
* {@code IllegalStateException} is thrown.
* <p>
* The {@link Sasl} class includes several well-known property names
* (For example, {@link Sasl#QOP}). A SASL provider can support other
* properties which are specific to the vendor and/or a mechanism.
*
* @param propName The non-null property name.
* @return The value of the negotiated property. If null, the property was
* not negotiated or is not applicable to this mechanism.
* @exception IllegalStateException if this authentication exchange
* has not completed
*/
public abstract Object getNegotiatedProperty(String propName);
/**
* Disposes of any system resources or security-sensitive information
* the SaslClient might be using. Invoking this method invalidates
* the SaslClient instance. This method is idempotent.
* @throws SaslException If a problem was encountered while disposing
* the resources.
*/
public abstract void dispose() throws SaslException;
}

112
src/java.security.sasl/share/classes/javax/security/sasl/SaslClientFactory.java Normal file
View file

@ -0,0 +1,112 @@
/*
* Copyright (c) 1999, 2013, 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 java.util.Map;
import javax.security.auth.callback.CallbackHandler;
/**
* An interface for creating instances of {@code SaslClient}.
* A class that implements this interface
* must be thread-safe and handle multiple simultaneous
* requests. It must also have a public constructor that accepts no
* argument.
*<p>
* This interface is not normally accessed directly by a client, which will use the
* {@code Sasl} static methods
* instead. However, a particular environment may provide and install a
* new or different {@code SaslClientFactory}.
*
* @since 1.5
*
* @see SaslClient
* @see Sasl
*
* @author Rosanna Lee
* @author Rob Weltman
*/
public abstract interface SaslClientFactory {
/**
* Creates a SaslClient using the parameters supplied.
*
* @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. See the {@code Sasl} class for a list of standard properties.
* 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, this factory cannot produce a {@code SaslClient}
* using the parameters supplied.
*@exception SaslException If cannot create a {@code SaslClient} because
* of an error.
*/
public abstract SaslClient createSaslClient(
String[] mechanisms,
String authorizationId,
String protocol,
String serverName,
Map<String,?> props,
CallbackHandler cbh) throws SaslException;
/**
* Returns an array of names of mechanisms that match the specified
* mechanism selection policies.
* @param props The possibly null set of properties used to specify the
* security policy of the SASL mechanisms. For example, if {@code props}
* contains the {@code Sasl.POLICY_NOPLAINTEXT} property with the value
* {@code "true"}, then the factory must not return any SASL mechanisms
* that are susceptible to simple plain passive attacks.
* See the {@code Sasl} class for a complete list of policy properties.
* Non-policy related properties, if present in {@code props}, are ignored,
* including any map entries with non-String keys.
* @return A non-null array containing a IANA-registered SASL mechanism names.
*/
public abstract String[] getMechanismNames(Map<String,?> props);
}

129
src/java.security.sasl/share/classes/javax/security/sasl/SaslException.java Normal file
View file

@ -0,0 +1,129 @@
/*
* Copyright (c) 1999, 2013, 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 java.io.IOException;
/**
* This class represents an error that has occurred when using SASL.
*
* @since 1.5
*
* @author Rosanna Lee
* @author Rob Weltman
*/
public class SaslException extends IOException {
/**
* The possibly null root cause exception.
* @serial
*/
// Required for serialization interoperability with JSR 28
private Throwable _exception;
/**
* Constructs a new instance of {@code SaslException}.
* The root exception and the detailed message are null.
*/
public SaslException () {
super();
}
/**
* Constructs a new instance of {@code SaslException} with a detailed message.
* The root exception is null.
* @param detail A possibly null string containing details of the exception.
*
* @see java.lang.Throwable#getMessage
*/
public SaslException (String detail) {
super(detail);
}
/**
* Constructs a new instance of {@code SaslException} with a detailed message
* and a root exception.
* For example, a SaslException might result from a problem with
* the callback handler, which might throw a NoSuchCallbackException if
* it does not support the requested callback, or throw an IOException
* if it had problems obtaining data for the callback. The
* SaslException's root exception would be then be the exception thrown
* by the callback handler.
*
* @param detail A possibly null string containing details of the exception.
* @param ex A possibly null root exception that caused this exception.
*
* @see java.lang.Throwable#getMessage
* @see #getCause
*/
public SaslException (String detail, Throwable ex) {
super(detail);
if (ex != null) {
initCause(ex);
}
}
/*
* Override Throwable.getCause() to ensure deserialized object from
* JSR 28 would return same value for getCause() (i.e., _exception).
*/
public Throwable getCause() {
return _exception;
}
/*
* Override Throwable.initCause() to match getCause() by updating
* _exception as well.
*/
public Throwable initCause(Throwable cause) {
super.initCause(cause);
_exception = cause;
return this;
}
/**
* Returns the string representation of this exception.
* The string representation contains
* this exception's class name, its detailed message, and if
* it has a root exception, the string representation of the root
* exception. This string representation
* is meant for debugging and not meant to be interpreted
* programmatically.
* @return The non-null string representation of this exception.
* @see java.lang.Throwable#getMessage
*/
// Override Throwable.toString() to conform to JSR 28
public String toString() {
String answer = super.toString();
if (_exception != null && _exception != this) {
answer += " [Caused by " + _exception.toString() + "]";
}
return answer;
}
/** Use serialVersionUID from JSR 28 RI for interoperability */
private static final long serialVersionUID = 4579784287983423626L;
}

220
src/java.security.sasl/share/classes/javax/security/sasl/SaslServer.java Normal file
View file

@ -0,0 +1,220 @@
/*
* Copyright (c) 2000, 2013, 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;
/**
* Performs SASL authentication as a server.
*<p>
* A server such an LDAP server gets an instance of this
* class in order to perform authentication defined by a specific SASL
* mechanism. Invoking methods on the {@code SaslServer} instance
* generates challenges according to the SASL
* mechanism implemented by the {@code SaslServer}.
* As the authentication proceeds, the instance
* encapsulates the state of a SASL server's authentication exchange.
*<p>
* Here's an example of how an LDAP server might use a {@code SaslServer}.
* It first gets an instance of a {@code SaslServer} for the SASL mechanism
* requested by the client:
*<blockquote><pre>
* SaslServer ss = Sasl.createSaslServer(mechanism,
* "ldap", myFQDN, props, callbackHandler);
*</pre></blockquote>
* It can then proceed to use the server for authentication.
* For example, suppose the LDAP server received an LDAP BIND request
* containing the name of the SASL mechanism and an (optional) initial
* response. It then might use the server as follows:
*<blockquote><pre>{@code
* while (!ss.isComplete()) {
* try {
* byte[] challenge = ss.evaluateResponse(response);
* if (ss.isComplete()) {
* status = ldap.sendBindResponse(mechanism, challenge, SUCCESS);
* } else {
* status = ldap.sendBindResponse(mechanism, challenge,
SASL_BIND_IN_PROGRESS);
* response = ldap.readBindRequest();
* }
* } catch (SaslException e) {
* status = ldap.sendErrorResponse(e);
* break;
* }
* }
* if (ss.isComplete() && status == SUCCESS) {
* String qop = (String) sc.getNegotiatedProperty(Sasl.QOP);
* if (qop != null
* && (qop.equalsIgnoreCase("auth-int")
* || qop.equalsIgnoreCase("auth-conf"))) {
*
* // Use SaslServer.wrap() and SaslServer.unwrap() for future
* // communication with client
* ldap.in = new SecureInputStream(ss, ldap.in);
* ldap.out = new SecureOutputStream(ss, ldap.out);
* }
* }
*}</pre></blockquote>
*
* @since 1.5
*
* @see Sasl
* @see SaslServerFactory
*
* @author Rosanna Lee
* @author Rob Weltman
*/
public abstract interface SaslServer {
/**
* Returns the IANA-registered mechanism name of this SASL server.
* (e.g. "CRAM-MD5", "GSSAPI").
* @return A non-null string representing the IANA-registered mechanism name.
*/
public abstract String getMechanismName();
/**
* Evaluates the response data and generates a challenge.
*
* If a response is received from the client during the authentication
* process, this method is called to prepare an appropriate next
* challenge to submit to the client. The challenge is null if the
* authentication has succeeded and no more challenge data is to be sent
* to the client. It is non-null if the authentication must be continued
* by sending a challenge to the client, or if the authentication has
* succeeded but challenge data needs to be processed by the client.
* {@code isComplete()} should be called
* after each call to {@code evaluateResponse()},to determine if any further
* response is needed from the client.
*
* @param response The non-null (but possibly empty) response sent
* by the client.
*
* @return The possibly null challenge to send to the client.
* It is null if the authentication has succeeded and there is
* no more challenge data to be sent to the client.
* @exception SaslException If an error occurred while processing
* the response or generating a challenge.
*/
public abstract byte[] evaluateResponse(byte[] response)
throws SaslException;
/**
* Determines whether the authentication exchange has completed.
* This method is typically called after each invocation of
* {@code evaluateResponse()} to determine whether the
* authentication has completed successfully or should be continued.
* @return true if the authentication exchange has completed; false otherwise.
*/
public abstract boolean isComplete();
/**
* Reports the authorization ID in effect for the client of this
* session.
* This method can only be called if isComplete() returns true.
* @return The authorization ID of the client.
* @exception IllegalStateException if this authentication session has not completed
*/
public String getAuthorizationID();
/**
* Unwraps a byte array received from the client.
* This method can be called only after the authentication exchange has
* completed (i.e., when {@code isComplete()} returns true) and only if
* the authentication exchange has negotiated integrity and/or privacy
* as the quality of protection; otherwise,
* an {@code IllegalStateException} is thrown.
*<p>
* {@code incoming} is the contents of the SASL buffer as defined in RFC 2222
* without the leading four octet field that represents the length.
* {@code offset} and {@code len} specify the portion of {@code incoming}
* to use.
*
* @param incoming A non-null byte array containing the encoded bytes
* from the client.
* @param offset The starting position at {@code incoming} of the bytes to use.
* @param len The number of bytes from {@code incoming} to use.
* @return A non-null byte array containing the decoded bytes.
* @exception SaslException if {@code incoming} cannot be successfully
* unwrapped.
* @exception IllegalStateException if the authentication exchange has
* not completed, or if the negotiated quality of protection
* has neither integrity nor privacy
*/
public abstract byte[] unwrap(byte[] incoming, int offset, int len)
throws SaslException;
/**
* Wraps a byte array to be sent to the client.
* This method can be called only after the authentication exchange has
* completed (i.e., when {@code isComplete()} returns true) and only if
* the authentication exchange has negotiated integrity and/or privacy
* as the quality of protection; otherwise, a {@code SaslException} is thrown.
*<p>
* The result of this method
* will make up the contents of the SASL buffer as defined in RFC 2222
* without the leading four octet field that represents the length.
* {@code offset} and {@code len} specify the portion of {@code outgoing}
* to use.
*
* @param outgoing A non-null byte array containing the bytes to encode.
* @param offset The starting position at {@code outgoing} of the bytes to use.
* @param len The number of bytes from {@code outgoing} to use.
* @return A non-null byte array containing the encoded bytes.
* @exception SaslException if {@code outgoing} cannot be successfully
* wrapped.
* @exception IllegalStateException if the authentication exchange has
* not completed, or if the negotiated quality of protection has
* neither integrity nor privacy.
*/
public abstract byte[] wrap(byte[] outgoing, int offset, int len)
throws SaslException;
/**
* Retrieves the negotiated property.
* This method can be called only after the authentication exchange has
* completed (i.e., when {@code isComplete()} returns true); otherwise, an
* {@code IllegalStateException} is thrown.
* <p>
* The {@link Sasl} class includes several well-known property names
* (For example, {@link Sasl#QOP}). A SASL provider can support other
* properties which are specific to the vendor and/or a mechanism.
*
* @param propName the property
* @return The value of the negotiated property. If null, the property was
* not negotiated or is not applicable to this mechanism.
* @exception IllegalStateException if this authentication exchange has not completed
*/
public abstract Object getNegotiatedProperty(String propName);
/**
* Disposes of any system resources or security-sensitive information
* the SaslServer might be using. Invoking this method invalidates
* the SaslServer instance. This method is idempotent.
* @throws SaslException If a problem was encountered while disposing
* the resources.
*/
public abstract void dispose() throws SaslException;
}

111
src/java.security.sasl/share/classes/javax/security/sasl/SaslServerFactory.java Normal file
View file

@ -0,0 +1,111 @@
/*
* Copyright (c) 2000, 2013, 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 java.util.Map;
import javax.security.auth.callback.CallbackHandler;
/**
* An interface for creating instances of {@code SaslServer}.
* A class that implements this interface
* must be thread-safe and handle multiple simultaneous
* requests. It must also have a public constructor that accepts no
* argument.
*<p>
* This interface is not normally accessed directly by a server, which will use the
* {@code Sasl} static methods
* instead. However, a particular environment may provide and install a
* new or different {@code SaslServerFactory}.
*
* @since 1.5
*
* @see SaslServer
* @see Sasl
*
* @author Rosanna Lee
* @author Rob Weltman
*/
public abstract interface SaslServerFactory {
/**
* Creates a {@code SaslServer} using the parameters supplied.
* It returns null
* if no {@code SaslServer} can be created using the parameters supplied.
* Throws {@code SaslException} if it cannot create a {@code SaslServer}
* because of an error.
*
* @param mechanism The non-null
* 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 to
* authenticate to, 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. See the {@code Sasl} class for a list of standard properties.
* 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, this factory cannot produce a {@code SaslServer}
* using the parameters supplied.
*@exception SaslException If cannot create a {@code SaslServer} because
* of an error.
*/
public abstract SaslServer createSaslServer(
String mechanism,
String protocol,
String serverName,
Map<String,?> props,
CallbackHandler cbh) throws SaslException;
/**
* Returns an array of names of mechanisms that match the specified
* mechanism selection policies.
* @param props The possibly null set of properties used to specify the
* security policy of the SASL mechanisms. For example, if {@code props}
* contains the {@code Sasl.POLICY_NOPLAINTEXT} property with the value
* {@code "true"}, then the factory must not return any SASL mechanisms
* that are susceptible to simple plain passive attacks.
* See the {@code Sasl} class for a complete list of policy properties.
* Non-policy related properties, if present in {@code props}, are ignored,
* including any map entries with non-String keys.
* @return A non-null array containing a IANA-registered SASL mechanism names.
*/
public abstract String[] getMechanismNames(Map<String,?> props);
}

103
src/java.security.sasl/share/classes/javax/security/sasl/package-info.java Normal file
View file

@ -0,0 +1,103 @@
/*
* Copyright (c) 1999, 2017, 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.
*/
/**
* Contains class and interfaces for supporting SASL.
*
* This package defines classes and interfaces for SASL mechanisms.
* It is used by developers to add authentication support for
* connection-based protocols that use SASL.
*
* <h3>SASL Overview</h3>
*
* Simple Authentication and Security Layer (SASL) specifies a
* challenge-response protocol in which data is exchanged between the
* client and the server for the purposes of
* authentication and (optional) establishment of a security layer on
* which to carry on subsequent communications. It is used with
* connection-based protocols such as LDAPv3 or IMAPv4. SASL is
* described in
* <A HREF="http://www.ietf.org/rfc/rfc2222.txt">RFC 2222</A>.
*
*
* There are various <em>mechanisms</em> defined for SASL.
* Each mechanism defines the data that must be exchanged between the
* client and server in order for the authentication to succeed.
* This data exchange required for a particular mechanism is referred to
* to as its <em>protocol profile</em>.
* The following are some examples of mechanisms that have been defined by
* the Internet standards community.
* <ul>
* <li>DIGEST-MD5 (<A HREF="http://www.ietf.org/rfc/rfc2831.txt">RFC 2831</a>).
* This mechanism defines how HTTP Digest Authentication can be used as a SASL
* mechanism.
* <li>Anonymous (<A HREF="http://www.ietf.org/rfc/rfc2245.txt">RFC 2245</a>).
* This mechanism is anonymous authentication in which no credentials are
* necessary.
* <li>External (<A HREF="http://www.ietf.org/rfc/rfc2222.txt">RFC 2222</A>).
* This mechanism obtains authentication information
* from an external source (such as TLS or IPsec).
* <li>S/Key (<A HREF="http://www.ietf.org/rfc/rfc2222.txt">RFC 2222</A>).
* This mechanism uses the MD4 digest algorithm to exchange data based on
* a shared secret.
* <li>GSSAPI (<A HREF="http://www.ietf.org/rfc/rfc2222.txt">RFC 2222</A>).
* This mechanism uses the
* <A HREF="http://www.ietf.org/rfc/rfc2078.txt">GSSAPI</A>
* for obtaining authentication information.
* </ul>
*
* Some of these mechanisms provide both authentication and establishment
* of a security layer, others only authentication. Anonymous and
* S/Key do not provide for any security layers. GSSAPI and DIGEST-MD5
* allow negotiation of the security layer. For External, the
* security layer is determined by the external protocol.
*
* <h3>Usage</h3>
*
* Users of this API are typically developers who produce
* client library implementations for connection-based protocols,
* such as LDAPv3 and IMAPv4,
* and developers who write servers (such as LDAP servers and IMAP servers).
* Developers who write client libraries use the
* {@code SaslClient} and {@code SaslClientFactory} interfaces.
* Developers who write servers use the
* {@code SaslServer} and {@code SaslServerFactory} interfaces.
*
* Among these two groups of users, each can be further divided into two groups:
* those who <em>produce</em> the SASL mechanisms and those
* who <em>use</em> the SASL mechanisms.
* The producers of SASL mechanisms need to provide implementations
* for these interfaces, while users of the SASL mechanisms use
* the APIs in this package to access those implementations.
*
* <h2>Related Documentation</h2>
*
* Please refer to the
* {@extLink security_guide_sasl Java SASL Programming Guide}
* for information on how to use this API.
*
* @since 1.5
*/
package javax.security.sasl;