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