Fossil SCM

Update to the default CSP page. Attempted to resolve merge conflicts, but more editting is likely necessary.

drh 2019-08-21 11:26 trunk
Commit 33a7b8babe56cc9dcd6bba4b5cf9df6d3452afc350673c1d6811d171790fd088
Parent 7b843f2d4354a49…
1 file changed +71 -78
~ www/defcsp.md
M www/defcsp.md
+71 -78
--- www/defcsp.md
+++ www/defcsp.md
@@ -1,46 +1,54 @@
11
 # The Default Content Security Policy (CSP)
22
33
 When Fossil’s web interface generates an HTML page, it
44
 normally includes a [Content Security Policy][csp] (CSP)
5
-which applies to all content on that page. The CSP tells the browser
6
-which types of content (HTML, image, CSS, JavaScript...) the repository
7
-is expected to serve, and thus which types of content a compliant
8
-browser is allowed to pay attention to. All of the major browsers
9
-enforce CSP restrictions.
10
-
11
-A CSP is an important security measure on any site where some of the
12
-content it serves is user-provided. It defines a “white list” of content
13
-types believed to be safe and desirable, so that if any content outside
14
-of that definition gets inserted into the repository later, the browser
15
-will treat that unwanted content as if it was not part of the document
16
-at all.
17
-
18
-A CSP is a fairly blunt tool. It cannot tell good and visually appealing
19
-enhancements from vandalism or outright attacks. All it does is tell the
20
-browser what types and sources for page content were anticipated by the
21
-site’s creators. The browser treats everything else as “unwanted” even
22
-if that’s not actually true. When the CSP prevents the browser from
23
-displaying wanted content, you then have to understand the current rules
24
-and what they’re trying to accomplish to decide on [an appropriate
25
-workaround](#override).
26
-
5
+in the `<head>`.
6
+The CSP tells the browser what types of content (HTML, image, CSS,
7
+JavaScript...) the document may reference and from where the
8
+content may be sourced.
9
+
10
+CSP is a security measure designed to prevent [cross-site scripting][xss]
11
+(XSS) and other similar code injection attacks.
12
+The CSP defines a “white list” of content types and origins that
13
+are considered safe. Any references to resources that are not
14
+on the white list are ignored.
15
+
16
+If Fossil were perfect and bug-free and never allowed any kind of
17
+code injection on the pages it generates, then the CSP would not
18
+be useful. The Fossil developers are not aware of any defects
19
+in Fossil that allow code injection, and will promptly fix any defects
20
+that are brought to their attention. Lots of eyeballs are looking at
21
+Fossil to find problems in the code, and the Fossil build process uses
22
+custom static analysis techniques to help identify code injection problems
23
+at compile-time. Nevertheless, problems do sometimes (rarely) slip
24
+through. The CSP serves as a final line of defense, preventing
25
+code injection defects in Fossil from turning into actual
26
+vulnerabilities.
27
+
28
+Fossil site administrators can [modify the default CSP](#override), perhaps
29
+to add trusted external sources for auxiliary content. But for maximum
30
+safety, site developers are encouraged to work within the restrictions
31
+imposed by the default CSP and avoid the temptation to relax the CSP
32
+unless they fully understand the security implications of what they are
33
+doing.
2734
2835
 ## The Default Restrictions
2936
3037
 The Fossil default CSP declares the following content restrictions:
3138
3239
33
-### <a name="base"></a> default-src 'self' data
40
+### <a name="base"></a> default-src 'self' data:
3441
3542
 This policy means mixed-origin content isn’t allowed, so you can’t refer to
36
-resources on other web domains, so the following Markdown for an inline
43
+resources (images, style-sheets, and scripts) on other web domains.
44
+Hence the following Markdown for an inline
3745
 image hosted on another site will cause a CSP error:
3846
3947
 ![fancy 3D Fossil logotype](https://i.imgur.com/HalpMgt.png)
4048
41
-This policy allows inline `data:` URIs, which means you could
49
+The default policy does allows inline `data:` URIs, which means you could
4250
 [data-encode][de] your image content and put it inline within the
4351
 document:
4452
4553
 ![small inline image](data:image/gif;base64,R0lGODlh...)
4654
@@ -47,68 +55,52 @@
4755
 That method is best used for fairly small resources. Large `data:` URIs
4856
 are hard to read and edit. Keep in mind that if you put such a thing
4957
 into a Fossil forum post, anyone subscribed to email alerts will get a
5058
 copy of the raw URI text, which is really ugly.
5159
52
-For larger files, you could instead store the file in Fossil as:
53
-
54
-* **versioned content** retrieved via a [`/raw`](/help?cmd=/raw) URL
55
-* **[unversioned content](./unvers.wiki)** retrieved
56
- via a [`/uv`](/help?cmd=/uv) URL
57
-
58
-Another path around this restriction is to [serve your
59
-repo](./server/) behind an HTTP proxy server, allowing mixed-mode
60
-content serving, with static images and such served directly by the HTTP
61
-server and the dynamic content by Fossil. That allows a URI scheme that
62
-prevents the browser’s CSP enforcement from distinguishing content from
63
-Fossil proper and that from the front-end proxy.
64
-
60
+For larger images in [embedded documentation](./embeddeddoc.wiki) you
61
+store the image as a separate file in the Fossil repository and reference
62
+it via a relative URI.
63
+
64
+ ![large inline image](./inlineimage.jpg)
65
+
66
+Any content from the same domain as the Fossil repository will work fine.
67
+So if the Fossil repository is but one path in a larger website, it will
68
+be able reference other static resources within that same website. It
69
+can also reference [unversioned content](./unvers.wiki). However, as
70
+unversioned content and content outside of the Fossil repository itself
71
+will not be transferred by [sync](/help?cmd=sync), the references probably
72
+will not work in clones of your repository.
6573
6674
 ### <a name="style"></a> style-src 'self' 'unsafe-inline'
6775
68
-This policy means CSS files can only come from the Fossil server or via
69
-a front-end proxy as in the inline image workarounds above. It also says
70
-that inline CSS is disallowed; this will give a CSP error:
71
-
72
- <p style="margin-left: 4em">Some bit of indented text</p>
73
-
74
-In practice, this means you must put your CSS into [the “CSS” section of
75
-a custom skin][cs], not inline within Markdown, Wiki, or
76
-HTML tags. You can refer to specific tags in the document through “`id`”
77
-and “`class`” attributes.
78
-
79
-The reason for this restriction might not be obvious, but the risks boil
80
-down to this: CSS is sufficiently powerful that if someone can apply
81
-their CSS to your site, they can make it say things you don’t want it to
82
-say, hide important information, and more. Thus, we restrict all CSS to
83
-come from trusted channels only.
84
-
85
-We do currently trust CSS checked into the repository as a file, but
86
-that stance might be overly-trusting, so we might revoke it later, as we
87
-do for JavaScript:
88
-
76
+This policy allows CSS information to come from separate files in the
77
+same domain of the Fossil server, or for CSS to be embedded inline within
78
+the document text.
79
+
80
+The `'unsafe-inline'` element means that an injection vulnerability in
81
+Fossil would allow an attacker to modify the CSS for a Fossil-generated
82
+page. This is not ideal, but nor is it as dangerous as allowing
83
+injected javascript to run, and Fossil uses of in-line CSS
84
+for things like setting background colors in timelines and defining
85
+line widths in bar graphs on the [Activity Reports](/reports) page,
86
+so it seems like in-line CSS is a necessary compromise at this time.
8987
9088
 ### <a name="script"></a> script-src 'self' 'nonce-%s'
9189
92
-This policy means HTML `<script>` tags are only allowed to be emitted
93
-into the output HTML by Fossil C or TH1 code, because only code running
94
-in those contexts can insert the correct “nonce” tag attribute, matching
95
-the one declared in the CSP.¹ Since the nonce is a very large random
96
-number that changes on each HTTP hit Fossil handles, it is effectively
97
-unguessable, which prevents attackers from inserting `<script>` tags
98
-statically.
99
-
100
-This means the workarounds given above will not work for JavaScript.
101
-Under this policy, the only JavaScript that Fossil can serve is that
102
-which it directly provided.
103
-
104
-Users with the all-powerful Setup capability can insert arbitrary
105
-JavaScript by [defining a custom skin][cs], adding it to the skin’s
106
-“JavaScript” section, which has the random nonce automatically inserted
107
-by Fossil when it serves the page. This is how the JS backing the
108
-default skin’s [hamburger menu](./customskin.md#menu) works.
109
-
90
+This policy disables in-line javascript and only allows `<script>`
91
+elements if the `<script>` includes a `nonce=` attribute the
92
+matches the %s section of the CSP. Fossil provides a different
93
+random nonce for every page it generates, and since an attacker has
94
+no way of predicting what that nonce will be, the attacker is unable
95
+to inject working javascript.
96
+
97
+For documents generated by the [CGI extensions](./serverext.wiki), the
98
+value of the nonce is accessible in the FOSSIL_NONCE environment variable.
99
+TH1 scripts that run while generating the header or footer can access
100
+the nonce in the $nonce variable. The JavaScript section of a
101
+[custom skin][cs] automatically includes the appropriate nonce.
110102
111103
 #### <a name="xss"></a>Cross-Site Scripting via Ordinary User Capabilities
112104
113105
 We’re so restrictive about how we treat JavaScript because it can lead
114106
 to difficult-to-avoid scripting attacks. If we used the same CSP for
@@ -168,11 +160,10 @@
168160
 [fp]: ./forum.wiki
169161
 [hfed]: ./embeddeddoc.wiki#html
170162
 [tkt]: ./tickets.wiki
171163
 [tn]: ./event.wiki
172164
 [wiki]: ./wikitheory.wiki
173
-
174165
175166
 ## <a name="override"></a>Replacing the Default CSP
176167
177168
 If you wish to relax the default CSP’s restrictions or to tighten them
178169
 further, there are two ways to accomplish that:
@@ -253,5 +244,7 @@
253244
254245
255246
 [cs]: ./customskin.md
256247
 [csp]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
257248
 [de]: https://dopiaza.org/tools/datauri/index.php
249
+[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
250
+[xssci]: https://fossil-scm.org/forum/forumpost/e7c386b21f
258251
--- www/defcsp.md
+++ www/defcsp.md
@@ -1,46 +1,54 @@
1 # The Default Content Security Policy (CSP)
2
3 When Fossil’s web interface generates an HTML page, it
4 normally includes a [Content Security Policy][csp] (CSP)
5 which applies to all content on that page. The CSP tells the browser
6 which types of content (HTML, image, CSS, JavaScript...) the repository
7 is expected to serve, and thus which types of content a compliant
8 browser is allowed to pay attention to. All of the major browsers
9 enforce CSP restrictions.
10
11 A CSP is an important security measure on any site where some of the
12 content it serves is user-provided. It defines a “white list” of content
13 types believed to be safe and desirable, so that if any content outside
14 of that definition gets inserted into the repository later, the browser
15 will treat that unwanted content as if it was not part of the document
16 at all.
17
18 A CSP is a fairly blunt tool. It cannot tell good and visually appealing
19 enhancements from vandalism or outright attacks. All it does is tell the
20 browser what types and sources for page content were anticipated by the
21 site’s creators. The browser treats everything else as “unwanted” even
22 if that’s not actually true. When the CSP prevents the browser from
23 displaying wanted content, you then have to understand the current rules
24 and what they’re trying to accomplish to decide on [an appropriate
25 workaround](#override).
26
 
 
 
 
 
 
 
27
28 ## The Default Restrictions
29
30 The Fossil default CSP declares the following content restrictions:
31
32
33 ### <a name="base"></a> default-src 'self' data
34
35 This policy means mixed-origin content isn’t allowed, so you can’t refer to
36 resources on other web domains, so the following Markdown for an inline
 
37 image hosted on another site will cause a CSP error:
38
39 ![fancy 3D Fossil logotype](https://i.imgur.com/HalpMgt.png)
40
41 This policy allows inline `data:` URIs, which means you could
42 [data-encode][de] your image content and put it inline within the
43 document:
44
45 ![small inline image](data:image/gif;base64,R0lGODlh...)
46
@@ -47,68 +55,52 @@
47 That method is best used for fairly small resources. Large `data:` URIs
48 are hard to read and edit. Keep in mind that if you put such a thing
49 into a Fossil forum post, anyone subscribed to email alerts will get a
50 copy of the raw URI text, which is really ugly.
51
52 For larger files, you could instead store the file in Fossil as:
53
54 * **versioned content** retrieved via a [`/raw`](/help?cmd=/raw) URL
55 * **[unversioned content](./unvers.wiki)** retrieved
56 via a [`/uv`](/help?cmd=/uv) URL
57
58 Another path around this restriction is to [serve your
59 repo](./server/) behind an HTTP proxy server, allowing mixed-mode
60 content serving, with static images and such served directly by the HTTP
61 server and the dynamic content by Fossil. That allows a URI scheme that
62 prevents the browser’s CSP enforcement from distinguishing content from
63 Fossil proper and that from the front-end proxy.
64
65
66 ### <a name="style"></a> style-src 'self' 'unsafe-inline'
67
68 This policy means CSS files can only come from the Fossil server or via
69 a front-end proxy as in the inline image workarounds above. It also says
70 that inline CSS is disallowed; this will give a CSP error:
71
72 <p style="margin-left: 4em">Some bit of indented text</p>
73
74 In practice, this means you must put your CSS into [the “CSS” section of
75 a custom skin][cs], not inline within Markdown, Wiki, or
76 HTML tags. You can refer to specific tags in the document through “`id`”
77 and “`class`” attributes.
78
79 The reason for this restriction might not be obvious, but the risks boil
80 down to this: CSS is sufficiently powerful that if someone can apply
81 their CSS to your site, they can make it say things you don’t want it to
82 say, hide important information, and more. Thus, we restrict all CSS to
83 come from trusted channels only.
84
85 We do currently trust CSS checked into the repository as a file, but
86 that stance might be overly-trusting, so we might revoke it later, as we
87 do for JavaScript:
88
89
90 ### <a name="script"></a> script-src 'self' 'nonce-%s'
91
92 This policy means HTML `<script>` tags are only allowed to be emitted
93 into the output HTML by Fossil C or TH1 code, because only code running
94 in those contexts can insert the correct “nonce” tag attribute, matching
95 the one declared in the CSP.¹ Since the nonce is a very large random
96 number that changes on each HTTP hit Fossil handles, it is effectively
97 unguessable, which prevents attackers from inserting `<script>` tags
98 statically.
99
100 This means the workarounds given above will not work for JavaScript.
101 Under this policy, the only JavaScript that Fossil can serve is that
102 which it directly provided.
103
104 Users with the all-powerful Setup capability can insert arbitrary
105 JavaScript by [defining a custom skin][cs], adding it to the skin’s
106 “JavaScript” section, which has the random nonce automatically inserted
107 by Fossil when it serves the page. This is how the JS backing the
108 default skin’s [hamburger menu](./customskin.md#menu) works.
109
110
111 #### <a name="xss"></a>Cross-Site Scripting via Ordinary User Capabilities
112
113 We’re so restrictive about how we treat JavaScript because it can lead
114 to difficult-to-avoid scripting attacks. If we used the same CSP for
@@ -168,11 +160,10 @@
168 [fp]: ./forum.wiki
169 [hfed]: ./embeddeddoc.wiki#html
170 [tkt]: ./tickets.wiki
171 [tn]: ./event.wiki
172 [wiki]: ./wikitheory.wiki
173
174
175 ## <a name="override"></a>Replacing the Default CSP
176
177 If you wish to relax the default CSP’s restrictions or to tighten them
178 further, there are two ways to accomplish that:
@@ -253,5 +244,7 @@
253
254
255 [cs]: ./customskin.md
256 [csp]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
257 [de]: https://dopiaza.org/tools/datauri/index.php
 
 
258
--- www/defcsp.md
+++ www/defcsp.md
@@ -1,46 +1,54 @@
1 # The Default Content Security Policy (CSP)
2
3 When Fossil’s web interface generates an HTML page, it
4 normally includes a [Content Security Policy][csp] (CSP)
5 in the `<head>`.
6 The CSP tells the browser what types of content (HTML, image, CSS,
7 JavaScript...) the document may reference and from where the
8 content may be sourced.
9
10 CSP is a security measure designed to prevent [cross-site scripting][xss]
11 (XSS) and other similar code injection attacks.
12 The CSP defines a “white list” of content types and origins that
13 are considered safe. Any references to resources that are not
14 on the white list are ignored.
15
16 If Fossil were perfect and bug-free and never allowed any kind of
17 code injection on the pages it generates, then the CSP would not
18 be useful. The Fossil developers are not aware of any defects
19 in Fossil that allow code injection, and will promptly fix any defects
20 that are brought to their attention. Lots of eyeballs are looking at
21 Fossil to find problems in the code, and the Fossil build process uses
22 custom static analysis techniques to help identify code injection problems
23 at compile-time. Nevertheless, problems do sometimes (rarely) slip
24 through. The CSP serves as a final line of defense, preventing
25 code injection defects in Fossil from turning into actual
26 vulnerabilities.
27
28 Fossil site administrators can [modify the default CSP](#override), perhaps
29 to add trusted external sources for auxiliary content. But for maximum
30 safety, site developers are encouraged to work within the restrictions
31 imposed by the default CSP and avoid the temptation to relax the CSP
32 unless they fully understand the security implications of what they are
33 doing.
34
35 ## The Default Restrictions
36
37 The Fossil default CSP declares the following content restrictions:
38
39
40 ### <a name="base"></a> default-src 'self' data:
41
42 This policy means mixed-origin content isn’t allowed, so you can’t refer to
43 resources (images, style-sheets, and scripts) on other web domains.
44 Hence the following Markdown for an inline
45 image hosted on another site will cause a CSP error:
46
47 ![fancy 3D Fossil logotype](https://i.imgur.com/HalpMgt.png)
48
49 The default policy does allows inline `data:` URIs, which means you could
50 [data-encode][de] your image content and put it inline within the
51 document:
52
53 ![small inline image](data:image/gif;base64,R0lGODlh...)
54
@@ -47,68 +55,52 @@
55 That method is best used for fairly small resources. Large `data:` URIs
56 are hard to read and edit. Keep in mind that if you put such a thing
57 into a Fossil forum post, anyone subscribed to email alerts will get a
58 copy of the raw URI text, which is really ugly.
59
60 For larger images in [embedded documentation](./embeddeddoc.wiki) you
61 store the image as a separate file in the Fossil repository and reference
62 it via a relative URI.
63
64 ![large inline image](./inlineimage.jpg)
65
66 Any content from the same domain as the Fossil repository will work fine.
67 So if the Fossil repository is but one path in a larger website, it will
68 be able reference other static resources within that same website. It
69 can also reference [unversioned content](./unvers.wiki). However, as
70 unversioned content and content outside of the Fossil repository itself
71 will not be transferred by [sync](/help?cmd=sync), the references probably
72 will not work in clones of your repository.
73
74 ### <a name="style"></a> style-src 'self' 'unsafe-inline'
75
76 This policy allows CSS information to come from separate files in the
77 same domain of the Fossil server, or for CSS to be embedded inline within
78 the document text.
79
80 The `'unsafe-inline'` element means that an injection vulnerability in
81 Fossil would allow an attacker to modify the CSS for a Fossil-generated
82 page. This is not ideal, but nor is it as dangerous as allowing
83 injected javascript to run, and Fossil uses of in-line CSS
84 for things like setting background colors in timelines and defining
85 line widths in bar graphs on the [Activity Reports](/reports) page,
86 so it seems like in-line CSS is a necessary compromise at this time.
 
 
 
 
 
 
 
 
 
 
87
88 ### <a name="script"></a> script-src 'self' 'nonce-%s'
89
90 This policy disables in-line javascript and only allows `<script>`
91 elements if the `<script>` includes a `nonce=` attribute the
92 matches the %s section of the CSP. Fossil provides a different
93 random nonce for every page it generates, and since an attacker has
94 no way of predicting what that nonce will be, the attacker is unable
95 to inject working javascript.
96
97 For documents generated by the [CGI extensions](./serverext.wiki), the
98 value of the nonce is accessible in the FOSSIL_NONCE environment variable.
99 TH1 scripts that run while generating the header or footer can access
100 the nonce in the $nonce variable. The JavaScript section of a
101 [custom skin][cs] automatically includes the appropriate nonce.
 
 
 
 
 
 
102
103 #### <a name="xss"></a>Cross-Site Scripting via Ordinary User Capabilities
104
105 We’re so restrictive about how we treat JavaScript because it can lead
106 to difficult-to-avoid scripting attacks. If we used the same CSP for
@@ -168,11 +160,10 @@
160 [fp]: ./forum.wiki
161 [hfed]: ./embeddeddoc.wiki#html
162 [tkt]: ./tickets.wiki
163 [tn]: ./event.wiki
164 [wiki]: ./wikitheory.wiki
 
165
166 ## <a name="override"></a>Replacing the Default CSP
167
168 If you wish to relax the default CSP’s restrictions or to tighten them
169 further, there are two ways to accomplish that:
@@ -253,5 +244,7 @@
244
245
246 [cs]: ./customskin.md
247 [csp]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
248 [de]: https://dopiaza.org/tools/datauri/index.php
249 [xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
250 [xssci]: https://fossil-scm.org/forum/forumpost/e7c386b21f
251

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button