1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/protocol/http/nsIHttpAuthenticator.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,173 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +interface nsIHttpAuthenticableChannel;
1.12 +
1.13 +/**
1.14 + * nsIHttpAuthenticator
1.15 + *
1.16 + * Interface designed to allow for pluggable HTTP authentication modules.
1.17 + * Implementations are registered under the ContractID:
1.18 + *
1.19 + * "@mozilla.org/network/http-authenticator;1?scheme=<auth-scheme>"
1.20 + *
1.21 + * where <auth-scheme> is the lower-cased value of the authentication scheme
1.22 + * found in the server challenge per the rules of RFC 2617.
1.23 + */
1.24 +[scriptable, uuid(16784db0-fcb1-4352-b0c9-6a3a67e3cf79)]
1.25 +interface nsIHttpAuthenticator : nsISupports
1.26 +{
1.27 + /**
1.28 + * Upon receipt of a server challenge, this function is called to determine
1.29 + * whether or not the current user identity has been rejected. If true,
1.30 + * then the user will be prompted by the channel to enter (or revise) their
1.31 + * identity. Following this, generateCredentials will be called.
1.32 + *
1.33 + * If the IDENTITY_IGNORED auth flag is set, then the aInvalidateIdentity
1.34 + * return value will be ignored, and user prompting will be suppressed.
1.35 + *
1.36 + * @param aChannel
1.37 + * the http channel that received the challenge.
1.38 + * @param aChallenge
1.39 + * the challenge from the WWW-Authenticate/Proxy-Authenticate
1.40 + * server response header. (possibly from the auth cache.)
1.41 + * @param aProxyAuth
1.42 + * flag indicating whether or not aChallenge is from a proxy.
1.43 + * @param aSessionState
1.44 + * see description below for generateCredentials.
1.45 + * @param aContinuationState
1.46 + * see description below for generateCredentials.
1.47 + * @param aInvalidateIdentity
1.48 + * return value indicating whether or not to prompt the user for a
1.49 + * revised identity.
1.50 + */
1.51 + void challengeReceived(in nsIHttpAuthenticableChannel aChannel,
1.52 + in string aChallenge,
1.53 + in boolean aProxyAuth,
1.54 + inout nsISupports aSessionState,
1.55 + inout nsISupports aContinuationState,
1.56 + out boolean aInvalidatesIdentity);
1.57 +
1.58 + /**
1.59 + * Called to generate the authentication credentials for a particular
1.60 + * server/proxy challenge. This is the value that will be sent back
1.61 + * to the server via an Authorization/Proxy-Authorization header.
1.62 + *
1.63 + * This function may be called using a cached challenge provided the
1.64 + * authenticator sets the REUSABLE_CHALLENGE flag.
1.65 + *
1.66 + * @param aChannel
1.67 + * the http channel requesting credentials
1.68 + * @param aChallenge
1.69 + * the challenge from the WWW-Authenticate/Proxy-Authenticate
1.70 + * server response header. (possibly from the auth cache.)
1.71 + * @param aProxyAuth
1.72 + * flag indicating whether or not aChallenge is from a proxy.
1.73 + * @param aDomain
1.74 + * string containing the domain name (if appropriate)
1.75 + * @param aUser
1.76 + * string containing the user name
1.77 + * @param aPassword
1.78 + * string containing the password
1.79 + * @param aSessionState
1.80 + * state stored along side the user's identity in the auth cache
1.81 + * for the lifetime of the browser session. if a new auth cache
1.82 + * entry is created for this challenge, then this parameter will
1.83 + * be null. on return, the result will be stored in the new auth
1.84 + * cache entry. this parameter is non-null when an auth cache entry
1.85 + * is being reused.
1.86 + * @param aContinuationState
1.87 + * state held by the channel between consecutive calls to
1.88 + * generateCredentials, assuming multiple calls are required
1.89 + * to authenticate. this state is held for at most the lifetime of
1.90 + * the channel.
1.91 + * @param aFlags
1.92 + * authenticator may return one of the generate flags bellow.
1.93 + */
1.94 + string generateCredentials(in nsIHttpAuthenticableChannel aChannel,
1.95 + in string aChallenge,
1.96 + in boolean aProxyAuth,
1.97 + in wstring aDomain,
1.98 + in wstring aUser,
1.99 + in wstring aPassword,
1.100 + inout nsISupports aSessionState,
1.101 + inout nsISupports aContinuationState,
1.102 + out unsigned long aFlags);
1.103 +
1.104 + /**
1.105 + * Generate flags
1.106 + */
1.107 +
1.108 + /**
1.109 + * Indicates that the authenticator has used an out-of-band or internal
1.110 + * source of identity and tells the consumer that it must not cache
1.111 + * the returned identity because it might not be valid and would overwrite
1.112 + * the cached identity. See bug 542318 comment 32.
1.113 + */
1.114 + const unsigned long USING_INTERNAL_IDENTITY = (1<<0);
1.115 +
1.116 + /**
1.117 + * Flags defining various properties of the authenticator.
1.118 + */
1.119 + readonly attribute unsigned long authFlags;
1.120 +
1.121 + /**
1.122 + * A request based authentication scheme only authenticates an individual
1.123 + * request (or a set of requests under the same authentication domain as
1.124 + * defined by RFC 2617). BASIC and DIGEST are request based authentication
1.125 + * schemes.
1.126 + */
1.127 + const unsigned long REQUEST_BASED = (1<<0);
1.128 +
1.129 + /**
1.130 + * A connection based authentication scheme authenticates an individual
1.131 + * connection. Multiple requests may be issued over the connection without
1.132 + * repeating the authentication steps. Connection based authentication
1.133 + * schemes can associate state with the connection being authenticated via
1.134 + * the aContinuationState parameter (see generateCredentials).
1.135 + */
1.136 + const unsigned long CONNECTION_BASED = (1<<1);
1.137 +
1.138 + /**
1.139 + * The credentials returned from generateCredentials may be reused with any
1.140 + * other URLs within "the protection space" as defined by RFC 2617 section
1.141 + * 1.2. If this flag is not set, then generateCredentials must be called
1.142 + * for each request within the protection space. REUSABLE_CREDENTIALS
1.143 + * implies REUSABLE_CHALLENGE.
1.144 + */
1.145 + const unsigned long REUSABLE_CREDENTIALS = (1<<2);
1.146 +
1.147 + /**
1.148 + * A challenge may be reused to later generate credentials in anticipation
1.149 + * of a duplicate server challenge for URLs within "the protection space"
1.150 + * as defined by RFC 2617 section 1.2.
1.151 + */
1.152 + const unsigned long REUSABLE_CHALLENGE = (1<<3);
1.153 +
1.154 + /**
1.155 + * This flag indicates that the identity of the user is not required by
1.156 + * this authentication scheme.
1.157 + */
1.158 + const unsigned long IDENTITY_IGNORED = (1<<10);
1.159 +
1.160 + /**
1.161 + * This flag indicates that the identity of the user includes a domain
1.162 + * attribute that the user must supply.
1.163 + */
1.164 + const unsigned long IDENTITY_INCLUDES_DOMAIN = (1<<11);
1.165 +
1.166 + /**
1.167 + * This flag indicates that the identity will be sent encrypted. It does
1.168 + * not make sense to combine this flag with IDENTITY_IGNORED.
1.169 + */
1.170 + const unsigned long IDENTITY_ENCRYPTED = (1<<12);
1.171 +};
1.172 +
1.173 +%{C++
1.174 +#define NS_HTTP_AUTHENTICATOR_CONTRACTID_PREFIX \
1.175 + "@mozilla.org/network/http-authenticator;1?scheme="
1.176 +%}
