ClientAuthContext


1   /*
2    * The contents of this file are subject to the terms 
3    * of the Common Development and Distribution License 
4    * (the License).  You may not use this file except in
5    * compliance with the License.
6    * 
7    * You can obtain a copy of the license at 
8    * https://glassfish.dev.java.net/public/CDDLv1.0.html or
9    * glassfish/bootstrap/legal/CDDLv1.0.txt.
10   * See the License for the specific language governing 
11   * permissions and limitations under the License.
12   * 
13   * When distributing Covered Code, include this CDDL 
14   * Header Notice in each file and include the License file 
15   * at glassfish/bootstrap/legal/CDDLv1.0.txt.  
16   * If applicable, add the following below the CDDL Header, 
17   * with the fields enclosed by brackets [] replaced by
18   * you own identifying information: 
19   * "Portions Copyrighted [year] [name of copyright owner]"
20   * 
21   * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
22   */
23  
24  package com.sun.enterprise.security.jauth;
25  
26  /**
27   * This ClientAuthContext class manages AuthModules that may be used
28   * to secure requests made as a client.  A caller typically uses this class
29   * in the following manner:
30   *
31   * <ol>
32   * <li> Retrieve an instance of this class via AuthConfig.getClientAuthContext.
33   * <li> Invoke <i>secureRequest</i>.
34   *  <br>
35   *  ClientAuthContext implementation invokes configured plug-in modules.
36   *  Modules attach credentials to initial request object
37   *  (for example, a username and password), and/or secure the request
38   *      (for example, sign and encrypt the request).
39   * <li> Issue request.
40   * <li> Receive response and pass it to <i>validateResponse</i>.
41   *  <br>
42   *  ClientAuthContext implementation invokes configured plug-in modules.
43   *  Modules verify or decrypt response as necessary.
44   * <li> The <i>disposeSubject</i> method may be invoked if necessary
45   *  to clean up any authentication state in the Subject.
46   * </ol>
47   * 
48   * <p> An instance may reuse module instances it
49   * previously created. As a result a single module instance may be used
50   * to issue different requests as different clients.
51   * It is the module implementation's responsibility to properly
52   * store and restore any necessary state.  A module that does not need
53   * to do so may remain completely stateless.
54   *
55   * <p> Instances of this class have custom logic to determine
56   * what modules to invoke, and in what order.  In addition,
57   * this custom logic may control whether subsequent modules are invoked
58   * based on the success or failure of previously invoked modules.
59   *
60   * <p> The caller is responsible for passing in a state Map
61   * that can be used by underlying modules to save state across
62   * a sequence of calls from <code>secureRequest</code>
63   * to <code>validateResponse</code> to <code>disposeSubject</code>.
64   * The same Map instance must be passed to all methods in the call sequence.
65   * Furthermore, each call sequence should be passed its own unique
66   * shared state Map instance.
67   *
68   * @version %I%, %G%
69   * @see AuthConfig
70   * @see SOAPAuthParam
71   */
72  public interface ClientAuthContext {
73  
74      /**
75       * Secure a request message.
76       *
77       * <p> Attach authentication credentials to an initial request,
78       * sign/encrypt a request, or respond to a server challenge, for example.
79       *
80       * <p> This method invokes configured modules to secure the request.
81       *
82       * @param param an authentication parameter that encapsulates the
83       *      client request and server response objects.
84       *
85       * @param subject the subject may be used by configured modules
86       *      to obtain Principals and credentials necessary to
87       *      secure the request, or null.  If null, the module may
88       *      use a CallbackHandler to obtain any information necessary
89       *      to secure the request.
90       *
91       * @param sharedState a Map for modules to save state across
92       *      a sequence of calls from <code>secureRequest</code>
93       *      to <code>validateResponse</code> to <code>disposeSubject</code>.
94       *
95       * @exception AuthException if the operation failed.
96       */
97      void secureRequest(AuthParam param,
98              javax.security.auth.Subject   subject,
99              java.util.Map   sharedState)
100         throws AuthException;
101 
102     /**
103      * Validate received response.
104      *
105      * <p> Validation may include verifying signature in response,
106      * or decrypting response contents, for example.
107      * 
108      * <p> This method invokes configured modules to validate the response.
109      *
110      * @param param an authentication parameter that encapsulates the
111      *      client request and server response objects.
112      *
113      * @param subject the subject may be used by configured modules
114      *      to store the Principals and credentials related
115      *      to the identity validated in the response.
116      *
117      * @param sharedState a Map for modules to save state across
118      *      a sequence of calls from <code>secureRequest</code>
119      *      to <code>validateResponse</code> to <code>disposeSubject</code>.
120      *
121      * @exception AuthException if the operation failed.
122      */
123     void validateResponse(AuthParam param,
124             javax.security.auth.Subject   subject,
125             java.util.Map   sharedState)
126         throws AuthException;
127 
128     /**
129      * Dispose of the Subject
130      * (remove Principals or credentials from the Subject object
131      * that were stored during <code>validateResponse</code>).
132      *
133      * <p> This method invokes configured modules to dispose the Subject.
134      *
135      * @param subject the subject to be disposed.
136      *
137      * @param sharedState a Map for modules to save state across
138      *      a sequence of calls from <code>secureRequest</code>
139      *      to <code>validateResponse</code> to <code>disposeSubject</code>.
140      *
141      * @exception AuthException if the operation failed.
142      */
143     void disposeSubject(javax.security.auth.Subject   subject,
144             java.util.Map   sharedState)
145         throws AuthException;
146 }
147
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags