ClientAuth


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: ClientAuth.java 45179 2006-05-23 20:18:57Z asaldhana $
29  
30  /**
31   *  An implementation of this interface is used to secure service request 
32   *  messages, and validate received 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)
35   *  @since  May 11, 2006 
36   *  @version $Revision: 45179 $
37   */
38  public interface ClientAuth
39  {
40     /**
41      * Remove module specific principals and credentials from the subject.
42      * @param subject the Subject instance from which the Principals and 
43      *                credentials are to be removed.
44      * @param sharedState a Map for modules to save state across a sequence 
45      *                of calls from secureRequest to validateResponse 
46      *                returning AuthStatus.PROCEED
47      * @return
48      * @throws AuthException if an error occurs during the Subject processing.
49      */
50     public AuthStatus cleanSubject( Subject   subject, Map   sharedState)
51     throws AuthException;
52     
53     /**
54      * <p>Secure a service request message before sending it to the service.</p>
55      * 
56      * <p>Sign and encrpt the service request, for example.</p>
57      * 
58      * @param authParam an authentication parameter that encapsulates the 
59      *                  client request and server response objects.
60      * @param client a Subject that represents the source of the service request, 
61      *               or null. It may be used by modules to retrieve Principals 
62      *               and credentials necessary to secure the request. The module 
63      *               may use a CallbackHandler to obtain any additional information 
64      *               necessary to secure the request. Newly obtained or validated 
65      *               credentials may be stored back into the Subject object.
66      * @param sharedState a Map for modules to save state across a sequence of calls 
67      *               from secureRequest to validateResponse returning AuthStatus.PROCEED
68      * @return an AuthStatus object representing the completion status of the processing 
69      *         performed by the module.
70      *         <ul>
71      *            <li>AuthStatus.PROCEED returned when the application request message
72      *                was successfully secured. The runtime may proceed to send the 
73      *                request message. returned in AuthParam.</li>
74      *            <li>AuthStatus.RETRY returned when the module replaces the application 
75      *                request message with an mechanism specific message to be sent in 
76      *                advance of the application message. The runtime should throw an 
77      *                exception if it is unable to process the rety. Otherwise, the 
78      *                runtime should send the request message returned in AuthParam 
79      *                (and without calling secureRequest).</li>
80      *           <li>AuthStatus.ERROR returned when the processing by the module failed 
81      *               and indicates that the module has defined an appropriate error request
82      *               message in the AuthParam. The runtime may send the request message 
83      *               returned in AuthParam (without calling SecureRequest), and must 
84      *               discontinue its processing of the application request.</li>
85      *           </ul>
86      * @throws AuthException when the module wishes to signal a failure in securing 
87      *               the request and without establishing a corresponding error request 
88      *               message. The runtime must discontinue its processing of the message 
89      *               exchange.
90      */
91     public AuthStatus secureRequest(AuthParam authParam,Subject   client, Map   sharedState)
92     throws AuthException;
93     
94     /**
95      * <p>Validate a received service response.</p>
96      * 
97      * <p>Decrypt and verify a signature on the response, for example.</p>
98      * 
99      * @param authParam an authentication parameter that encapsulates the client 
100     *                  request and server response objects.
101     * @param client a Subject that represents the recipient of the service response, 
102     *               or null. It may be used by modules to retrieve Principals and 
103     *               credentials necessary to validate the response. The module may use
104     *               a CallbackHandler to obtain any additional information necessary 
105     *               to validate the response. Newly obtained information may be stored 
106     *               back into the Subject object.
107     * @param service a Subject that represents the source of the service response, 
108     *               or null. It may be used by modules to store Principals and credentials 
109     *               validated in the response.
110     * @param sharedState a Map for modules to save state across a sequence of calls from 
111     *               secureRequest to validateResponse returning AuthStatus.PROCEED
112     * @return an AuthStatus object representing the completion status of the processing 
113     *         performed by the module.
114     *         <ul>
115     *            <li>AuthStatus.PROCEED returned when the validation of the application 
116     *                response message succeded. The runtime may proceed to return the 
117     *                response message in the AuthParam to the application.</li>
118     *            <li>AuthStatus.RETRY returned when the message validation succeded, but 
119     *                when the validated message is a mechanism specific message sent in 
120     *                advance of the application message. The runtime must not proceed to 
121     *                process the response message in the AuthParam. The runtime should 
122     *                throw an exception if it is unable to process the retry. Otherwise, 
123     *                it should send the request message returned in AuthParam (and without 
124     *                calling secureRequest).</li>
125     *           <li>AuthStatus.ERROR returned when the validation failed and indicates 
126     *               that the module has defined an appropriate error request message in 
127     *               the AuthParam. The runtime must not proceed to process the response 
128     *               message in the AuthParam, and may send the request message returned in
129     *               AuthParam (and without calling secureRequest).</li>
130     *           </ul>
131     * @throws AuthException
132     */
133    public AuthStatus validateResponse(AuthParam authParam, Subject   client, 
134          Subject   service, Map   sharedState)
135    throws AuthException;
136 }
137
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags