You are viewing a plain text version of this content. The canonical link for it is here.
Posted to scm@geronimo.apache.org by gn...@apache.org on 2006/05/31 15:35:19 UTC
svn commit: r410520 - in /geronimo/sandbox/jaspi-spec: ./ src/ src/main/
src/main/java/ src/main/java/javax/ src/main/java/javax/security/
src/main/java/javax/security/auth/
src/main/java/javax/security/auth/container/
Author: gnodet
Date: Wed May 31 06:35:18 2006
New Revision: 410520
URL: http://svn.apache.org/viewvc?rev=410520&view=rev
Log:
JASPI Api (JSR-196, aka Java Authentication SPI for Containers)
Added:
geronimo/sandbox/jaspi-spec/
geronimo/sandbox/jaspi-spec/pom.xml
geronimo/sandbox/jaspi-spec/src/
geronimo/sandbox/jaspi-spec/src/main/
geronimo/sandbox/jaspi-spec/src/main/java/
geronimo/sandbox/jaspi-spec/src/main/java/javax/
geronimo/sandbox/jaspi-spec/src/main/java/javax/security/
geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/
geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/
geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/AuthContextFactory.java
geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/AuthException.java
geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/AuthParam.java
geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/ClientAuthConfig.java
geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/ClientAuthContext.java
geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/ClientAuthModule.java
geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/FailureException.java
geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/HttpServletAuthParam.java
geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/MessageLayer.java
geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/MessagePolicy.java
geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/PendingException.java
geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/SOAPAuthParam.java
geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/ServerAuthConfig.java
geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/ServerAuthContext.java
geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/ServerAuthModule.java
Added: geronimo/sandbox/jaspi-spec/pom.xml
URL: http://svn.apache.org/viewvc/geronimo/sandbox/jaspi-spec/pom.xml?rev=410520&view=auto
==============================================================================
--- geronimo/sandbox/jaspi-spec/pom.xml (added)
+++ geronimo/sandbox/jaspi-spec/pom.xml Wed May 31 06:35:18 2006
@@ -0,0 +1,21 @@
+<project>
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>org.apache.geronimo.specs</groupId>
+ <artifactId>geronimo-jaspi_edr_spec</artifactId>
+ <version>1.0</version>
+ <name>JASPI</name>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.geronimo.specs</groupId>
+ <artifactId>geronimo-servlet_2.4_spec</artifactId>
+ <version>1.0</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.geronimo.specs</groupId>
+ <artifactId>geronimo-saaj_1.1_spec</artifactId>
+ <version>1.0</version>
+ </dependency>
+ </dependencies>
+</project>
+
Added: geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/AuthContextFactory.java
URL: http://svn.apache.org/viewvc/geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/AuthContextFactory.java?rev=410520&view=auto
==============================================================================
--- geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/AuthContextFactory.java (added)
+++ geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/AuthContextFactory.java Wed May 31 06:35:18 2006
@@ -0,0 +1,229 @@
+/**
+ * Copyright 2006 The Apache Software Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.security.auth.container;
+
+import java.net.URI;
+
+import javax.security.auth.callback.CallbackHandler;
+
+/**
+ * This factory is sued to obtain context objects that encapsulates authentication
+ * modules. An authentication module represents a pluggable component for
+ * performing security-related processing of requests and responses.
+ *
+ * Callers do not operate on modules directly. Instead they rely on a
+ * ClientAuthContext or ServerAuthContext to manage the invocation of modules.
+ * A called obtains an instanceof ClientAuthContext or ServerAuthContext by
+ * calling the respective <code>getAuthContext</code> method on this factory.
+ *
+ * The factory implementation encapsulates the modules to be invoked in a
+ * returned ClientAuthContext or ServerAuthContext instance. The returned
+ * instance is responsible for instanciating, initializing, and invoking
+ * the modules.
+ *
+ * The following represents a typical sequence of calls for obtaining a client
+ * authentication context object, and then securing a request using that
+ * context object:
+ * 1. AuthContextFactory factory = AuthContextFactory.getFactory();
+ * 2. AuthContextConfig config = factory.getClientAuthContig(...);
+ * 3. ClientAuthContext context = factory.getAuthContext(config, ...);
+ * 4. context.secureRequest(...);
+ *
+ * A system-wide AuthContextFactory implementation can be set by invoking
+ * <code>setFactory</code>, and retrieved via <code>getFactory</code>.
+ *
+ * @see ClientAuthContext
+ * @see ServerAuthContext
+ * @see ClientAuthConfig
+ * @see ServerAuthConfig
+ */
+public abstract class AuthContextFactory {
+
+ /**
+ * Get a ClientAuthContext instance from this factory.
+ *
+ * The implementation of this method returns a ClientAuthContext instance that
+ * encapsulates the ClientAuthModules used to secure and validate
+ * requests/reponses associated with the given <i>operation</i>.
+ *
+ * Specifically, this method indexes the provided ClientAuthConfig object with
+ * the given <i>operation</i> to determine the ClientAuthModules that are to
+ * be encapsulated in the returned ClientAuthContext instance.
+ *
+ * Note that the ClientAuthConfig object contains requests and responses
+ * MessagePolicy objects that are passes to the encapsulated modules when
+ * they are initialized by the returned ClientAUthContext instance. It is
+ * the modules' responsability to enforce these policies when invoked.
+ *
+ * @param config a ClientAuthConfig object used by the factory to map the
+ * given <i>operation</i> to a configuration of ClientAuthModules.
+ * @param operation an operation identifier used ot index the provided
+ * <i>config</i>, or null. This value must be identical to the
+ * value returned by the <code>getOperation</code> method on all
+ * <code>AuthParam</code> objects passes to the
+ * <code>secureRequest</code> or <code>validateResponse</code>
+ * methods on the returned ClientAuthContext.
+ * @returns a ClientAuthContext instance that encapsulates the ClientAuthModules
+ * used to secure and validate requests/responses associated with the
+ * given <i>operation</id>, or null (indicating that no modules
+ * are configured).
+ * @throws AuthException if this operation fails.
+ */
+ public abstract ClientAuthContext getAuthContext(
+ ClientAuthConfig config,
+ String operation) throws AuthException;
+
+ /**
+ * Get a ServerAuthContext instance from this factory.
+ *
+ * The implementation of this method returns a ServerAuthContext
+ * instance that encapsulates the ServerAuthModules used to validate
+ * and secure requests/responses associated with the given <i>operation</i>.
+ *
+ * Specifically, this method indexes the provided ServerAuthConfig
+ * object with the given <i>operation</i> to determine the ServerAuthModules
+ * that are to be encapsulated in the returned ServerAuthContext instance.
+ *
+ * Note that the ServerAuthConfig object contains request and response
+ * MessagePolicy objects that are passed to the encapsulated modules when
+ * they are initialized by the returned ServerAuthContext instance. It is the
+ * modules' responsibility to enforce these policies when invoked.
+ *
+ * @param config a ServerAuthConfig object used by the factory to map
+ * the given operation to a configuration of ServerAuthModules.
+ * @param operation an operation identifier used to index the provided config,
+ * or null. This value must be identical to the value returned
+ * by the getOperation method on any AuthParam object passed to
+ * the validateRequest or secureResponse methods on the returned
+ * ServerAuthContext.
+ * @return a ServerAuthContext instance that encapsulates the
+ * ServerAuthModules used to validate and secure requests/responses
+ * associated with the given operation, or null (indicating that
+ * no modules are configured).
+ * @throws AuthException if this operation fails.
+ */
+ public abstract ServerAuthContext getAuthContext(
+ ServerAuthConfig config,
+ String operation) throws AuthException;
+
+ /**
+ * Get an instance of ClientAuthConfig from this factory.
+ *
+ * The implementation of this method returns a ClientAuthConfig instance
+ * that describes the configuration of ClientAuthModules at a given message
+ * layer, and for a particular URI.
+ *
+ * @param layer a MessageLayer object identifying the message layer for
+ * the returned ClientAuthConfig object.
+ * @param uri the returned ClientAuthConfig describes a configuration for this URI.
+ * @param handler a CallbackHandler to be passed to the ClientAuthModules encapsulated
+ * by ClientAuthContext objects derived from the returned ClientAuthConfig.
+ * This parameter may be null, in which case the implementation may assign
+ * a default handler to the configuration.
+ * @return a ClientAuthConfig Object that describes the configuration of
+ * ClientAuthModules at a given message layer, and for a particular URI.
+ * @throws AuthException if this factory does not support the assignment of a
+ * default CallbackHandler to the returned ClientAuthConfig.
+ * @throws SecurityException if the caller does not have permission to retrieve the
+ * configuration.
+ */
+ public abstract ClientAuthConfig getClientAuthConfig(
+ MessageLayer layer,
+ URI uri,
+ CallbackHandler handler) throws AuthException;
+
+ /**
+ * Get the system-wide AuthContextFactory implementation.
+ *
+ * If a non-null factory instance has been set with setfactory it will be
+ * returned. Otherwise the value of the "authcontextfactory.provider" security
+ * property (in the Java security properties file) is used to determine the fully
+ * qualified name of the default factory implementation class. An instance of that
+ * class will be constructed and returned. If that property is not set, null is returned.
+ *
+ * The Java security properties file is located in the file named
+ * <JAVA_HOME>/lib/security/java.security, where <JAVA_HOME> refers to the directory
+ * where the JDK was installed.
+
+ * @return the system-wide AuthContextFactory instance, or null.
+ * @throws SecurityException if the caller does not have permission to retrieve the factory.
+ */
+ public static AuthContextFactory getFactory() {
+ SecurityManager sm = System.getSecurityManager();
+ if (sm != null) {
+ sm.checkPermission(new RuntimePermission("getAuthContextFactory"));
+ }
+ if (FACTORY == null) {
+ try {
+ FACTORY = (AuthContextFactory) java.security.AccessController.doPrivileged(
+ new java.security.PrivilegedExceptionAction() {
+ public Object run() throws Exception {
+ String factoryClassName = java.security.Security
+ .getProperty("authcontextfactory.provider");
+ if (factoryClassName == null || factoryClassName.length() == 0)
+ return null;
+ Class c = Class.forName(factoryClassName);
+ return c.newInstance();
+ }
+ });
+ } catch (java.security.PrivilegedActionException pae) {
+ // We will just return null
+ }
+ }
+ return FACTORY;
+ }
+
+ /**
+ * Get an instance of ServerAuthConfig from this factory.
+ *
+ * The implementation of this method returns a ServerAuthConfig instance that
+ * describes the configuration of ServerAuthModules at a given message layer,
+ * and for a particular URI.
+ *
+ * @param layer a MessageLayer object identifying the message layer for
+ * the returned ServerAuthConfig object.
+ * @param uri the returned ServerAuthConfig describes a configuration for this URI.
+ * @param handler a CallbackHandler to be passed to the ServerAuthModules encapsulated
+ * by ServerAuthContext objects derived from the returned ServerAuthConfig.
+ * This parameter may be null, in which case the implementation may assign
+ * a default handler to the configuration.
+ * @return a ServerAuthConfig Object that describes the configuration of
+ * ServerAuthModules at a given message layer, and for a particular URI.
+ * @throws AuthException if this factory does not support the assignment of a
+ * default CallbackHandler to the returned ServerAuthConfig.
+ * @throws SecurityException if the caller does not have permission to retrieve the
+ * configuration.
+ */
+ public abstract ServerAuthConfig getServerAuthConfig(
+ MessageLayer layer,
+ URI uri,
+ CallbackHandler handler) throws AuthException;
+
+ /**
+ * Set the system-wide AuthContextFactory implementation.
+ *
+ * If an implementation was set previously, it will be overridden.
+ *
+ * @param factory the AuthContextFactory instance, which may be null.
+ * @throws SecurityException if the caller does not have permission to set the factory.
+ */
+ public static void setFactory(AuthContextFactory factory) {
+ FACTORY = factory;
+ }
+
+ private static AuthContextFactory FACTORY;
+
+}
Added: geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/AuthException.java
URL: http://svn.apache.org/viewvc/geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/AuthException.java?rev=410520&view=auto
==============================================================================
--- geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/AuthException.java (added)
+++ geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/AuthException.java Wed May 31 06:35:18 2006
@@ -0,0 +1,46 @@
+/**
+ * Copyright 2006 The Apache Software Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.security.auth.container;
+
+import javax.security.auth.login.LoginException;
+
+/**
+ * A generic authentication exception.
+ */
+public class AuthException extends LoginException {
+
+ /**
+ * Generated serial version UID
+ */
+ private static final long serialVersionUID = 6688423461351758778L;
+
+ /**
+ * Constructs a AuthException with no detail message.
+ * A detail message is a String that describes this particular exception.
+ */
+ public AuthException() {
+ }
+
+ /**
+ * Constructs a AuthException with the specified detail message.
+ * A detail message is a String that describes this particular exception.
+ * @param msg the detail message.
+ */
+ public AuthException(String msg) {
+ super(msg);
+ }
+
+}
Added: geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/AuthParam.java
URL: http://svn.apache.org/viewvc/geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/AuthParam.java?rev=410520&view=auto
==============================================================================
--- geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/AuthParam.java (added)
+++ geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/AuthParam.java Wed May 31 06:35:18 2006
@@ -0,0 +1,51 @@
+/**
+ * Copyright 2006 The Apache Software Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.security.auth.container;
+
+/**
+ * This interface represents an authentication parameter that encapsulates
+ * a request object and a response object at a given messag layer, and for
+ * a particular operation.
+ *
+ * The message layer for an AuthParam implementation can be retrieved via
+ * the getMessageLayer method, and the layer-specific operation related to
+ * the encapsulated request and response objects can be retrieved via the
+ * getOperation method.
+ *
+ * Implementations of this interface provide access to message layer-specific
+ * request and response objects.
+ */
+public interface AuthParam {
+
+ /**
+ * Get the message layer for this AuthParam.
+ *
+ * @return the MessageLayer for this AuthParam.
+ */
+ public MessageLayer getMessageLayer();
+
+ /**
+ * Get the operation identifier related to the encapsulated request and
+ * response objects. The operation identifier is used to call
+ * AuthContextFactory.getContextMethod to select the context at which
+ * to process the AuthParam.
+ *
+ * @return the operation identifier related to the encapsulated request
+ * and response objects, or null.
+ */
+ public String getOperation();
+
+}
Added: geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/ClientAuthConfig.java
URL: http://svn.apache.org/viewvc/geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/ClientAuthConfig.java?rev=410520&view=auto
==============================================================================
--- geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/ClientAuthConfig.java (added)
+++ geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/ClientAuthConfig.java Wed May 31 06:35:18 2006
@@ -0,0 +1,43 @@
+/**
+ * Copyright 2006 The Apache Software Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.security.auth.container;
+
+/**
+ * This interface describes a configuration of ClientAuthModules.
+ *
+ * Implementations of this interface are created by the AuthContextFactory.
+ * The factory produces ClientAuthConfig implementations for a given message
+ * layer and URI. Each returned implementation may represent its internal
+ * module configuration in a custom manner.
+ *
+ * Callers pass an ClientAuthConfig instances to the AuthContextFactory to
+ * obtain ClientAuthContext objects. The AuthContextFactory looks into the
+ * ClientAuthConfig to determine the ClientAuthModules to be encapsulated in
+ * a returned ClientAuthContext, which is then used to secure client requests
+ * and to validate server responses.
+ *
+ * @see AuthContextFactory
+ */
+public interface ClientAuthConfig {
+
+ /**
+ * Get the message layer for this ClientAuthConfig.
+ *
+ * @return the message layer for this ClientAuthConfig.
+ */
+ public MessageLayer getMessageLayer();
+
+}
Added: geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/ClientAuthContext.java
URL: http://svn.apache.org/viewvc/geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/ClientAuthContext.java?rev=410520&view=auto
==============================================================================
--- geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/ClientAuthContext.java (added)
+++ geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/ClientAuthContext.java Wed May 31 06:35:18 2006
@@ -0,0 +1,149 @@
+/**
+ * Copyright 2006 The Apache Software Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.security.auth.container;
+
+import java.util.Map;
+
+import javax.security.auth.Subject;
+
+/**
+ * This ClientAuthContext class encapsulates ClientAuthModules that are used
+ * to secure requests made as a client.
+ *
+ * A caller typically uses this class in the following manner:
+ * 1. Retrieve an instance of this class via AuthContextFactory.getAuthContext.
+ * 2. Invoke secureRequest.
+ * ClientAuthContext implementation invokes encapsulated
+ * ClientAuthModule(s). Module(s) attach credentials to initial request
+ * object (for example, a username and password), and/or secure the request
+ * (for example, sign and encrypt the request).
+ * 3. Send request and receive response.
+ * 4. Invoke validateResponse.
+ * ClientAuthContext implementation invokes encapsulated ClientAuthModule(s).
+ * Module(s) verify or decrypt response as necessary.
+ * 5. Invoke disposeSubject method (as necessary) to clean up any authentication
+ * state in Subject.
+ *
+ * A ClientAuthContext instance may be used concurrently by multiple callers.
+ *
+ * Implementations of this interface are responsible for constructing and initializing
+ * the encapsulated modules. The initialization step includes passing the relevant
+ * request and response MessagePolicy objects to the encapsulated modules. The
+ * MessagePolicy objects are obtained from the ClientAuthConfig instance that was
+ * provided when this ClientAuthContext instance was created. See
+ * AuthContextFactory.getAuthContext for more information.
+ *
+ * Implementations also have custom logic to determine what modules to invoke, and in
+ * what order. In addition, this custom logic may control whether subsequent modules
+ * are invoked based on the success or failure of previously invoked modules.
+ *
+ * The caller is responsible for passing in a state Map that can be used by underlying
+ * modules to save and communicate state across a sequence of calls from secureRequest
+ * to validateResponse to disposeSubject. The same Map instance must be passed to all
+ * methods in the call sequence. Furthermore, each call sequence should be passed its
+ * own unique shared state Map instance.
+ *
+ * @see AuthContextFactory
+ * @see ClientAuthModule
+ */
+public interface ClientAuthContext {
+
+ /**
+ * Dispose of the Subject.
+ *
+ * Remove Principals or credentials from the Subject object that were stored
+ * during validateResponse). This method invokes encapsulated modules to
+ * dispose the Subject.
+ *
+ * @param subject the subject to be disposed.
+ * @param sharedState a Map for modules to save state across a sequence of
+ * calls from secureRequest to validateResponse to disposeSubject.
+ * @throws AuthException if the operation failed.
+ */
+ public void disposeSubject(
+ Subject subject,
+ Map sharedState) throws AuthException;
+
+ /**
+ * Get the message layer for this ClientAuthContext.
+ *
+ * @return the message layer for this ClientAuthContext.
+ */
+ public MessageLayer getMessageLayer();
+
+ /**
+ * Secure a request message.
+ *
+ * Attach authentication credentials to an initial request, sign/encrypt a request,
+ * or respond to a server challenge, for example.
+ *
+ * @param param an authentication parameter that encapsulates the client
+ * request and server response objects.
+ * @param source a Subject that represents the source of the request, or null.
+ * It may be used by modules to retrieve Principals and credentials
+ * necessary to secure the request. The module may use a
+ * CallbackHandler to obtain any additional information necessary
+ * to secure the request. Newly obtained information may be stored
+ * back into the Subject object.
+ * @param sharedState a Map for modules to save state across a sequence of calls from
+ * <code>secureRequest</code> to <code>validateResponse</code> to
+ * <code>disposeSubject</code>.
+ * @throws AuthException if the operation failed.
+ */
+ public void secureRequest(
+ AuthParam authParam,
+ Subject source,
+ Map sharedState) throws AuthException;
+
+ /**
+ * Returns the description of the ClientAuthModules encapsulated in
+ * this ClientAuthContext.
+ *
+ * @return a String description of the ClientAuthModules encapsulated in
+ * this ClientAuthContext.
+ */
+ public String toString();
+
+ /**
+ * Validate a received response.
+ *
+ * Validation may include verifying signature in response, or decrypting
+ * response contents, for example. This method invokes encapsulated modules
+ * to validate the response.
+ *
+ * @param param an authentication parameter that encapsulates the client
+ * request and server response objects.
+ * @param source a Subject that represents the source of the request, or null.
+ * It may be used by modules to store Principals and credentials
+ * validated in the response.
+ * @param recipient a Subject that represents the recipient of the response, or null.
+ * It may be used by modules to retrieve Principals and credentials
+ * necessary to validate the response. The module may use a
+ * CallbackHandler to obtain any additional information necessary to
+ * validate the response. Newly obtained information may be stored
+ * back into the Subject object.
+ * @param sharedState a Map for modules to save state across a sequence of calls from
+ * <code>secureRequest</code> to <code>validateResponse</code> to
+ * <code>disposeSubject</code>.
+ * @throws AuthException if the operation failed.
+ */
+ public void validateResponse(
+ AuthParam authParam,
+ Subject source,
+ Subject recipient,
+ Map sharedState) throws AuthException;
+
+}
Added: geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/ClientAuthModule.java
URL: http://svn.apache.org/viewvc/geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/ClientAuthModule.java?rev=410520&view=auto
==============================================================================
--- geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/ClientAuthModule.java (added)
+++ geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/ClientAuthModule.java Wed May 31 06:35:18 2006
@@ -0,0 +1,141 @@
+/**
+ * Copyright 2006 The Apache Software Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.security.auth.container;
+
+import java.util.Map;
+
+import javax.security.auth.Subject;
+import javax.security.auth.callback.CallbackHandler;
+
+/**
+ * A ClientAuthModule secures request messages, and validates received
+ * response messages.
+ *
+ * A module implementation should assume it may be used to secure different
+ * requests as different clients. A module should also assume it may be used
+ * concurrently by multiple callers. It is the module implementations
+ * responsibility to properly save and restore any state as necessary. A module
+ * that does not need to do so may remain completely stateless.
+ */
+public interface ClientAuthModule {
+
+ /**
+ * Dispose of the Subject.
+ *
+ * Causes the module to remove the Principals and credentials that it added
+ * to a Subject during its processing of either <code>secureRequest</code> or
+ * <code>validateResponse</code>.
+ *
+ * @param subject the Subject instance from which the Principals and
+ * credentials are to be removed.
+ * @param sharedState a Map for modules to save state across a sequence of
+ * calls from secureRequest to validateResponse to disposeSubject.
+ * @throws AuthException if the operation failed.
+ */
+ public void disposeSubject(
+ Subject subject,
+ Map sharedState) throws AuthException;
+
+ /**
+ * Get a MessageLayer instance that identifies the layer implemented by the module.
+ *
+ * @return a MessageLayer instance that identifies the message layer.
+ */
+ public MessageLayer getMessageLayer();
+
+ /**
+ * Initialize this module with request and response message policies to enforce,
+ * a CallbackHandler, and any module-specific configuration properties.
+ *
+ * The request policy and the response policy must not both be null.
+ *
+ * @param requestPolicy the request policy this module must enforce, or null.
+ * @param responsePolicy the response policy this module must enforce, or null.
+ * @param handler CallbackHandler used to request information.
+ * @param options a Map of module-specific configuration properties.
+ * @param mustBeTransactional if true, any failure of either <code>secureRequest</code>
+ * or <code>validateResponse</code> must leave both the
+ * request and response components of the provided
+ * <code>AuthParam</code> parameter unchanged.
+ * @throws AuthException if this module does not support the
+ * <i>mustBeTransactional</i> parameter.
+ */
+ public void initialize(
+ MessagePolicy requestPolicy,
+ MessagePolicy responsePolicy,
+ CallbackHandler handler,
+ Map options,
+ boolean mustBeTransactional) throws AuthException;
+
+ /**
+ * Secure a request.
+ *
+ * Attach authentication credentials to an initial request, sign/encrypt a request,
+ * or respond to a server challenge, for example. This method invokes encapsulated
+ * modules to secure the request.
+ *
+ * @param param an authentication parameter that encapsulates the client
+ * request and server response objects.
+ * @param source a Subject that represents the source of the request, or null.
+ * It may be used by modules to retrieve Principals and credentials
+ * necessary to secure the request. The module may use a
+ * CallbackHandler to obtain any additional information necessary
+ * to secure the request. Newly obtained information may be stored
+ * back into the Subject object.
+ * @param sharedState a Map for modules to save state across a sequence of calls from
+ * <code>secureRequest</code> to <code>validateResponse</code> to
+ * <code>disposeSubject</code>.
+ * @throws AuthException if the operation failed.
+ */
+ public void secureRequest(
+ AuthParam param,
+ Subject source,
+ Map sharedState) throws AuthException;
+
+ /**
+ * Returns a description of the module.
+ * @return a String describing the authentication mechanisms implemented by the module.
+ */
+ public String toString();
+
+ /**
+ * Validate a received response.
+ *
+ * Decrypt and verify a signature on the response, for example.
+ *
+ * @param param an authentication parameter that encapsulates the client
+ * request and server response objects.
+ * @param source a Subject that represents the source of the request, or null.
+ * It may be used by modules to store Principals and credentials
+ * validated in the response.
+ * @param recipient a Subject that represents the recipient of the response, or null.
+ * It may be used by modules to retrieve Principals and credentials
+ * necessary to validate the response. The module may use a
+ * CallbackHandler to obtain any additional information necessary to
+ * validate the response. Newly obtained information may be stored
+ * back into the Subject object.
+ * @param sharedState a Map for modules to save state across a sequence of calls from
+ * <code>secureRequest</code> to <code>validateResponse</code> to
+ * <code>disposeSubject</code>.
+ * @throws AuthException if the operation failed.
+ */
+ public void validateResponse(
+ AuthParam param,
+ Subject source,
+ Subject recipient,
+ Map sharedState) throws AuthException;
+
+}
Added: geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/FailureException.java
URL: http://svn.apache.org/viewvc/geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/FailureException.java?rev=410520&view=auto
==============================================================================
--- geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/FailureException.java (added)
+++ geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/FailureException.java Wed May 31 06:35:18 2006
@@ -0,0 +1,49 @@
+/**
+ * Copyright 2006 The Apache Software Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.security.auth.container;
+
+/**
+ * Authentication failed.
+ *
+ * This exception is thrown by an AuthModule when authentication failed.
+ * This exception is only thrown when the module has updated the response
+ * message in the AuthParam.
+ */
+public class FailureException extends AuthException {
+
+ /**
+ * Generated serial version UID
+ */
+ private static final long serialVersionUID = -3941782025248234747L;
+
+ /**
+ * Constructs a FailureException with no detail message.
+ * A detail message is a String that describes this particular exception.
+ */
+ public FailureException() {
+ super();
+ }
+
+ /**
+ * Constructs a FailureException with the specified detail message.
+ * A detail message is a String that describes this particular exception.
+ * @param msg the detail message.
+ */
+ public FailureException(String msg) {
+ super(msg);
+ }
+
+}
Added: geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/HttpServletAuthParam.java
URL: http://svn.apache.org/viewvc/geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/HttpServletAuthParam.java?rev=410520&view=auto
==============================================================================
--- geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/HttpServletAuthParam.java (added)
+++ geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/HttpServletAuthParam.java Wed May 31 06:35:18 2006
@@ -0,0 +1,115 @@
+/**
+ * Copyright 2006 The Apache Software Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.security.auth.container;
+
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+
+/**
+ * An HTTP Servlet authentication parameter that encapsulates HTTP Servlet
+ * request and response objects.
+ *
+ * HttpServletAuthParam may be created with null request or response objects.
+ * The following table describes when it is appropriate to pass null:
+ *
+ * Request Response
+ * ------- --------
+ * ClientAuthModule.secureRequest non-null null
+ * ClientAuthModule.validateResponse null non-null
+ * ServerAuthModule.validateRequest non-null null
+ * ServerAuthModule.secureResponse null non-null
+ *
+ * As noted above, in the case of <code>ServerAuthModule.validateRequest</code>
+ * the module receives a null response object. If the implementation of
+ * <code>validateRequest</code> encounters an authentication error, it may
+ * construct the appropriate response object itself and set it into the
+ * HttpServletAuthParam via the <code>setResponse</code> method.
+ */
+public class HttpServletAuthParam implements AuthParam {
+
+ private HttpServletRequest request;
+ private HttpServletResponse response;
+
+ /**
+ * Create an HTTPServletAuthParam with HTTP request and response objects.
+ *
+ * @param request the HTTP Servlet request object, or null.
+ * @param response the HTTP Servlet response object, or null.
+ */
+ public HttpServletAuthParam(
+ HttpServletRequest request,
+ HttpServletResponse response) {
+ this.request = request;
+ this.response = response;
+ }
+
+ /**
+ * Get a MessageLayer instance that identifies HttpServlet as the message layer.
+ *
+ * @return a MessageLayer instance that identifies HttpServlet as the message layer.
+ */
+ public MessageLayer getMessageLayer() {
+ return new MessageLayer(MessageLayer.HTTP_SERVLET);
+ }
+
+ /**
+ * Get the operation related to the encapsulated HTTP Servlet request
+ * and response objects.
+ *
+ * @return the operation related to the encapsulated request and
+ * response objects, or null.
+ */
+ public String getOperation() {
+ return null;
+ }
+
+ /**
+ * Get the HTTP Servlet request object.
+ *
+ * @return the HTTP Servlet request object, or null.
+ */
+ public HttpServletRequest getRequest() {
+ return request;
+ }
+
+ /**
+ * Get the HTTP Servlet response object.
+ *
+ * @return the HTTP Servlet response object, or null.
+ */
+ public HttpServletResponse getResponse() {
+ return response;
+ }
+
+ /**
+ * Set a new HTTP Servlet response object.
+ *
+ * If a response has already been set (it is non-null), this method returns.
+ * The original response is not overwritten.
+ *
+ * @param response the HTTP Servlet response object.
+ * @throws IllegalArgumentException if the specified response is null.
+ */
+ public void setResponse(HttpServletResponse response) {
+ if (response == null) {
+ throw new IllegalArgumentException("response is null");
+ }
+ if (this.response == null) {
+ return;
+ }
+ this.response = response;
+ }
+}
Added: geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/MessageLayer.java
URL: http://svn.apache.org/viewvc/geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/MessageLayer.java?rev=410520&view=auto
==============================================================================
--- geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/MessageLayer.java (added)
+++ geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/MessageLayer.java Wed May 31 06:35:18 2006
@@ -0,0 +1,64 @@
+/**
+ * Copyright 2006 The Apache Software Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.security.auth.container;
+
+/**
+ * This class represents a message layer over which message-specific requests
+ * and responses are delivered.
+ *
+ * The following represents a list of standard layer names:
+ * <ul>
+ * <li>HTTPServlet</li>
+ * <li>SOAP</li>
+ * </ul>
+ */
+public class MessageLayer {
+
+ /**
+ * Standard message name for HTTP servlets.
+ */
+ public static final String HTTP_SERVLET = "HTTPServlet";
+
+ /**
+ * Standard message name for SOAP
+ */
+ public static final String SOAP = "SOAP";
+
+ private final String name;
+
+ /**
+ * Construct an instance of MessageLayer.
+ *
+ * @param name name of the layer.
+ * @throws IllegalArgumentException if the specified name is null.
+ */
+ public MessageLayer(String name) {
+ if (name == null) {
+ throw new IllegalArgumentException("name is null");
+ }
+ this.name = name;
+ }
+
+ /**
+ * Return the message layer name.
+ *
+ * @return the message layer name.
+ */
+ public String getName() {
+ return name;
+ }
+
+}
Added: geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/MessagePolicy.java
URL: http://svn.apache.org/viewvc/geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/MessagePolicy.java?rev=410520&view=auto
==============================================================================
--- geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/MessagePolicy.java (added)
+++ geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/MessagePolicy.java Wed May 31 06:35:18 2006
@@ -0,0 +1,169 @@
+/**
+ * Copyright 2006 The Apache Software Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.security.auth.container;
+
+import java.net.URI;
+
+public class MessagePolicy {
+
+ /**
+ * This interface is implemented by objects that represent and perform message
+ * targeting on behalf of authentication modules.
+ *
+ * The internal state of a Target indicates whether it applies to the request
+ * or response message of an AuthParam and to which components it applies within
+ * the identified message.
+ */
+ public interface Target {
+
+ /**
+ * Get the Object identified by the Target from the AuthParam.
+ *
+ * @param authParam the AuthParam containing the request or response message
+ * from which the target is to be obtained.
+ * @return an Object representing the target, or null when the target could
+ * not be found in the AuthParam.
+ */
+ public Object get(AuthParam authParam);
+
+ /**
+ * Put the Object into the AuthParam at the location identified by the target.
+ *
+ * @param authParam the AuthParam containing the request or response message
+ * into which the object is to be put.
+ * @param data
+ */
+ public void put(AuthParam authParam, Object data);
+
+ /**
+ * Remove the Object identified by the Target from the AuthParam.
+ *
+ * @param authParam the AuthParam containing the request or response message
+ * from which the target is to be removed.
+ */
+ public void remote(AuthParam authParam);
+ }
+
+ public static class TargetPolicy {
+
+ /**
+ * A URI that represents a recipient entity authentication policy
+ */
+ public static final URI AUTHENTICATE_RECIPIENT = URI.create("AUTHENTICATE_RECIPIENT");
+
+ /**
+ * A URI that represents a data recipient authentication policy
+ */
+ public static final URI AUTHENTICATE_RECIPIENT_CONTENT = URI.create("AUTHENTICATE_RECIPIENT_CONTENT");
+
+ /**
+ * A URI that represents a source entity authentication policy
+ */
+ public static final URI AUTHENTICATE_SOURCE = URI.create("AUTHENTICATE_SOURCE");
+
+ /**
+ * A URI that represents a data origin authentication policy
+ */
+ public static final URI AUTHENTICATE_SOURCE_CONTENT = URI.create("AUTHENTICATE_SOURCE_CONTENT");
+
+ private final Target[] targets;
+ private final URI protectionPolicy;
+
+ /**
+ * Create a TargetPolicy instance with an array of Targets and with a protection
+ * policy URI.
+ *
+ * @param targets an array of Targets.
+ * @param protectionPolicy the protection policy URI.
+ * @throws IllegalArgumentException if the specified targets or
+ * protectionPolicyURI is null.
+ */
+ public TargetPolicy(Target[] targets,
+ URI protectionPolicy) {
+ if (targets == null) {
+ throw new IllegalArgumentException("targets is null");
+ }
+ if (protectionPolicy == null) {
+ throw new IllegalArgumentException("protectionPolicy is null");
+ }
+ this.targets = targets;
+ this.protectionPolicy = protectionPolicy;
+ }
+
+ /**
+ * Get the URI that identifies the policy that applies to the targets.
+ *
+ * @return a URI that identifies a source or recipient authentication policy.
+ */
+ public URI getProtectionPolicy() {
+ return protectionPolicy;
+ }
+
+ /**
+ * Get the array of layer-specific target descriptors that identify the one
+ * or more message parts to which the specified message protection policy applies.
+ *
+ * @return an array of Target that identify targets within a message. This method
+ * returns null when the specified policy applies to the whole message
+ * (excluding any meta data added to the message to satisfy the policy).
+ * This method never returns a zero-length array.
+ */
+ public Target[] getTargets() {
+ if (targets.length == 0) {
+ return null;
+ }
+ return targets;
+ }
+
+ }
+
+ private final TargetPolicy[] targetPolicies;
+
+ /**
+ * Create a MessagePolicy instance with an array of target policies.
+ *
+ * @param targetPolicies an array of target policies.
+ * @throws IllegalArgumentException if the specified targetPolicies is null.
+ */
+ public MessagePolicy(TargetPolicy[] targetPolicies) {
+ if (targetPolicies == null) {
+ throw new IllegalArgumentException("targetPolicies is null");
+ }
+ this.targetPolicies = targetPolicies;
+ }
+
+ /**
+ * Get the target policies that comprise the authentication policy.
+ *
+ * @return an array of target authentication policies, where each element
+ * describes an authentication policy and the parts of the message
+ * to which the authentication policy applies. This method returns null to
+ * indicate that no security operations should be performed on the messages
+ * to which the policy applies. This method never returns a zero-length array.
+ *
+ * When this method returns an array of target policies, the order of elements
+ * in the array represents the order that the corresponding message
+ * transformations or validations described by the target policies are
+ * to be performed by the authentication module.
+ */
+ public TargetPolicy[] getTargetPolicies() {
+ if (targetPolicies.length == 0) {
+ return null;
+ }
+ return targetPolicies;
+ }
+
+}
Added: geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/PendingException.java
URL: http://svn.apache.org/viewvc/geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/PendingException.java?rev=410520&view=auto
==============================================================================
--- geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/PendingException.java (added)
+++ geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/PendingException.java Wed May 31 06:35:18 2006
@@ -0,0 +1,48 @@
+/**
+ * Copyright 2006 The Apache Software Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.security.auth.container;
+
+
+/**
+ * Authentication is pending.
+ *
+ * This exception can be thrown by an AuthModule issuing a challenge, for example.
+ *
+ */
+public class PendingException extends AuthException {
+
+ /**
+ * Generated serial version UID
+ */
+ private static final long serialVersionUID = -4767781782326275810L;
+
+ /**
+ * Constructs a PendingException with no detail message.
+ * A detail message is a String that describes this particular exception.
+ */
+ public PendingException() {
+ }
+
+ /**
+ * Constructs a PendingException with the specified detail message.
+ * A detail message is a String that describes this particular exception.
+ * @param msg the detail message.
+ */
+ public PendingException(String msg) {
+ super(msg);
+ }
+
+}
Added: geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/SOAPAuthParam.java
URL: http://svn.apache.org/viewvc/geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/SOAPAuthParam.java?rev=410520&view=auto
==============================================================================
--- geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/SOAPAuthParam.java (added)
+++ geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/SOAPAuthParam.java Wed May 31 06:35:18 2006
@@ -0,0 +1,117 @@
+/**
+ * Copyright 2006 The Apache Software Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.security.auth.container;
+
+import javax.xml.soap.SOAPMessage;
+
+/**
+ * A SOAP authentication parameter that encapsulates SOAPMessage request and response objects.
+ *
+ * SOAPAuthParam may be created with null request or response objects.
+ * The following table describes when it is appropriate to pass null:
+ *
+ * Request Response
+ * ------- --------
+ * ClientAuthModule.secureRequest non-null null
+ * ClientAuthModule.validateResponse null non-null
+ * ServerAuthModule.validateRequest non-null null
+ * ServerAuthModule.secureResponse null non-null
+ *
+ * As noted above, in the case of ServerAuthModule.validateRequest the module
+ * receives a null response object. If the implementation of validateRequest
+ * encounters an authentication error, it may construct the appropriate response
+ * object itself and set it into the SOAPAuthParam via the setResponse
+ * method.
+ */
+public class SOAPAuthParam implements AuthParam {
+
+ private SOAPMessage request;
+ private SOAPMessage response;
+
+ /**
+ * Create a SOAPAuthParam with SOAP request and response messages.
+ *
+ * @param request SOAPMessage corresponding to the request, or null.
+ * @param response SOAPMessage corresponding to the response, or null.
+ */
+ public SOAPAuthParam(SOAPMessage request,
+ SOAPMessage response) {
+ this.request = request;
+ this.response = response;
+ }
+
+ /**
+ * Get a MessageLayer instance that identifies SOAP as the message layer.
+ *
+ * @return a MessageLayer instance that identifies SOAP as the message layer.
+ */
+ public MessageLayer getMessageLayer() {
+ return new MessageLayer(MessageLayer.SOAP);
+ }
+
+ /**
+ * Get the operation related to the encapsulated SOAP request and response messages.
+ *
+ * This method returns the value specified in the request objects SOAPAction header.
+ * If the value is not present, this method returns the name of the first child element
+ * of the request objects SOAP envelope. If this value is not present, this method
+ * returns null.
+ *
+ * @return the operation related to the encapsulated request and response messages, or null.
+ */
+ public String getOperation() {
+ // TODO
+ return null;
+ }
+
+ /**
+ * Get the SOAP request message.
+ *
+ * @return the SOAP request message, or null.
+ */
+ public SOAPMessage getRequest() {
+ return request;
+ }
+
+ /**
+ * Get the SOAP response message.
+ *
+ * @return the SOAP response message, or null.
+ */
+ public SOAPMessage getResponse() {
+ return response;
+ }
+
+ /**
+ * Set a new SOAP response message.
+ *
+ * If a response has already been set (it is non-null), this method returns.
+ * The original response is not overwritten.
+ *
+ * @param response the SOAP response message.
+ * @throws IllegalArgumentException if the specified response is null.
+ */
+ public void setResponse(SOAPMessage response) {
+ if (response == null) {
+ throw new IllegalArgumentException("response is null");
+ }
+ if (this.response != null) {
+ return;
+ }
+ this.response = response;
+ }
+
+}
Added: geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/ServerAuthConfig.java
URL: http://svn.apache.org/viewvc/geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/ServerAuthConfig.java?rev=410520&view=auto
==============================================================================
--- geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/ServerAuthConfig.java (added)
+++ geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/ServerAuthConfig.java Wed May 31 06:35:18 2006
@@ -0,0 +1,42 @@
+/**
+ * Copyright 2006 The Apache Software Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.security.auth.container;
+
+/**
+ * This interface describes a configuration of ServerAuthModules.
+ *
+ * Implementations of this interface are created by the AuthContextFactory.
+ * The factory produces ServerAuthConfig implementations for a given message
+ * layer and URI. Each returned implementation may represent its internal module
+ * configuration in a custom manner.
+ *
+ * Callers pass an ServerAuthConfig instances to the AuthContextFactory to obtain
+ * ServerAuthContext objects. The AuthContextFactory looks into the ServerAuthConfig
+ * to determine the ServerAuthModules to be encapsulated in a returned ServerAuthContext,
+ * which is then used to validate client requests and to secure server responses.
+ *
+ * @see AuthContextFactory
+ */
+public interface ServerAuthConfig {
+
+ /**
+ * Get the message layer for this ServerAuthConfig.
+ *
+ * @return the MessageLayer for this ServerAuthConfig.
+ */
+ public MessageLayer getMessageLayer();
+
+}
Added: geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/ServerAuthContext.java
URL: http://svn.apache.org/viewvc/geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/ServerAuthContext.java?rev=410520&view=auto
==============================================================================
--- geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/ServerAuthContext.java (added)
+++ geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/ServerAuthContext.java Wed May 31 06:35:18 2006
@@ -0,0 +1,158 @@
+/**
+ * Copyright 2006 The Apache Software Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.security.auth.container;
+
+import java.util.Map;
+
+import javax.security.auth.Subject;
+
+/**
+ * This ServerAuthContext class encapsulates ServerAuthModules that are used to
+ * validate client requests.
+ *
+ * A caller typically uses this class in the following manner:
+ * 1. Retrieve an instance of this class via AuthContextFactory.getAuthContext.
+ * 2. Invoke validateRequest.
+ * ServerAuthContext implementation invokes encapsulated ServerAuthModule(s).
+ * Module(s) validate credentials present in request (for example, decrypt and
+ * verify a signature). If credentials valid and sufficient, return. Otherwise
+ * throw an AuthException.
+ * 3. Authentication complete.
+ * Perform authorization check on authenticated identity and, if successful,
+ * dispatch to requested service application.
+ * 4. Service application finished.
+ * 5. Invoke secureResponse.
+ * ServerAuthContext implementation invokes encapsulated ServerAuthModule(s).
+ * Module(s) secure response (sign and encrypt response, for example).
+ * 6. Send final response to client.
+ * 7. Invoke disposeSubject (as necessary) to clean up any authentication
+ * state in Subject.
+ *
+ * A ClientAuthContext instance may be used concurrently by multiple callers.
+ *
+ * Implementations of this interface are responsible for constructing and initializing
+ * the encapsulated modules. The initialization step includes passing the relevant
+ * request and response MessagePolicy objects to the encapsulated modules. The
+ * MessagePolicy objects are obtained from the ServerAuthConfig instance that was
+ * provided when this ServerAuthContext instance was created. See
+ * AuthContextFactory.getAuthContext for more information.
+ *
+ * Implementations also have custom logic to determine what modules to invoke, and in
+ * what order. In addition, this custom logic may control whether subsequent modules
+ * are invoked based on the success or failure of previously invoked modules.
+ *
+ * The caller is responsible for passing in a state Map that can be used by underlying
+ * modules to save and communicate state across a sequence of calls from validateRequest
+ * to secureResponse to disposeSubject. The same Map instance must be passed to all
+ * methods in the call sequence. Furthermore, each call sequence should be passed its
+ * own unique shared state Map instance.
+ *
+ * @see AuthContextFactory
+ * @see ServerAuthModule
+ */
+public interface ServerAuthContext {
+
+ /**
+ * Dispose of the Subject.
+ *
+ * Remove Principals or credentials from the Subject object that were stored
+ * during validateResponse). This method invokes encapsulated modules to
+ * dispose the Subject.
+ *
+ * @param subject the subject to be disposed.
+ * @param sharedState a Map for modules to save state across a sequence of
+ * calls from secureRequest to validateResponse to disposeSubject.
+ * @throws AuthException if the operation failed.
+ */
+ public void disposeSubject(
+ Subject subject,
+ Map sharedState) throws AuthException;
+
+ /**
+ * Get the message layer for this ServerAuthContext.
+ *
+ * @return the message layer for this ServerAuthContext.
+ */
+ public MessageLayer getMessageLayer();
+
+ /**
+ * Secure the response to the client.
+ *
+ * Sign and encrypt the response, for example. This method invokes encapsulated
+ * modules to secure the response.
+ *
+ * @param authParam an authentication parameter that encapsulates the client
+ * request and server response objects
+ * @param source a Subject that represents the source of the response, or null.
+ * It may be used by modules to retrieve Principals and credentials
+ * necessary to secure the response. The module may use a
+ * CallbackHandler to obtain any additional information necessary
+ * to secure the response. Newly obtained information may be stored
+ * back into the Subject object.
+ * @param sharedState a Map for modules to save state across a sequence of calls from
+ * <code>secureRequest</code> to <code>validateResponse</code> to
+ * <code>disposeSubject</code>.
+ * @throws AuthException if the operation failed.
+ */
+ public void secureResponse(
+ AuthParam authParam,
+ Subject source,
+ Map sharedState) throws AuthException;
+
+ /**
+ * Returns the description of the ServerAuthModules encapsulated in this
+ * ServerAuthContext.
+ *
+ * @return a String description of the ServerAuthModules encapsulated in
+ * this ServerAuthContext.
+ */
+ public String toString();
+
+ /**
+ * Authenticate a client request.
+ *
+ * Decrypt a request and verify a signature, for example.
+ *
+ * This method invokes encapsulated modules to authenticate the request.
+ *
+ * @param param an authentication parameter that encapsulates the client
+ * request and server response objects.
+ * @param source a Subject that represents the source of the request, or null.
+ * It may be used by modules to store Principals and credentials
+ * validated in the response.
+ * @param recipient a Subject that represents the recipient of the response, or null.
+ * It may be used by modules to retrieve Principals and credentials
+ * necessary to validate the response. The module may use a
+ * CallbackHandler to obtain any additional information necessary to
+ * validate the response. Newly obtained information may be stored
+ * back into the Subject object.
+ * @param sharedState a Map for modules to save state across a sequence of calls from
+ * <code>secureRequest</code> to <code>validateResponse</code> to
+ * <code>disposeSubject</code>.
+ * @throws PendingException if the operation is pending (for example, when a module issues
+ * a challenge). The module must have updated the response
+ * object in the authParam input parameter.
+ * @throws FailureException if the authentication failed. The module must have updated
+ * the response object in the <i>authParam</i> input parameter.
+ * @throws AuthException if the operation failed.
+ */
+ public void validateRequest(
+ AuthParam authParam,
+ Subject source,
+ Subject recipient,
+ Map sharedState) throws AuthException;
+
+}
Added: geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/ServerAuthModule.java
URL: http://svn.apache.org/viewvc/geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/ServerAuthModule.java?rev=410520&view=auto
==============================================================================
--- geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/ServerAuthModule.java (added)
+++ geronimo/sandbox/jaspi-spec/src/main/java/javax/security/auth/container/ServerAuthModule.java Wed May 31 06:35:18 2006
@@ -0,0 +1,144 @@
+/**
+ * Copyright 2006 The Apache Software Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.security.auth.container;
+
+import java.util.Map;
+
+import javax.security.auth.Subject;
+import javax.security.auth.callback.CallbackHandler;
+
+/**
+ * A ServerAuthModule validates client requests and secures responses back to the client.
+ *
+ * A module implementation should assume it may be used to secure different requests as
+ * different clients. A module should also assume it may be used concurrently by multiple
+ * callers. It is the module implementation's responsibility to properly save and restore
+ * any state as necessary. A module that does not need to do so may remain completely
+ * stateless.
+ */
+public interface ServerAuthModule {
+
+ /**
+ * Dispose of the Subject.
+ *
+ * Causes the module to remove the Principals and credentials that it added
+ * to a Subject during its processing of either <code>secureRequest</code> or
+ * <code>validateResponse</code>.
+ *
+ * @param subject the Subject instance from which the Principals and
+ * credentials are to be removed.
+ * @param sharedState a Map for modules to save state across a sequence of
+ * calls from secureRequest to validateResponse to disposeSubject.
+ * @throws AuthException if the operation failed.
+ */
+ public void disposeSubject(
+ Subject subject,
+ Map sharedState) throws AuthException;
+
+ /**
+ * Get a MessageLayer instance that identifies the layer implemented by the module.
+ *
+ * @return a MessageLayer instance that identifies the message layer.
+ */
+ public MessageLayer getMessageLayer();
+
+ /**
+ * Initialize this module with request and response message policies to enforce,
+ * a CallbackHandler, and any module-specific configuration properties.
+ *
+ * The request policy and the response policy must not both be null.
+ *
+ * @param requestPolicy the request policy this module must enforce, or null.
+ * @param responsePolicy the response policy this module must enforce, or null.
+ * @param handler CallbackHandler used to request information.
+ * @param options a Map of module-specific configuration properties.
+ * @param mustBeTransactional if true, any failure of either <code>secureRequest</code>
+ * or <code>validateResponse</code> must leave both the
+ * request and response components of the provided
+ * <code>AuthParam</code> parameter unchanged.
+ * @throws AuthException if this module does not support the
+ * <i>mustBeTransactional</i> parameter.
+ */
+ public void initialize(
+ MessagePolicy requestPolicy,
+ MessagePolicy responsePolicy,
+ CallbackHandler handler,
+ Map options,
+ boolean mustBeTransactional) throws AuthException;
+
+ /**
+ * Secure the response to the client.
+ *
+ * Sign and encrypt the response, for example.
+ *
+ * @param authParam an authentication parameter that encapsulates the client
+ * request and server response objects
+ * @param source a Subject that represents the source of the response, or null.
+ * It may be used by modules to retrieve Principals and credentials
+ * necessary to secure the response. The module may use a
+ * CallbackHandler to obtain any additional information necessary
+ * to secure the response. Newly obtained information may be stored
+ * back into the Subject object.
+ * @param sharedState a Map for modules to save state across a sequence of calls from
+ * <code>secureRequest</code> to <code>validateResponse</code> to
+ * <code>disposeSubject</code>.
+ * @throws AuthException if the operation failed.
+ */
+ public void secureResponse(
+ AuthParam authParam,
+ Subject source,
+ Map sharedState) throws AuthException;
+
+ /**
+ * Returns a description of the module.
+ *
+ * @return a String describing the authentications mechanisms implemented by the module.
+ */
+ public String toString();
+
+ /**
+ * Authenticate a client request.
+ *
+ * Decrypt a request and verify a signature, for example.
+ *
+ * @param param an authentication parameter that encapsulates the client
+ * request and server response objects.
+ * @param source a Subject that represents the source of the request, or null.
+ * It may be used by modules to store Principals and credentials
+ * validated in the response.
+ * @param recipient a Subject that represents the recipient of the response, or null.
+ * It may be used by modules to retrieve Principals and credentials
+ * necessary to validate the response. The module may use a
+ * CallbackHandler to obtain any additional information necessary to
+ * validate the response. Newly obtained information may be stored
+ * back into the Subject object.
+ * @param sharedState a Map for modules to save state across a sequence of calls from
+ * <code>secureRequest</code> to <code>validateResponse</code> to
+ * <code>disposeSubject</code>.
+ * @throws PendingException if the operation is pending (for example, when a module issues
+ * a challenge). The module must have updated the response
+ * object in the authParam input parameter.
+ * @throws FailureException if the authentication failed. The module must have updated
+ * the response object in the <i>authParam</i> input parameter.
+ * @throws AuthException if the operation failed.
+ */
+ public void validateRequest(
+ AuthParam authParam,
+ Subject source,
+ Subject recipient,
+ Map sharedState) throws AuthException;
+
+}