KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > security > auth > message > 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 JavaDoc;
25
26 import javax.security.auth.Subject JavaDoc;
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 JavaDoc subject, Map JavaDoc 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 JavaDoc client, Map JavaDoc 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 JavaDoc client,
134          Subject JavaDoc service, Map JavaDoc sharedState)
135    throws AuthException;
136 }
137
Popular Tags