1 /* 2 * Copyright (c) 1999, 2005, 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</code> class implementation 53 * may be specified in the <i>auth.login.defaultCallbackHandler</i> 54 * security property. The security property can be set 55 * in the Java security properties file located in the file named 56 * <JAVA_HOME>/lib/security/java.security. 57 * <JAVA_HOME> refers to the value of the java.home system property, 58 * and specifies the directory where the JRE is installed. 59 * 60 * <p> If the security property is set to the fully qualified name of a 61 * <code>CallbackHandler</code> implementation class, 62 * then a <code>LoginContext</code> will load the specified 63 * <code>CallbackHandler</code> and pass it to the underlying LoginModules. 64 * The <code>LoginContext</code> only loads the default handler 65 * if it was not provided one. 66 * 67 * <p> All default handler implementations must provide a public 68 * zero-argument constructor. 69 * 70 */ 71 public interface CallbackHandler { 72 73 /** 74 * <p> Retrieve or display the information requested in the 75 * provided Callbacks. 76 * 77 * <p> The <code>handle</code> method implementation checks the 78 * instance(s) of the <code>Callback</code> object(s) passed in 79 * to retrieve or display the requested information. 80 * The following example is provided to help demonstrate what an 81 * <code>handle</code> method implementation might look like. 82 * This example code is for guidance only. Many details, 83 * including proper error handling, are left out for simplicity. 84 * 85 * <pre> 86 * public void handle(Callback[] callbacks) 87 * throws IOException, UnsupportedCallbackException { 88 * 89 * for (int i = 0; i < callbacks.length; i++) { 90 * if (callbacks[i] instanceof TextOutputCallback) { 91 * 92 * // display the message according to the specified type 93 * TextOutputCallback toc = (TextOutputCallback)callbacks[i]; 94 * switch (toc.getMessageType()) { 95 * case TextOutputCallback.INFORMATION: 96 * System.out.println(toc.getMessage()); 97 * break; 98 * case TextOutputCallback.ERROR: 99 * System.out.println("ERROR: " + toc.getMessage()); 100 * break; 101 * case TextOutputCallback.WARNING: 102 * System.out.println("WARNING: " + toc.getMessage()); 103 * break; 104 * default: 105 * throw new IOException("Unsupported message type: " + 106 * toc.getMessageType()); 107 * } 108 * 109 * } else if (callbacks[i] instanceof NameCallback) { 110 * 111 * // prompt the user for a username 112 * NameCallback nc = (NameCallback)callbacks[i]; 113 * 114 * // ignore the provided defaultName 115 * System.err.print(nc.getPrompt()); 116 * System.err.flush(); 117 * nc.setName((new BufferedReader 118 * (new InputStreamReader(System.in))).readLine()); 119 * 120 * } else if (callbacks[i] instanceof PasswordCallback) { 121 * 122 * // prompt the user for sensitive information 123 * PasswordCallback pc = (PasswordCallback)callbacks[i]; 124 * System.err.print(pc.getPrompt()); 125 * System.err.flush(); 126 * pc.setPassword(readPassword(System.in)); 127 * 128 * } else { 129 * throw new UnsupportedCallbackException 130 * (callbacks[i], "Unrecognized Callback"); 131 * } 132 * } 133 * } 134 * 135 * // Reads user password from given input stream. 136 * private char[] readPassword(InputStream in) throws IOException { 137 * // insert code to read a user password from the input stream 138 * } 139 * </pre> 140 * 141 * @param callbacks an array of <code>Callback</code> objects provided 142 * by an underlying security service which contains 143 * the information requested to be retrieved or displayed. 144 * 145 * @exception java.io.IOException if an input or output error occurs. <p> 146 * 147 * @exception UnsupportedCallbackException if the implementation of this 148 * method does not support one or more of the Callbacks 149 * specified in the <code>callbacks</code> parameter. 150 */ handle(Callback[] callbacks)151 void handle(Callback[] callbacks) 152 throws java.io.IOException, UnsupportedCallbackException; 153 } 154