| // Copyright 2017 The Chromium Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| syntax = "proto3"; |
| package traffic_annotation; |
| |
| // chrome_settings_full_runtime.proto is a version of the following proto |
| // without lite runtime optimization: |
| // out/Debug/gen/components/policy/proto/chrome_settings.proto |
| import "chrome_settings_full_runtime.proto"; |
| |
| // Describes a specific kind of network traffic based on a fine-grained |
| // semantic classification of all network traffic generated by Chrome. |
| // Used for auditing purposes. Please refer to |
| // "/docs/network_traffic_annotations.md" for users guide. |
| message NetworkTrafficAnnotation { |
| // This is a globally unique identifier that must stay unchanged while the |
| // network request carries the same semantic meaning. If the network request |
| // gets a new meaning, this ID needs to be changed. |
| // The purpose of this ID is to give humans a chance to reference |
| // NetworkTrafficAnnotations externally even when those change a little bit |
| // (e.g. adding a new piece of data that is sent along with a network |
| // request). |
| // IDs of one component should have a shared prefix so that sorting all |
| // NetworkTrafficAnnotations by unique_id groups those that belong to the same |
| // component together. |
| // For example: |
| // "spellchecker_lookup" |
| string unique_id = 1; |
| |
| // Encapsulates information about the code location that generates this kind |
| // of network traffic. |
| message TrafficSource { |
| // File name where the network request is triggered. |
| // This is typically filled by the extractor and does not need to be |
| // specified in the source code. For manual whitelisting this needs to be |
| // specified. |
| string file = 1; |
| |
| // Function name where the network request is instantiated. |
| // This is typically filled by the extractor and does not need to be |
| // specified in the source code. For manual whitelisting this needs to be |
| // specified. |
| string function = 2; |
| |
| // __LINE__ in file, where the AuditPolicy object is instantiated. |
| // This is typically filled by the extractor and does not need to be |
| // specified in the source code. |
| // For whitelisted network requests in third_party/ that cannot be properly |
| // annotated in the source code, this attribute is empty. |
| int32 line = 3; |
| |
| // For whitelisted network requests in third_party/ that cannot be properly |
| // annotated in the source code, this distinguishes between the first, |
| // second, ... annotated call. |
| // For annotations in the source code, this is not used because the line |
| // attribute uniquely identifies the network request. |
| int32 call_number = 4; |
| } |
| |
| TrafficSource source = 2; |
| |
| // Meta information about the network request. |
| message TrafficSemantics { |
| // What component triggers the request. The components should be human |
| // readable and don’t need to reflect the components/ directory. Avoid |
| // abbreviations. |
| // Examples: Online Spellcheck, Safe Browsing, WebView. |
| string sender = 1; |
| |
| // Plaintext description of the network request in language that is |
| // understandable by admins (ideally also users). Please avoid acronyms. |
| // Please describe the feature and the feature's value proposition as well. |
| // Examples: |
| // - Google Chrome can provide smarter spell-checking by sending text you |
| // type into the browser to Google's servers, allowing you to use the same |
| // spell-checking technology used by Google products, such as Docs. |
| // If the feature is enabled, Chrome will send the entire contents of text |
| // fields as you type in them to Google along with the browser’s default |
| // language. Google returns a list of suggested spellings, which will be |
| // displayed in the context menu. |
| // - A network request that comes from web content (a page the user visits) |
| string description = 2; |
| |
| // What triggered the network request. Use a textual description. This |
| // should be a human readable string. |
| // For things that are clearly part of the website (resource load, form |
| // submission, fetch by a service worker,...), you *may* just put “website” |
| // here. |
| string trigger = 3; |
| |
| // What nature of data is being sent. This should be a human readable |
| // string. Any user data and/or PII should be pointed out. |
| // Examples: “log files from /var/...”, “statistics about foobar”, “the |
| // signature of a form of a website”, “installed extensions and their |
| // version”, “a word on a website the user tapped on” |
| string data = 4; |
| |
| enum Destination { |
| // Do not use this value. It's just a placeholder for default value. |
| UNSPECIFIED = 0; |
| // A website the user visits or interacts with. The distinction from a |
| // google owned service can be difficult when the user navigates to |
| // google.com or searches with the omnibar. Therefore follow the following |
| // guideline: If the source code has hardcoded that the request goes to |
| // Google (e.g. for ZeroSuggest), use GOOGLE_OWNED_SERVICE. If the request |
| // can go to other domains and is perceived as a part of a website rather |
| // than a native browser feature, use WEBSITE. Use LOCAL if the request is |
| // processed locally and does not go to network, otherwise use OTHER. If |
| // OTHER is used, please add plain text description in 'destination_other' |
| // tag. |
| WEBSITE = 1; |
| // A Google owned service, like SafeBrowsing, spellchecking, ... |
| GOOGLE_OWNED_SERVICE = 2; |
| // Does not go to the network and just fetches a resource locally. |
| LOCAL = 3; |
| // Other endpoints, e.g. a service hosting a PAC script. In case of doubt, |
| // use this category. We will audit it in the future to see whether we |
| // need more categories. |
| OTHER = 1000; |
| } |
| Destination destination = 5; |
| |
| // Human readable description in case the destination points to OTHER. |
| string destination_other = 6; |
| } |
| |
| TrafficSemantics semantics = 3; |
| |
| message TrafficPolicy { |
| enum CookiesAllowed { |
| // Do not use this value. It's just a placeholder for default value. |
| UNSPECIFIED = 0; |
| // Cookies are never used. |
| NO = 1; |
| // Cookies/channel IDs/... can be sent or saved (use if at least one is |
| // correct). |
| YES = 2; |
| } |
| CookiesAllowed cookies_allowed = 1; |
| |
| // If a request sends or stores cookies/channel IDs/... (i.e. if |
| // cookies_allowed is true), we want to know which cookie store is being |
| // used. The answer to this question can typically be derived from the |
| // URLRequestContext that is being used. |
| // The three most common cases will be: |
| // - If cookies_allowed is false, leave this field unset. |
| // - If the profile's default URLRequestContext is being used (e.g. from |
| // Profile::GetRequestContext()), this means that the user's normal |
| // cookies are sent. In this case, put "user" here. |
| // - If the system URLRequestContext is being used (for example via |
| // io_thread()->system_url_request_context_getter()), put "system" here. |
| // Otherwise, please explain (e.g. SafeBrowsing uses a separate cookie |
| // store). |
| string cookies_store = 2; |
| |
| // Human readable description of how to enable/disable a feature that |
| // triggers this network request by a user (e.g. “Disable ‘Use a web service |
| // to help resolve spelling errors.’ in settings under Advanced”). |
| string setting = 3; |
| |
| // Policy configuration(s) that disable or limit this network request. |
| // This would be a text serialized protobuf of any enterprise policy. |
| // see out/Debug/gen/components/policy/proto/chrome_settings.proto |
| repeated enterprise_management.ChromeSettingsProto chrome_policy = 4; |
| |
| // Justification for not having a policy that disables this feature. |
| string policy_exception_justification = 5; |
| } |
| |
| TrafficPolicy policy = 4; |
| |
| // Human readable extra comments, if required. |
| string comments = 5; |
| }; |
| |
| // NetworkTrafficAnnotations that were extracted from the source code. |
| message ExtractedNetworkTrafficAnnotation { |
| repeated NetworkTrafficAnnotation network_traffic_annotation = 1; |
| }; |
| |
| // NetworkTrafficAnnotations that had to go into a whitelist file because the |
| // source code could not be annotated (e.g. because it is in a third-party |
| // library). |
| message WhitelistedNetworkTrafficAnnotations { |
| repeated NetworkTrafficAnnotation network_traffic_annotation = 1; |
| }; |
| |
| // All NetworkTrafficAnnotations from a Chromium configuration. |
| message NetworkTrafficAnnotations { |
| ExtractedNetworkTrafficAnnotation extracted_network_traffic_annotations = 1; |
| WhitelistedNetworkTrafficAnnotations whitelisted_network_traffic_annotations = |
| 2; |
| }; |