19439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly/* 29439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * Copyright (c) 2008-2009, Motorola, Inc. 39439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * 49439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * All rights reserved. 59439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * 69439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * Redistribution and use in source and binary forms, with or without 79439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * modification, are permitted provided that the following conditions are met: 89439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * 99439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * - Redistributions of source code must retain the above copyright notice, 109439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * this list of conditions and the following disclaimer. 119439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * 129439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * - Redistributions in binary form must reproduce the above copyright notice, 139439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * this list of conditions and the following disclaimer in the documentation 149439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * and/or other materials provided with the distribution. 159439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * 169439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * - Neither the name of the Motorola, Inc. nor the names of its contributors 179439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * may be used to endorse or promote products derived from this software 189439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * without specific prior written permission. 199439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * 209439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 219439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 229439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 239439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 249439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 259439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 269439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 279439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 289439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 299439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 309439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * POSSIBILITY OF SUCH DAMAGE. 319439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly */ 329439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly 339439a7fe517b858bc5e5c654b459315e4722feb2Nick Pellypackage javax.obex; 349439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly 359439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly/** 369439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * This interface provides a way to respond to authentication challenge and 3705ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * authentication response headers. When a client or server receives an 389439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * authentication challenge or authentication response header, the 399439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <code>onAuthenticationChallenge()</code> or 4005ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * <code>onAuthenticationResponse()</code> will be called, respectively, by the 4105ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * implementation. 429439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <P> 439439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * For more information on how the authentication procedure works in OBEX, 4405ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * please review the IrOBEX specification at <A 4505ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * HREF="http://www.irda.org">http://www.irda.org</A>. 469439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <P> 479439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <STRONG>Authentication Challenges</STRONG> 489439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <P> 499439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * When a client or server receives an authentication challenge header, the 5005ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * <code>onAuthenticationChallenge()</code> method will be invoked by the OBEX 5105ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * API implementation. The application will then return the user name (if 5205ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * needed) and password via a <code>PasswordAuthentication</code> object. The 5305ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * password in this object is not sent in the authentication response. Instead, 5405ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * the 16-byte challenge received in the authentication challenge is combined 5505ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * with the password returned from the <code>onAuthenticationChallenge()</code> 5605ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * method and passed through the MD5 hash algorithm. The resulting value is sent 5705ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * in the authentication response along with the user name if it was provided. 589439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <P> 599439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <STRONG>Authentication Responses</STRONG> 609439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <P> 619439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * When a client or server receives an authentication response header, the 629439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <code>onAuthenticationResponse()</code> method is invoked by the API 639439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * implementation with the user name received in the authentication response 6405ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * header. (The user name will be <code>null</code> if no user name was provided 6505ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * in the authentication response header.) The application must determine the 6605ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * correct password. This value should be returned from the 6705ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * <code>onAuthenticationResponse()</code> method. If the authentication request 6805ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * should fail without the implementation checking the password, 6905ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * <code>null</code> should be returned by the application. (This is needed for 7005ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * reasons like not recognizing the user name, etc.) If the returned value is 7105ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * not <code>null</code>, the OBEX API implementation will combine the password 729439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * returned from the <code>onAuthenticationResponse()</code> method and 739439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * challenge sent via the authentication challenge, apply the MD5 hash 749439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * algorithm, and compare the result to the response hash received in the 7505ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * authentication response header. If the values are not equal, an 7605ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * <code>IOException</code> will be thrown if the client requested 7705ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * authentication. If the server requested authentication, the 789439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <code>onAuthenticationFailure()</code> method will be called on the 7905ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * <code>ServerRequestHandler</code> that failed authentication. The connection 8005ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * is <B>not</B> closed if authentication failed. 812e0da96e757a977154063f980d3f4e1abd41cf09Nick Pelly * @hide 829439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly */ 839439a7fe517b858bc5e5c654b459315e4722feb2Nick Pellypublic interface Authenticator { 849439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly 859439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly /** 869439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * Called when a client or a server receives an authentication challenge 879439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * header. It should respond to the challenge with a 889439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <code>PasswordAuthentication</code> that contains the correct user name 899439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * and password for the challenge. 9005ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * @param description the description of which user name and password should 9105ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * be used; if no description is provided in the authentication 9205ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * challenge or the description is encoded in an encoding scheme that 9305ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * is not supported, an empty string will be provided 949439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * @param isUserIdRequired <code>true</code> if the user ID is required; 9505ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * <code>false</code> if the user ID is not required 9605ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * @param isFullAccess <code>true</code> if full access to the server will 9705ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * be granted; <code>false</code> if read only access will be granted 9805ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * @return a <code>PasswordAuthentication</code> object containing the user 9905ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * name and password used for authentication 1009439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly */ 1013998bf009acaf8cde4d7f837f8b8e41ae0a65141Tao Liejun PasswordAuthentication onAuthenticationChallenge(String description, boolean isUserIdRequired, 1023998bf009acaf8cde4d7f837f8b8e41ae0a65141Tao Liejun boolean isFullAccess); 1039439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly 1049439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly /** 1059439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * Called when a client or server receives an authentication response 10605ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * header. This method will provide the user name and expect the correct 1079439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * password to be returned. 10805ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * @param userName the user name provided in the authentication response; may 10905ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * be <code>null</code> 1109439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * @return the correct password for the user name provided; if 11105ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * <code>null</code> is returned then the authentication request 11205ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * failed 1139439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly */ 1143998bf009acaf8cde4d7f837f8b8e41ae0a65141Tao Liejun byte[] onAuthenticationResponse(byte[] userName); 1159439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly} 116