chrome/browser/resources/safe_browsing/README.md - Issue 1881273002: Revert of Add download_file_types.proto with ascii->binary conversion, as a resource.

Side by Side Diff: chrome/browser/resources/safe_browsing/README.md

Issue 1881273002: Revert of Add download_file_types.proto with ascii->binary conversion, as a resource. (Closed) Base URL: https://chromium.googlesource.com/chromium/src.git@master

Patch Set: Created 4 years, 8 months ago

Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.

Jump to:

View unified diff | Download patch

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