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.config;
23
24 import javax.security.auth.callback.CallbackHandler;
25 import javax.security.auth.message.AuthException;
26
27 //$Id: AuthConfigProvider.java 45179 2006-05-23 20:18:57Z asaldhana $
28
29 /**
30 * <p>This interface is implemented by objects that can be used to obtain authentication
31 * context configuration objects i.e., ClientAuthConfig or ServerAuthConfig objects.
32 * Authentication context configuration objects serve as sources of the authentication
33 * context objects, i.e, ClientAuthContext or ServerAuthContext objects, for a
34 * specific message layer and messaging context.</p>
35 * <p>Authentication context objects encapsulate the initialization, configuration,
36 * and invocation of authentication modules, i.e., ClientAuthModule or ServerAuthModule
37 * objects, for a specific message exchange within a specific message layer and
38 * messaging context.</p>
39 * <p>Callers do not directly operate on authentication modules. Instead, they rely on
40 * a ClientAuthContext or ServerAuthContext to manage the invocation of modules. A
41 * caller obtains an instance of ClientAuthContext or ServerAuthContext by calling the
42 * respective getAuthContext method on a ClientAuthConfig or ServerAuthConfig object
43 * obtained from an AuthConfigProvider.</p>
44 * <p> The following represents a typical sequence of calls for obtaining a client
45 * authentication context object, and then using it to secure a request.</p>
46 * <ol>
47 * <li>AuthConfigProvider provider;</li>
48 * <li>ClientAuthConfig config = provider.getClientAuthConfig(layer,appID,cbh);</li>
49 * <li>String operation = config.getOperation(authParam);</li>
50 * <li>ClientAuthContext context = config.getAuthContext(operation,properties);</li>
51 * <li>context.secureRequest(authParam,subject,...);</li>
52 * </ol>
53 * <p>Every implementation of this interface must offer a public, single argument
54 * constructor with the following signature:</p>
55 * <pre> public AuthConfigProviderImpl(Map properties);</pre>
56 * <p>where the properties argument may be null, and where all values and keys occuring
57 * in a non-null properties argument must be of type String.</p>
58 * <p>An AuthConfigFactory may be used to obtain the ConfigProvider for a specific
59 * message layer and application context identifier.</p>
60 * @author <a href="mailto:Anil.Saldhana@jboss.org">Anil Saldhana</a>
61 * @author Charlie Lai, Ron Monzillo (Javadoc for JSR-196)</a>
62 * @since May 12, 2006
63 * @version $Revision: 45179 $
64 */
65 public interface AuthConfigProvider
66 {
67 /**
68 * Get an instance of ClientAuthConfig from this provider.
69 * The implementation of this method returns a ClientAuthConfig instance that
70 * describes the configuration of ClientAuthModules at a given message layer, and
71 * for use in an identified application context.
72 *
73 * @param layer a String identifying the message layer for the returned
74 * ClientAuthConfig object.
75 * @param appContext a String that identifies the messaging context for the
76 * returned ClientAuthConfig object.
77 * @param handler a CallbackHandler to be passed to the ClientAuthModules
78 * encapsulated by ClientAuthContext objects derived from the
79 * returned ClientAuthConfig. This parameter may be null, in which
80 * case the implementation may assign a default handler to the
81 * configuration. The ?authconfigprovider.client.callbackhandler?
82 * security property is used to define the fully qualified name of
83 * the default CallbackHandler implementation class.
84 * @return a ClientAuthConfig Object that describes the configuration of
85 * ClientAuthModules at the message layer and messaging context
86 * identified by the layer and appContext arguments. This method does
87 * not return null.
88 * @throws AuthException if this factory does not support the assignment of a
89 * default CallbackHandler to the returned ClientAuthConfig.
90 * @throws SecurityException if the caller does not have permission to retrieve
91 * the configuration.
92 */
93 ClientAuthConfig getClientAuthConfig( String layer, String appContext,
94 CallbackHandler handler) throws AuthException, SecurityException;
95
96 /**
97 * Get an instance of ServerAuthConfig from this provider.
98 * The implementation of this method returns a ServerAuthConfig instance that
99 * describes the configuration of ServerAuthModules at a given message layer, and
100 * for use in an identified application context.
101 *
102 * @param layer a String identifying the message layer for the returned
103 * ServerAuthConfig object.
104 * @param appContext a String that identifies the messaging context for the
105 * returned ServerAuthConfig object.
106 * @param handler a CallbackHandler to be passed to the ServerAuthModules
107 * encapsulated by ServerAuthContext objects derived from the
108 * returned ServerAuthConfig. This parameter may be null, in which
109 * case the implementation may assign a default handler to the
110 * configuration. The ?authconfigprovider.client.callbackhandler?
111 * security property is used to define the fully qualified name of
112 * the default CallbackHandler implementation class.
113 * @return a ServerAuthConfig Object that describes the configuration of
114 * ServerAuthModules at the message layer and messaging context
115 * identified by the layer and appContext arguments. This method does
116 * not return null.
117 * @throws AuthException if this factory does not support the assignment of a
118 * default CallbackHandler to the returned ServerAuthConfig.
119 * @throws SecurityException if the caller does not have permission to retrieve
120 * the configuration.
121 */
122 ServerAuthConfig getServerAuthConfig( String layer, String appContext,
123 CallbackHandler handler) throws AuthException, SecurityException;
124
125 /**
126 * Causes a dynamic configuration provider to update its internal state such that
127 * any resulting change to its state is recognized by authentication context
128 * configuration objects previously created by the provider within the current
129 * process context.
130 * <p> The effect on the authentication context configuration objects should be
131 * extended to the authentication context objects obtained from the configuration
132 * objects, such that the context objects recognize changes in the state of the
133 * configuration object from which they were obtained.</p>
134 * @throws AuthException if an error occured during the refresh.
135 * @throws SecurityException if the caller does not have permission to
136 * refresh the provider.
137 */
138 void refresh() throws AuthException, SecurityException;
139 }