ServerAuth


1   /*
2     * JBoss, Home of Professional Open Source
3     * Copyright 2005, JBoss Inc., and individual contributors as indicated
4     * by the @authors tag. See the copyright.txt in the distribution for a
5     * full listing of individual contributors.
6     *
7     * This is free software; you can redistribute it and/or modify it
8     * under the terms of the GNU Lesser General Public License as
9     * published by the Free Software Foundation; either version 2.1 of
10    * the License, or (at your option) any later version.
11    *
12    * This software is distributed in the hope that it will be useful,
13    * but WITHOUT ANY WARRANTY; without even the implied warranty of
14    * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15    * Lesser General Public License for more details.
16    *
17    * You should have received a copy of the GNU Lesser General Public
18    * License along with this software; if not, write to the Free
19    * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
20    * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
21    */
22  package javax.security.auth.message;
23  
24  import java.util.Map  ;
25  
26  import javax.security.auth.Subject  ;
27  
28  //$Id: ServerAuth.java 45179 2006-05-23 20:18:57Z asaldhana $
29  
30  /**
31   *  An implementation of this interface is used to validate received service 
32   *  request messages, and to secure service response messages.
33   *  @author <a HREF="mailto:Anil.Saldhana@jboss.org">Anil Saldhana</a>
34   *  @author Charlie Lai, Ron Monzillo (Javadoc for JSR-196)</a> 
35   *  @since  May 12, 2006 
36   *  @version $Revision: 45179 $
37   */
38  public interface ServerAuth
39  {
40     /**
41      * Remove module specific principals and credentials from the subject.
42      * @param subject the Subject instance from which the Principals and credentials 
43      *                are to be removed.  
44      * @param sharedState a Map for modules to save state across a sequence of calls from
45      *                   validateRequest to secureResponse returning AuthStatus.PROCEED.
46      * @throws AuthException if an error occurs during the Subject processing.
47      */
48     public void cleanSubject(Subject   subject, Map   sharedState)
49     throws AuthException;
50     
51     /**
52      * <p>Secure a service response before sending it to the client.</p>
53      * <p>Sign and encrypt the response, for example.</p>
54      * 
55      * @param authParam an authentication parameter that encapsulates the client 
56      *                  request and server response objects.
57      * @param service a Subject that represents the source of the service response, 
58      *                or null. It may be used by modules to retrieve Principals and 
59      *                credentials necessary to secure the response. The module may 
60      *                use a CallbackHandler to obtain any additional information 
61      *                necessary to secure the response. Newly obtained information 
62      *                may be stored back into the Subject object.
63      * @param sharedState a Map for modules to save state across a sequence of calls 
64      *                from validateRequest to secureResponse returning AuthStatus.PROCEED.
65      * @return an AuthStatus object representing the completion status of the processing 
66      *                performed by the module.
67      *                <ul>
68      *                  <li>AuthStatus.PROCEED returned when the application response 
69      *                  message was successfully secured. The runtime may proceed to 
70      *                  send the response message. returned in AuthParam.</li>
71      *                  <li>AuthStatus.RETRY returned when the module replaces the 
72      *                  application response message with an mechanism specific message 
73      *                  to be sent in advance of the application message. The runtime 
74      *                  should send the response message returned in AuthParam.</li>
75      *                  <li>AuthStatus.ERROR returned when the processing by the module 
76      *                  failed and indicates that the module has defined an appropriate 
77      *                  error response message in the AuthParam. The runtime may send 
78      *                  the response message returned in AuthParam.</li>
79      *                </ul>
80      * @throws AuthException
81      */
82     public AuthStatus secureResponse(AuthParam authParam, Subject   service, Map   sharedState)
83     throws AuthException;
84     
85     /**
86      * <p>Authenticate a received service request.</p>
87      * <p>Decrypt content and verify a signature on a request, for example.</p>
88      * 
89      * @param authParam an authentication parameter that encapsulates the client 
90      *                  request and server response objects.
91      * @param client a Subject that represents the source of the service request. 
92      *               It is used by modules to store Principals and credentials 
93      *               validated in the request.
94      * @param service a Subject that represents the recipient of the service request, 
95      *               or null. It may be used by modules to retrieve Principals and 
96      *               credentials necessary to validate the request. The module may 
97      *               use a CallbackHandler to obtain any additional information 
98      *               necessary to validate the response. Newly obtained information 
99      *               may be stored back into the Subject object.
100     * @param sharedState a Map for modules to save state across a sequence of calls from
101     *               <i>validateRequest</i> to <i>secureResponse</i>
102     *               returning AuthStatus.PROCEED.
103     * @return an AuthStatus object representing the completion status of the processing 
104     *                performed by the module.
105     *                <ul>
106     *                  <li>AuthStatus.PROCEED returned when the validation of the 
107     *                  application message succeded. The runtime may proceed to process 
108     *                  the request message in the AuthParam.</li>
109     *                  <li>AuthStatus.RETRY returned when the message validation 
110     *                  succeded, but when the validated message was sent in advance of 
111     *                  either the application message or the security credentials. 
112     *                  This return value indicates that the message authentication was 
113     *                  not completed. If the runtime�s request processing policy 
114     *                  requires that the authentication be completed, the runtime must 
115     *                  not proceed to process the request message in the AuthParam, and 
116     *                  should send the response message returned in the AuthParam (and 
117     *                  without calling secureResponse).</li>
118     *                  <li>AuthStatus.ERROR returned when the validation failed and 
119     *                  indicates that the module has defined an appropriate error 
120     *                  response message in the AuthParam. The runtime must not proceed 
121     *                  to process the request message in the AuthParam, and may send 
122     *                  the response message returned in AuthParam (and without calling 
123     *                  secureResponse).</li>
124     *                </ul>
125     * @throws AuthException
126     */
127    public AuthStatus validateRequest(AuthParam authParam, Subject   client,  
128        Subject   service,  Map   sharedState) throws AuthException;
129 }
130
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags