Fossil SCM
Rewrote the section "Overriding the Default CSP" in the defcsp.md doc. Although it's hard to see from the diffs, it largly just adds more detail to what it already said.
Commit
896aa056498a86afe5417dbf8c3472f5fbae1324c479678b2f5b4f13ca9dea62
Parent
f5778d0d9116642…
1 file changed
+151
-65
+151
-65
| --- www/defcsp.md | ||
| +++ www/defcsp.md | ||
| @@ -304,80 +304,163 @@ | ||
| 304 | 304 | |
| 305 | 305 | |
| 306 | 306 | ## <a name="override"></a>Overriding the Default CSP |
| 307 | 307 | |
| 308 | 308 | If you wish to relax the default CSP’s restrictions or to tighten them |
| 309 | -further, there are multiple ways to accomplish that: | |
| 309 | +further, there are multiple ways to accomplish that. | |
| 310 | + | |
| 311 | +The following methods are listed in top-down order to give the simplest | |
| 312 | +and most straightforward method first. Further methods dig down deeper | |
| 313 | +into the stack, which is helpful to understand even if you end up using | |
| 314 | +a higher-level method. | |
| 315 | + | |
| 310 | 316 | |
| 311 | 317 | ### <a name="cspsetting"></a>The `default-csp` Setting |
| 312 | 318 | |
| 313 | -If the [`default-csp` setting](/help?cmd=default-csp) | |
| 314 | -is defined and is not an empty string, | |
| 315 | -then the content of that setting is used as the default CSP. This | |
| 316 | -is the easiest way to use non-standard CSP on your site. | |
| 317 | - | |
| 318 | -You can edit the default-csp setting directly from the web interface | |
| 319 | -by visiting the Admin/Settings page and changing the text in the | |
| 320 | -edit box for "default-csp". | |
| 319 | +If the [`default-csp` setting](/help?cmd=default-csp) is defined and is | |
| 320 | +not an empty string, its value is injected into the page using | |
| 321 | +[TH1](./th1.md) via one or more of the methods below, depending on the | |
| 322 | +skin you’re using and local configuration. | |
| 323 | + | |
| 324 | +Changing this setting is the easiest way to set a nonstandard CSP on | |
| 325 | +your site. | |
| 326 | + | |
| 327 | +Because a blank setting tells Fossil to use its hard-coded default CSP, | |
| 328 | +you have to say something like the following to get a repository without | |
| 329 | +content security policy restrictions: | |
| 330 | + | |
| 331 | + $ fossil set -R /path/to/served/repo.fossil default-csp 'default-src *' | |
| 332 | + | |
| 333 | +We recommend that instead of using the command line to change this | |
| 334 | +setting that you do it via the repository’s web interface, in | |
| 335 | +Admin → Settings. Write your CSP rules in the edit box marked | |
| 336 | +"`default-csp`". Do not add hard newlines in that box: the setting needs | |
| 337 | +to be on a single long line. Beware that changes take effect | |
| 338 | +immediately, so be careful with your edits: you could end up locking | |
| 339 | +yourself out of the repository with certain CSP changes! | |
| 340 | + | |
| 341 | +There are a few reasons why changing this setting via the command line | |
| 342 | +is inadvisable, except for very short settings like the example above: | |
| 343 | + | |
| 344 | +1. You have to be sure to set it on the repository where you want the | |
| 345 | + CSP to apply. Changing this setting on your local clone doesn’t | |
| 346 | + affect the remote repo you cloned from, which is most likely where | |
| 347 | + you want the CSP restrictions. | |
| 348 | + | |
| 349 | +2. For more complicated CSPs, the quoting rules for your shell and the | |
| 350 | + CSP syntax may interact, making it difficult or impossible to set | |
| 351 | + your desired CSP via the command line. Setting it via the web UI | |
| 352 | + doesn’t have this problem. | |
| 353 | + | |
| 321 | 354 | |
| 322 | 355 | |
| 323 | 356 | ### <a name="th1"></a>TH1 Setup Hook |
| 324 | 357 | |
| 325 | -The stock CSP text is hard-coded in the Fossil C source code, but it’s | |
| 326 | -only used to set the default value of one of [the TH1 skinning | |
| 327 | -variables](./customskin.md#vars), `$default_csp`. That means you can | |
| 328 | -override the default CSP by giving this variable a value before Fossil | |
| 329 | -sees that it’s undefined and uses this default. | |
| 330 | - | |
| 331 | -The best place to do that is from the [`th1-setup` | |
| 332 | -script](./th1-hooks.md), which runs before TH1 processing happens during | |
| 333 | -skin processing: | |
| 358 | +Fossil sets [the TH1 variable `$default_csp`][thvar] from the | |
| 359 | +`default-csp` setting and uses *that* to inject the value into generated | |
| 360 | +HTML pages in its stock configuration. | |
| 361 | + | |
| 362 | +This means that another way you can override this value is to use | |
| 363 | +the [`th1-setup` hook script](./th1-hooks.md), which runs before TH1 | |
| 364 | +processing happens during skin processing: | |
| 334 | 365 | |
| 335 | 366 | $ fossil set th1-setup "set default_csp {default-src 'self'}" |
| 336 | 367 | |
| 337 | -This is the cleanest method, allowing you to set a custom CSP without | |
| 338 | -recompiling Fossil or providing a hand-written `<head>` section in the | |
| 339 | -Header section of a custom skin. | |
| 340 | - | |
| 341 | -You can’t remove the CSP entirely with this method, but you can get the | |
| 342 | -same effect by telling the browser there are no content restrictions: | |
| 343 | - | |
| 344 | - $ fossil set th1-setup 'set default_csp {default-src *}' | |
| 345 | - | |
| 346 | - | |
| 347 | -### <a name="header"></a>Custom Skin Header | |
| 348 | - | |
| 349 | -Fossil only inserts a CSP into the HTML pages it generates when the | |
| 350 | -[skin’s Header section](./customskin.md#headfoot) doesn’t contain a | |
| 351 | -`<head>` tag. None of the stock skins include a `<head>` tag,² so if you | |
| 352 | -haven’t [created a custom skin][cs], you should be getting Fossil’s | |
| 353 | -default CSP. | |
| 354 | - | |
| 355 | -We say “should” because long-time Fossil users may be hanging onto a | |
| 356 | -legacy behavior from before Fossil 2.5, when Fossil added this automatic | |
| 357 | -`<head>` insertion feature. Repositories created before that release | |
| 358 | -where the admin either defined a custom skin *or chose one of the stock | |
| 359 | -skins* (!) will effectively override this automatic HTML `<head>` | |
| 360 | -insertion feature because the skins from before that time did include | |
| 361 | -these elements. Unless the admin for such a repository updated the skin | |
| 362 | -to track this switch to automatic `<head>` insertion, the default CSP | |
| 363 | -added to the generated header text in Fossil 2.7 is probably being | |
| 364 | -overridden by the skin. | |
| 365 | - | |
| 366 | -If you want the protection of the default CSP in your custom skin, the | |
| 367 | -simplest method is to leave the `<html><head>...` elements out of the | |
| 368 | -skin’s Header section, starting it with the `<div class="head">` element | |
| 369 | -instead as described in the custom skinning guide. Alternately, you can | |
| 370 | -[make use of `$default_csp`](#th1). | |
| 371 | - | |
| 372 | -This then tells you one way to override Fossil’s default CSP: provide | |
| 373 | -your own HTML header in a custom skin. | |
| 374 | - | |
| 375 | -A useful combination is to entirely override the default CSP in the skin | |
| 376 | -but then provide a new CSP [in the front-end proxy layer][svr] | |
| 377 | -using any of the many reverse proxy servers that can define custom HTTP | |
| 378 | -headers. | |
| 368 | +After [the above](#admin-ui), this is the cleanest method. | |
| 369 | + | |
| 370 | +[thvar]: ./customskin.md#vars | |
| 371 | + | |
| 372 | + | |
| 373 | + | |
| 374 | +### <a name="csrc"></a>Fossil C Source Code | |
| 375 | + | |
| 376 | +When you do neither of the above things, Fossil uses | |
| 377 | +[a hard-coded default](/info?ln=527-530&name=65a555d0d4fb846b). | |
| 378 | + | |
| 379 | +We tell you about this not to suggest that you hack the Fossil C source | |
| 380 | +code to change the CSP but simply to document the next step before we | |
| 381 | +move down-stack. | |
| 382 | + | |
| 383 | + | |
| 384 | + | |
| 385 | +### <a name="header"></a>Skin Header | |
| 386 | + | |
| 387 | +[In the normal case](./customskin.md#override), Fossil injects the CSP | |
| 388 | +retrieved by one of the above methods into the header of all HTML | |
| 389 | +documents it generates: | |
| 390 | + | |
| 391 | +```HTML | |
| 392 | +<head>... | |
| 393 | + <meta http-equiv="Content-Security-Policy" content="..."> | |
| 394 | + ... | |
| 395 | +``` | |
| 396 | + | |
| 397 | +Fossil skips this when you’re using a custom skin *and* its | |
| 398 | +[Header section](./customskin.md#headfoot) includes a `<body>` tag. This | |
| 399 | +is because prior to Fossil 2.5, the Header for a custom skin normally | |
| 400 | +contained everything from the opening `<html>` tag through the leading | |
| 401 | +`<body>` tag. From that version onward, Fossil now generates that header | |
| 402 | +when possible, so that the skin’s Header normally provides only the | |
| 403 | +opening tags of the document body, rather than the HTML header. | |
| 404 | + | |
| 405 | +When we added CSP support in Fossil 2.7, we made use of that mechanism | |
| 406 | +to inject the CSP into the generated HTML document header. | |
| 407 | + | |
| 408 | +For backwards compatibility, Fossil skips this when the skin’s Header | |
| 409 | +includes a `<body>` tag. Fossil takes that as a hint that it’s dealing | |
| 410 | +with a skin made in the pre-Fossil-2.5 days and doesn’t try to blindly | |
| 411 | +override it. | |
| 412 | + | |
| 413 | +The problem then is that you may be a Fossil user from the days before | |
| 414 | +Fossil 2.5, and you may be using a custom skin. This includes users who | |
| 415 | +selected one of the stock skins, since for the purposes of this section, | |
| 416 | +there is no difference between the cases. If you go into Admin → Skins → | |
| 417 | +Header and find a `<body>` tag, none of the above will apply to your | |
| 418 | +repo since Fossil will not be injecting its CSP into your pages. | |
| 419 | + | |
| 420 | +If you selected one of the stock skins (e.g. Khaki) prior to upgrading | |
| 421 | +to Fossil 2.5+ and didn’t make any changes to it since that time, you | |
| 422 | +can take the simplest option, which is to simply revert to the stock | |
| 423 | +version of the skin, so your pages will have the CSP injected, at which | |
| 424 | +point this document will begin describing what Fossil does with that | |
| 425 | +repo. | |
| 426 | + | |
| 427 | +If you’re using a customized version of one of the stock skins, the | |
| 428 | +skinning mechanism has a diff feature to make it easier to fold your | |
| 429 | +local changes into the stock version. | |
| 430 | + | |
| 431 | +If you’re using a fully customized skin, we recommend replicating the | |
| 432 | +method that [the Bootstrap skin uses][dcinj].² Alone among the stock | |
| 433 | +Fossil skins, Bootstrap still does old-style Header processing, | |
| 434 | +providing the entire HTML header and the start of the document body. | |
| 435 | + | |
| 436 | +We do *not* recommend injecting an explicit `Content-Security-Policy` | |
| 437 | +meta tag into a header to override Fossil’s default CSP. That means you | |
| 438 | +have to edit the skin every time you want to change the CSP. Use the TH1 | |
| 439 | +`$default_csp` variable like the Bootstrap skin does so you can use one | |
| 440 | +of the methods above with your custom skin, so the CSP can vary | |
| 441 | +independently of the skin. | |
| 442 | + | |
| 443 | +[dcinj]: /info?ln=7&name=bef080a6929a3e6f | |
| 444 | + | |
| 445 | + | |
| 446 | +### <a name="fep"></a>Front-End Proxy | |
| 447 | + | |
| 448 | +If your Fossil repo is behind some sort of HTTP [front-end proxy][svr], | |
| 449 | +the [preferred method][pmcsp] for setting the CSP is via a custom HTTP | |
| 450 | +header, which most HTTP reverse proxy programs allow. | |
| 451 | + | |
| 452 | +Beware that if you have a CSP set via both the HTTP and HTML headers | |
| 453 | +that the two CSPs [merge](https://stackoverflow.com/a/51153816/142454), | |
| 454 | +taking the most restrictive elements of each CSP. If you wish the proxy | |
| 455 | +layer’s setting to completely override Fossil’s setting, you will need | |
| 456 | +to combine that with one of the methods above to either remove the | |
| 457 | +Fossil-provided CSP or to make Fossil provide a no-restrictions CSP | |
| 458 | +which the front-end proxy can then tighten down. | |
| 459 | + | |
| 460 | +[pmcsp]: https://developers.google.com/web/fundamentals/security/csp/#the_meta_tag | |
| 461 | + | |
| 379 | 462 | |
| 380 | 463 | |
| 381 | 464 | ------------ |
| 382 | 465 | |
| 383 | 466 | |
| @@ -385,16 +468,19 @@ | ||
| 385 | 468 | |
| 386 | 469 | 1. Fossil might someday switch to serving the “JavaScript” section of a |
| 387 | 470 | custom skin as a virtual text file, allowing it to be cached by the |
| 388 | 471 | browser, reducing page load times. |
| 389 | 472 | |
| 390 | -2. The stock Bootstrap skin does actually include a `<head>` tag, but | |
| 391 | - from Fossil 2.7 through Fossil 2.9, it just repeated the same CSP | |
| 392 | - text that Fossil’s C code inserts into the HTML header for all other | |
| 393 | - stock skins. With Fossil 2.10, the stock Bootstrap skin uses | |
| 394 | - `$default_csp` instead, so you can [override it as above](#th1). | |
| 473 | +2. The stock Bootstrap skin *did* provide redundant CSP text from | |
| 474 | + Fossil 2.7 through Fossil 2.9, so setting the CSP via the higher | |
| 475 | + level methods did not work with that skin. We fixed this in Fossil | |
| 476 | + 2.10, but if you selected the Bootstrap skin prior to that, you’re | |
| 477 | + now running on a *copy* of it stored in your repo settings table, so | |
| 478 | + the change to the stock version of the skin won’t affect that repo | |
| 479 | + automatically. You will have to either merge the diffs in with your | |
| 480 | + local changes or revert to the stock version of the skin. | |
| 395 | 481 | |
| 396 | 482 | |
| 397 | 483 | [cs]: ./customskin.md |
| 398 | 484 | [csp]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP |
| 399 | 485 | [de]: https://dopiaza.org/tools/datauri/index.php |
| 400 | 486 | [xss]: https://en.wikipedia.org/wiki/Cross-site_scripting |
| 401 | 487 |
| --- www/defcsp.md | |
| +++ www/defcsp.md | |
| @@ -304,80 +304,163 @@ | |
| 304 | |
| 305 | |
| 306 | ## <a name="override"></a>Overriding the Default CSP |
| 307 | |
| 308 | If you wish to relax the default CSP’s restrictions or to tighten them |
| 309 | further, there are multiple ways to accomplish that: |
| 310 | |
| 311 | ### <a name="cspsetting"></a>The `default-csp` Setting |
| 312 | |
| 313 | If the [`default-csp` setting](/help?cmd=default-csp) |
| 314 | is defined and is not an empty string, |
| 315 | then the content of that setting is used as the default CSP. This |
| 316 | is the easiest way to use non-standard CSP on your site. |
| 317 | |
| 318 | You can edit the default-csp setting directly from the web interface |
| 319 | by visiting the Admin/Settings page and changing the text in the |
| 320 | edit box for "default-csp". |
| 321 | |
| 322 | |
| 323 | ### <a name="th1"></a>TH1 Setup Hook |
| 324 | |
| 325 | The stock CSP text is hard-coded in the Fossil C source code, but it’s |
| 326 | only used to set the default value of one of [the TH1 skinning |
| 327 | variables](./customskin.md#vars), `$default_csp`. That means you can |
| 328 | override the default CSP by giving this variable a value before Fossil |
| 329 | sees that it’s undefined and uses this default. |
| 330 | |
| 331 | The best place to do that is from the [`th1-setup` |
| 332 | script](./th1-hooks.md), which runs before TH1 processing happens during |
| 333 | skin processing: |
| 334 | |
| 335 | $ fossil set th1-setup "set default_csp {default-src 'self'}" |
| 336 | |
| 337 | This is the cleanest method, allowing you to set a custom CSP without |
| 338 | recompiling Fossil or providing a hand-written `<head>` section in the |
| 339 | Header section of a custom skin. |
| 340 | |
| 341 | You can’t remove the CSP entirely with this method, but you can get the |
| 342 | same effect by telling the browser there are no content restrictions: |
| 343 | |
| 344 | $ fossil set th1-setup 'set default_csp {default-src *}' |
| 345 | |
| 346 | |
| 347 | ### <a name="header"></a>Custom Skin Header |
| 348 | |
| 349 | Fossil only inserts a CSP into the HTML pages it generates when the |
| 350 | [skin’s Header section](./customskin.md#headfoot) doesn’t contain a |
| 351 | `<head>` tag. None of the stock skins include a `<head>` tag,² so if you |
| 352 | haven’t [created a custom skin][cs], you should be getting Fossil’s |
| 353 | default CSP. |
| 354 | |
| 355 | We say “should” because long-time Fossil users may be hanging onto a |
| 356 | legacy behavior from before Fossil 2.5, when Fossil added this automatic |
| 357 | `<head>` insertion feature. Repositories created before that release |
| 358 | where the admin either defined a custom skin *or chose one of the stock |
| 359 | skins* (!) will effectively override this automatic HTML `<head>` |
| 360 | insertion feature because the skins from before that time did include |
| 361 | these elements. Unless the admin for such a repository updated the skin |
| 362 | to track this switch to automatic `<head>` insertion, the default CSP |
| 363 | added to the generated header text in Fossil 2.7 is probably being |
| 364 | overridden by the skin. |
| 365 | |
| 366 | If you want the protection of the default CSP in your custom skin, the |
| 367 | simplest method is to leave the `<html><head>...` elements out of the |
| 368 | skin’s Header section, starting it with the `<div class="head">` element |
| 369 | instead as described in the custom skinning guide. Alternately, you can |
| 370 | [make use of `$default_csp`](#th1). |
| 371 | |
| 372 | This then tells you one way to override Fossil’s default CSP: provide |
| 373 | your own HTML header in a custom skin. |
| 374 | |
| 375 | A useful combination is to entirely override the default CSP in the skin |
| 376 | but then provide a new CSP [in the front-end proxy layer][svr] |
| 377 | using any of the many reverse proxy servers that can define custom HTTP |
| 378 | headers. |
| 379 | |
| 380 | |
| 381 | ------------ |
| 382 | |
| 383 | |
| @@ -385,16 +468,19 @@ | |
| 385 | |
| 386 | 1. Fossil might someday switch to serving the “JavaScript” section of a |
| 387 | custom skin as a virtual text file, allowing it to be cached by the |
| 388 | browser, reducing page load times. |
| 389 | |
| 390 | 2. The stock Bootstrap skin does actually include a `<head>` tag, but |
| 391 | from Fossil 2.7 through Fossil 2.9, it just repeated the same CSP |
| 392 | text that Fossil’s C code inserts into the HTML header for all other |
| 393 | stock skins. With Fossil 2.10, the stock Bootstrap skin uses |
| 394 | `$default_csp` instead, so you can [override it as above](#th1). |
| 395 | |
| 396 | |
| 397 | [cs]: ./customskin.md |
| 398 | [csp]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP |
| 399 | [de]: https://dopiaza.org/tools/datauri/index.php |
| 400 | [xss]: https://en.wikipedia.org/wiki/Cross-site_scripting |
| 401 |
| --- www/defcsp.md | |
| +++ www/defcsp.md | |
| @@ -304,80 +304,163 @@ | |
| 304 | |
| 305 | |
| 306 | ## <a name="override"></a>Overriding the Default CSP |
| 307 | |
| 308 | If you wish to relax the default CSP’s restrictions or to tighten them |
| 309 | further, there are multiple ways to accomplish that. |
| 310 | |
| 311 | The following methods are listed in top-down order to give the simplest |
| 312 | and most straightforward method first. Further methods dig down deeper |
| 313 | into the stack, which is helpful to understand even if you end up using |
| 314 | a higher-level method. |
| 315 | |
| 316 | |
| 317 | ### <a name="cspsetting"></a>The `default-csp` Setting |
| 318 | |
| 319 | If the [`default-csp` setting](/help?cmd=default-csp) is defined and is |
| 320 | not an empty string, its value is injected into the page using |
| 321 | [TH1](./th1.md) via one or more of the methods below, depending on the |
| 322 | skin you’re using and local configuration. |
| 323 | |
| 324 | Changing this setting is the easiest way to set a nonstandard CSP on |
| 325 | your site. |
| 326 | |
| 327 | Because a blank setting tells Fossil to use its hard-coded default CSP, |
| 328 | you have to say something like the following to get a repository without |
| 329 | content security policy restrictions: |
| 330 | |
| 331 | $ fossil set -R /path/to/served/repo.fossil default-csp 'default-src *' |
| 332 | |
| 333 | We recommend that instead of using the command line to change this |
| 334 | setting that you do it via the repository’s web interface, in |
| 335 | Admin → Settings. Write your CSP rules in the edit box marked |
| 336 | "`default-csp`". Do not add hard newlines in that box: the setting needs |
| 337 | to be on a single long line. Beware that changes take effect |
| 338 | immediately, so be careful with your edits: you could end up locking |
| 339 | yourself out of the repository with certain CSP changes! |
| 340 | |
| 341 | There are a few reasons why changing this setting via the command line |
| 342 | is inadvisable, except for very short settings like the example above: |
| 343 | |
| 344 | 1. You have to be sure to set it on the repository where you want the |
| 345 | CSP to apply. Changing this setting on your local clone doesn’t |
| 346 | affect the remote repo you cloned from, which is most likely where |
| 347 | you want the CSP restrictions. |
| 348 | |
| 349 | 2. For more complicated CSPs, the quoting rules for your shell and the |
| 350 | CSP syntax may interact, making it difficult or impossible to set |
| 351 | your desired CSP via the command line. Setting it via the web UI |
| 352 | doesn’t have this problem. |
| 353 | |
| 354 | |
| 355 | |
| 356 | ### <a name="th1"></a>TH1 Setup Hook |
| 357 | |
| 358 | Fossil sets [the TH1 variable `$default_csp`][thvar] from the |
| 359 | `default-csp` setting and uses *that* to inject the value into generated |
| 360 | HTML pages in its stock configuration. |
| 361 | |
| 362 | This means that another way you can override this value is to use |
| 363 | the [`th1-setup` hook script](./th1-hooks.md), which runs before TH1 |
| 364 | processing happens during skin processing: |
| 365 | |
| 366 | $ fossil set th1-setup "set default_csp {default-src 'self'}" |
| 367 | |
| 368 | After [the above](#admin-ui), this is the cleanest method. |
| 369 | |
| 370 | [thvar]: ./customskin.md#vars |
| 371 | |
| 372 | |
| 373 | |
| 374 | ### <a name="csrc"></a>Fossil C Source Code |
| 375 | |
| 376 | When you do neither of the above things, Fossil uses |
| 377 | [a hard-coded default](/info?ln=527-530&name=65a555d0d4fb846b). |
| 378 | |
| 379 | We tell you about this not to suggest that you hack the Fossil C source |
| 380 | code to change the CSP but simply to document the next step before we |
| 381 | move down-stack. |
| 382 | |
| 383 | |
| 384 | |
| 385 | ### <a name="header"></a>Skin Header |
| 386 | |
| 387 | [In the normal case](./customskin.md#override), Fossil injects the CSP |
| 388 | retrieved by one of the above methods into the header of all HTML |
| 389 | documents it generates: |
| 390 | |
| 391 | ```HTML |
| 392 | <head>... |
| 393 | <meta http-equiv="Content-Security-Policy" content="..."> |
| 394 | ... |
| 395 | ``` |
| 396 | |
| 397 | Fossil skips this when you’re using a custom skin *and* its |
| 398 | [Header section](./customskin.md#headfoot) includes a `<body>` tag. This |
| 399 | is because prior to Fossil 2.5, the Header for a custom skin normally |
| 400 | contained everything from the opening `<html>` tag through the leading |
| 401 | `<body>` tag. From that version onward, Fossil now generates that header |
| 402 | when possible, so that the skin’s Header normally provides only the |
| 403 | opening tags of the document body, rather than the HTML header. |
| 404 | |
| 405 | When we added CSP support in Fossil 2.7, we made use of that mechanism |
| 406 | to inject the CSP into the generated HTML document header. |
| 407 | |
| 408 | For backwards compatibility, Fossil skips this when the skin’s Header |
| 409 | includes a `<body>` tag. Fossil takes that as a hint that it’s dealing |
| 410 | with a skin made in the pre-Fossil-2.5 days and doesn’t try to blindly |
| 411 | override it. |
| 412 | |
| 413 | The problem then is that you may be a Fossil user from the days before |
| 414 | Fossil 2.5, and you may be using a custom skin. This includes users who |
| 415 | selected one of the stock skins, since for the purposes of this section, |
| 416 | there is no difference between the cases. If you go into Admin → Skins → |
| 417 | Header and find a `<body>` tag, none of the above will apply to your |
| 418 | repo since Fossil will not be injecting its CSP into your pages. |
| 419 | |
| 420 | If you selected one of the stock skins (e.g. Khaki) prior to upgrading |
| 421 | to Fossil 2.5+ and didn’t make any changes to it since that time, you |
| 422 | can take the simplest option, which is to simply revert to the stock |
| 423 | version of the skin, so your pages will have the CSP injected, at which |
| 424 | point this document will begin describing what Fossil does with that |
| 425 | repo. |
| 426 | |
| 427 | If you’re using a customized version of one of the stock skins, the |
| 428 | skinning mechanism has a diff feature to make it easier to fold your |
| 429 | local changes into the stock version. |
| 430 | |
| 431 | If you’re using a fully customized skin, we recommend replicating the |
| 432 | method that [the Bootstrap skin uses][dcinj].² Alone among the stock |
| 433 | Fossil skins, Bootstrap still does old-style Header processing, |
| 434 | providing the entire HTML header and the start of the document body. |
| 435 | |
| 436 | We do *not* recommend injecting an explicit `Content-Security-Policy` |
| 437 | meta tag into a header to override Fossil’s default CSP. That means you |
| 438 | have to edit the skin every time you want to change the CSP. Use the TH1 |
| 439 | `$default_csp` variable like the Bootstrap skin does so you can use one |
| 440 | of the methods above with your custom skin, so the CSP can vary |
| 441 | independently of the skin. |
| 442 | |
| 443 | [dcinj]: /info?ln=7&name=bef080a6929a3e6f |
| 444 | |
| 445 | |
| 446 | ### <a name="fep"></a>Front-End Proxy |
| 447 | |
| 448 | If your Fossil repo is behind some sort of HTTP [front-end proxy][svr], |
| 449 | the [preferred method][pmcsp] for setting the CSP is via a custom HTTP |
| 450 | header, which most HTTP reverse proxy programs allow. |
| 451 | |
| 452 | Beware that if you have a CSP set via both the HTTP and HTML headers |
| 453 | that the two CSPs [merge](https://stackoverflow.com/a/51153816/142454), |
| 454 | taking the most restrictive elements of each CSP. If you wish the proxy |
| 455 | layer’s setting to completely override Fossil’s setting, you will need |
| 456 | to combine that with one of the methods above to either remove the |
| 457 | Fossil-provided CSP or to make Fossil provide a no-restrictions CSP |
| 458 | which the front-end proxy can then tighten down. |
| 459 | |
| 460 | [pmcsp]: https://developers.google.com/web/fundamentals/security/csp/#the_meta_tag |
| 461 | |
| 462 | |
| 463 | |
| 464 | ------------ |
| 465 | |
| 466 | |
| @@ -385,16 +468,19 @@ | |
| 468 | |
| 469 | 1. Fossil might someday switch to serving the “JavaScript” section of a |
| 470 | custom skin as a virtual text file, allowing it to be cached by the |
| 471 | browser, reducing page load times. |
| 472 | |
| 473 | 2. The stock Bootstrap skin *did* provide redundant CSP text from |
| 474 | Fossil 2.7 through Fossil 2.9, so setting the CSP via the higher |
| 475 | level methods did not work with that skin. We fixed this in Fossil |
| 476 | 2.10, but if you selected the Bootstrap skin prior to that, you’re |
| 477 | now running on a *copy* of it stored in your repo settings table, so |
| 478 | the change to the stock version of the skin won’t affect that repo |
| 479 | automatically. You will have to either merge the diffs in with your |
| 480 | local changes or revert to the stock version of the skin. |
| 481 | |
| 482 | |
| 483 | [cs]: ./customskin.md |
| 484 | [csp]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP |
| 485 | [de]: https://dopiaza.org/tools/datauri/index.php |
| 486 | [xss]: https://en.wikipedia.org/wiki/Cross-site_scripting |
| 487 |