gecko/netwerk/protocol/http/nsIHttpAuthenticator.idl

207 lines
8.7 KiB
Plaintext

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* ***** BEGIN LICENSE BLOCK *****
* Version: MPL 1.1/GPL 2.0/LGPL 2.1
*
* The contents of this file are subject to the Mozilla Public License Version
* 1.1 (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
* http://www.mozilla.org/MPL/
*
* Software distributed under the License is distributed on an "AS IS" basis,
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
* for the specific language governing rights and limitations under the
* License.
*
* The Original Code is Mozilla.
*
* The Initial Developer of the Original Code is
* Netscape Communications.
* Portions created by the Initial Developer are Copyright (C) 2001
* the Initial Developer. All Rights Reserved.
*
* Contributor(s):
* Darin Fisher <darin@netscape.com> (original author)
*
* Alternatively, the contents of this file may be used under the terms of
* either the GNU General Public License Version 2 or later (the "GPL"), or
* the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
* in which case the provisions of the GPL or the LGPL are applicable instead
* of those above. If you wish to allow use of your version of this file only
* under the terms of either the GPL or the LGPL, and not to allow others to
* use your version of this file under the terms of the MPL, indicate your
* decision by deleting the provisions above and replace them with the notice
* and other provisions required by the GPL or the LGPL. If you do not delete
* the provisions above, a recipient may use your version of this file under
* the terms of any one of the MPL, the GPL or the LGPL.
*
* ***** END LICENSE BLOCK ***** */
#include "nsISupports.idl"
interface nsIHttpAuthenticableChannel;
/**
* nsIHttpAuthenticator
*
* Interface designed to allow for pluggable HTTP authentication modules.
* Implementations are registered under the ContractID:
*
* "@mozilla.org/network/http-authenticator;1?scheme=<auth-scheme>"
*
* where <auth-scheme> is the lower-cased value of the authentication scheme
* found in the server challenge per the rules of RFC 2617.
*/
[scriptable, uuid(16784db0-fcb1-4352-b0c9-6a3a67e3cf79)]
interface nsIHttpAuthenticator : nsISupports
{
/**
* Upon receipt of a server challenge, this function is called to determine
* whether or not the current user identity has been rejected. If true,
* then the user will be prompted by the channel to enter (or revise) their
* identity. Following this, generateCredentials will be called.
*
* If the IDENTITY_IGNORED auth flag is set, then the aInvalidateIdentity
* return value will be ignored, and user prompting will be suppressed.
*
* @param aChannel
* the http channel that received the challenge.
* @param aChallenge
* the challenge from the WWW-Authenticate/Proxy-Authenticate
* server response header. (possibly from the auth cache.)
* @param aProxyAuth
* flag indicating whether or not aChallenge is from a proxy.
* @param aSessionState
* see description below for generateCredentials.
* @param aContinuationState
* see description below for generateCredentials.
* @param aInvalidateIdentity
* return value indicating whether or not to prompt the user for a
* revised identity.
*/
void challengeReceived(in nsIHttpAuthenticableChannel aChannel,
in string aChallenge,
in boolean aProxyAuth,
inout nsISupports aSessionState,
inout nsISupports aContinuationState,
out boolean aInvalidatesIdentity);
/**
* Called to generate the authentication credentials for a particular
* server/proxy challenge. This is the value that will be sent back
* to the server via an Authorization/Proxy-Authorization header.
*
* This function may be called using a cached challenge provided the
* authenticator sets the REUSABLE_CHALLENGE flag.
*
* @param aChannel
* the http channel requesting credentials
* @param aChallenge
* the challenge from the WWW-Authenticate/Proxy-Authenticate
* server response header. (possibly from the auth cache.)
* @param aProxyAuth
* flag indicating whether or not aChallenge is from a proxy.
* @param aDomain
* string containing the domain name (if appropriate)
* @param aUser
* string containing the user name
* @param aPassword
* string containing the password
* @param aSessionState
* state stored along side the user's identity in the auth cache
* for the lifetime of the browser session. if a new auth cache
* entry is created for this challenge, then this parameter will
* be null. on return, the result will be stored in the new auth
* cache entry. this parameter is non-null when an auth cache entry
* is being reused.
* @param aContinuationState
* state held by the channel between consecutive calls to
* generateCredentials, assuming multiple calls are required
* to authenticate. this state is held for at most the lifetime of
* the channel.
* @param aFlags
* authenticator may return one of the generate flags bellow.
*/
string generateCredentials(in nsIHttpAuthenticableChannel aChannel,
in string aChallenge,
in boolean aProxyAuth,
in wstring aDomain,
in wstring aUser,
in wstring aPassword,
inout nsISupports aSessionState,
inout nsISupports aContinuationState,
out unsigned long aFlags);
/**
* Generate flags
*/
/**
* Indicates that the authenticator has used an out-of-band or internal
* source of identity and tells the consumer that it must not cache
* the returned identity because it might not be valid and would overwrite
* the cached identity. See bug 542318 comment 32.
*/
const unsigned long USING_INTERNAL_IDENTITY = (1<<0);
/**
* Flags defining various properties of the authenticator.
*/
readonly attribute unsigned long authFlags;
/**
* A request based authentication scheme only authenticates an individual
* request (or a set of requests under the same authentication domain as
* defined by RFC 2617). BASIC and DIGEST are request based authentication
* schemes.
*/
const unsigned long REQUEST_BASED = (1<<0);
/**
* A connection based authentication scheme authenticates an individual
* connection. Multiple requests may be issued over the connection without
* repeating the authentication steps. Connection based authentication
* schemes can associate state with the connection being authenticated via
* the aContinuationState parameter (see generateCredentials).
*/
const unsigned long CONNECTION_BASED = (1<<1);
/**
* The credentials returned from generateCredentials may be reused with any
* other URLs within "the protection space" as defined by RFC 2617 section
* 1.2. If this flag is not set, then generateCredentials must be called
* for each request within the protection space. REUSABLE_CREDENTIALS
* implies REUSABLE_CHALLENGE.
*/
const unsigned long REUSABLE_CREDENTIALS = (1<<2);
/**
* A challenge may be reused to later generate credentials in anticipation
* of a duplicate server challenge for URLs within "the protection space"
* as defined by RFC 2617 section 1.2.
*/
const unsigned long REUSABLE_CHALLENGE = (1<<3);
/**
* This flag indicates that the identity of the user is not required by
* this authentication scheme.
*/
const unsigned long IDENTITY_IGNORED = (1<<10);
/**
* This flag indicates that the identity of the user includes a domain
* attribute that the user must supply.
*/
const unsigned long IDENTITY_INCLUDES_DOMAIN = (1<<11);
/**
* This flag indicates that the identity will be sent encrypted. It does
* not make sense to combine this flag with IDENTITY_IGNORED.
*/
const unsigned long IDENTITY_ENCRYPTED = (1<<12);
};
%{C++
#define NS_HTTP_AUTHENTICATOR_CONTRACTID_PREFIX \
"@mozilla.org/network/http-authenticator;1?scheme="
%}