OLD | NEW |
---|---|
(Empty) | |
1 # Behavior of Download File Types in Chrome | |
2 | |
3 This describes how to adjust file-type download behavior in Chrome including | |
4 interactions with Safe Browsing. The metadata in download_file_types.asciipb | |
5 is both baked into Chrome and pushable to Chrome between releases. | |
6 | |
7 Rendered version of this file: https://chromium.googlesource.com/chromium/src/+/ master/chrome/browser/resources/safe_browsing/README.md | |
8 | |
9 | |
10 # Procedure for adding a new type | |
11 * Edit `download_file_types.asciipb`. Update `histograms.xml` | |
12 * Get it reviewed, submit. | |
13 * Push via component update (PROCEDURE TBD) | |
14 | |
15 # Guidelines for a DownloadFileType entry: | |
16 See `download_file_types.proto` for all fields. | |
17 * `extension` value must be unique within the config. It should be | |
18 lowercase ASCII and not contain a dot. If there _is_ a duplicate, | |
19 last one will win. Only the default_file_type should leave this unset. | |
20 * `uma_value` value must be unique and match one in the | |
21 SBClientDownloadExtensions enum in histograms.xml | |
22 * `is_archive`: True if this filetype is a container for other files. | |
23 Leave it unset for 'false'. | |
asanka
2016/04/11 20:45:03
Nit: backticks.
Nathan Parker
2016/04/12 21:03:41
Done.
| |
24 * `platform_settings`: (repeated) Must have one entry with an unset | |
25 `platform` field, and optionally additional entries with overrides | |
26 for one or more platforms. An unset `platform` field acts as a | |
27 default for any platforms that don't have an override. There should | |
28 not be two settings with the same `platform`, but if there are, | |
29 last one wins. Keep them sorted by platform. | |
asanka
2016/04/11 20:45:02
Implementation-wise, "first one wins" is better. T
Nathan Parker
2016/04/12 21:03:41
Done.
| |
30 * `platform_settings.danger_level`: Required. | |
31 * `NOT_DANGEROUS`: Safe to download and open, even if the download | |
32 was accidental. | |
33 * `DANGEROUS`: Always warn the user that this file may harm their | |
34 computer. We let them continue or discard the file. If Safe | |
35 Browsing returns a SAFE verdict, we still warn the user. | |
36 * `ALLOW_ON_USER_GESTURE`: Warn the user normally but skip the warning | |
37 if there was a user gesture or the user visited this site before | |
38 midnight last night (i.e. is a repeat visit). If Safe Browsing | |
39 returns a SAFE verdict for this file, it won't show a warning. | |
40 * `platform_settings.auto_open_hint`: Required. | |
41 * `ALLOW_AUTO_OPEN`: File type can be opened automatically if the user | |
42 selected that option from the download tray on a previous download | |
43 of this type. | |
44 * `DISALLOW_AUTO_OPEN`: Never let the file automatically open. | |
45 Files that should be disallowed from auto-opening include those that | |
46 execute arbitrary or harmful code with user privileges, or change | |
47 configuration of the system to cause harmful behavior immediately | |
48 or at some time in the future. We *do* allow auto-open for files | |
49 that upon opening sufficiently warn the user about the fact that it | |
50 was downloaded from the internet and can do damage. (TODO(asanka): | |
51 Clarify this sentence: We don't warn for files that... | |
asanka
2016/04/11 20:45:02
To rephrase:
"Some file types (e.g.: .local and .
Nathan Parker
2016/04/12 21:03:41
Done.
| |
52 "do nothing particularly dangerous, despite the act | |
53 of downloading itself being dangerous (E.g. .local and .manifest | |
54 files)). | |
55 * `platform_settings.ping_setting`: Required. This controls what sort | |
56 of ping is sent to Safe Browsing and if a verdict is checked before | |
57 the user can access the file. | |
58 * `SAMPLED_PING`: Don't send a full Safe Browsing ping, but | |
59 send a no-PII "light-ping" for a random sample of SBER users. | |
60 This should be the default for unknown types. The verdict won't | |
61 be used. | |
62 * `NO_PING`: Don’t send any pings. This file is whitelisted. All | |
63 NOT_DANGEROUS files should normally use this. | |
64 * `FULL_PING`: Send full pings and use the verdict. All dangerous | |
65 file should use this. | |
66 * TODO(nparker): Support this: `platform_settings.unpacker`: | |
67 optional. Specifies which archive unpacker internal to Chrome | |
68 should be used. If potentially dangerous file types are found, | |
69 Chrome will send a full-ping for the entire file. Otherwise, it'll | |
70 follow the ping settings. Can be one of UNPACKER_ZIP or UNPACKER_DMG. | |
71 | |
72 # Guidelines for the top level DownloadFileTypeConfig entry: | |
73 * `version_id`: Must be increased (+1) every time the file is checked in. | |
74 Will be logged to UMA. | |
75 | |
76 * `light_ping_probability`: For what fraction of extended-reporting users' | |
77 downloads with unknown extensions (or ping_setting=SAMPLED_PING) | |
78 should we send light-pings? [0..1] | |
79 | |
80 * `file_type`: The big list of all known file types. Keep them | |
81 sorted by extension. | |
82 | |
83 * `default_file_type`: Settings used if a file is not in the above list. | |
84 `extension` is ignored, but other settings are used. The ping_setting | |
85 should be SAMPLED_PING for all platforms. | |
86 | |
OLD | NEW |