151 lines
6.6 KiB
Java
151 lines
6.6 KiB
Java
/*
|
|
* Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
|
|
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
|
|
*
|
|
* This code is free software; you can redistribute it and/or modify it
|
|
* under the terms of the GNU General Public License version 2 only, as
|
|
* published by the Free Software Foundation. Oracle designates this
|
|
* particular file as subject to the "Classpath" exception as provided
|
|
* by Oracle in the LICENSE file that accompanied this code.
|
|
*
|
|
* This code is distributed in the hope that it will be useful, but WITHOUT
|
|
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
|
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
|
|
* version 2 for more details (a copy is included in the LICENSE file that
|
|
* accompanied this code).
|
|
*
|
|
* You should have received a copy of the GNU General Public License version
|
|
* 2 along with this work; if not, write to the Free Software Foundation,
|
|
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
|
|
*
|
|
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
|
|
* or visit www.oracle.com if you need additional information or have any
|
|
* questions.
|
|
*/
|
|
|
|
package javax.security.auth.callback;
|
|
|
|
/**
|
|
* <p> An application implements a {@code CallbackHandler} and passes
|
|
* it to underlying security services so that they may interact with
|
|
* the application to retrieve specific authentication data,
|
|
* such as usernames and passwords, or to display certain information,
|
|
* such as error and warning messages.
|
|
*
|
|
* <p> CallbackHandlers are implemented in an application-dependent fashion.
|
|
* For example, implementations for an application with a graphical user
|
|
* interface (GUI) may pop up windows to prompt for requested information
|
|
* or to display error messages. An implementation may also choose to obtain
|
|
* requested information from an alternate source without asking the end user.
|
|
*
|
|
* <p> Underlying security services make requests for different types
|
|
* of information by passing individual Callbacks to the
|
|
* {@code CallbackHandler}. The {@code CallbackHandler}
|
|
* implementation decides how to retrieve and display information
|
|
* depending on the Callbacks passed to it. For example,
|
|
* if the underlying service needs a username and password to
|
|
* authenticate a user, it uses a {@code NameCallback} and
|
|
* {@code PasswordCallback}. The {@code CallbackHandler}
|
|
* can then choose to prompt for a username and password serially,
|
|
* or to prompt for both in a single window.
|
|
*
|
|
* <p> A default {@code CallbackHandler} class implementation
|
|
* may be specified by setting the value of the
|
|
* {@code auth.login.defaultCallbackHandler} security property.
|
|
*
|
|
* <p> If the security property is set to the fully qualified name of a
|
|
* {@code CallbackHandler} implementation class,
|
|
* then a {@code LoginContext} will load the specified
|
|
* {@code CallbackHandler} and pass it to the underlying LoginModules.
|
|
* The {@code LoginContext} only loads the default handler
|
|
* if it was not provided one.
|
|
*
|
|
* <p> All default handler implementations must provide a public
|
|
* zero-argument constructor.
|
|
*
|
|
* @see java.security.Security security properties
|
|
*/
|
|
public interface CallbackHandler {
|
|
|
|
/**
|
|
* <p> Retrieve or display the information requested in the
|
|
* provided Callbacks.
|
|
*
|
|
* <p> The {@code handle} method implementation checks the
|
|
* instance(s) of the {@code Callback} object(s) passed in
|
|
* to retrieve or display the requested information.
|
|
* The following example is provided to help demonstrate what an
|
|
* {@code handle} method implementation might look like.
|
|
* This example code is for guidance only. Many details,
|
|
* including proper error handling, are left out for simplicity.
|
|
*
|
|
* <pre>{@code
|
|
* public void handle(Callback[] callbacks)
|
|
* throws IOException, UnsupportedCallbackException {
|
|
*
|
|
* for (int i = 0; i < callbacks.length; i++) {
|
|
* if (callbacks[i] instanceof TextOutputCallback) {
|
|
*
|
|
* // display the message according to the specified type
|
|
* TextOutputCallback toc = (TextOutputCallback)callbacks[i];
|
|
* switch (toc.getMessageType()) {
|
|
* case TextOutputCallback.INFORMATION:
|
|
* System.out.println(toc.getMessage());
|
|
* break;
|
|
* case TextOutputCallback.ERROR:
|
|
* System.out.println("ERROR: " + toc.getMessage());
|
|
* break;
|
|
* case TextOutputCallback.WARNING:
|
|
* System.out.println("WARNING: " + toc.getMessage());
|
|
* break;
|
|
* default:
|
|
* throw new IOException("Unsupported message type: " +
|
|
* toc.getMessageType());
|
|
* }
|
|
*
|
|
* } else if (callbacks[i] instanceof NameCallback) {
|
|
*
|
|
* // prompt the user for a username
|
|
* NameCallback nc = (NameCallback)callbacks[i];
|
|
*
|
|
* // ignore the provided defaultName
|
|
* System.err.print(nc.getPrompt());
|
|
* System.err.flush();
|
|
* nc.setName((new BufferedReader
|
|
* (new InputStreamReader(System.in))).readLine());
|
|
*
|
|
* } else if (callbacks[i] instanceof PasswordCallback) {
|
|
*
|
|
* // prompt the user for sensitive information
|
|
* PasswordCallback pc = (PasswordCallback)callbacks[i];
|
|
* System.err.print(pc.getPrompt());
|
|
* System.err.flush();
|
|
* pc.setPassword(readPassword(System.in));
|
|
*
|
|
* } else {
|
|
* throw new UnsupportedCallbackException
|
|
* (callbacks[i], "Unrecognized Callback");
|
|
* }
|
|
* }
|
|
* }
|
|
*
|
|
* // Reads user password from given input stream.
|
|
* private char[] readPassword(InputStream in) throws IOException {
|
|
* // insert code to read a user password from the input stream
|
|
* }
|
|
* }</pre>
|
|
*
|
|
* @param callbacks an array of {@code Callback} objects provided
|
|
* by an underlying security service which contains
|
|
* the information requested to be retrieved or displayed.
|
|
*
|
|
* @exception java.io.IOException if an input or output error occurs. <p>
|
|
*
|
|
* @exception UnsupportedCallbackException if the implementation of this
|
|
* method does not support one or more of the Callbacks
|
|
* specified in the {@code callbacks} parameter.
|
|
*/
|
|
void handle(Callback[] callbacks)
|
|
throws java.io.IOException, UnsupportedCallbackException;
|
|
}
|