Skip to content

Commit c64988b

Browse files
soatoksoatok
authored
Update pkd-crypto, spec nits (#67)
1 parent b325df5 commit c64988b

18 files changed

Lines changed: 692 additions & 213 deletions

File tree

‎composer.json‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,10 +17,11 @@
1717
"type": "project",
1818
"require": {
1919
"php": "^8.4",
20-
"ext-pdo": "*",
2120
"ext-json": "*",
21+
"ext-pdo": "*",
22+
"ext-openssl": "*",
2223
"ext-sodium": "*",
23-
"fedi-e2ee/pkd-crypto": "^0.31|1",
24+
"fedi-e2ee/pkd-crypto": "^0.34|1",
2425
"fedi-e2ee/pkd-extensions": "^0.2|^1",
2526
"guzzlehttp/guzzle": "^7",
2627
"laminas/laminas-diactoros": "^3",

‎docs/reference/classes/protocol.md‎

Lines changed: 35 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -294,30 +294,42 @@ static · Returns `string`
294294

295295
**Throws:** `BaseJsonException`
296296

297-
#### [`assertAllArrayKeysExist`](../../../src/Protocol/KeyWrapping.php#L27-L32)
297+
#### [`assertAllArrayKeysExist`](../../../src/Protocol/KeyWrapping.php#L30-L35)
298298

299299
static · Returns `void`
300300

301+
This method throws an InputException if any of the expected keys are absent.
302+
303+
It does not return anything.
304+
301305
**Parameters:**
302306

303307
- `$target`: `array`
304308
- `...$arrayKeys`: `string`
305309

306310
**Throws:** `InputException`
307311

308-
#### [`allArrayKeysExist`](../../../src/Protocol/KeyWrapping.php#L34-L41)
312+
#### [`allArrayKeysExist`](../../../src/Protocol/KeyWrapping.php#L43-L50)
309313

310314
static · Returns `bool`
311315

316+
This method returns true if every expected array key is found in the target array.
317+
318+
Otherwise, it returns false. This is useful for input validation.
319+
312320
**Parameters:**
313321

314322
- `$target`: `array`
315323
- `...$arrayKeys`: `string`
316324

317-
#### [`constantTimeSelect`](../../../src/Protocol/KeyWrapping.php#L48-L65)
325+
#### [`constantTimeSelect`](../../../src/Protocol/KeyWrapping.php#L65-L82)
318326

319327
Returns `string`
320328

329+
This is a constant-time conditional select. It should be read like a ternary operation.
330+
331+
$result = ClassWithTrait::constantTimeSelect(1, $left, $right); -> $result === $left. $result = ClassWithTrait::constantTimeSelect(0, $left, $right); -> $result === $right.
332+
321333
**Parameters:**
322334

323335
- `$select`: `int`
@@ -326,49 +338,63 @@ Returns `string`
326338

327339
**Throws:** `CryptoException`
328340

329-
#### [`dos2unix`](../../../src/Protocol/KeyWrapping.php#L73-L76)
341+
#### [`dos2unix`](../../../src/Protocol/KeyWrapping.php#L92-L95)
330342

331343
static · Returns `string`
332344

333345
Normalize line-endings to UNIX-style (LF rather than CRLF).
334346

347+
This is mostly used for PEM-encoded strings.
348+
335349
**Parameters:**
336350

337351
- `$in`: `string`
338352

339-
#### [`preAuthEncode`](../../../src/Protocol/KeyWrapping.php#L84-L97)
353+
#### [`preAuthEncode`](../../../src/Protocol/KeyWrapping.php#L113-L126)
340354

341355
static · Returns `string`
342356

357+
This is an implementation of PAE() from PASETO. It encodes an array of strings into a flat string consisting of:
358+
359+
1. The number of pieces. 2. For each piece: 1. The length of the piece (in bytes). 2. The contents of the piece. This allows multipart messages to have an injective canonical representation before passing ot a hash function (or other cryptographic function).
360+
343361
**Parameters:**
344362

345363
- `$pieces`: `array`
346364

347-
#### [`sortByKey`](../../../src/Protocol/KeyWrapping.php#L99-L107)
365+
#### [`sortByKey`](../../../src/Protocol/KeyWrapping.php#L133-L141)
348366

349367
static · Returns `void`
350368

369+
This sorts the target array in-place, by its keys, including child arrays.
370+
371+
Used for ensuring arrays are sorted before JSON encoding.
372+
351373
**Parameters:**
352374

353375
- `$arr`: `array`
354376

355-
#### [`LE64`](../../../src/Protocol/KeyWrapping.php#L111-L114)
377+
#### [`LE64`](../../../src/Protocol/KeyWrapping.php#L148-L151)
356378

357379
static · Returns `string`
358380

381+
Mostly used by preAuthEncode() above. This packs an integer as 8 bytes.
382+
359383
**Parameters:**
360384

361385
- `$n`: `int`
362386

363-
#### [`stringToByteArray`](../../../src/Protocol/KeyWrapping.php#L116-L123)
387+
#### [`stringToByteArray`](../../../src/Protocol/KeyWrapping.php#L156-L163)
364388

365389
Returns `array`
366390

391+
Get an array of bytes representing the input string.
392+
367393
**Parameters:**
368394

369395
- `$str`: `string`
370396

371-
#### [`stripNewlines`](../../../src/Protocol/KeyWrapping.php#L131-L165)
397+
#### [`stripNewlines`](../../../src/Protocol/KeyWrapping.php#L171-L205)
372398

373399
static · Returns `string`
374400

‎docs/reference/classes/ratelimit-storage.md‎

Lines changed: 70 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -114,30 +114,42 @@ static · Returns `string`
114114

115115
**Throws:** `BaseJsonException`
116116

117-
#### [`assertAllArrayKeysExist`](../../../src/RateLimit/Storage/Filesystem.php#L27-L32)
117+
#### [`assertAllArrayKeysExist`](../../../src/RateLimit/Storage/Filesystem.php#L30-L35)
118118

119119
static · Returns `void`
120120

121+
This method throws an InputException if any of the expected keys are absent.
122+
123+
It does not return anything.
124+
121125
**Parameters:**
122126

123127
- `$target`: `array`
124128
- `...$arrayKeys`: `string`
125129

126130
**Throws:** `InputException`
127131

128-
#### [`allArrayKeysExist`](../../../src/RateLimit/Storage/Filesystem.php#L34-L41)
132+
#### [`allArrayKeysExist`](../../../src/RateLimit/Storage/Filesystem.php#L43-L50)
129133

130134
static · Returns `bool`
131135

136+
This method returns true if every expected array key is found in the target array.
137+
138+
Otherwise, it returns false. This is useful for input validation.
139+
132140
**Parameters:**
133141

134142
- `$target`: `array`
135143
- `...$arrayKeys`: `string`
136144

137-
#### [`constantTimeSelect`](../../../src/RateLimit/Storage/Filesystem.php#L48-L65)
145+
#### [`constantTimeSelect`](../../../src/RateLimit/Storage/Filesystem.php#L65-L82)
138146

139147
Returns `string`
140148

149+
This is a constant-time conditional select. It should be read like a ternary operation.
150+
151+
$result = ClassWithTrait::constantTimeSelect(1, $left, $right); -> $result === $left. $result = ClassWithTrait::constantTimeSelect(0, $left, $right); -> $result === $right.
152+
141153
**Parameters:**
142154

143155
- `$select`: `int`
@@ -146,49 +158,63 @@ Returns `string`
146158

147159
**Throws:** `CryptoException`
148160

149-
#### [`dos2unix`](../../../src/RateLimit/Storage/Filesystem.php#L73-L76)
161+
#### [`dos2unix`](../../../src/RateLimit/Storage/Filesystem.php#L92-L95)
150162

151163
static · Returns `string`
152164

153165
Normalize line-endings to UNIX-style (LF rather than CRLF).
154166

167+
This is mostly used for PEM-encoded strings.
168+
155169
**Parameters:**
156170

157171
- `$in`: `string`
158172

159-
#### [`preAuthEncode`](../../../src/RateLimit/Storage/Filesystem.php#L84-L97)
173+
#### [`preAuthEncode`](../../../src/RateLimit/Storage/Filesystem.php#L113-L126)
160174

161175
static · Returns `string`
162176

177+
This is an implementation of PAE() from PASETO. It encodes an array of strings into a flat string consisting of:
178+
179+
1. The number of pieces. 2. For each piece: 1. The length of the piece (in bytes). 2. The contents of the piece. This allows multipart messages to have an injective canonical representation before passing ot a hash function (or other cryptographic function).
180+
163181
**Parameters:**
164182

165183
- `$pieces`: `array`
166184

167-
#### [`sortByKey`](../../../src/RateLimit/Storage/Filesystem.php#L99-L107)
185+
#### [`sortByKey`](../../../src/RateLimit/Storage/Filesystem.php#L133-L141)
168186

169187
static · Returns `void`
170188

189+
This sorts the target array in-place, by its keys, including child arrays.
190+
191+
Used for ensuring arrays are sorted before JSON encoding.
192+
171193
**Parameters:**
172194

173195
- `$arr`: `array`
174196

175-
#### [`LE64`](../../../src/RateLimit/Storage/Filesystem.php#L111-L114)
197+
#### [`LE64`](../../../src/RateLimit/Storage/Filesystem.php#L148-L151)
176198

177199
static · Returns `string`
178200

201+
Mostly used by preAuthEncode() above. This packs an integer as 8 bytes.
202+
179203
**Parameters:**
180204

181205
- `$n`: `int`
182206

183-
#### [`stringToByteArray`](../../../src/RateLimit/Storage/Filesystem.php#L116-L123)
207+
#### [`stringToByteArray`](../../../src/RateLimit/Storage/Filesystem.php#L156-L163)
184208

185209
Returns `array`
186210

211+
Get an array of bytes representing the input string.
212+
187213
**Parameters:**
188214

189215
- `$str`: `string`
190216

191-
#### [`stripNewlines`](../../../src/RateLimit/Storage/Filesystem.php#L131-L165)
217+
#### [`stripNewlines`](../../../src/RateLimit/Storage/Filesystem.php#L171-L205)
192218

193219
static · Returns `string`
194220

@@ -293,30 +319,42 @@ static · Returns `string`
293319

294320
**Throws:** `BaseJsonException`
295321

296-
#### [`assertAllArrayKeysExist`](../../../src/RateLimit/Storage/Redis.php#L27-L32)
322+
#### [`assertAllArrayKeysExist`](../../../src/RateLimit/Storage/Redis.php#L30-L35)
297323

298324
static · Returns `void`
299325

326+
This method throws an InputException if any of the expected keys are absent.
327+
328+
It does not return anything.
329+
300330
**Parameters:**
301331

302332
- `$target`: `array`
303333
- `...$arrayKeys`: `string`
304334

305335
**Throws:** `InputException`
306336

307-
#### [`allArrayKeysExist`](../../../src/RateLimit/Storage/Redis.php#L34-L41)
337+
#### [`allArrayKeysExist`](../../../src/RateLimit/Storage/Redis.php#L43-L50)
308338

309339
static · Returns `bool`
310340

341+
This method returns true if every expected array key is found in the target array.
342+
343+
Otherwise, it returns false. This is useful for input validation.
344+
311345
**Parameters:**
312346

313347
- `$target`: `array`
314348
- `...$arrayKeys`: `string`
315349

316-
#### [`constantTimeSelect`](../../../src/RateLimit/Storage/Redis.php#L48-L65)
350+
#### [`constantTimeSelect`](../../../src/RateLimit/Storage/Redis.php#L65-L82)
317351

318352
Returns `string`
319353

354+
This is a constant-time conditional select. It should be read like a ternary operation.
355+
356+
$result = ClassWithTrait::constantTimeSelect(1, $left, $right); -> $result === $left. $result = ClassWithTrait::constantTimeSelect(0, $left, $right); -> $result === $right.
357+
320358
**Parameters:**
321359

322360
- `$select`: `int`
@@ -325,49 +363,63 @@ Returns `string`
325363

326364
**Throws:** `CryptoException`
327365

328-
#### [`dos2unix`](../../../src/RateLimit/Storage/Redis.php#L73-L76)
366+
#### [`dos2unix`](../../../src/RateLimit/Storage/Redis.php#L92-L95)
329367

330368
static · Returns `string`
331369

332370
Normalize line-endings to UNIX-style (LF rather than CRLF).
333371

372+
This is mostly used for PEM-encoded strings.
373+
334374
**Parameters:**
335375

336376
- `$in`: `string`
337377

338-
#### [`preAuthEncode`](../../../src/RateLimit/Storage/Redis.php#L84-L97)
378+
#### [`preAuthEncode`](../../../src/RateLimit/Storage/Redis.php#L113-L126)
339379

340380
static · Returns `string`
341381

382+
This is an implementation of PAE() from PASETO. It encodes an array of strings into a flat string consisting of:
383+
384+
1. The number of pieces. 2. For each piece: 1. The length of the piece (in bytes). 2. The contents of the piece. This allows multipart messages to have an injective canonical representation before passing ot a hash function (or other cryptographic function).
385+
342386
**Parameters:**
343387

344388
- `$pieces`: `array`
345389

346-
#### [`sortByKey`](../../../src/RateLimit/Storage/Redis.php#L99-L107)
390+
#### [`sortByKey`](../../../src/RateLimit/Storage/Redis.php#L133-L141)
347391

348392
static · Returns `void`
349393

394+
This sorts the target array in-place, by its keys, including child arrays.
395+
396+
Used for ensuring arrays are sorted before JSON encoding.
397+
350398
**Parameters:**
351399

352400
- `$arr`: `array`
353401

354-
#### [`LE64`](../../../src/RateLimit/Storage/Redis.php#L111-L114)
402+
#### [`LE64`](../../../src/RateLimit/Storage/Redis.php#L148-L151)
355403

356404
static · Returns `string`
357405

406+
Mostly used by preAuthEncode() above. This packs an integer as 8 bytes.
407+
358408
**Parameters:**
359409

360410
- `$n`: `int`
361411

362-
#### [`stringToByteArray`](../../../src/RateLimit/Storage/Redis.php#L116-L123)
412+
#### [`stringToByteArray`](../../../src/RateLimit/Storage/Redis.php#L156-L163)
363413

364414
Returns `array`
365415

416+
Get an array of bytes representing the input string.
417+
366418
**Parameters:**
367419

368420
- `$str`: `string`
369421

370-
#### [`stripNewlines`](../../../src/RateLimit/Storage/Redis.php#L131-L165)
422+
#### [`stripNewlines`](../../../src/RateLimit/Storage/Redis.php#L171-L205)
371423

372424
static · Returns `string`
373425

0 commit comments

Comments
 (0)