Skip to content

Commit c2d1515

Browse files
jcheronjcheron
committed
add csp javadoc
1 parent 82ae54c commit c2d1515

File tree

6 files changed

+173
-23
lines changed

6 files changed

+173
-23
lines changed

‎src/Ubiquity/security/csp/ContentSecurity.php‎

Lines changed: 92 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -22,12 +22,24 @@ class ContentSecurity {
2222

2323
private $header = self::HEADER;
2424

25+
/**
26+
* ContentSecurity constructor.
27+
*
28+
* @param bool|null $reportOnly
29+
*/
2530
public function __construct(?bool $reportOnly = null) {
2631
if (isset($reportOnly)) {
2732
$this->reportOnly($reportOnly);
2833
}
2934
}
3035

36+
/**
37+
* Adds new values to a directive.
38+
*
39+
* @param string $directive
40+
* @param string ...$values
41+
* @return $this
42+
*/
3143
public function addPolicy(string $directive, string ...$values): self {
3244
$policies = $this->policies[$directive] ?? [];
3345
foreach ($values as $v) {
@@ -40,31 +52,63 @@ public function addPolicy(string $directive, string ...$values): self {
4052
return $this;
4153
}
4254

55+
/**
56+
* Adds new values to a directive, re-using default-src actual values.
57+
*
58+
* @param string $directive
59+
* @param string ...$values
60+
* @return $this
61+
*/
4362
public function addPolicyDefault(string $directive, string ...$values): self {
4463
$default = \array_keys($this->policies[CspDirectives::DEFAULT_SRC] ?? []);
4564
$values = \array_merge($default, $values);
4665
$this->addPolicy($directive, ...$values);
4766
return $this;
4867
}
4968

69+
/**
70+
* Adds a nonce to the directives.
71+
*
72+
* @param string $nonce
73+
* @param string ...$directives
74+
* @return $this
75+
*/
5076
public function addNonce(string $nonce, string ...$directives): self {
5177
foreach ($directives as $directive) {
5278
$this->addPolicy($directive, "'nonce-$nonce'", CspValues::STRICT_DYNAMIC);
5379
}
5480
return $this;
5581
}
5682

83+
/**
84+
* Adds a nonce to a directive, re-using default-src actual values.
85+
*
86+
* @param string $nonce
87+
* @param string ...$directives
88+
* @return $this
89+
*/
5790
public function addNonceDefault(string $nonce, string ...$directives): self {
5891
foreach ($directives as $directive) {
5992
$this->addPolicyDefault($directive, "'nonce-$nonce'", CspValues::STRICT_DYNAMIC);
6093
}
6194
return $this;
6295
}
6396

64-
public function setDefaultSrc(string ...$policies) {
97+
/**
98+
* Defines the policies for default-src directive.
99+
*
100+
* @param string ...$policies
101+
* @return $this
102+
*/
103+
public function setDefaultSrc(string ...$policies): self {
65104
return $this->addPolicy(CspDirectives::DEFAULT_SRC, ...$policies);
66105
}
67106

107+
/**
108+
* Generates the header string.
109+
*
110+
* @return string
111+
*/
68112
public function generate(): string {
69113
$strs = '';
70114
foreach ($this->policies as $directive => $policy) {
@@ -74,37 +118,84 @@ public function generate(): string {
74118
return $strs;
75119
}
76120

121+
/**
122+
* Display a ContentSecurity object.
123+
*
124+
* @param callable $directiveCall
125+
* @param callable $policyCall
126+
* @return string
127+
*/
128+
public function display(callable $directiveCall, callable $policyCall): string {
129+
$strs = '';
130+
foreach ($this->policies as $directive => $policy) {
131+
$policies = \array_keys($policy);
132+
$strs .= $directiveCall($directive) . $policyCall(\implode(' ', $policies));
133+
}
134+
return $strs;
135+
}
136+
137+
/**
138+
* Sets reportOnly.
139+
*
140+
* @param bool|null $reportOnly
141+
* @return $this
142+
*/
77143
public function reportOnly(?bool $reportOnly = true): self {
78144
if (isset($reportOnly)) {
79145
$this->header = $reportOnly ? self::DEBUG_HEADER : self::HEADER;
80146
}
81147
return $this;
82148
}
83149

150+
/**
151+
* Adds headers to the response.
152+
*
153+
* @param bool|null $reportOnly
154+
*/
84155
public function addHeaderToResponse(?bool $reportOnly = null): void {
85156
if (isset($reportOnly)) {
86157
$this->reportOnly($reportOnly);
87158
}
88159
UResponse::header($this->header, $this->generate(), false);
89160
}
90161

162+
/**
163+
* Creates a nonce and add it to some directives.
164+
*
165+
* @param
166+
* $nonce
167+
* @param string ...$directives
168+
* @return ContentSecurity
169+
*/
91170
public static function nonce($nonce, string ...$directives): ContentSecurity {
92171
$csp = new self();
93172
return $csp->addNonce($nonce, ...$directives);
94173
}
95174

175+
/**
176+
* Creates a new ContentSecurity object, with self in default-src.
177+
*
178+
* @return ContentSecurity
179+
*/
96180
public static function all(): ContentSecurity {
97181
$csp = new self();
98182
return $csp->addPolicy(CspDirectives::DEFAULT_SRC, CspValues::SELF);
99183
}
100184

101185
/**
186+
* Returns the actual policies.
187+
*
102188
* @return array
103189
*/
104190
public function getPolicies(): array {
105191
return $this->policies;
106192
}
107193

194+
/**
195+
* Creates a new ContentSecurity object for Ubiquity Webtools.
196+
*
197+
* @return ContentSecurity
198+
*/
108199
public static function defaultUbiquity(): ContentSecurity {
109200
$csp = new self();
110201
$csp->addPolicy(CspDirectives::DEFAULT_SRC, 'self', 'cdn.jsdelivr.net', 'cdnjs.cloudflare.com');
@@ -114,12 +205,4 @@ public static function defaultUbiquity(): ContentSecurity {
114205
$csp->addPolicy(CspDirectives::IMG_SRC, 'data:');
115206
return $csp;
116207
}
117-
118-
/**
119-
* @param array $policies
120-
*/
121-
public function setPolicies(array $policies): void {
122-
$this->policies = $policies;
123-
}
124-
125208
}

‎src/Ubiquity/security/csp/ContentSecurityManager.php‎

Lines changed: 48 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -18,32 +18,72 @@ class ContentSecurityManager {
1818

1919
private static bool $reportOnly;
2020

21-
public static function start(string $nonceGeneratorClass = null, bool $reportOnly = false, ?callable $onNonce = null) {
21+
/**
22+
* Starts the Content Security Policies manager.
23+
*
24+
* @param string|null $nonceGeneratorClass
25+
* The class used for generating nonces.
26+
* @param bool $reportOnly
27+
* @param callable|null $onNonce
28+
*/
29+
public static function start(string $nonceGeneratorClass = null, bool $reportOnly = false, ?callable $onNonce = null): void {
2230
$nonceGeneratorClass ??= NonceGenerator::class;
2331
self::$nonceGenerator = new $nonceGeneratorClass($onNonce);
2432
self::$reportOnly = $reportOnly;
2533
}
2634

27-
public static function getNonce(string $name) {
35+
/**
36+
* Returns a new or an existing nonce.
37+
*
38+
* @param string $name
39+
* The nonce to create
40+
* @return string
41+
*/
42+
public static function getNonce(string $name): string {
2843
return self::$nonceGenerator->getNonce($name);
2944
}
3045

46+
/**
47+
* Checks if the manager is started.
48+
*
49+
* @return bool
50+
*/
3151
public static function isStarted(): bool {
3252
return isset(self::$nonceGenerator);
3353
}
3454

55+
/**
56+
* Creates and returns a new ContentSecurity object.
57+
*
58+
* @param bool|null $reportOnly
59+
* @return ContentSecurity
60+
*/
3561
public static function addCsp(?bool $reportOnly = null): ContentSecurity {
3662
return self::$csp[] = new ContentSecurity($reportOnly ?? self::$reportOnly);
3763
}
3864

39-
public static function clearCsp() {
65+
/**
66+
* Removes all CSP objects.
67+
*/
68+
public static function clearCsp(): void {
4069
self::$csp = [];
4170
}
4271

72+
/**
73+
* Creates a new ContentSecurity object for Ubiquity Webtools.
74+
*
75+
* @param bool|null $reportOnly
76+
* @return ContentSecurity
77+
*/
4378
public static function defaultUbiquity(?bool $reportOnly = null): ContentSecurity {
4479
return self::$csp[] = ContentSecurity::defaultUbiquity()->reportOnly($reportOnly);
4580
}
4681

82+
/**
83+
* Adds all Content security policies to headers.
84+
*
85+
* @param bool|null $reportOnly
86+
*/
4787
public static function addHeadersToResponse(?bool $reportOnly = null): void {
4888
$reportOnly ??= self::$reportOnly;
4989
foreach (self::$csp as $csp) {
@@ -52,26 +92,28 @@ public static function addHeadersToResponse(?bool $reportOnly = null): void {
5292
}
5393

5494
/**
95+
* Returns the NonceGenerator instance.
96+
*
5597
* @return NonceGenerator
5698
*/
5799
public static function getNonceGenerator(): NonceGenerator {
58100
return self::$nonceGenerator;
59101
}
60102

61103
/**
104+
*
62105
* @return array
63106
*/
64107
public static function getCsp(): array {
65108
return self::$csp;
66109
}
67-
68110

69111
/**
112+
* Returns true if reportOnly header is activated.
113+
*
70114
* @return bool
71115
*/
72116
public static function isReportOnly(): bool {
73117
return self::$reportOnly;
74118
}
75-
76119
}
77-

‎src/Ubiquity/security/csp/CspDirectives.php‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,15 @@
11
<?php
22
namespace Ubiquity\security\csp;
33

4+
/**
5+
* Ubiquity\security\cspCspDirectives
6+
* This class is part of Ubiquity
7+
*
8+
* @author jc
9+
* @version 1.0.0
10+
*
11+
*
12+
*/
413
class CspDirectives {
514

615
const DEFAULT_SRC = 'default-src';
@@ -51,4 +60,3 @@ class CspDirectives {
5160

5261
const NAVIGATE_TO = 'navigate-to';
5362
}
54-

‎src/Ubiquity/security/csp/CspValues.php‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,4 +35,3 @@ class CspValues {
3535
self::UNSAFE_HASHES
3636
];
3737
}
38-

‎src/Ubiquity/security/csp/NonceGenerator.php‎

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -17,18 +17,24 @@ protected function _generateNonce(string $name, ?int $value = null): string {
1717
$bytes = \random_bytes((int) ($value ?? 32));
1818
$nonce = \base64_encode($bytes);
1919
if (isset($this->onNonce) && ! URequest::isAjax()) {
20-
$onNonce=$this->onNonce;
20+
$onNonce = $this->onNonce;
2121
$onNonce($name, $nonce);
2222
}
2323
return $nonce;
2424
}
2525

26-
public function getNonce(string $name,int $size=32) {
26+
/**
27+
* Returns a new or an existing nonce value.
28+
*
29+
* @param string $name
30+
* @param int $size
31+
* @return string
32+
*/
33+
public function getNonce(string $name, int $size = 32): string {
2734
return $this->nonces[$name] ??= self::_generateNonce($name, $size);
2835
}
29-
30-
public function __toString(){
36+
37+
public function __toString() {
3138
return \count($this->nonces);
3239
}
3340
}
34-

‎src/Ubiquity/security/shieldon/ShieldonManager.php‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,12 @@ public static function getFirewall(): Firewall {
2222
return self::$firewall;
2323
}
2424

25-
public static function start(string $writable = null) {
25+
/**
26+
* Starts th Shieldon service.
27+
*
28+
* @param string $writable
29+
*/
30+
public static function start(string $writable = null): void {
2631
$writable ??= \ROOT . \DS . 'cache' . \DS . 'shieldon';
2732
self::$firewall = new Firewall();
2833
self::$firewall->configure($writable);
@@ -33,12 +38,19 @@ public static function start(string $writable = null) {
3338
}
3439
}
3540

41+
/**
42+
* Creates the admin panel.
43+
*/
3644
public static function createPanel(string $uri): Panel {
3745
$panel = new Panel();
3846
self::$firewall->controlPanel($uri);
3947
return $panel;
4048
}
4149

50+
/**
51+
*
52+
* @return ResponseInterface
53+
*/
4254
public static function run(): ResponseInterface {
4355
return self::$firewall->run();
4456
}

0 commit comments

Comments
 (0)