001/* 002 * ==================================================================== 003 * Licensed to the Apache Software Foundation (ASF) under one 004 * or more contributor license agreements. See the NOTICE file 005 * distributed with this work for additional information 006 * regarding copyright ownership. The ASF licenses this file 007 * to you under the Apache License, Version 2.0 (the 008 * "License"); you may not use this file except in compliance 009 * with the License. You may obtain a copy of the License at 010 * 011 * http://www.apache.org/licenses/LICENSE-2.0 012 * 013 * Unless required by applicable law or agreed to in writing, 014 * software distributed under the License is distributed on an 015 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 016 * KIND, either express or implied. See the License for the 017 * specific language governing permissions and limitations 018 * under the License. 019 * ==================================================================== 020 * 021 * This software consists of voluntary contributions made by many 022 * individuals on behalf of the Apache Software Foundation. For more 023 * information on the Apache Software Foundation, please see 024 * <http://www.apache.org/>. 025 * 026 */ 027package org.apache.http.auth; 028 029import org.apache.http.Header; 030import org.apache.http.HttpRequest; 031 032/** 033 * This interface represents an abstract challenge-response oriented 034 * authentication scheme. 035 * <p> 036 * An authentication scheme should be able to support the following 037 * functions: 038 * <ul> 039 * <li>Parse and process the challenge sent by the target server 040 * in response to request for a protected resource 041 * <li>Provide its textual designation 042 * <li>Provide its parameters, if available 043 * <li>Provide the realm this authentication scheme is applicable to, 044 * if available 045 * <li>Generate authorization string for the given set of credentials 046 * and the HTTP request in response to the authorization challenge. 047 * </ul> 048 * <p> 049 * Authentication schemes may be stateful involving a series of 050 * challenge-response exchanges. 051 * <p> 052 * IMPORTANT: implementations of this interface MUST also implement {@link ContextAwareAuthScheme} 053 * interface in order to remain API compatible with newer versions of HttpClient. 054 * 055 * @since 4.0 056 */ 057 058public interface AuthScheme { 059 060 /** 061 * Processes the given challenge token. Some authentication schemes 062 * may involve multiple challenge-response exchanges. Such schemes must be able 063 * to maintain the state information when dealing with sequential challenges 064 * 065 * @param header the challenge header 066 */ 067 void processChallenge(final Header header) throws MalformedChallengeException; 068 069 /** 070 * Returns textual designation of the given authentication scheme. 071 * 072 * @return the name of the given authentication scheme 073 */ 074 String getSchemeName(); 075 076 /** 077 * Returns authentication parameter with the given name, if available. 078 * 079 * @param name The name of the parameter to be returned 080 * 081 * @return the parameter with the given name 082 */ 083 String getParameter(final String name); 084 085 /** 086 * Returns authentication realm. If the concept of an authentication 087 * realm is not applicable to the given authentication scheme, returns 088 * {@code null}. 089 * 090 * @return the authentication realm 091 */ 092 String getRealm(); 093 094 /** 095 * Tests if the authentication scheme is provides authorization on a per 096 * connection basis instead of usual per request basis 097 * 098 * @return {@code true} if the scheme is connection based, {@code false} 099 * if the scheme is request based. 100 */ 101 boolean isConnectionBased(); 102 103 /** 104 * Authentication process may involve a series of challenge-response exchanges. 105 * This method tests if the authorization process has been completed, either 106 * successfully or unsuccessfully, that is, all the required authorization 107 * challenges have been processed in their entirety. 108 * 109 * @return {@code true} if the authentication process has been completed, 110 * {@code false} otherwise. 111 */ 112 boolean isComplete(); 113 114 /** 115 * Produces an authorization string for the given set of {@link Credentials}. 116 * 117 * @param credentials The set of credentials to be used for athentication 118 * @param request The request being authenticated 119 * @throws AuthenticationException if authorization string cannot 120 * be generated due to an authentication failure 121 * 122 * @return the authorization string 123 * 124 * @deprecated (4.1) Use {@link ContextAwareAuthScheme#authenticate(Credentials, HttpRequest, org.apache.http.protocol.HttpContext)} 125 */ 126 @Deprecated 127 Header authenticate(Credentials credentials, HttpRequest request) 128 throws AuthenticationException; 129 130}