Fossil

Check-in [33a7b8ba]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Update to the default CSP page. Attempted to resolve merge conflicts, but more editting is likely necessary.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 33a7b8babe56cc9dcd6bba4b5cf9df6d3452afc350673c1d6811d171790fd088
User & Date: drh 2019-08-21 11:26:19
Context
2019-08-21
12:32
Disallow versioning of security sensitive settings tcl-setup, th1-setup, and th1-uri-regexp. For effective security, these settings should only be controllable by an administrator. check-in: 2da704c5 user: drh tags: trunk
11:26
Update to the default CSP page. Attempted to resolve merge conflicts, but more editting is likely necessary. check-in: 33a7b8ba user: drh tags: trunk
11:09
Added a header to the new XSS material in defcsp.md so we can refer directly to it. check-in: 7b843f2d user: wyoung tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to www/defcsp.md.

1
2
3
4
5
6
7
8
9
10

11
12
13
14
15
16
17


18
19
20
21
22
23
24
25

26






27
28
29
30
31
32
33
34
35

36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52


53
54
55
56
57
58
59
60
61
62
63
64

65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
...
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
...
251
252
253
254
255
256
257


# The Default Content Security Policy (CSP)

When Fossil’s web interface generates an HTML page, it
normally includes a [Content Security Policy][csp] (CSP)
which applies to all content on that page. The CSP tells the browser
which types of content (HTML, image, CSS, JavaScript...) the repository
is expected to serve, and thus which types of content a compliant
browser is allowed to pay attention to. All of the major browsers
enforce CSP restrictions.


A CSP is an important security measure on any site where some of the
content it serves is user-provided. It defines a “white list” of content
types believed to be safe and desirable, so that if any content outside
of that definition gets inserted into the repository later, the browser
will treat that unwanted content as if it was not part of the document
at all.



A CSP is a fairly blunt tool. It cannot tell good and visually appealing
enhancements from vandalism or outright attacks. All it does is tell the
browser what types and sources for page content were anticipated by the
site’s creators. The browser treats everything else as “unwanted” even
if that’s not actually true. When the CSP prevents the browser from
displaying wanted content, you then have to understand the current rules
and what they’re trying to accomplish to decide on [an appropriate
workaround](#override).









## The Default Restrictions

The Fossil default CSP declares the following content restrictions:


### <a name="base"></a> default-src 'self' data

This policy means mixed-origin content isn’t allowed, so you can’t refer to

resources on other web domains, so the following Markdown for an inline
image hosted on another site will cause a CSP error:

         ![fancy 3D Fossil logotype](https://i.imgur.com/HalpMgt.png)

This policy allows inline `data:` URIs, which means you could
[data-encode][de] your image content and put it inline within the
document:

         ![small inline image](data:image/gif;base64,R0lGODlh...)

That method is best used for fairly small resources. Large `data:` URIs
are hard to read and edit. Keep in mind that if you put such a thing
into a Fossil forum post, anyone subscribed to email alerts will get a
copy of the raw URI text, which is really ugly.

For larger files, you could instead store the file in Fossil as:



*   **versioned content** retrieved via a [`/raw`](/help?cmd=/raw) URL
*   **[unversioned content](./unvers.wiki)** retrieved
    via a [`/uv`](/help?cmd=/uv) URL

Another path around this restriction is to [serve your
repo](./server/) behind an HTTP proxy server, allowing mixed-mode
content serving, with static images and such served directly by the HTTP
server and the dynamic content by Fossil. That allows a URI scheme that
prevents the browser’s CSP enforcement from distinguishing content from
Fossil proper and that from the front-end proxy.



### <a name="style"></a> style-src 'self' 'unsafe-inline'

This policy means CSS files can only come from the Fossil server or via
a front-end proxy as in the inline image workarounds above. It also says
that inline CSS is disallowed; this will give a CSP error:

        <p style="margin-left: 4em">Some bit of indented text</p>

In practice, this means you must put your CSS into [the “CSS” section of
a custom skin][cs], not inline within Markdown, Wiki, or
HTML tags. You can refer to specific tags in the document through “`id`”
and “`class`” attributes.

The reason for this restriction might not be obvious, but the risks boil
down to this: CSS is sufficiently powerful that if someone can apply
their CSS to your site, they can make it say things you don’t want it to
say, hide important information, and more. Thus, we restrict all CSS to
come from trusted channels only.

We do currently trust CSS checked into the repository as a file, but
that stance might be overly-trusting, so we might revoke it later, as we
do for JavaScript:


### <a name="script"></a> script-src 'self' 'nonce-%s'

This policy means HTML `<script>` tags are only allowed to be emitted
into the output HTML by Fossil C or TH1 code, because only code running
in those contexts can insert the correct “nonce” tag attribute, matching
the one declared in the CSP.¹ Since the nonce is a very large random
number that changes on each HTTP hit Fossil handles, it is effectively
unguessable, which prevents attackers from inserting `<script>` tags
statically.

This means the workarounds given above will not work for JavaScript.
Under this policy, the only JavaScript that Fossil can serve is that
which it directly provided.

Users with the all-powerful Setup capability can insert arbitrary
JavaScript by [defining a custom skin][cs], adding it to the skin’s
“JavaScript” section, which has the random nonce automatically inserted
by Fossil when it serves the page. This is how the JS backing the
default skin’s [hamburger menu](./customskin.md#menu) works.


#### <a name="xss"></a>Cross-Site Scripting via Ordinary User Capabilities

We’re so restrictive about how we treat JavaScript because it can lead
to difficult-to-avoid scripting attacks. If we used the same CSP for
`<script>` tags [as for `<style>` tags](#style), anyone with check-in
rights on your repository could add a JavaScript file to your repository
................................................................................
[ed]:   ./embeddeddoc.wiki
[edtf]: ./embeddeddoc.wiki#th1
[fp]:   ./forum.wiki
[hfed]: ./embeddeddoc.wiki#html
[tkt]:  ./tickets.wiki
[tn]:   ./event.wiki
[wiki]: ./wikitheory.wiki


## <a name="override"></a>Replacing the Default CSP

If you wish to relax the default CSP’s restrictions or to tighten them
further, there are two ways to accomplish that:


................................................................................
    stock skins. With Fossil 2.10, the stock Bootstrap skin uses
    `$default_csp` instead, so you can [override it as above](#th1).


[cs]:    ./customskin.md
[csp]:   https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
[de]:    https://dopiaza.org/tools/datauri/index.php






|
|
|
|
<

>
|
|
|
|
<
<

>
>
|
|
|
|
|
|
|
|
>

>
>
>
>
>
>






|


>
|




|










|
>
>

<
<
|

|
|
|
|
|
|
<
>



|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<







 







<







 







>
>
1
2
3
4
5
6
7
8

9
10
11
12
13
14


15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63


64
65
66
67
68
69
70
71

72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
















102
103
104
105
106
107
108
...
158
159
160
161
162
163
164

165
166
167
168
169
170
171
...
242
243
244
245
246
247
248
249
250
# The Default Content Security Policy (CSP)

When Fossil’s web interface generates an HTML page, it
normally includes a [Content Security Policy][csp] (CSP)
in the `<head>`.
The CSP tells the browser what types of content (HTML, image, CSS,
JavaScript...) the document may reference and from where the
content may be sourced.


CSP is a security measure designed to prevent [cross-site scripting][xss]
(XSS) and other similar code injection attacks.
The CSP defines a “white list” of content types and origins that
are considered safe.  Any references to resources that are not
on the white list are ignored.



If Fossil were perfect and bug-free and never allowed any kind of
code injection on the pages it generates, then the CSP would not
be useful.  The Fossil developers are not aware of any defects
in Fossil that allow code injection, and will promptly fix any defects 
that are brought to their attention.  Lots of eyeballs are looking at
Fossil to find problems in the code, and the Fossil build process uses
custom static analysis techniques to help identify code injection problems
at compile-time.  Nevertheless, problems do sometimes (rarely) slip
through.  The CSP serves as a final line of defense, preventing
code injection defects in Fossil from turning into actual
vulnerabilities.

Fossil site administrators can [modify the default CSP](#override), perhaps
to add trusted external sources for auxiliary content.  But for maximum
safety, site developers are encouraged to work within the restrictions
imposed by the default CSP and avoid the temptation to relax the CSP
unless they fully understand the security implications of what they are
doing.

## The Default Restrictions

The Fossil default CSP declares the following content restrictions:


### <a name="base"></a> default-src 'self' data:

This policy means mixed-origin content isn’t allowed, so you can’t refer to
resources (images, style-sheets, and scripts) on other web domains.
Hence the following Markdown for an inline
image hosted on another site will cause a CSP error:

         ![fancy 3D Fossil logotype](https://i.imgur.com/HalpMgt.png)

The default policy does allows inline `data:` URIs, which means you could
[data-encode][de] your image content and put it inline within the
document:

         ![small inline image](data:image/gif;base64,R0lGODlh...)

That method is best used for fairly small resources. Large `data:` URIs
are hard to read and edit. Keep in mind that if you put such a thing
into a Fossil forum post, anyone subscribed to email alerts will get a
copy of the raw URI text, which is really ugly.

For larger images in [embedded documentation](./embeddeddoc.wiki) you
store the image as a separate file in the Fossil repository and reference
it via a relative URI.



         ![large inline image](./inlineimage.jpg)

Any content from the same domain as the Fossil repository will work fine.
So if the Fossil repository is but one path in a larger website, it will
be able reference other static resources within that same website.  It
can also reference [unversioned content](./unvers.wiki).  However, as
unversioned content and content outside of the Fossil repository itself
will not be transferred by [sync](/help?cmd=sync), the references probably

will not work in clones of your repository.

### <a name="style"></a> style-src 'self' 'unsafe-inline'

This policy allows CSS information to come from separate files in the
same domain of the Fossil server, or for CSS to be embedded inline within
the document text.

The `'unsafe-inline'` element means that an injection vulnerability in
Fossil would allow an attacker to modify the CSS for a Fossil-generated
page.  This is not ideal, but nor is it as dangerous as allowing
injected javascript to run, and Fossil uses of in-line CSS
for things like setting background colors in timelines and defining
line widths in bar graphs on the [Activity Reports](/reports) page, 
so it seems like in-line CSS is a necessary compromise at this time.

### <a name="script"></a> script-src 'self' 'nonce-%s'

This policy disables in-line javascript and only allows `<script>`
elements if the `<script>` includes a `nonce=` attribute the
matches the %s section of the CSP.  Fossil provides a different
random nonce for every page it generates, and since an attacker has
no way of predicting what that nonce will be, the attacker is unable
to inject working javascript.

For documents generated by the [CGI extensions](./serverext.wiki), the
value of the nonce is accessible in the FOSSIL_NONCE environment variable.
TH1 scripts that run while generating the header or footer can access
the nonce in the $nonce variable.  The JavaScript section of a
[custom skin][cs] automatically includes the appropriate nonce.

















#### <a name="xss"></a>Cross-Site Scripting via Ordinary User Capabilities

We’re so restrictive about how we treat JavaScript because it can lead
to difficult-to-avoid scripting attacks. If we used the same CSP for
`<script>` tags [as for `<style>` tags](#style), anyone with check-in
rights on your repository could add a JavaScript file to your repository
................................................................................
[ed]:   ./embeddeddoc.wiki
[edtf]: ./embeddeddoc.wiki#th1
[fp]:   ./forum.wiki
[hfed]: ./embeddeddoc.wiki#html
[tkt]:  ./tickets.wiki
[tn]:   ./event.wiki
[wiki]: ./wikitheory.wiki


## <a name="override"></a>Replacing the Default CSP

If you wish to relax the default CSP’s restrictions or to tighten them
further, there are two ways to accomplish that:


................................................................................
    stock skins. With Fossil 2.10, the stock Bootstrap skin uses
    `$default_csp` instead, so you can [override it as above](#th1).


[cs]:    ./customskin.md
[csp]:   https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
[de]:    https://dopiaza.org/tools/datauri/index.php
[xss]:   https://en.wikipedia.org/wiki/Cross-site_scripting
[xssci]: https://fossil-scm.org/forum/forumpost/e7c386b21f