geronimo-scm mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From gno...@apache.org
Subject 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/
Date Wed, 31 May 2006 13:35:19 GMT
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 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 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 object’s SOAPAction header. 
+     * If the value is not present, this method returns the name of the first child element 
+     * of the request object’s 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;
+    
+}



Mime
View raw message