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 * Some utility methods used by the url classifier.
8 */
9
10interface nsIURI;
11interface nsIChannel;
12
13/**
14 * Interface for parseFindFullHashResponseV4 callback
15 */
16[scriptable, uuid(fbb9684a-a0aa-11e6-88b0-08606e456b8a)]
17interface nsIUrlClassifierParseFindFullHashCallback : nsISupports {
18  /**
19   * Callback when a match is found in full hash response. This callback may be
20   * called multiple times when there are more than one matches in response.
21   *
22   * @param aCompleteHash A 32-byte complete hash string.
23   * @param aTableNames The table names that this complete hash is associated with.
24   *                    Since the server responded with a threat type, multiple
25   *                    list names can be returned. The caller is reponsible
26   *                    for filtering out the unrequested table names.
27   *                    See |convertThreatTypeToListNames| for the format.
28   * @param aPerHashCacheDuration See "FindFullHashesResponse" in safebrowsing.proto.
29   *
30   */
31  void onCompleteHashFound(in ACString aCompleteHash,
32                           in ACString aTableNames,
33                           in unsigned long aPerHashCacheDuration);
34
35  /**
36   * Callback when full hash response is received.
37   *
38   * @param aMinWaitDuration See "FindFullHashesResponse" in safebrowsing.proto.
39   * @param aNegCacheDuration See "FindFullHashesResponse" in safebrowsing.proto.
40   *
41   */
42  void onResponseParsed(in unsigned long aMinWaitDuration,
43                        in unsigned long aNegCacheDuration);
44};
45
46[scriptable, uuid(e4f0e59c-b922-48b0-a7b6-1735c1f96fed)]
47interface nsIUrlClassifierUtils : nsISupports
48{
49  /**
50   * Get the lookup string for a given URI.  This normalizes the hostname,
51   * url-decodes the string, and strips off the protocol.
52   *
53   * @param uri URI to get the lookup key for.
54   *
55   * @returns String containing the canonicalized URI.
56   */
57  ACString getKeyForURI(in nsIURI uri);
58
59  /**
60   * Get the provider by table name.
61   *
62   * @param tableName The table name that we want to lookup
63   *
64   * @returns the provider name that the given table belongs.
65   */
66  ACString getProvider(in ACString tableName);
67
68  /**
69   * Get the provider used for Telemetry.
70   * Because recording Telemetry will leak user-controlled strings,
71   * only built-in providers should be recorded.
72   *
73   * @param tableName The table name that we want to lookup
74   *
75   * @returns the filtered provider for telemetry.
76   *
77   */
78  ACString getTelemetryProvider(in ACString tableName);
79
80  /**
81   * Get the protocol version for the given provider.
82   *
83   * @param provider String the provider name. e.g. "google"
84   *
85   * @returns String to indicate the protocol version. e.g. "2.2"
86   */
87  ACString getProtocolVersion(in ACString provider);
88
89  /**
90   * Convert threat type to list name.
91   *
92   * @param Integer to indicate threat type.
93   *
94   * @returns The list names separated by ','. For example,
95   *          'goog-phish-proto,test-phish-proto'.
96   */
97  ACString convertThreatTypeToListNames(in uint32_t threatType);
98
99  /**
100   * Convert list name to threat type.
101   *
102   * @param The list name.
103   *
104   * @returns The threat type in integer.
105   */
106  uint32_t convertListNameToThreatType(in ACString listName);
107
108  /**
109   * Make update request for given lists and their states.
110   *
111   * @param aListNames An array of list name represented in string.
112   * @param aState An array of states (encoded in base64 format) for each list.
113   *
114   * The two argument arrays must be the same length.
115   *
116   * @returns A base64url encoded string.
117   */
118  ACString makeUpdateRequestV4(in Array<ACString> aListNames,
119                               in Array<ACString> aStatesBase64);
120
121    /**
122   * Make "find full hash" request by for the given prefixes.
123   *
124   * @param aListNames An array of list names represented in string.
125   * @param aListStatesBase64 An array of list states represented in base64.
126   * @param aPrefixes An array of prefixes for which we'd like to find full hashes..
127   *
128   * The aListNames and aListStatesBase64 arrays must be the same length.
129   *
130   * @returns A base64url encoded string.
131   */
132  ACString makeFindFullHashRequestV4(in Array<ACString> aListNames,
133                                     in Array<ACString> aListStatesBase64,
134                                     in Array<ACString> aPrefixes);
135
136  /**
137   * Make ThreatHit report request body.
138   *
139   * @param aChannel channel which encountered the threat.
140   * @param aListName listname represented in string.
141   * @param aHashBase64 hash-based hit represented in base64.
142   *
143   * @returns A base64 encoded string.
144   */
145  ACString makeThreatHitReport(in nsIChannel aChannel,
146                               in ACString aListName,
147                               in ACString aHashBase64);
148
149  /**
150   * Parse V4 FindFullHash response.
151   *
152   * @param aResponse Byte stream from the server.
153   * @param aCallback The callback function on each complete hash parsed.
154   *                  Can be called multiple times in one parsing.
155   */
156  void parseFindFullHashResponseV4(in ACString aResponse,
157                                   in nsIUrlClassifierParseFindFullHashCallback aCallback);
158};
159