1 /*
2 * Copyright (c) 1999, 2012, Oracle and/or its affiliates. All rights reserved.
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
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
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 *
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.
24 */
25
26 package javax.security.auth.callback;
27
28 /**
29 * <p> An application implements a <code>CallbackHandler</code> and passes
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
43 * <code>CallbackHandler</code>. The <code>CallbackHandler</code>
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
47 * authenticate a user, it uses a <code>NameCallback</code> and
48 * <code>PasswordCallback</code>. The <code>CallbackHandler</code>
49 * can then choose to prompt for a username and password serially,
50 * or to prompt for both in a single window.
51 *
52 * <p> A default {@code CallbackHandler} class implementation
53 * may be specified by setting the value of the
54 * {@code auth.login.defaultCallbackHandler} security property.
55 *
56 * <p> If the security property is set to the fully qualified name of a
57 * <code>CallbackHandler</code> implementation class,
58 * then a <code>LoginContext</code> will load the specified
59 * <code>CallbackHandler</code> and pass it to the underlying LoginModules.
60 * The <code>LoginContext</code> only loads the default handler
61 * if it was not provided one.
62 *
63 * <p> All default handler implementations must provide a public
64 * zero-argument constructor.
65 *
66 * @see java.security.Security security properties
67 */
68 public interface CallbackHandler {
69
70 /**
71 * <p> Retrieve or display the information requested in the
72 * provided Callbacks.
73 *
74 * <p> The <code>handle</code> method implementation checks the
75 * instance(s) of the <code>Callback</code> object(s) passed in
76 * to retrieve or display the requested information.
77 * The following example is provided to help demonstrate what an
78 * <code>handle</code> method implementation might look like.
79 * This example code is for guidance only. Many details,
80 * including proper error handling, are left out for simplicity.
81 *
82 * <pre>
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 * }
136 * </pre>
137 *
138 * @param callbacks an array of <code>Callback</code> objects provided
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
146 * specified in the <code>callbacks</code> parameter.
147 */
148 void handle(Callback[] callbacks)
149 throws java.io.IOException, UnsupportedCallbackException;
150 }