Fossil SCM

Expanded the discussion of in-repo and out-of-repo resource links in defcsp.md.

wyoung 2019-08-22 13:13 trunk
Commit 23fcd765f6183aada401460c8a3ba27fb240b45626d54cd4bbdfd0042c1908f6
Parent 1c4df5bf0a52724…
1 file changed +55 -20
~ www/defcsp.md
M www/defcsp.md
+55 -20
--- www/defcsp.md
+++ www/defcsp.md
@@ -49,41 +49,75 @@
4949
 The Fossil default CSP declares the following content restrictions:
5050
5151
5252
 ### <a name="base"></a> default-src 'self' data:
5353
54
-This policy means mixed-origin content isn’t allowed, so you can’t refer to
55
-resources (images, style-sheets, and scripts) on other web domains.
56
-Hence the following Markdown for an inline
57
-image hosted on another site will cause a CSP error:
54
+This policy means mixed-origin content isn’t allowed, so you can’t refer
55
+to resources on other web domains. Browsers will ignore a link like the
56
+one in the following Markdown under our default CSP:
5857
5958
 ![fancy 3D Fossil logotype](https://i.imgur.com/HalpMgt.png)
59
+
60
+If you look in the browser’s developer console, you should see a CSP
61
+error when attempting to render such a page.
6062
6163
 The default policy does allows inline `data:` URIs, which means you could
6264
 [data-encode][de] your image content and put it inline within the
6365
 document:
6466
6567
 ![small inline image](data:image/gif;base64,R0lGODlh...)
6668
6769
 That method is best used for fairly small resources. Large `data:` URIs
68
-are hard to read and edit. Keep in mind that if you put such a thing
69
-into a Fossil forum post, anyone subscribed to email alerts will get a
70
-copy of the raw URI text, which is really ugly.
70
+are hard to read and edit. There are secondary problems as well: if you
71
+put a large image into a Fossil forum post this way, anyone subscribed
72
+to email alerts will get a copy of the raw URI text, which can amount to
73
+pages and pages of [ugly Base64-encoded text][b64].
74
+
75
+Fossil offers several alternatives for serving large content resources
76
+from within the repository:
77
+
78
+* **versioned content** via [`/raw`](/help?cmd=/raw)
79
+* **[unversioned content](./unvers.wiki)** via [`/uv`](/help?cmd=/uv)
80
+* **relative links**
7181
72
-For larger images in [embedded documentation](./embeddeddoc.wiki) you
73
-store the image as a separate file in the Fossil repository and reference
74
-it via a relative URI.
82
+Only the first two options work in [wiki articles][wiki],
83
+[tickets][tkt], [forum posts][fp], and [tech notes][tn]. The last
84
+option is a much simpler alternative, but it only works within [embedded
85
+documentation][ed]:
7586
7687
 ![large inline image](./inlineimage.jpg)
7788
78
-Any content from the same domain as the Fossil repository will work fine.
79
-So if the Fossil repository is but one path in a larger website, it will
80
-be able reference other static resources within that same website. It
81
-can also reference [unversioned content](./unvers.wiki). However, as
82
-unversioned content and content outside of the Fossil repository itself
83
-will not be transferred by [sync](/help?cmd=sync), the references probably
84
-will not work in clones of your repository.
89
+Because all of these methods pull content from within the Fossil
90
+repository, they all count as “self” for the purposes of the CSP.
91
+
92
+This rule also works when the Fossil repository is but one path in a
93
+larger website. The browser can’t distinguish Fossil-served content from
94
+that served by the rest of the same web domain, so your repository can
95
+refer to other resources within that same web site, whether they are
96
+static files served by [an HTTP proxy in front of Fossil][svr], by
97
+another Fossil repository served under that same domain, or dynamic
98
+content served by, say, a PHP app on that same site.
99
+
100
+Beware that there are a number of problems that come up with using such
101
+out-of-repository resources, which all stem from the fact that they
102
+aren’t included in a [sync](/help?cmd=sync):
103
+
104
+1. Relative links break in `fossil ui` when run on a clone.
105
+
106
+2. Absolute links break under certain types of failover and
107
+ load-balancing schemes.
108
+
109
+3. Absolute links fail when one’s purpose in using a clone is to
110
+ recover from the loss of a project web site by standing that clone
111
+ up [as a server][svr] elsewhere.
112
+
113
+You can avoid all of these problems by referring to in-repo resources
114
+exclusively.
115
+
116
+[b64]: https://en.wikipedia.org/wiki/Base64
117
+[svr]: ./server/
118
+
85119
86120
 ### <a name="style"></a> style-src 'self' 'unsafe-inline'
87121
88122
 This policy allows CSS information to come from separate files in the
89123
 same domain of the Fossil server, or for CSS to be embedded inline within
@@ -104,11 +138,11 @@
104138
 matches the %s section of the CSP. Fossil provides a different
105139
 random nonce for every page it generates, and since an attacker has
106140
 no way of predicting what that nonce will be, the attacker is unable
107141
 to inject working javascript.
108142
109
-For documents generated by the [CGI extensions](./serverext.wiki), the
143
+For documents generated by the [CGI extensions][ext], the
110144
 value of the nonce is accessible in the FOSSIL_NONCE environment variable.
111145
 TH1 scripts that run while generating the header or footer can access
112146
 the nonce in the $nonce variable. The JavaScript section of a
113147
 [custom skin][cs] automatically includes the appropriate nonce.
114148
@@ -167,10 +201,11 @@
167201
 since the only way to create or modify HTML-formatted embedded docs is
168202
 through check-ins.
169203
170204
 [ed]: ./embeddeddoc.wiki
171205
 [edtf]: ./embeddeddoc.wiki#th1
206
+[ext]: ./serverext.wiki
172207
 [fp]: ./forum.wiki
173208
 [hfed]: ./embeddeddoc.wiki#html
174209
 [tkt]: ./tickets.wiki
175210
 [tn]: ./event.wiki
176211
 [wiki]: ./wikitheory.wiki
@@ -232,11 +267,11 @@
232267
233268
 This then tells you one way to override Fossil’s default CSP: provide
234269
 your own HTML header in a custom skin.
235270
236271
 A useful combination is to entirely override the default CSP in the skin
237
-but then provide a new CSP [in the front-end proxy layer](./server/)
272
+but then provide a new CSP [in the front-end proxy layer][svr]
238273
 using any of the many reverse proxy servers that can define custom HTTP
239274
 headers.
240275
241276
242277
 ------------
@@ -243,11 +278,11 @@
243278
244279
245280
 **Asides and Digressions:**
246281
247282
 1. There is actually a third context that can correctly insert this
248
- nonce attribute: [a CGI server extension](./serverext.wiki), by use of
283
+ nonce attribute: [a CGI server extension][ext], by use of
249284
 the `FOSSIL_NONCE` variable sent to the CGI by Fossil.
250285
251286
 2. The stock Bootstrap skin does actually include a `<head>` tag, but
252287
 from Fossil 2.7 through Fossil 2.9, it just repeated the same CSP
253288
 text that Fossil’s C code inserts into the HTML header for all other
254289
--- www/defcsp.md
+++ www/defcsp.md
@@ -49,41 +49,75 @@
49 The Fossil default CSP declares the following content restrictions:
50
51
52 ### <a name="base"></a> default-src 'self' data:
53
54 This policy means mixed-origin content isn’t allowed, so you can’t refer to
55 resources (images, style-sheets, and scripts) on other web domains.
56 Hence the following Markdown for an inline
57 image hosted on another site will cause a CSP error:
58
59 ![fancy 3D Fossil logotype](https://i.imgur.com/HalpMgt.png)
 
 
 
60
61 The default policy does allows inline `data:` URIs, which means you could
62 [data-encode][de] your image content and put it inline within the
63 document:
64
65 ![small inline image](data:image/gif;base64,R0lGODlh...)
66
67 That method is best used for fairly small resources. Large `data:` URIs
68 are hard to read and edit. Keep in mind that if you put such a thing
69 into a Fossil forum post, anyone subscribed to email alerts will get a
70 copy of the raw URI text, which is really ugly.
 
 
 
 
 
 
 
 
71
72 For larger images in [embedded documentation](./embeddeddoc.wiki) you
73 store the image as a separate file in the Fossil repository and reference
74 it via a relative URI.
 
75
76 ![large inline image](./inlineimage.jpg)
77
78 Any content from the same domain as the Fossil repository will work fine.
79 So if the Fossil repository is but one path in a larger website, it will
80 be able reference other static resources within that same website. It
81 can also reference [unversioned content](./unvers.wiki). However, as
82 unversioned content and content outside of the Fossil repository itself
83 will not be transferred by [sync](/help?cmd=sync), the references probably
84 will not work in clones of your repository.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
85
86 ### <a name="style"></a> style-src 'self' 'unsafe-inline'
87
88 This policy allows CSS information to come from separate files in the
89 same domain of the Fossil server, or for CSS to be embedded inline within
@@ -104,11 +138,11 @@
104 matches the %s section of the CSP. Fossil provides a different
105 random nonce for every page it generates, and since an attacker has
106 no way of predicting what that nonce will be, the attacker is unable
107 to inject working javascript.
108
109 For documents generated by the [CGI extensions](./serverext.wiki), the
110 value of the nonce is accessible in the FOSSIL_NONCE environment variable.
111 TH1 scripts that run while generating the header or footer can access
112 the nonce in the $nonce variable. The JavaScript section of a
113 [custom skin][cs] automatically includes the appropriate nonce.
114
@@ -167,10 +201,11 @@
167 since the only way to create or modify HTML-formatted embedded docs is
168 through check-ins.
169
170 [ed]: ./embeddeddoc.wiki
171 [edtf]: ./embeddeddoc.wiki#th1
 
172 [fp]: ./forum.wiki
173 [hfed]: ./embeddeddoc.wiki#html
174 [tkt]: ./tickets.wiki
175 [tn]: ./event.wiki
176 [wiki]: ./wikitheory.wiki
@@ -232,11 +267,11 @@
232
233 This then tells you one way to override Fossil’s default CSP: provide
234 your own HTML header in a custom skin.
235
236 A useful combination is to entirely override the default CSP in the skin
237 but then provide a new CSP [in the front-end proxy layer](./server/)
238 using any of the many reverse proxy servers that can define custom HTTP
239 headers.
240
241
242 ------------
@@ -243,11 +278,11 @@
243
244
245 **Asides and Digressions:**
246
247 1. There is actually a third context that can correctly insert this
248 nonce attribute: [a CGI server extension](./serverext.wiki), by use of
249 the `FOSSIL_NONCE` variable sent to the CGI by Fossil.
250
251 2. The stock Bootstrap skin does actually include a `<head>` tag, but
252 from Fossil 2.7 through Fossil 2.9, it just repeated the same CSP
253 text that Fossil’s C code inserts into the HTML header for all other
254
--- www/defcsp.md
+++ www/defcsp.md
@@ -49,41 +49,75 @@
49 The Fossil default CSP declares the following content restrictions:
50
51
52 ### <a name="base"></a> default-src 'self' data:
53
54 This policy means mixed-origin content isn’t allowed, so you can’t refer
55 to resources on other web domains. Browsers will ignore a link like the
56 one in the following Markdown under our default CSP:
 
57
58 ![fancy 3D Fossil logotype](https://i.imgur.com/HalpMgt.png)
59
60 If you look in the browser’s developer console, you should see a CSP
61 error when attempting to render such a page.
62
63 The default policy does allows inline `data:` URIs, which means you could
64 [data-encode][de] your image content and put it inline within the
65 document:
66
67 ![small inline image](data:image/gif;base64,R0lGODlh...)
68
69 That method is best used for fairly small resources. Large `data:` URIs
70 are hard to read and edit. There are secondary problems as well: if you
71 put a large image into a Fossil forum post this way, anyone subscribed
72 to email alerts will get a copy of the raw URI text, which can amount to
73 pages and pages of [ugly Base64-encoded text][b64].
74
75 Fossil offers several alternatives for serving large content resources
76 from within the repository:
77
78 * **versioned content** via [`/raw`](/help?cmd=/raw)
79 * **[unversioned content](./unvers.wiki)** via [`/uv`](/help?cmd=/uv)
80 * **relative links**
81
82 Only the first two options work in [wiki articles][wiki],
83 [tickets][tkt], [forum posts][fp], and [tech notes][tn]. The last
84 option is a much simpler alternative, but it only works within [embedded
85 documentation][ed]:
86
87 ![large inline image](./inlineimage.jpg)
88
89 Because all of these methods pull content from within the Fossil
90 repository, they all count as “self” for the purposes of the CSP.
91
92 This rule also works when the Fossil repository is but one path in a
93 larger website. The browser can’t distinguish Fossil-served content from
94 that served by the rest of the same web domain, so your repository can
95 refer to other resources within that same web site, whether they are
96 static files served by [an HTTP proxy in front of Fossil][svr], by
97 another Fossil repository served under that same domain, or dynamic
98 content served by, say, a PHP app on that same site.
99
100 Beware that there are a number of problems that come up with using such
101 out-of-repository resources, which all stem from the fact that they
102 aren’t included in a [sync](/help?cmd=sync):
103
104 1. Relative links break in `fossil ui` when run on a clone.
105
106 2. Absolute links break under certain types of failover and
107 load-balancing schemes.
108
109 3. Absolute links fail when one’s purpose in using a clone is to
110 recover from the loss of a project web site by standing that clone
111 up [as a server][svr] elsewhere.
112
113 You can avoid all of these problems by referring to in-repo resources
114 exclusively.
115
116 [b64]: https://en.wikipedia.org/wiki/Base64
117 [svr]: ./server/
118
119
120 ### <a name="style"></a> style-src 'self' 'unsafe-inline'
121
122 This policy allows CSS information to come from separate files in the
123 same domain of the Fossil server, or for CSS to be embedded inline within
@@ -104,11 +138,11 @@
138 matches the %s section of the CSP. Fossil provides a different
139 random nonce for every page it generates, and since an attacker has
140 no way of predicting what that nonce will be, the attacker is unable
141 to inject working javascript.
142
143 For documents generated by the [CGI extensions][ext], the
144 value of the nonce is accessible in the FOSSIL_NONCE environment variable.
145 TH1 scripts that run while generating the header or footer can access
146 the nonce in the $nonce variable. The JavaScript section of a
147 [custom skin][cs] automatically includes the appropriate nonce.
148
@@ -167,10 +201,11 @@
201 since the only way to create or modify HTML-formatted embedded docs is
202 through check-ins.
203
204 [ed]: ./embeddeddoc.wiki
205 [edtf]: ./embeddeddoc.wiki#th1
206 [ext]: ./serverext.wiki
207 [fp]: ./forum.wiki
208 [hfed]: ./embeddeddoc.wiki#html
209 [tkt]: ./tickets.wiki
210 [tn]: ./event.wiki
211 [wiki]: ./wikitheory.wiki
@@ -232,11 +267,11 @@
267
268 This then tells you one way to override Fossil’s default CSP: provide
269 your own HTML header in a custom skin.
270
271 A useful combination is to entirely override the default CSP in the skin
272 but then provide a new CSP [in the front-end proxy layer][svr]
273 using any of the many reverse proxy servers that can define custom HTTP
274 headers.
275
276
277 ------------
@@ -243,11 +278,11 @@
278
279
280 **Asides and Digressions:**
281
282 1. There is actually a third context that can correctly insert this
283 nonce attribute: [a CGI server extension][ext], by use of
284 the `FOSSIL_NONCE` variable sent to the CGI by Fossil.
285
286 2. The stock Bootstrap skin does actually include a `<head>` tag, but
287 from Fossil 2.7 through Fossil 2.9, it just repeated the same CSP
288 text that Fossil’s C code inserts into the HTML header for all other
289

Keyboard Shortcuts

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