1// Copyright 2015 The Chromium Authors. All rights reserved. 2// Use of this source code is governed by a BSD-style license that can be 3// found in the LICENSE file. 4// 5// This file includes Safe Browsing V4 API blacklist request and response 6// protocol buffers. They should be kept in sync with the server implementation. 7 8syntax = "proto2"; 9 10option optimize_for = LITE_RUNTIME; 11 12package mozilla.safebrowsing; 13 14message ThreatInfo { 15 // The threat types to be checked. 16 repeated ThreatType threat_types = 1; 17 18 // The platform types to be checked. 19 repeated PlatformType platform_types = 2; 20 21 // The entry types to be checked. 22 repeated ThreatEntryType threat_entry_types = 4; 23 24 // The threat entries to be checked. 25 repeated ThreatEntry threat_entries = 3; 26} 27 28// A match when checking a threat entry in the Safe Browsing threat lists. 29message ThreatMatch { 30 // The threat type matching this threat. 31 optional ThreatType threat_type = 1; 32 33 // The platform type matching this threat. 34 optional PlatformType platform_type = 2; 35 36 // The threat entry type matching this threat. 37 optional ThreatEntryType threat_entry_type = 6; 38 39 // The threat matching this threat. 40 optional ThreatEntry threat = 3; 41 42 // Optional metadata associated with this threat. 43 optional ThreatEntryMetadata threat_entry_metadata = 4; 44 45 // The cache lifetime for the returned match. Clients must not cache this 46 // response for more than this duration to avoid false positives. 47 optional Duration cache_duration = 5; 48} 49 50// Request to check entries against lists. 51message FindThreatMatchesRequest { 52 // The client metadata. 53 optional ClientInfo client = 1; 54 55 // The lists and entries to be checked for matches. 56 optional ThreatInfo threat_info = 2; 57} 58 59// Response type for requests to find threat matches. 60message FindThreatMatchesResponse { 61 // The threat list matches. 62 repeated ThreatMatch matches = 1; 63} 64 65// Describes a Safe Browsing API update request. Clients can request updates for 66// multiple lists in a single request. 67message FetchThreatListUpdatesRequest { 68 // The client metadata. 69 optional ClientInfo client = 1; 70 71 // A single list update request. 72 message ListUpdateRequest { 73 // The type of threat posed by entries present in the list. 74 optional ThreatType threat_type = 1; 75 76 // The type of platform at risk by entries present in the list. 77 optional PlatformType platform_type = 2; 78 79 // The types of entries present in the list. 80 optional ThreatEntryType threat_entry_type = 5; 81 82 // The current state of the client for the requested list (the encrypted 83 // ClientState that was sent to the client from the previous update 84 // request). 85 optional bytes state = 3; 86 87 // The constraints for this update. 88 message Constraints { 89 // The maximum size in number of entries. The update will not contain more 90 // entries than this value. This should be a power of 2 between 2**10 and 91 // 2**20. If zero, no update size limit is set. 92 optional int32 max_update_entries = 1; 93 94 // Sets the maxmimum number of entries that the client is willing to have 95 // in the local database. This should be a power of 2 between 2**10 and 96 // 2**20. If zero, no database size limit is set. 97 optional int32 max_database_entries = 2; 98 99 // Requests the list for a specific geographic location. If not set the 100 // server may pick that value based on the user's IP address. Expects ISO 101 // 3166-1 alpha-2 format. 102 optional string region = 3; 103 104 // The compression types supported by the client. 105 repeated CompressionType supported_compressions = 4; 106 } 107 108 // The constraints associated with this request. 109 optional Constraints constraints = 4; 110 } 111 112 // The requested threat list updates. 113 repeated ListUpdateRequest list_update_requests = 3; 114 115 // Chrome-specific client information. 116 optional ChromeClientInfo chrome_client_info = 4; 117} 118 119// Response type for threat list update requests. 120message FetchThreatListUpdatesResponse { 121 // An update to an individual list. 122 message ListUpdateResponse { 123 // The threat type for which data is returned. 124 optional ThreatType threat_type = 1; 125 126 // The format of the threats. 127 optional ThreatEntryType threat_entry_type = 2; 128 129 // The platform type for which data is returned. 130 optional PlatformType platform_type = 3; 131 132 // The type of response sent to the client. 133 enum ResponseType { 134 // Unknown. 135 RESPONSE_TYPE_UNSPECIFIED = 0; 136 137 // Partial updates are applied to the client's existing local database. 138 PARTIAL_UPDATE = 1; 139 140 // Full updates replace the client's entire local database. This means 141 // that either the client was seriously out-of-date or the client is 142 // believed to be corrupt. 143 FULL_UPDATE = 2; 144 } 145 146 // The type of response. This may indicate that an action is required by the 147 // client when the response is received. 148 optional ResponseType response_type = 4; 149 150 // A set of entries to add to a local threat type's list. Repeated to allow 151 // for a combination of compressed and raw data to be sent in a single 152 // response. 153 repeated ThreatEntrySet additions = 5; 154 155 // A set of entries to remove from a local threat type's list. In practice, 156 // this field is empty or contains exactly one ThreatEntrySet. 157 repeated ThreatEntrySet removals = 6; 158 159 // The new client state, in encrypted format. Opaque to clients. 160 optional bytes new_client_state = 7; 161 162 // The expected SHA256 hash of the client state; that is, of the sorted list 163 // of all hashes present in the database after applying the provided update. 164 // If the client state doesn't match the expected state, the client must 165 // disregard this update and retry later. 166 optional Checksum checksum = 8; 167 } 168 169 // The list updates requested by the clients. 170 repeated ListUpdateResponse list_update_responses = 1; 171 172 // The minimum duration the client must wait before issuing any update 173 // request. If this field is not set clients may update as soon as they want. 174 optional Duration minimum_wait_duration = 2; 175} 176 177// Request to return full hashes matched by the provided hash prefixes. 178message FindFullHashesRequest { 179 // The client metadata. 180 optional ClientInfo client = 1; 181 182 // The current client states for each of the client's local threat lists. 183 repeated bytes client_states = 2; 184 185 // The lists and hashes to be checked. 186 optional ThreatInfo threat_info = 3; 187} 188 189// Response type for requests to find full hashes. 190message FindFullHashesResponse { 191 // The full hashes that matched the requested prefixes. 192 repeated ThreatMatch matches = 1; 193 194 // The minimum duration the client must wait before issuing any find hashes 195 // request. If this field is not set, clients can issue a request as soon as 196 // they want. 197 optional Duration minimum_wait_duration = 2; 198 199 // For requested entities that did not match the threat list, how long to 200 // cache the response. 201 optional Duration negative_cache_duration = 3; 202} 203 204// A hit comprised of multiple resources; one is the threat list entry that was 205// encountered by the client, while others give context as to how the client 206// arrived at the unsafe entry. 207message ThreatHit { 208 // The threat type reported. 209 optional ThreatType threat_type = 1; 210 211 // The platform type reported. 212 optional PlatformType platform_type = 2; 213 214 // The threat entry responsible for the hit. Full hash should be reported for 215 // hash-based hits. 216 optional ThreatEntry entry = 3; 217 218 // Types of resources reported by the client as part of a single hit. 219 enum ThreatSourceType { 220 // Unknown. 221 THREAT_SOURCE_TYPE_UNSPECIFIED = 0; 222 // The URL that matched the threat list (for which GetFullHash returned a 223 // valid hash). 224 MATCHING_URL = 1; 225 // The final top-level URL of the tab that the client was browsing when the 226 // match occurred. 227 TAB_URL = 2; 228 // A redirect URL that was fetched before hitting the final TAB_URL. 229 TAB_REDIRECT = 3; 230 // A resource loaded within the final TAB_URL. 231 TAB_RESOURCE = 4; 232 } 233 234 // A single resource related to a threat hit. 235 message ThreatSource { 236 // The URL of the resource. 237 optional string url = 1; 238 239 // The type of source reported. 240 optional ThreatSourceType type = 2; 241 242 // The remote IP of the resource in ASCII format. Either IPv4 or IPv6. 243 optional string remote_ip = 3; 244 245 // Referrer of the resource. Only set if the referrer is available. 246 optional string referrer = 4; 247 } 248 249 // The resources related to the threat hit. 250 repeated ThreatSource resources = 4; 251 252 // Client-reported identification. 253 optional ClientInfo client_info = 5; 254 255 // Details about the user that encountered the threat. 256 message UserInfo { 257 // The UN M.49 region code associated with the user's location. 258 optional string region_code = 1; 259 260 // Unique ID stable over a week or two 261 optional bytes user_id = 2; 262 } 263 264 // Details about the user that encountered the threat. 265 optional UserInfo user_info = 6; 266} 267 268// Types of threats. 269enum ThreatType { 270 // Unknown. 271 THREAT_TYPE_UNSPECIFIED = 0; 272 273 // Malware threat type. 274 MALWARE_THREAT = 1; 275 276 // Social engineering threat type. 277 SOCIAL_ENGINEERING_PUBLIC = 2; 278 279 // Unwanted software threat type. 280 UNWANTED_SOFTWARE = 3; 281 282 // Potentially harmful application threat type. 283 POTENTIALLY_HARMFUL_APPLICATION = 4; 284 285 // Social engineering threat type for internal use. 286 SOCIAL_ENGINEERING = 5; 287 288 // API abuse threat type. 289 API_ABUSE = 6; 290 291 // Malicious binary threat type. 292 MALICIOUS_BINARY = 7; 293 294 // Client side detection whitelist threat type. 295 CSD_WHITELIST = 8; 296 297 // Client side download detection whitelist threat type. 298 CSD_DOWNLOAD_WHITELIST = 9; 299 300 // Client incident threat type. 301 CLIENT_INCIDENT = 10; 302 303 // Patterns to be used for activating the subresource filter. Interstitial 304 // will not be shown for patterns from this list. 305 SUBRESOURCE_FILTER = 13; 306} 307 308// Types of platforms. 309enum PlatformType { 310 // Unknown platform. 311 PLATFORM_TYPE_UNSPECIFIED = 0; 312 313 // Threat posed to Windows. 314 WINDOWS_PLATFORM = 1; 315 316 // Threat posed to Linux. 317 LINUX_PLATFORM = 2; 318 319 // Threat posed to Android. 320 // This cannot be ANDROID because that symbol is defined for android builds 321 // here: build/config/android/BUILD.gn line21. 322 ANDROID_PLATFORM = 3; 323 324 // Threat posed to OSX. 325 OSX_PLATFORM = 4; 326 327 // Threat posed to iOS. 328 IOS_PLATFORM = 5; 329 330 // Threat posed to at least one of the defined platforms. 331 ANY_PLATFORM = 6; 332 333 // Threat posed to all defined platforms. 334 ALL_PLATFORMS = 7; 335 336 // Threat posed to Chrome. 337 CHROME_PLATFORM = 8; 338} 339 340// The client metadata associated with Safe Browsing API requests. 341message ClientInfo { 342 // A client ID that (hopefully) uniquely identifies the client implementation 343 // of the Safe Browsing API. 344 optional string client_id = 1; 345 346 // The version of the client implementation. 347 optional string client_version = 2; 348} 349 350// The client metadata associated with Safe Browsing API requests specific to 351// users of Chrome. 352message ChromeClientInfo { 353 // Safe Browsing reporting populations in Chrome. 354 enum SafeBrowsingReportingPopulation { 355 // Unspecified reporting verbosity. 356 UNSPECIFIED = 0; 357 358 // Client is opted out of reporting. 359 OPT_OUT = 1; 360 361 // Legacy extended reporting population. 362 EXTENDED = 2; 363 364 // Scout reporting population. 365 SCOUT = 3; 366 } 367 368 // The reporting population of the user. 369 optional SafeBrowsingReportingPopulation reporting_population = 1; 370} 371 372// The expected state of a client's local database. 373message Checksum { 374 // The SHA256 hash of the client state; that is, of the sorted list of all 375 // hashes present in the database. 376 optional bytes sha256 = 1; 377} 378 379// The ways in which threat entry sets can be compressed. 380enum CompressionType { 381 // Unknown. 382 COMPRESSION_TYPE_UNSPECIFIED = 0; 383 384 // Raw, uncompressed data. 385 RAW = 1; 386 387 // Rice-Golomb encoded data. 388 RICE = 2; 389} 390 391// An individual threat; for example, a malicious URL or its hash 392// representation. Only one of these fields should be set. 393message ThreatEntry { 394 // A variable-length SHA256 hash with size between 4 and 32 bytes inclusive. 395 optional bytes hash = 1; 396 397 // A URL. 398 optional string url = 2; 399} 400 401// Types of entries that pose threats. Threat lists are collections of entries 402// of a single type. 403enum ThreatEntryType { 404 // Unspecified. 405 THREAT_ENTRY_TYPE_UNSPECIFIED = 0; 406 407 // A host-suffix/path-prefix URL expression; for example, "foo.bar.com/baz/". 408 URL = 1; 409 410 // An executable program. 411 EXECUTABLE = 2; 412 413 // An IP range. 414 IP_RANGE = 3; 415 416 // Chrome extension. 417 CHROME_EXTENSION = 4; 418 419 // Filename. 420 FILENAME = 5; 421 422 // CERT. 423 CERT = 6; 424} 425 426// A set of threats that should be added or removed from a client's local 427// database. 428message ThreatEntrySet { 429 // The compression type for the entries in this set. 430 optional CompressionType compression_type = 1; 431 432 // At most one of the following fields should be set. 433 434 // The raw SHA256-formatted entries. 435 optional RawHashes raw_hashes = 2; 436 437 // The raw removal indices for a local list. 438 optional RawIndices raw_indices = 3; 439 440 // The encoded 4-byte prefixes of SHA256-formatted entries, using a 441 // Golomb-Rice encoding. 442 optional RiceDeltaEncoding rice_hashes = 4; 443 444 // The encoded local, lexicographically-sorted list indices, using a 445 // Golomb-Rice encoding. Used for sending compressed removal indicies. 446 optional RiceDeltaEncoding rice_indices = 5; 447} 448 449// A set of raw indicies to remove from a local list. 450message RawIndices { 451 // The indicies to remove from a lexicographically-sorted local list. 452 repeated int32 indices = 1; 453} 454 455// The uncompressed threat entries in hash format of a particular prefix length. 456// Hashes can be anywhere from 4 to 32 bytes in size. A large majority are 4 457// bytes, but some hashes are lengthened if they collide with the hash of a 458// popular URL. 459// 460// Used for sending ThreatEntrySet to clients that do not support compression, 461// or when sending non-4-byte hashes to clients that do support compression. 462message RawHashes { 463 // The number of bytes for each prefix encoded below. This field can be 464 // anywhere from 4 (shortest prefix) to 32 (full SHA256 hash). 465 optional int32 prefix_size = 1; 466 467 // The hashes, all concatenated into one long string. Each hash has a prefix 468 // size of |prefix_size| above. Hashes are sorted in lexicographic order. 469 optional bytes raw_hashes = 2; 470} 471 472// The Rice-Golomb encoded data. Used for sending compressed 4-byte hashes or 473// compressed removal indices. 474message RiceDeltaEncoding { 475 // The offset of the first entry in the encoded data, or, if only a single 476 // integer was encoded, that single integer's value. 477 optional int64 first_value = 1; 478 479 // The Golomb-Rice parameter which is a number between 2 and 28. This field 480 // is missing (that is, zero) if num_entries is zero. 481 optional int32 rice_parameter = 2; 482 483 // The number of entries that are delta encoded in the encoded data. If only a 484 // single integer was encoded, this will be zero and the single value will be 485 // stored in first_value. 486 optional int32 num_entries = 3; 487 488 // The encoded deltas that are encoded using the Golomb-Rice coder. 489 optional bytes encoded_data = 4; 490} 491 492// The metadata associated with a specific threat entry. The client is expected 493// to know the metadata key/value pairs associated with each threat type. 494message ThreatEntryMetadata { 495 // A single metadata entry. 496 message MetadataEntry { 497 // The metadata entry key. 498 optional bytes key = 1; 499 500 // The metadata entry value. 501 optional bytes value = 2; 502 } 503 504 // The metadata entries. 505 repeated MetadataEntry entries = 1; 506} 507 508// Describes an individual threat list. A list is defined by three parameters: 509// the type of threat posed, the type of platform targeted by the threat, and 510// the type of entries in the list. 511message ThreatListDescriptor { 512 // The threat type posed by the list's entries. 513 optional ThreatType threat_type = 1; 514 515 // The platform type targeted by the list's entries. 516 optional PlatformType platform_type = 2; 517 518 // The entry types contained in the list. 519 optional ThreatEntryType threat_entry_type = 3; 520} 521 522// A collection of lists available for download. 523message ListThreatListsResponse { 524 // The lists available for download. 525 repeated ThreatListDescriptor threat_lists = 1; 526} 527 528message Duration { 529 // Signed seconds of the span of time. Must be from -315,576,000,000 530 // to +315,576,000,000 inclusive. 531 optional int64 seconds = 1; 532 533 // Signed fractions of a second at nanosecond resolution of the span 534 // of time. Durations less than one second are represented with a 0 535 // `seconds` field and a positive or negative `nanos` field. For durations 536 // of one second or more, a non-zero value for the `nanos` field must be 537 // of the same sign as the `seconds` field. Must be from -999,999,999 538 // to +999,999,999 inclusive. 539 optional int32 nanos = 2; 540} 541