nsISocketProvider.idl (5575B)
1 /* -*- Mode: C++; tab-width: 4; 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 interface nsIProxyInfo; 9 interface nsITLSSocketControl; 10 [ptr] native PRFileDescStar(struct PRFileDesc); 11 native OriginAttributes(mozilla::OriginAttributes); 12 [ref] native const_OriginAttributesRef(const mozilla::OriginAttributes); 13 14 %{ C++ 15 #include "mozilla/BasePrincipal.h" 16 %} 17 18 /** 19 * nsISocketProvider 20 */ 21 [scriptable, uuid(508d5469-9e1e-4a08-b5b0-7cfebba1e51a)] 22 interface nsISocketProvider : nsISupports 23 { 24 /** 25 * newSocket 26 * 27 * @param aFamily 28 * The address family for this socket (PR_AF_INET or PR_AF_INET6). 29 * @param aHost 30 * The origin hostname for this connection. 31 * @param aPort 32 * The origin port for this connection. 33 * @param aProxyHost 34 * If non-null, the proxy hostname for this connection. 35 * @param aProxyPort 36 * The proxy port for this connection. 37 * @param aFlags 38 * Control flags that govern this connection (see below.) 39 * @param aTlsFlags 40 * An opaque flags for non-standard behavior of the TLS system. 41 * It is unlikely this will need to be set outside of telemetry 42 * studies relating to the TLS implementation. 43 * @param aFileDesc 44 * The resulting PRFileDesc. 45 * @param aTLSSocketControl 46 * TLS socket control object that should be associated with 47 * aFileDesc, if applicable. 48 */ 49 [noscript] 50 void newSocket(in long aFamily, 51 in string aHost, 52 in long aPort, 53 in nsIProxyInfo aProxy, 54 in const_OriginAttributesRef aOriginAttributes, 55 in unsigned long aFlags, 56 in unsigned long aTlsFlags, 57 out PRFileDescStar aFileDesc, 58 out nsITLSSocketControl aTLSSocketControl); 59 60 /** 61 * addToSocket 62 * 63 * This function is called to allow the socket provider to layer a 64 * PRFileDesc on top of another PRFileDesc. For example, SSL via a SOCKS 65 * proxy. 66 * 67 * Parameters are the same as newSocket with the exception of aFileDesc, 68 * which is an in-param instead. 69 */ 70 [noscript] 71 void addToSocket(in long aFamily, 72 in string aHost, 73 in long aPort, 74 in nsIProxyInfo aProxy, 75 in const_OriginAttributesRef aOriginAttributes, 76 in unsigned long aFlags, 77 in unsigned long aTlsFlags, 78 in PRFileDescStar aFileDesc, 79 out nsITLSSocketControl aTLSSocketControl); 80 81 /** 82 * PROXY_RESOLVES_HOST 83 * 84 * This flag is set if the proxy is to perform hostname resolution instead 85 * of the client. When set, the hostname parameter passed when in this 86 * interface will be used instead of the address structure passed for a 87 * later connect et al. request. 88 */ 89 const long PROXY_RESOLVES_HOST = 1 << 0; 90 91 /** 92 * When setting this flag, the socket will not apply any 93 * credentials when establishing a connection. For example, 94 * an SSL connection would not send any client-certificates 95 * if this flag is set. 96 */ 97 const long ANONYMOUS_CONNECT = 1 << 1; 98 99 /** 100 * If set, indicates that the connection was initiated from a source 101 * defined as being private in the sense of Private Browsing. Generally, 102 * there should be no state shared between connections that are private 103 * and those that are not; it is OK for multiple private connections 104 * to share state with each other, and it is OK for multiple non-private 105 * connections to share state with each other. 106 */ 107 const unsigned long NO_PERMANENT_STORAGE = 1 << 2; 108 109 /** 110 * If set, do not use newer protocol features that might have interop problems 111 * on the Internet. Intended only for use with critical infra like the updater. 112 * default is false. 113 */ 114 const unsigned long BE_CONSERVATIVE = 1 << 3; 115 116 /** 117 * This is used for a temporary workaround for a web-compat issue. The flag is 118 * only set on CORS preflight request to allowed sending client certificates 119 * on a connection for an anonymous request. 120 */ 121 const long ANONYMOUS_CONNECT_ALLOW_CLIENT_CERT = 1 << 4; 122 123 /** 124 * If set, indicates that this is a speculative connection. 125 */ 126 const unsigned long IS_SPECULATIVE_CONNECTION = 1 << 5; 127 128 /** 129 * If set, do not send an ECH extension (whether GREASE or 'real'). 130 * Currently false by default and is set when retrying failed connections. 131 */ 132 const unsigned long DONT_TRY_ECH = (1 << 10); 133 134 /** 135 * If set, indicates that the connection is a retry. 136 */ 137 const unsigned long IS_RETRY = (1 << 11); 138 139 /** 140 * If set, indicates that the connection used a privacy-preserving DNS 141 * transport such as DoH, DoQ or similar. Currently this field is 142 * set only when DoH is used via the TRR. 143 */ 144 const unsigned long USED_PRIVATE_DNS = (1 << 12); 145 };