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