nsIProtocolHandler.idl (11514B)
1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ 2 /* This Source Code Form is subject to the terms of the Mozilla Public 3 * License, v. 2.0. If a copy of the MPL was not distributed with this 4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 5 6 #include "nsISupports.idl" 7 8 %{C++ 9 #include "nsCOMPtr.h" 10 11 /** 12 * Protocol handlers are registered with XPCOM under the following CONTRACTID prefix: 13 */ 14 #define NS_NETWORK_PROTOCOL_CONTRACTID_PREFIX "@mozilla.org/network/protocol;1?name=" 15 /** 16 * For example, "@mozilla.org/network/protocol;1?name=http" 17 */ 18 19 #if defined(MOZ_THUNDERBIRD) || defined(MOZ_SUITE) 20 #define IS_ORIGIN_IS_FULL_SPEC_DEFINED 1 21 #endif 22 %} 23 24 interface nsIURI; 25 interface nsIChannel; 26 interface nsILoadInfo; 27 28 /** 29 * nsIProtocolHandlerWithDynamicFlags 30 * 31 * Protocols that wish to return different flags depending on the URI should 32 * implement this interface. 33 */ 34 [scriptable, builtinclass, uuid(65a8e823-0591-4fc0-a56a-03265e0a4ce8)] 35 interface nsIProtocolHandlerWithDynamicFlags : nsISupports 36 { 37 /* 38 * Returns protocol flags for the given URI, which may be different from the 39 * flags for another URI of the same scheme. 40 * 41 * Only DYNAMIC_URI_FLAGS may be different from the registered flags for the 42 * protocol handler. 43 */ 44 unsigned long getFlagsForURI(in nsIURI aURI); 45 }; 46 47 /** 48 * nsIProtocolHandler 49 */ 50 [scriptable, uuid(a87210e6-7c8c-41f7-864d-df809015193e)] 51 interface nsIProtocolHandler : nsISupports 52 { 53 /** 54 * The scheme of this protocol (e.g., "file"). 55 */ 56 readonly attribute ACString scheme; 57 58 /** 59 * Constructs a new channel from the given URI for this protocol handler and 60 * sets the loadInfo for the constructed channel. 61 */ 62 nsIChannel newChannel(in nsIURI aURI, in nsILoadInfo aLoadinfo); 63 64 /** 65 * Allows a protocol to override blacklisted ports. 66 * 67 * This method will be called when there is an attempt to connect to a port 68 * that is blacklisted. For example, for most protocols, port 25 (Simple Mail 69 * Transfer) is banned. When a URI containing this "known-to-do-bad-things" 70 * port number is encountered, this function will be called to ask if the 71 * protocol handler wants to override the ban. 72 */ 73 boolean allowPort(in long port, in string scheme); 74 75 76 /************************************************************************** 77 * Constants for the protocol flags (the first is the default mask, the 78 * others are deviations): 79 * 80 * NOTE: Protocol flags are provided when the protocol handler is 81 * registered, either through a static component or dynamically with 82 * `nsIIOService.registerProtocolHandler`. 83 * 84 * NOTE: Implementation must ignore any flags they do not understand. 85 */ 86 87 /** 88 * standard full URI with authority component and concept of relative 89 * URIs (http, ...) 90 */ 91 const unsigned long URI_STD = 0; 92 93 /** 94 * no concept of relative URIs (about, javascript, finger, ...) 95 */ 96 const unsigned long URI_NORELATIVE = (1<<0); 97 98 /** 99 * no authority component (file, ...) 100 */ 101 const unsigned long URI_NOAUTH = (1<<1); 102 103 /** 104 * This protocol handler can be proxied via a proxy (socks or http) 105 * (e.g., irc, smtp, http, etc.). If the protocol supports transparent 106 * proxying, the handler should implement nsIProxiedProtocolHandler. 107 * 108 * If it supports only HTTP proxying, then it need not support 109 * nsIProxiedProtocolHandler, but should instead set the ALLOWS_PROXY_HTTP 110 * flag (see below). 111 * 112 * @see nsIProxiedProtocolHandler 113 */ 114 const unsigned long ALLOWS_PROXY = (1<<2); 115 116 /** 117 * This protocol handler can be proxied using a http proxy (e.g., http, 118 * etc.). nsIIOService::newChannelFromURI will feed URIs from this 119 * protocol handler to the HTTP protocol handler instead. This flag is 120 * ignored if ALLOWS_PROXY is not set. 121 */ 122 const unsigned long ALLOWS_PROXY_HTTP = (1<<3); 123 124 /** 125 * The URIs for this protocol have no inherent security context, so 126 * documents loaded via this protocol should inherit the security context 127 * from the document that loads them. 128 */ 129 const unsigned long URI_INHERITS_SECURITY_CONTEXT = (1<<4); 130 131 /** 132 * "Automatic" loads that would replace the document (e.g. <meta> refresh, 133 * certain types of XLinks, possibly other loads that the application 134 * decides are not user triggered) are not allowed if the originating (NOT 135 * the target) URI has this protocol flag. Note that the decision as to 136 * what constitutes an "automatic" load is made externally, by the caller 137 * of nsIScriptSecurityManager::CheckLoadURI. See documentation for that 138 * method for more information. 139 * 140 * A typical protocol that might want to set this flag is a protocol that 141 * shows highly untrusted content in a viewing area that the user expects 142 * to have a lot of control over, such as an e-mail reader. 143 */ 144 const unsigned long URI_FORBIDS_AUTOMATIC_DOCUMENT_REPLACEMENT = (1<<5); 145 146 /** 147 * +-------------------------------------------------------------------+ 148 * | | 149 * | ALL PROTOCOL HANDLERS MUST SET ONE OF THE FOLLOWING SIX FLAGS. | 150 * | | 151 * +-------------------------------------------------------------------+ 152 * 153 * * URI_LOADABLE_BY_ANYONE 154 * * URI_DANGEROUS_TO_LOAD 155 * * URI_IS_UI_RESOURCE 156 * * URI_IS_LOCAL_FILE 157 * * URI_LOADABLE_BY_SUBSUMERS 158 * * URI_IS_WEBEXTENSION_RESOURCE 159 * 160 * These flags are used to determine who is allowed to load URIs for this 161 * protocol. Note that if a URI is nested, only the flags for the 162 * innermost URI matter. See nsINestedURI. 163 * 164 * If none of these five flags are set, the ContentSecurityManager will 165 * deny the load. 166 */ 167 168 /** 169 * The URIs for this protocol can be loaded by anyone. For example, any 170 * website should be allowed to trigger a load of a URI for this protocol. 171 * Web-safe protocols like "http" should set this flag. 172 */ 173 const unsigned long URI_LOADABLE_BY_ANYONE = (1<<6); 174 175 /** 176 * The URIs for this protocol are UNSAFE if loaded by untrusted (web) 177 * content and may only be loaded by privileged code (for example, code 178 * which has the system principal). Various internal protocols should set 179 * this flag. 180 */ 181 const unsigned long URI_DANGEROUS_TO_LOAD = (1<<7); 182 183 /** 184 * The URIs for this protocol point to resources that are part of the 185 * application's user interface. There are cases when such resources may 186 * be made accessible to untrusted content such as web pages, so this is 187 * less restrictive than URI_DANGEROUS_TO_LOAD but more restrictive than 188 * URI_LOADABLE_BY_ANYONE. See the documentation for 189 * nsIScriptSecurityManager::CheckLoadURI. 190 */ 191 const unsigned long URI_IS_UI_RESOURCE = (1<<8); 192 193 /** 194 * Loading of URIs for this protocol from other origins should only be 195 * allowed if those origins should have access to the local filesystem. 196 * It's up to the application to decide what origins should have such 197 * access. Protocols like "file" that point to local data should set this 198 * flag. 199 */ 200 const unsigned long URI_IS_LOCAL_FILE = (1<<9); 201 202 /** 203 * The URIs for this protocol can be loaded only by callers with a 204 * principal that subsumes this uri. For example, privileged code and 205 * websites that are same origin as this uri. 206 */ 207 const unsigned long URI_LOADABLE_BY_SUBSUMERS = (1<<10); 208 209 /** 210 * Channels using this protocol never call OnDataAvailable 211 * on the listener passed to AsyncOpen and they therefore 212 * do not return any data that we can use. 213 */ 214 const unsigned long URI_DOES_NOT_RETURN_DATA = (1<<11); 215 216 /** 217 * URIs for this protocol are considered to be local resources. This could 218 * be a local file (URI_IS_LOCAL_FILE), a UI resource (URI_IS_UI_RESOURCE), 219 * or something else that would not hit the network. 220 */ 221 const unsigned long URI_IS_LOCAL_RESOURCE = (1<<12); 222 223 /** 224 * URIs for this protocol execute script when they are opened. 225 */ 226 const unsigned long URI_OPENING_EXECUTES_SCRIPT = (1<<13); 227 228 /** 229 * Loading channels from this protocol has side-effects that make 230 * it unsuitable for saving to a local file. 231 */ 232 const unsigned long URI_NON_PERSISTABLE = (1<<14); 233 234 /** 235 * URIs for this protocol require the webapps permission on the principal 236 * when opening URIs for a different domain. See bug#773886 237 */ 238 const unsigned long URI_CROSS_ORIGIN_NEEDS_WEBAPPS_PERM = (1<<15); 239 240 /** 241 * Channels for this protocol don't need to spin the event loop to handle 242 * Open() and reads on the resulting stream. 243 */ 244 const unsigned long URI_SYNC_LOAD_IS_OK = (1<<16); 245 246 /** 247 * All the origins whose URI has this scheme are considered potentially 248 * trustworthy. 249 * Per the SecureContext spec, https: and wss: should be considered 250 * a priori secure, and implementations may consider other, 251 * implementation-specific URI schemes as secure. 252 */ 253 const unsigned long URI_IS_POTENTIALLY_TRUSTWORTHY = (1<<17); 254 255 /** 256 * The URI corresponds to a WebExtension resource (i.e. moz-extension://). 257 * If this flag is set, the ExtensionPolicyService must be consulted to 258 * determine whether loading this URI is allowed. 259 */ 260 const unsigned long URI_IS_WEBEXTENSION_RESOURCE = (1<<18); 261 262 /** 263 * If this flag is set, then the origin for this protocol is the full URI 264 * spec, not just the scheme + host + port. 265 * 266 * Note: this is not supported in Firefox. It is currently only available 267 * in Thunderbird and SeaMonkey. 268 */ 269 const unsigned long ORIGIN_IS_FULL_SPEC = (1<<19); 270 271 /** 272 * If this flag is set, the URI does not always allow content using the same 273 * protocol to link to it. 274 */ 275 const unsigned long URI_SCHEME_NOT_SELF_LINKABLE = (1<<20); 276 277 /** 278 * The URIs for this protocol can be loaded by extensions. 279 */ 280 const unsigned long URI_LOADABLE_BY_EXTENSIONS = (1<<21); 281 282 /** 283 * This protocol handler forbids accessing cookies e.g. for mail related 284 * protocols. Only used in Mailnews (comm-central). 285 */ 286 const unsigned long URI_FORBIDS_COOKIE_ACCESS = (1<<22); 287 288 /** 289 * This URI has a webexposed origin, meaning the URI has a non-null origin 290 * See https://url.spec.whatwg.org/#origin 291 */ 292 const unsigned long URI_HAS_WEB_EXPOSED_ORIGIN = (1<<23); 293 294 /** 295 * Flags which are allowed to be different from the static flags when 296 * returned from `nsIProtocolHandlerWithDynamicFlags::getFlagsForURI`. 297 * 298 * All other flags must match the flags provided when the protocol handler 299 * was registered. 300 * 301 * The following protocols are the reasons why each flag is dynamic: 302 * about: URI_LOADABLE_BY_ANYONE, URI_DANGEROUS_TO_LOAD, URI_IS_POTENTIALLY_TRUSTWORTHY 303 * view-source: URI_LOADABLE_BY_EXTENSIONS 304 */ 305 const unsigned long DYNAMIC_URI_FLAGS = 306 URI_LOADABLE_BY_ANYONE | URI_DANGEROUS_TO_LOAD | 307 URI_IS_POTENTIALLY_TRUSTWORTHY | URI_LOADABLE_BY_EXTENSIONS; 308 };