netwerk/base/nsIClassifiedChannel.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   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 /**
   9  * nsIClassifiedChannel
  10  *
  11  * A channel may optionally implement this interface if it carries classified
  12  * result information of channel classifier. The information contains, for
  13  * example, the name of matched table and the name of matched provider.
  14  */
  15 [builtinclass, scriptable, uuid(70cf6091-a1de-4aa8-8224-058f8964be31)]
  16 interface nsIClassifiedChannel : nsISupports
  17 {
  18   /**
  19    * Sets matched info of the classified channel.
  20    *
  21    * @param aList
  22    *        Name of the Safe Browsing list that matched (e.g. goog-phish-shavar).
  23    * @param aProvider
  24    *        Name of the Safe Browsing provider that matched (e.g. google)
  25    * @param aFullHash
  26    *        Full hash of URL that matched Safe Browsing list.
  27    */
  28   void setMatchedInfo(in ACString aList,
  29                       in ACString aProvider,
  30                       in ACString aFullHash);
  31
  32   /**
  33    * Name of the list that matched
  34    */
  35   readonly attribute ACString matchedList;
  36
  37   /**
  38    * Name of provider that matched
  39    */
  40   readonly attribute ACString matchedProvider;
  41
  42   /**
  43    * Full hash of URL that matched
  44    */
  45   readonly attribute ACString matchedFullHash;
  46
  47   /**
  48    * Sets matched tracking info of the classified channel.
  49    *
  50    * @param aLists
  51    *        Name of the Tracking Protection list that matched (e.g. content-track-digest256).
  52    * @param aFullHash
  53    *        Full hash of URLs that matched Tracking Protection list.
  54    */
  55   void setMatchedTrackingInfo(in Array<ACString> aLists,
  56                               in Array<ACString> aFullHashes);
  57
  58   /**
  59    * Name of the lists that matched
  60    */
  61   readonly attribute Array<ACString> matchedTrackingLists;
  62
  63   /**
  64    * Full hash of URLs that matched
  65    */
  66   readonly attribute Array<ACString> matchedTrackingFullHashes;
  67
  68   /**
  69    * Returns the classification flags if the channel has been processed by
  70    * URL-Classifier features and is considered first-party.
  71    */
  72   [infallible] readonly attribute unsigned long firstPartyClassificationFlags;
  73
  74   /**
  75    * Returns the classification flags if the channel has been processed by
  76    * URL-Classifier features and is considered third-party with the top
  77    * window URI.
  78    */
  79   [infallible] readonly attribute unsigned long thirdPartyClassificationFlags;
  80
  81   /*
  82     * Returns the classification flags if the channel has been processed by
  83     * URL-Classifier features. This value is equal to
  84     * "firstPartyClassificationFlags || thirdPartyClassificationFlags".
  85     *
  86     * Note that top-level channels could be classified as well.
  87     * In order to identify third-party resources specifically, use
  88     * classificationThirdPartyFlags;
  89     */
  90   [infallible] readonly attribute unsigned long classificationFlags;
  91
  92   cenum ClassificationFlags : 32 {
  93     /**
  94      * The resource is on the fingerprinting list.
  95      */
  96     CLASSIFIED_FINGERPRINTING = 0x0001,
  97     CLASSIFIED_FINGERPRINTING_CONTENT = 0x0080,
  98
  99     /**
 100      * The resource is on the cryptomining list.
 101      */
 102     CLASSIFIED_CRYPTOMINING = 0x0002,
 103     CLASSIFIED_CRYPTOMINING_CONTENT = 0x0100,
 104
 105     /**
 106      * The following are about tracking annotation and are available only
 107      * if the privacy.trackingprotection.annotate_channels pref.
 108      * CLASSIFIED_TRACKING is set if we are not able to identify the
 109      * type of classification.
 110      */
 111     CLASSIFIED_TRACKING = 0x0004,
 112     CLASSIFIED_TRACKING_AD = 0x0008,
 113     CLASSIFIED_TRACKING_ANALYTICS = 0x0010,
 114     CLASSIFIED_TRACKING_SOCIAL = 0x0020,
 115     CLASSIFIED_TRACKING_CONTENT = 0x0040,
 116
 117     /**
 118      * The following are about social tracking.
 119      */
 120     CLASSIFIED_SOCIALTRACKING = 0x0200,
 121     CLASSIFIED_SOCIALTRACKING_FACEBOOK = 0x0400,
 122     CLASSIFIED_SOCIALTRACKING_LINKEDIN = 0x0800,
 123     CLASSIFIED_SOCIALTRACKING_TWITTER = 0x1000,
 124
 125     /**
 126      * The following are about email tracking.
 127      */
 128     CLASSIFIED_EMAILTRACKING = 0x2000,
 129     CLASSIFIED_EMAILTRACKING_CONTENT = 0x4000,
 130
 131     /**
 132      * This is exposed to help to identify tracking classification using the
 133      * basic lists.
 134      */
 135     CLASSIFIED_ANY_BASIC_TRACKING = CLASSIFIED_TRACKING |
 136       CLASSIFIED_TRACKING_AD | CLASSIFIED_TRACKING_ANALYTICS |
 137       CLASSIFIED_TRACKING_SOCIAL | CLASSIFIED_FINGERPRINTING,
 138
 139     /**
 140      * This is exposed to help to identify tracking classification using the
 141      * strict lists.
 142      */
 143     CLASSIFIED_ANY_STRICT_TRACKING = CLASSIFIED_ANY_BASIC_TRACKING |
 144       CLASSIFIED_TRACKING_CONTENT | CLASSIFIED_FINGERPRINTING_CONTENT,
 145
 146     /**
 147      * This is exposed to help to identify social tracking classification
 148      * flags.
 149      */
 150     CLASSIFIED_ANY_SOCIAL_TRACKING = CLASSIFIED_SOCIALTRACKING |
 151       CLASSIFIED_SOCIALTRACKING_FACEBOOK |
 152       CLASSIFIED_SOCIALTRACKING_LINKEDIN | CLASSIFIED_SOCIALTRACKING_TWITTER,
 153   };
 154
 155   /**
 156    * Returns true  if the channel has been processed by URL-Classifier features
 157    * and is considered third-party with the top window URI, and if it has loaded
 158    * a resource that is classified as a tracker.
 159    *
 160    * This is a helper attribute which returns the same value of
 161    * (thirdPartyClassificationFlags & CLASSIFIED_ANY_BASIC_TRACKING) or
 162    * (thirdPartyClassificationFlags & CLASSIFIED_ANY_STRICT_TRACKING) or
 163    * (thirdPartyClassificationFlags & CLASSIFIED_ANY_SOCIAL_TRACKING)
 164    */
 165   boolean isThirdPartyTrackingResource();
 166
 167 %{ C++
 168   inline bool IsThirdPartyTrackingResource()
 169   {
 170     bool value = false;
 171     if (NS_SUCCEEDED(IsThirdPartyTrackingResource(&value)) && value) {
 172       return true;
 173     }
 174     return false;
 175   }
 176 %}
 177
 178   /**
 179    * Returns true if the channel has loaded a 3rd party resource that is
 180    * classified as a social tracker.
 181    *
 182    * This is a helper attribute which returns the same value of
 183    * (classificationFlags & CLASSIFIED_ANY_SOCIAL_TRACKING)
 184    *
 185    * Note that top-level channels could be marked as tracking
 186    * resources. In order to identify third-party social tracking resources
 187    * specifically, check the flags manually or add a new helper here.
 188    */
 189   boolean isThirdPartySocialTrackingResource();
 190
 191 %{ C++
 192   inline bool IsThirdPartySocialTrackingResource()
 193   {
 194     bool value = false;
 195     if (NS_SUCCEEDED(IsThirdPartySocialTrackingResource(&value)) && value) {
 196       return true;
 197     }
 198     return false;
 199   }
 200 %}
 201 };