author | juh |
Tue, 16 Jul 2013 12:19:41 -0700 | |
changeset 18830 | 90956ead732f |
parent 18156 | edb590d448c5 |
permissions | -rw-r--r-- |
2 | 1 |
/* |
18830 | 2 |
* Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved. |
2 | 3 |
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
4 |
* |
|
5 |
* This code is free software; you can redistribute it and/or modify it |
|
6 |
* under the terms of the GNU General Public License version 2 only, as |
|
5506 | 7 |
* published by the Free Software Foundation. Oracle designates this |
2 | 8 |
* particular file as subject to the "Classpath" exception as provided |
5506 | 9 |
* by Oracle in the LICENSE file that accompanied this code. |
2 | 10 |
* |
11 |
* This code is distributed in the hope that it will be useful, but WITHOUT |
|
12 |
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
13 |
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
14 |
* version 2 for more details (a copy is included in the LICENSE file that |
|
15 |
* accompanied this code). |
|
16 |
* |
|
17 |
* You should have received a copy of the GNU General Public License version |
|
18 |
* 2 along with this work; if not, write to the Free Software Foundation, |
|
19 |
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
|
20 |
* |
|
5506 | 21 |
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
22 |
* or visit www.oracle.com if you need additional information or have any |
|
23 |
* questions. |
|
2 | 24 |
*/ |
25 |
||
26 |
package javax.security.auth.callback; |
|
27 |
||
28 |
/** |
|
18830 | 29 |
* <p> An application implements a {@code CallbackHandler} and passes |
2 | 30 |
* it to underlying security services so that they may interact with |
31 |
* the application to retrieve specific authentication data, |
|
32 |
* such as usernames and passwords, or to display certain information, |
|
33 |
* such as error and warning messages. |
|
34 |
* |
|
35 |
* <p> CallbackHandlers are implemented in an application-dependent fashion. |
|
36 |
* For example, implementations for an application with a graphical user |
|
37 |
* interface (GUI) may pop up windows to prompt for requested information |
|
38 |
* or to display error messages. An implementation may also choose to obtain |
|
39 |
* requested information from an alternate source without asking the end user. |
|
40 |
* |
|
41 |
* <p> Underlying security services make requests for different types |
|
42 |
* of information by passing individual Callbacks to the |
|
18830 | 43 |
* {@code CallbackHandler}. The {@code CallbackHandler} |
2 | 44 |
* implementation decides how to retrieve and display information |
45 |
* depending on the Callbacks passed to it. For example, |
|
46 |
* if the underlying service needs a username and password to |
|
18830 | 47 |
* authenticate a user, it uses a {@code NameCallback} and |
48 |
* {@code PasswordCallback}. The {@code CallbackHandler} |
|
2 | 49 |
* can then choose to prompt for a username and password serially, |
50 |
* or to prompt for both in a single window. |
|
51 |
* |
|
14775
2ed01c760aea
8004064: Downgrade normative references to ${java.home}/lib/security/java.security
mullan
parents:
5506
diff
changeset
|
52 |
* <p> A default {@code CallbackHandler} class implementation |
2ed01c760aea
8004064: Downgrade normative references to ${java.home}/lib/security/java.security
mullan
parents:
5506
diff
changeset
|
53 |
* may be specified by setting the value of the |
2ed01c760aea
8004064: Downgrade normative references to ${java.home}/lib/security/java.security
mullan
parents:
5506
diff
changeset
|
54 |
* {@code auth.login.defaultCallbackHandler} security property. |
2 | 55 |
* |
56 |
* <p> If the security property is set to the fully qualified name of a |
|
18830 | 57 |
* {@code CallbackHandler} implementation class, |
58 |
* then a {@code LoginContext} will load the specified |
|
59 |
* {@code CallbackHandler} and pass it to the underlying LoginModules. |
|
60 |
* The {@code LoginContext} only loads the default handler |
|
2 | 61 |
* if it was not provided one. |
62 |
* |
|
63 |
* <p> All default handler implementations must provide a public |
|
64 |
* zero-argument constructor. |
|
65 |
* |
|
14775
2ed01c760aea
8004064: Downgrade normative references to ${java.home}/lib/security/java.security
mullan
parents:
5506
diff
changeset
|
66 |
* @see java.security.Security security properties |
2 | 67 |
*/ |
68 |
public interface CallbackHandler { |
|
69 |
||
70 |
/** |
|
71 |
* <p> Retrieve or display the information requested in the |
|
72 |
* provided Callbacks. |
|
73 |
* |
|
18830 | 74 |
* <p> The {@code handle} method implementation checks the |
75 |
* instance(s) of the {@code Callback} object(s) passed in |
|
2 | 76 |
* to retrieve or display the requested information. |
77 |
* The following example is provided to help demonstrate what an |
|
18830 | 78 |
* {@code handle} method implementation might look like. |
2 | 79 |
* This example code is for guidance only. Many details, |
80 |
* including proper error handling, are left out for simplicity. |
|
81 |
* |
|
18156 | 82 |
* <pre>{@code |
2 | 83 |
* public void handle(Callback[] callbacks) |
84 |
* throws IOException, UnsupportedCallbackException { |
|
85 |
* |
|
86 |
* for (int i = 0; i < callbacks.length; i++) { |
|
87 |
* if (callbacks[i] instanceof TextOutputCallback) { |
|
88 |
* |
|
89 |
* // display the message according to the specified type |
|
90 |
* TextOutputCallback toc = (TextOutputCallback)callbacks[i]; |
|
91 |
* switch (toc.getMessageType()) { |
|
92 |
* case TextOutputCallback.INFORMATION: |
|
93 |
* System.out.println(toc.getMessage()); |
|
94 |
* break; |
|
95 |
* case TextOutputCallback.ERROR: |
|
96 |
* System.out.println("ERROR: " + toc.getMessage()); |
|
97 |
* break; |
|
98 |
* case TextOutputCallback.WARNING: |
|
99 |
* System.out.println("WARNING: " + toc.getMessage()); |
|
100 |
* break; |
|
101 |
* default: |
|
102 |
* throw new IOException("Unsupported message type: " + |
|
103 |
* toc.getMessageType()); |
|
104 |
* } |
|
105 |
* |
|
106 |
* } else if (callbacks[i] instanceof NameCallback) { |
|
107 |
* |
|
108 |
* // prompt the user for a username |
|
109 |
* NameCallback nc = (NameCallback)callbacks[i]; |
|
110 |
* |
|
111 |
* // ignore the provided defaultName |
|
112 |
* System.err.print(nc.getPrompt()); |
|
113 |
* System.err.flush(); |
|
114 |
* nc.setName((new BufferedReader |
|
115 |
* (new InputStreamReader(System.in))).readLine()); |
|
116 |
* |
|
117 |
* } else if (callbacks[i] instanceof PasswordCallback) { |
|
118 |
* |
|
119 |
* // prompt the user for sensitive information |
|
120 |
* PasswordCallback pc = (PasswordCallback)callbacks[i]; |
|
121 |
* System.err.print(pc.getPrompt()); |
|
122 |
* System.err.flush(); |
|
123 |
* pc.setPassword(readPassword(System.in)); |
|
124 |
* |
|
125 |
* } else { |
|
126 |
* throw new UnsupportedCallbackException |
|
127 |
* (callbacks[i], "Unrecognized Callback"); |
|
128 |
* } |
|
129 |
* } |
|
130 |
* } |
|
131 |
* |
|
132 |
* // Reads user password from given input stream. |
|
133 |
* private char[] readPassword(InputStream in) throws IOException { |
|
134 |
* // insert code to read a user password from the input stream |
|
135 |
* } |
|
18156 | 136 |
* }</pre> |
2 | 137 |
* |
18830 | 138 |
* @param callbacks an array of {@code Callback} objects provided |
2 | 139 |
* by an underlying security service which contains |
140 |
* the information requested to be retrieved or displayed. |
|
141 |
* |
|
142 |
* @exception java.io.IOException if an input or output error occurs. <p> |
|
143 |
* |
|
144 |
* @exception UnsupportedCallbackException if the implementation of this |
|
145 |
* method does not support one or more of the Callbacks |
|
18830 | 146 |
* specified in the {@code callbacks} parameter. |
2 | 147 |
*/ |
148 |
void handle(Callback[] callbacks) |
|
149 |
throws java.io.IOException, UnsupportedCallbackException; |
|
150 |
} |