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