Skip to content

Commit 07e070e

Browse files
natanfellesnatanfelles
committed
Update user guide
1 parent db08b54 commit 07e070e

File tree

1 file changed

+104
-22
lines changed

1 file changed

+104
-22
lines changed

‎guide/index.rst‎

Lines changed: 104 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -670,11 +670,11 @@ Values for a single directive can be passed with the ``setDirective`` method:
670670
]);
671671
672672
Methods that start with ``set`` override directive values. To just add new values,
673-
use the ``addValue`` method:
673+
use the ``addValues`` method:
674674

675675
.. code-block:: php
676676
677-
$csp->addValue(CSP::styleSrc, [
677+
$csp->addValues(CSP::styleSrc, [
678678
'self',
679679
'cdn.foo.tld',
680680
]);
@@ -731,10 +731,14 @@ CSP Hashes
731731
To cache the page in browsers, such as by `ETag`_, we can use hashes of the
732732
contents of the ``script`` and ``style`` tags.
733733
734-
Let's look at the following HTML page:
734+
Let's look at the following HTML page. We will activate the output buffer with
735+
`ob_start <https://www.php.net/manual/en/function.ob-start.php>`_:
735736
736-
.. code-block:: html
737+
.. code-block:: php
737738
739+
<?php
740+
ob_start();
741+
?>
738742
<!doctype html>
739743
<html lang="en">
740744
<head>
@@ -756,18 +760,42 @@ Let's look at the following HTML page:
756760
</script>
757761
</body>
758762
</html>
763+
<?php
764+
$html = ob_get_clean();
765+
766+
Next, we retrieve the output using
767+
`ob_get_clean <https://www.php.net/manual/en/function.ob-get-clean.php>`_ and
768+
save its contents to the ``$html`` variable.
759769

760770
In order to get all the hashes of the ``style`` tags we can pass the content of
761771
the HTML page in the ``getStyleHashes`` method and it will return an array with
762772
all the hashes.
763773

774+
.. code-block:: php
775+
776+
$styleHashes = CSP::getStyleHashes($html);
777+
778+
We can use the ``var_dump`` function to obtain style hashes:
779+
780+
.. code-block:: php
781+
782+
var_dump($styleHashes);
783+
784+
.. code-block:: text
785+
786+
array(1) {
787+
[0]=>
788+
string(51) "sha256-CvbCUHrSwRhSRk6O3h7eTuSY9r3oKFudXNGTM/oLBI8="
789+
}
790+
764791
And then we can add them in the ``style-src`` directive via the ``addValues``
765792
method:
766793

767794
.. code-block:: php
768795
769-
$styleHashes = CSP::getStyleHashes($html);
770-
$csp->addValue(CSP::styleSrc, $styleHashes);
796+
$csp->addValues(CSP::styleSrc, [
797+
'sha256-CvbCUHrSwRhSRk6O3h7eTuSY9r3oKFudXNGTM/oLBI8='
798+
]);
771799
772800
The CSP header will look like the following:
773801

@@ -776,51 +804,105 @@ The CSP header will look like the following:
776804
Content-Security-Policy: style-src 'sha256-CvbCUHrSwRhSRk6O3h7eTuSY9r3oKFudXNGTM/oLBI8=';
777805
778806
Similarly, we can get the hashes of the ``script`` tags and add them via the
779-
``addValues`` method:
807+
``addValues`` method.
808+
809+
First, let's get the script hashes:
780810

781811
.. code-block:: php
782812
783813
$scriptHashes = CSP::getScriptHashes($html);
784-
$csp->addValue(CSP::scriptSrc, $scriptHashes);
814+
815+
We can view them with a ``var_dump``:
816+
817+
.. code-block:: php
818+
819+
var_dump($scriptHashes);
820+
821+
.. code-block:: text
822+
823+
array(2) {
824+
[0]=>
825+
string(51) "sha256-IfEVrz7Me6SW7O7OHy04/VaUhErMLxjWHdJd8MYN5b0="
826+
[1]=>
827+
string(51) "sha256-0TppQmjw9at2nEl3givShY5l6nABmQ84qrh1dRgvMJ0="
828+
}
829+
830+
So, we added the script hashes to the CSP object:
831+
832+
.. code-block:: php
833+
834+
$csp->addValues(CSP::scriptSrc, [
835+
'sha256-IfEVrz7Me6SW7O7OHy04/VaUhErMLxjWHdJd8MYN5b0=',
836+
'sha256-0TppQmjw9at2nEl3givShY5l6nABmQ84qrh1dRgvMJ0='
837+
]);
838+
839+
Finally, we send the Content-Security-Policy header with the directives and also
840+
the HTML content:
841+
842+
.. code-block:: php
843+
844+
header('Content-Security-Policy: ' . $csp);
845+
echo $html;
785846
786847
The CSP header will look similar to the following example:
787848

788849
.. code-block:: http
789850
790851
Content-Security-Policy: style-src 'sha256-CvbCUHrSwRhSRk6O3h7eTuSY9r3oKFudXNGTM/oLBI8='; script-src 'sha256-IfEVrz7Me6SW7O7OHy04/VaUhErMLxjWHdJd8MYN5b0=' 'sha256-0TppQmjw9at2nEl3givShY5l6nABmQ84qrh1dRgvMJ0=';
791852
853+
And the HTML can be cached because it doesn't have dynamic CSP nonces, only
854+
hashes in the header.
855+
792856
CSP in Response
793857
###############
794858

795859
An object of the CSP class can be set to an object of the Framework\HTTP\Response
796-
class and then it will be sent with the response via the ``send`` method:
860+
class and then it will be sent with the response via the ``send`` method.
861+
862+
Below, we see how to instantiate the objects:
797863

798864
.. code-block:: php
799865
866+
use Framework\HTTP\CSP;
867+
use Framework\HTTP\Request;
868+
use Framework\HTTP\Response;
869+
800870
$csp = new CSP([
801871
CSP::defaultSrc => [
802872
'self',
803873
],
804-
CSP::styleSrc => [
805-
'self',
806-
'cdn.foo.tld',
807-
],
808-
CSP::scriptSrc => [
809-
'self',
810-
'cdn.foo.tld',
811-
],
812874
]);
813875
814-
$response = new Framework\HTTP\Response;
876+
$response = new Response(new Request());
815877
$response->setCsp($csp);
816878
817-
Only if you're sure the page doesn't have any malicious scripts, get the hashes
818-
from the response body and add them to the CSP object:
879+
We can use the CSP object through the Response. Adding nonces dynamically:
880+
881+
.. code-block:: php
882+
883+
<?php
884+
ob_start();
885+
?>
886+
...
887+
<head>
888+
<style<?= $response->getCsp()->getStyleNonceAttr() ?>>
889+
...
890+
</style>
891+
</head>
892+
<body>
893+
<script<?= $response->getCsp()->getScriptNonceAttr() ?>>
894+
...
895+
</script>
896+
</body>
897+
...
898+
<?php
899+
$html = ob_get_clean();
900+
901+
With the captured HTML, we can set the response body:
819902

820903
.. code-block:: php
821904
822-
$scriptHashes = CSP::getScriptHashes($response->getBody());
823-
$csp->addValue(CSP::scriptSrc, $scriptHashes);
905+
$response->setBody($html);
824906
825907
Then the response can be sent:
826908

0 commit comments

Comments
 (0)