1/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 2/* vim: set sw=2 ts=8 et tw=80 : */ 3/* This Source Code Form is subject to the terms of the Mozilla Public 4 * License, v. 2.0. If a copy of the MPL was not distributed with this 5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 6 7#include "nsICancelable.idl" 8 9interface nsIHttpChannel; 10interface nsIHttpAuthenticableChannel; 11 12/** 13 * nsIHttpChannelAuthProvider 14 * 15 * This interface is intended for providing authentication for http-style 16 * channels, like nsIHttpChannel and nsIWebSocket, which implement the 17 * nsIHttpAuthenticableChannel interface. 18 * 19 * When requesting pages AddAuthorizationHeaders MUST be called 20 * in order to get the http cached headers credentials. When the request is 21 * unsuccessful because of receiving either a 401 or 407 http response code 22 * ProcessAuthentication MUST be called and the page MUST be requested again 23 * with the new credentials that the user has provided. After a successful 24 * request, checkForSuperfluousAuth MAY be called, and disconnect MUST be 25 * called. 26 */ 27 28[scriptable, uuid(788f331b-2e1f-436c-b405-4f88a31a105b)] 29interface nsIHttpChannelAuthProvider : nsICancelable 30{ 31 /** 32 * Initializes the http authentication support for the channel. 33 * Implementations must hold a weak reference of the channel. 34 */ 35 [must_use] void init(in nsIHttpAuthenticableChannel channel); 36 37 /** 38 * Upon receipt of a server challenge, this function is called to determine 39 * the credentials to send. 40 * 41 * @param httpStatus 42 * the http status received. 43 * @param sslConnectFailed 44 * if the last ssl tunnel connection attempt was or not successful. 45 * @param callback 46 * the callback to be called when it returns NS_ERROR_IN_PROGRESS. 47 * The implementation must hold a weak reference. 48 * 49 * @returns NS_OK if the credentials were got and set successfully. 50 * NS_ERROR_IN_PROGRESS if the credentials are going to be asked to 51 * the user. The channel reference must be 52 * alive until the feedback from 53 * nsIHttpAuthenticableChannel's methods or 54 * until disconnect be called. 55 */ 56 [must_use] void processAuthentication(in unsigned long httpStatus, 57 in boolean sslConnectFailed); 58 59 /** 60 * Add credentials from the http auth cache. 61 * 62 * @param dontUseCachedWWWCreds 63 * When true, the method will not add any Authorization headers from 64 * the auth cache. 65 */ 66 [must_use] void addAuthorizationHeaders(in boolean dontUseCachedWWWCreds); 67 68 /** 69 * Check if an unnecessary(and maybe malicious) url authentication has been 70 * provided. 71 */ 72 [must_use] void checkForSuperfluousAuth(); 73 74 /** 75 * Cancel pending user auth prompts and release the callback and channel 76 * weak references. 77 */ 78 [must_use] void disconnect(in nsresult status); 79}; 80