nsIHttpMoonshot.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * The contents of this file are subject to the Mozilla Public
   4  * License Version 1.1 (the "License"); you may not use this file
   5  * except in compliance with the License. You may obtain a copy of
   6  * the License at http://www.mozilla.org/MPL/
   7  *
   8  * Software distributed under the License is distributed on an "AS
   9  * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
  10  * implied. See the License for the specific language governing
  11  * rights and limitations under the License.
  12  *
  13  * The Original Code is Mozilla.
  14  *
  15  * The Initial Developer of the Original Code is Netscape
  16  * Communications.  Portions created by Netscape Communications are
  17  * Copyright (C) 2001 by Netscape Communications.  All
  18  * Rights Reserved.
  19  *
  20  * Contributor(s):
  21  *   Darin Fisher <darin@netscape.com> (original author)
  22  */
  23
  24 #include "nsISupports.idl"
  25
  26 #include "nsIHttpChannel.idl"
  27
  28 /**
  29  * nsIHttpAuthenticator
  30  *
  31  * Interface designed to allow for pluggable HTTP authentication modules.
  32  * Implementations are registered under the ContractID:
  33  *
  34  *   "@mozilla.org/network/http-authenticator;1?scheme=<auth-scheme>"
  35  *
  36  * where <auth-scheme> is the lower-cased value of the authentication scheme
  37  * found in the server challenge per the rules of RFC 2617.
  38  */
  39 [scriptable, uuid(0f331436-8bc8-4c68-a124-d0253a19d06f)]
  40 interface nsIHttpAuthenticator: nsISupports
  41 {
  42     /**
  43      * Upon receipt of a server challenge, this function is called to determine
  44      * whether or not the current user identity has been rejected.  If true,
  45      * then the user will be prompted by the channel to enter (or revise) their
  46      * identity.  Following this, generateCredentials will be called.
  47      *
  48      * If the IDENTITY_IGNORED auth flag is set, then the aInvalidateIdentity
  49      * return value will be ignored, and user prompting will be suppressed.
  50      *
  51      * @param aChannel
  52      *        the http channel that received the challenge.
  53      * @param aChallenge
  54      *        the challenge from the WWW-Authenticate/Proxy-Authenticate
  55      *        server response header.  (possibly from the auth cache.)
  56      * @param aProxyAuth
  57      *        flag indicating whether or not aChallenge is from a proxy.
  58      * @param aSessionState
  59      *        see description below for generateCredentials.
  60      * @param aContinuationState
  61      *        see description below for generateCredentials.
  62      * @param aInvalidateIdentity
  63      *        return value indicating whether or not to prompt the user for a
  64      *        revised identity.
  65      */
  66     void challengeReceived(in nsIHttpChannel aChannel,
  67                            in string         aChallenge,
  68                            in boolean        aProxyAuth,
  69                            inout nsISupports aSessionState,
  70                            inout nsISupports aContinuationState,
  71                            out boolean       aInvalidatesIdentity);
  72
  73     /**
  74      * Called to generate the authentication credentials for a particular
  75      * server/proxy challenge.  This is the value that will be sent back
  76      * to the server via an Authorization/Proxy-Authorization header.
  77      *
  78      * This function may be called using a cached challenge provided the
  79      * authenticator sets the REUSABLE_CHALLENGE flag.
  80      *
  81      * @param aChannel
  82      *        the http channel requesting credentials
  83      * @param aChallenge
  84      *        the challenge from the WWW-Authenticate/Proxy-Authenticate
  85      *        server response header.  (possibly from the auth cache.)
  86      * @param aProxyAuth
  87      *        flag indicating whether or not aChallenge is from a proxy.
  88      * @param aDomain
  89      *        string containing the domain name (if appropriate)
  90      * @param aUser
  91      *        string containing the user name
  92      * @param aPassword
  93      *        string containing the password
  94      * @param aSessionState
  95      *        state stored along side the user's identity in the auth cache
  96      *        for the lifetime of the browser session.  if a new auth cache
  97      *        entry is created for this challenge, then this parameter will
  98      *        be null.  on return, the result will be stored in the new auth
  99      *        cache entry.  this parameter is non-null when an auth cache entry
 100      *        is being reused.
 101      * @param aContinuationState
 102      *        state held by the channel between consecutive calls to
 103      *        generateCredentials, assuming multiple calls are required
 104      *        to authenticate.  this state is held for at most the lifetime of
 105      *        the channel.
 106      */
 107     string generateCredentials(in nsIHttpChannel aChannel,
 108                                in string         aChallenge,
 109                                in boolean        aProxyAuth,
 110                                in wstring        aDomain,
 111                                in wstring        aUser,
 112                                in wstring        aPassword,
 113                                inout nsISupports aSessionState,
 114                                inout nsISupports aContinuationState);
 115
 116     /**
 117      * Flags defining various properties of the authenticator.
 118      */
 119     readonly attribute unsigned long authFlags;
 120
 121     /**
 122      * A request based authentication scheme only authenticates an individual
 123      * request (or a set of requests under the same authentication domain as
 124      * defined by RFC 2617).  BASIC and DIGEST are request based authentication
 125      * schemes.
 126      */
 127     const unsigned long REQUEST_BASED = (1<<0);
 128
 129     /**
 130      * A connection based authentication scheme authenticates an individual
 131      * connection.  Multiple requests may be issued over the connection without
 132      * repeating the authentication steps.  Connection based authentication
 133      * schemes can associate state with the connection being authenticated via
 134      * the aContinuationState parameter (see generateCredentials).
 135      */
 136     const unsigned long CONNECTION_BASED = (1<<1);
 137
 138     /**
 139      * The credentials returned from generateCredentials may be reused with any
 140      * other URLs within "the protection space" as defined by RFC 2617 section
 141      * 1.2.  If this flag is not set, then generateCredentials must be called
 142      * for each request within the protection space.  REUSABLE_CREDENTIALS
 143      * implies REUSABLE_CHALLENGE.
 144      */
 145     const unsigned long REUSABLE_CREDENTIALS = (1<<2);
 146
 147     /**
 148      * A challenge may be reused to later generate credentials in anticipation
 149      * of a duplicate server challenge for URLs within "the protection space"
 150      * as defined by RFC 2617 section 1.2.
 151      */
 152     const unsigned long REUSABLE_CHALLENGE = (1<<3);
 153
 154     /**
 155      * This flag indicates that the identity of the user is not required by
 156      * this authentication scheme.
 157      */
 158     const unsigned long IDENTITY_IGNORED = (1<<10);
 159
 160     /**
 161      * This flag indicates that the identity of the user includes a domain
 162      * attribute that the user must supply.
 163      */
 164     const unsigned long IDENTITY_INCLUDES_DOMAIN = (1<<11);
 165 };