security/manager/ssl/nsISiteSecurityService.idl

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this
   3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 #include "nsISupports.idl"
   6
   7 interface nsIURI;
   8
   9 [ref] native const_OriginAttributesRef(const mozilla::OriginAttributes);
  10
  11 [scriptable, uuid(275127f8-dbd7-4681-afbf-6df0c6587a01)]
  12 interface nsISiteSecurityService : nsISupports
  13 {
  14     const uint32_t Success = 0;
  15     const uint32_t ERROR_UNKNOWN = 1;
  16     // ERROR_UNTRUSTWORTHY_CONNECTION was 2 (the caller is now responsible for
  17     // checking this)
  18     const uint32_t ERROR_COULD_NOT_PARSE_HEADER = 3;
  19     const uint32_t ERROR_NO_MAX_AGE = 4;
  20     const uint32_t ERROR_MULTIPLE_MAX_AGES = 5;
  21     const uint32_t ERROR_INVALID_MAX_AGE = 6;
  22     const uint32_t ERROR_MULTIPLE_INCLUDE_SUBDOMAINS = 7;
  23     const uint32_t ERROR_INVALID_INCLUDE_SUBDOMAINS = 8;
  24     // The constants that were removed below were used in HPKP processing
  25     // (which has been removed entirely).
  26     // ERROR_INVALID_PIN was 9
  27     // ERROR_MULTIPLE_REPORT_URIS was 10
  28     // ERROR_PINSET_DOES_NOT_MATCH_CHAIN was 11
  29     // ERROR_NO_BACKUP_PIN was 12
  30     const uint32_t ERROR_COULD_NOT_SAVE_STATE = 13;
  31     // ERROR_ROOT_NOT_BUILT_IN was 14
  32
  33     /**
  34      * Parses a given HTTP header and records the results internally.
  35      * Currently one header type is supported: HSTS (aka STS).
  36      * The format of the HSTS header is defined by the HSTS specification:
  37      * https://tools.ietf.org/html/rfc6797
  38      * and allows a host to specify that future HTTP requests should be
  39      * upgraded to HTTPS.
  40      * The caller is responsible for first determining that the header was
  41      * delivered via a trustworthy connection (namely, https with no errors).
  42      *
  43      * @param aSourceURI the URI of the resource with the HTTP header.
  44      * @param aHeader the HTTP response header specifying security data.
  45      * @param aOriginAttributes the origin attributes that isolate this origin,
  46      *                          (note that this implementation does not isolate
  47      *                          by userContextId because of the risk of man-in-
  48      *                          the-middle attacks before trust-on-second-use
  49      *                          happens).
  50      *                          If mPrivateBrowsingId > 0, information gathered
  51      *                          from this header will not be saved persistently.
  52      * @param aMaxAge the parsed max-age directive of the header.
  53      * @param aIncludeSubdomains the parsed includeSubdomains directive.
  54      * @param aFailureResult a more specific failure result if NS_ERROR_FAILURE
  55                              was returned.
  56      * @return NS_OK            if it succeeds
  57      *         NS_ERROR_FAILURE if it can't be parsed
  58      *         NS_SUCCESS_LOSS_OF_INSIGNIFICANT_DATA
  59      *                          if there are unrecognized tokens in the header.
  60      */
  61     [binaryname(ProcessHeader), noscript, must_use]
  62     void processHeaderNative(in nsIURI aSourceURI,
  63                              in ACString aHeader,
  64                              in const_OriginAttributesRef aOriginAttributes,
  65                              [optional] out unsigned long long aMaxAge,
  66                              [optional] out boolean aIncludeSubdomains,
  67                              [optional] out uint32_t aFailureResult);
  68
  69     [binaryname(ProcessHeaderScriptable), implicit_jscontext, optional_argc,
  70      must_use]
  71     void processHeader(in nsIURI aSourceURI,
  72                        in ACString aHeader,
  73                        [optional] in jsval aOriginAttributes,
  74                        [optional] out unsigned long long aMaxAge,
  75                        [optional] out boolean aIncludeSubdomains,
  76                        [optional] out uint32_t aFailureResult);
  77
  78     // Helper enum for use with resetState.
  79     cenum ResetStateBy : 8 {
  80       // reset state for the exact domain
  81       ExactDomain,
  82       // reset state for any domain rooted by the given domain
  83       // (e.g. foo.example.com if given example.com)
  84       RootDomain,
  85       // reset all state associated with the given base domain (e.g. data
  86       // partitioned by total cookie protection)
  87       BaseDomain,
  88     };
  89
  90     /**
  91      * Resets HSTS state a host, including the includeSubdomains state that
  92      * would affect subdomains. This essentially removes the state for the
  93      * domain tree rooted at this host. If any preloaded information is present
  94      * for that host, that information will then be used instead of any other
  95      * previously existing state.
  96      *
  97      * @param aURI    the URI of the target host
  98      * @param aOriginAttributes the origin attributes that isolate this origin,
  99      *                          (note that this implementation does not isolate
 100      *                          by userContextId because of the risk of man-in-
 101      *                          the-middle attacks before trust-on-second-use
 102      *                          happens).
 103      * @param aScope  The scope of state to reset. See ResetStateBy. Defaults
 104      *                to ExactDomain.
 105      */
 106     [implicit_jscontext, optional_argc, must_use]
 107     void resetState(in nsIURI aURI,
 108                     [optional] in jsval aOriginAttributes,
 109                     [optional] in nsISiteSecurityService_ResetStateBy aScope);
 110
 111     /**
 112      * Checks whether or not the URI's hostname has HSTS set.
 113      * For example:
 114      * The URI is an HSTS URI if either the host has the HSTS state set, or one
 115      * of its super-domains has the HSTS "includeSubdomains" flag set.
 116      * NOTE: this function makes decisions based only on the
 117      * host contained in the URI, and disregards other portions of the URI
 118      * such as path and port.
 119      *
 120      * @param aURI the URI to query for STS state.
 121      * @param aOriginAttributes the origin attributes that isolate this origin,
 122      *                          (note that this implementation does not isolate
 123      *                          by userContextId because of the risk of man-in-
 124      *                          the-middle attacks before trust-on-second-use
 125      *                          happens).
 126      */
 127     [binaryname(IsSecureURI), noscript, must_use]
 128     boolean isSecureURINative(in nsIURI aURI,
 129                               in const_OriginAttributesRef aOriginAttributes);
 130
 131     [binaryname(IsSecureURIScriptable), implicit_jscontext, optional_argc,
 132      must_use]
 133     boolean isSecureURI(in nsIURI aURI, [optional] in jsval aOriginAttributes);
 134
 135     /**
 136      * Removes all non-preloaded HSTS state by resetting to factory-original
 137      * settings.
 138      */
 139     [must_use]
 140     void clearAll();
 141 };
 142
 143 %{C++
 144 #define NS_SSSERVICE_CONTRACTID "@mozilla.org/ssservice;1"
 145 %}