system-design-primer-skill 2.3.0 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. package/README.md +15 -7
  2. package/SKILL.md +22 -2
  3. package/VERSION +1 -1
  4. package/evals/README.md +1022 -0
  5. package/evals/system-design-cases.json +414 -0
  6. package/package.json +3 -2
  7. package/references/03-data-and-storage.md +8 -2
  8. package/references/04-caching.md +3 -3
  9. package/references/05-async-and-messaging.md +4 -0
  10. package/references/06-distributed-systems.md +2 -2
  11. package/references/07-reliability-and-resilience.md +7 -3
  12. package/references/08-api-security-observability.md +4 -0
  13. package/references/15-failure-analysis.md +4 -0
  14. package/references/19-agent-security-and-permissions.md +22 -6
  15. package/references/20-agent-state-and-memory.md +4 -0
  16. package/references/22-kubernetes-and-container-platforms.md +1 -1
  17. package/references/24-multi-region-and-disaster-recovery.md +6 -2
  18. package/references/27-production-observability-and-slo.md +4 -0
  19. package/references/28-event-streaming-and-kafka-pulsar.md +6 -0
  20. package/references/32-workflow-orchestration-and-temporal.md +4 -0
  21. package/references/34-postgresql-internals-and-performance.md +2 -0
  22. package/references/35-mysql-innodb-and-performance.md +2 -0
  23. package/references/36-sharding-and-distributed-sql.md +1 -1
  24. package/references/37-consensus-and-distributed-transactions.md +7 -3
  25. package/references/40-zero-downtime-database-migrations.md +3 -3
  26. package/references/48-oauth-oidc-and-passkeys.md +3 -3
  27. package/references/49-iam-rbac-abac-rebac.md +7 -3
  28. package/references/51-secrets-kms-pki-and-key-management.md +4 -0
  29. package/references/52-supply-chain-security-sbom-slsa.md +62 -0
  30. package/references/54-privacy-engineering-and-data-governance.md +4 -0
  31. package/references/55-opentelemetry-and-instrumentation.md +4 -0
  32. package/references/56-distributed-tracing-and-context-propagation.md +4 -0
  33. package/references/59-capacity-planning-and-performance-modeling.md +8 -4
  34. package/references/60-chaos-engineering-and-resilience-experiments.md +4 -0
  35. package/references/61-incident-management-and-postmortems.md +4 -0
  36. package/references/67-storage-infrastructure-and-storage-systems.md +4 -0
  37. package/references/68-tcp-quic-and-network-performance.md +1 -1
  38. package/references/69-task-routing-and-evidence.md +75 -18
  39. package/scripts/audit_chain.py +36 -0
  40. package/scripts/compare_reports.py +43 -0
  41. package/scripts/evaluate.py +475 -0
  42. package/scripts/evaluation_catalog.py +129 -0
  43. package/scripts/evaluation_fingerprints.py +20 -0
  44. package/scripts/evidence_archive.py +79 -0
  45. package/scripts/evidence_signing.py +98 -0
  46. package/scripts/evidence_timestamp.py +441 -0
  47. package/scripts/install.ps1 +2 -2
  48. package/scripts/install.sh +2 -2
  49. package/scripts/report_integrity.py +184 -0
  50. package/scripts/review_consensus.py +77 -0
  51. package/scripts/review_evidence.py +105 -0
  52. package/scripts/review_provenance.py +44 -0
  53. package/scripts/reviewer_calibration.py +215 -0
  54. package/scripts/rubric_compatibility.py +134 -0
  55. package/scripts/run_evals.py +130 -0
  56. package/scripts/run_manifest.py +179 -0
  57. package/scripts/statistical_analysis.py +308 -0
  58. package/scripts/tsa_attestation.py +709 -0
  59. package/scripts/tsa_validation_report.py +627 -0
  60. package/scripts/validate.py +233 -21
  61. package/scripts/verify_build_provenance.py +625 -0
  62. package/scripts/verify_tsa_ocsp.py +962 -0
  63. package/scripts/verify_tsa_revocation.py +782 -0
  64. package/scripts/windows_broker_protocol.py +274 -0
  65. package/scripts/windows_broker_transport.py +141 -0
  66. package/scripts/windows_broker_win32.py +713 -0
@@ -0,0 +1,962 @@
1
+ """Verify an archived OCSP response for a certificate at the current validation time."""
2
+ from __future__ import annotations
3
+ import argparse
4
+ import hashlib
5
+ import json
6
+ import os
7
+ import re
8
+ import shutil
9
+ import stat
10
+ import subprocess
11
+ import sys
12
+ import tempfile
13
+ from datetime import datetime, timedelta, timezone
14
+ from pathlib import Path
15
+ from typing import Any
16
+
17
+ from cryptography import x509
18
+ from cryptography.hazmat.primitives import hashes, serialization
19
+ from cryptography.x509 import ocsp
20
+
21
+ HEX256 = re.compile(r"^[0-9a-f]{64}$")
22
+
23
+ # Bound preflight work for untrusted OCSP response bytes. These are local
24
+ # verifier resource limits, not protocol-level size constraints.
25
+ MAX_OCSP_RESPONSE_BYTES = 16 * 1024 * 1024
26
+ MAX_OCSP_INPUT_BYTES = 16 * 1024 * 1024
27
+ MAX_DER_DEPTH = 64
28
+ MAX_DER_NODES = 200_000
29
+ MAX_DER_CHILDREN = 50_000
30
+ def parse_historical_at_time(value: str) -> datetime:
31
+ """Parse UTC historical targets without silently truncating sub-microsecond precision."""
32
+ match = re.fullmatch(
33
+ r"(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(?:\.(\d+))?Z",
34
+ value,
35
+ )
36
+ if not match:
37
+ raise ValueError("historical OCSP --at-time must be an RFC 3339 UTC timestamp ending in Z")
38
+ fraction = match.group(2)
39
+ if fraction is not None and len(fraction) > 6:
40
+ raise ValueError(
41
+ "historical OCSP --at-time supports at most six fractional digits; "
42
+ "refusing datetime precision truncation"
43
+ )
44
+ try:
45
+ return datetime.fromisoformat(value[:-1] + "+00:00")
46
+ except ValueError as exc:
47
+ raise ValueError("historical OCSP --at-time is not a valid UTC timestamp") from exc
48
+
49
+
50
+ def verification_time_bounds(value: datetime) -> tuple[int, ...]:
51
+ """Return exact floor/ceiling Unix seconds for a timezone-aware instant."""
52
+ if value.tzinfo is None or value.utcoffset() is None:
53
+ raise ValueError("validation time must be timezone-aware")
54
+ delta = value.astimezone(timezone.utc) - datetime(1970, 1, 1, tzinfo=timezone.utc)
55
+ floor_second = delta.days * 86400 + delta.seconds
56
+ return (floor_second, floor_second + 1) if delta.microseconds else (floor_second,)
57
+
58
+
59
+ def load_certificate(path: Path, description: str) -> x509.Certificate:
60
+ raw = _read_stable_ocsp_input(
61
+ path, description, MAX_OCSP_INPUT_BYTES
62
+ )
63
+ try:
64
+ return x509.load_pem_x509_certificate(raw)
65
+ except ValueError:
66
+ try:
67
+ return x509.load_der_x509_certificate(raw)
68
+ except ValueError as exc:
69
+ raise ValueError("could not parse " + description) from exc
70
+
71
+
72
+ def _read_stable_ocsp_input(
73
+ source: Path,
74
+ description: str,
75
+ max_bytes: int = MAX_OCSP_INPUT_BYTES,
76
+ ) -> bytes:
77
+ """Read one bounded regular input and reject files that change during the read."""
78
+ flags = os.O_RDONLY | getattr(os, "O_BINARY", 0)
79
+ # A FIFO/device must not block the verifier while it waits for a writer.
80
+ # O_NONBLOCK is ignored for ordinary regular files on supported platforms.
81
+ flags |= getattr(os, "O_NONBLOCK", 0)
82
+ descriptor = os.open(source, flags)
83
+ with os.fdopen(descriptor, "rb") as stream:
84
+ before = os.fstat(stream.fileno())
85
+ if not stat.S_ISREG(before.st_mode):
86
+ raise ValueError(description + " must be a regular file")
87
+ if before.st_size > max_bytes:
88
+ raise ValueError(
89
+ description + " exceeds the maximum supported size of "
90
+ + str(max_bytes) + " bytes"
91
+ )
92
+ raw = stream.read(max_bytes + 1)
93
+ after = os.fstat(stream.fileno())
94
+
95
+ if len(raw) > max_bytes:
96
+ raise ValueError(
97
+ description + " exceeds the maximum supported size of "
98
+ + str(max_bytes) + " bytes"
99
+ )
100
+ identity_before = (
101
+ before.st_dev, before.st_ino, before.st_size,
102
+ before.st_mtime_ns, before.st_ctime_ns,
103
+ )
104
+ identity_after = (
105
+ after.st_dev, after.st_ino, after.st_size,
106
+ after.st_mtime_ns, after.st_ctime_ns,
107
+ )
108
+ if identity_before != identity_after or len(raw) != after.st_size:
109
+ raise ValueError(
110
+ description + " changed while being snapshotted: " + str(source)
111
+ )
112
+ return raw
113
+
114
+
115
+ def _read_bounded_ocsp_response(path: Path) -> bytes:
116
+ """Read one bounded, stable OCSP response input."""
117
+ return _read_stable_ocsp_input(
118
+ path, "OCSP response", MAX_OCSP_RESPONSE_BYTES
119
+ )
120
+
121
+
122
+ def _der_tlv(data: bytes | memoryview, offset: int = 0) -> tuple[int, memoryview, int]:
123
+ if offset >= len(data):
124
+ raise ValueError("truncated DER value")
125
+ view = memoryview(data)
126
+ tag = view[offset]
127
+ offset += 1
128
+ if tag & 0x1f == 0x1f:
129
+ raise ValueError("high-tag-number DER encoding is not supported in OCSP structures")
130
+ if offset >= len(view):
131
+ raise ValueError("truncated DER length")
132
+ first = view[offset]
133
+ offset += 1
134
+ if first & 0x80:
135
+ count = first & 0x7f
136
+ if count == 0 or count > 4 or offset + count > len(view):
137
+ raise ValueError("invalid DER length")
138
+ if view[offset] == 0:
139
+ raise ValueError("non-minimal DER length")
140
+ length = int.from_bytes(view[offset:offset + count], "big")
141
+ if length < 128:
142
+ raise ValueError("non-minimal DER long-form length")
143
+ offset += count
144
+ else:
145
+ length = first
146
+ end = offset + length
147
+ if end > len(view):
148
+ raise ValueError("truncated DER value")
149
+ # memoryview slices share the original buffer; nested constructed values
150
+ # therefore do not repeatedly copy their full contents during traversal.
151
+ return tag, view[offset:end], end
152
+
153
+
154
+ def _der_children(data: bytes | memoryview):
155
+ """Yield bounded, complete DER child values from a constructed value."""
156
+ offset = 0
157
+ child_count = 0
158
+ while offset < len(data):
159
+ if child_count >= MAX_DER_CHILDREN:
160
+ raise ValueError("DER constructed value exceeds the child-count limit")
161
+ tag, value, end = _der_tlv(data, offset)
162
+ yield tag, value
163
+ offset = end
164
+ child_count += 1
165
+ if offset != len(data):
166
+ raise ValueError("DER constructed value has trailing bytes")
167
+
168
+
169
+ def _der_encoded_children(data: bytes | memoryview):
170
+ """Yield each DER child together with its complete original TLV encoding."""
171
+ offset = 0
172
+ child_count = 0
173
+ view = memoryview(data)
174
+ while offset < len(view):
175
+ if child_count >= MAX_DER_CHILDREN:
176
+ raise ValueError("DER constructed value exceeds the child-count limit")
177
+ start = offset
178
+ tag, value, end = _der_tlv(view, offset)
179
+ yield tag, value, view[start:end]
180
+ offset = end
181
+ child_count += 1
182
+ if offset != len(view):
183
+ raise ValueError("DER constructed value has trailing bytes")
184
+
185
+
186
+ def _require_single_der_value(
187
+ data: bytes | memoryview, expected_tag: int, field: str
188
+ ) -> memoryview:
189
+ tag, value, end = _der_tlv(data)
190
+ if tag != expected_tag or end != len(data):
191
+ raise ValueError(field + " is not one complete DER value")
192
+ return value
193
+
194
+
195
+ def _validate_generalized_time_value(value: bytes | memoryview) -> None:
196
+ # Reject oversized values before copying a view into a standalone bytes object.
197
+ if len(value) != 15:
198
+ raise ValueError(
199
+ "OCSP GeneralizedTime values must be UTC seconds with no fractional seconds"
200
+ )
201
+ raw = bytes(value)
202
+ if not re.fullmatch(rb"[0-9]{14}Z", raw):
203
+ raise ValueError(
204
+ "OCSP GeneralizedTime values must be UTC seconds with no fractional seconds"
205
+ )
206
+ try:
207
+ datetime.strptime(raw.decode("ascii"), "%Y%m%d%H%M%SZ")
208
+ except (UnicodeDecodeError, ValueError) as exc:
209
+ raise ValueError("OCSP GeneralizedTime contains an invalid calendar time") from exc
210
+
211
+
212
+ def _validate_oid_content(value: bytes | memoryview) -> None:
213
+ """Reject empty, unterminated, or non-minimal base-128 OID subidentifiers."""
214
+ if not value:
215
+ raise ValueError("DER OBJECT IDENTIFIER must contain at least one subidentifier")
216
+ component_start = True
217
+ for octet in value:
218
+ if component_start and octet == 0x80:
219
+ raise ValueError("DER OBJECT IDENTIFIER contains a non-minimal subidentifier")
220
+ component_start = not bool(octet & 0x80)
221
+ if not component_start:
222
+ raise ValueError("DER OBJECT IDENTIFIER has an unterminated subidentifier")
223
+
224
+
225
+ def _validate_der_primitive(tag: int, value: bytes | memoryview) -> None:
226
+ """Enforce canonical DER forms for primitive universal ASN.1 types used by OCSP."""
227
+ if tag & 0xC0:
228
+ return
229
+ number = tag & 0x1F
230
+ constructed = bool(tag & 0x20)
231
+
232
+ if number == 0:
233
+ raise ValueError("DER must not contain end-of-contents values")
234
+ if number in (16, 17):
235
+ if not constructed:
236
+ raise ValueError("DER SEQUENCE and SET values must use constructed encoding")
237
+ return
238
+
239
+ # DER uses primitive encoding for the universal string/value types below.
240
+ primitive_numbers = {
241
+ 1, 2, 3, 4, 5, 6, 9, 10, 12, 13, 14, 18, 19, 20, 21, 22, 23, 24,
242
+ 25, 26, 27, 28, 30,
243
+ }
244
+ if number in primitive_numbers and constructed:
245
+ raise ValueError("DER universal primitive value uses constructed encoding")
246
+
247
+ if number == 1: # BOOLEAN: DER TRUE is all one bits; FALSE is all zero bits.
248
+ if len(value) != 1 or value[0] not in (0x00, 0xFF):
249
+ raise ValueError("DER BOOLEAN must be one octet encoded as 00 or FF")
250
+ elif number in (2, 10): # INTEGER and ENUMERATED use minimal two's-complement form.
251
+ if not value:
252
+ raise ValueError("DER INTEGER/ENUMERATED must contain at least one octet")
253
+ if len(value) > 1:
254
+ first, second = value[0], value[1]
255
+ if (first == 0x00 and not second & 0x80) or (
256
+ first == 0xFF and second & 0x80
257
+ ):
258
+ raise ValueError("DER INTEGER/ENUMERATED has redundant sign octets")
259
+ elif number == 3: # BIT STRING: first content octet counts unused trailing bits.
260
+ if not value:
261
+ raise ValueError("DER BIT STRING is missing its unused-bit count")
262
+ unused = value[0]
263
+ if unused > 7:
264
+ raise ValueError("DER BIT STRING unused-bit count must be between 0 and 7")
265
+ if len(value) == 1 and unused:
266
+ raise ValueError("DER empty BIT STRING must have zero unused bits")
267
+ if unused and value[-1] & ((1 << unused) - 1):
268
+ raise ValueError("DER BIT STRING has non-zero padding bits")
269
+ elif number == 4: # OCTET STRING must be primitive in DER; content remains opaque.
270
+ return
271
+ elif number == 5: # NULL has no content octets.
272
+ if value:
273
+ raise ValueError("DER NULL must have empty contents")
274
+ elif number == 6:
275
+ _validate_oid_content(value)
276
+ elif number == 24:
277
+ _validate_generalized_time_value(value)
278
+
279
+
280
+ def _validate_generalized_time_tree(data: bytes | memoryview) -> None:
281
+ """Validate OCSP times with explicit depth and total-node budgets."""
282
+ archive_cutoff_oid = bytes.fromhex("2b0601050507300106") # id-pkix-ocsp-archive-cutoff
283
+ crl_id_oid = bytes.fromhex("2b0601050507300103") # id-pkix-ocsp-crl
284
+ invalidity_date_oid = bytes.fromhex("551d18") # id-ce-invalidityDate
285
+
286
+ # Use an explicit stack instead of Python recursion so hostile nesting cannot
287
+ # exhaust the interpreter call stack. OCTET STRING payloads stay opaque unless
288
+ # an identified OCSP extension defines them as an embedded ASN.1 value.
289
+ pending: list[tuple[int, memoryview, int]] = [(0x30, memoryview(data), 0)]
290
+ visited_nodes = 0
291
+ while pending:
292
+ parent_tag, parent_value, depth = pending.pop()
293
+ if depth > MAX_DER_DEPTH:
294
+ raise ValueError("OCSP DER structure exceeds the nesting-depth limit")
295
+
296
+ children = list(_der_children(parent_value))
297
+ if parent_tag == 0x30 and len(children) in (2, 3):
298
+ # Extension ::= SEQUENCE { extnID, critical DEFAULT FALSE, extnValue }
299
+ if (children[0][0] == 0x06 and children[-1][0] == 0x04
300
+ and (len(children) == 2 or children[1][0] == 0x01)):
301
+ extension_oid = children[0][1]
302
+ extension_value = children[-1][1]
303
+ if extension_oid in (archive_cutoff_oid, invalidity_date_oid):
304
+ field = (
305
+ "OCSP archiveCutoff"
306
+ if extension_oid == archive_cutoff_oid
307
+ else "OCSP invalidityDate"
308
+ )
309
+ embedded_time = _require_single_der_value(
310
+ extension_value, 0x18, field
311
+ )
312
+ visited_nodes += 1
313
+ if visited_nodes > MAX_DER_NODES:
314
+ raise ValueError("OCSP DER structure exceeds the node-count limit")
315
+ _validate_generalized_time_value(embedded_time)
316
+ elif extension_oid == crl_id_oid:
317
+ crl_id = _require_single_der_value(
318
+ extension_value, 0x30, "OCSP CrlID"
319
+ )
320
+ visited_nodes += 1
321
+ if visited_nodes > MAX_DER_NODES:
322
+ raise ValueError("OCSP DER structure exceeds the node-count limit")
323
+ pending.append((0x30, crl_id, depth + 1))
324
+
325
+ for tag, value in children:
326
+ visited_nodes += 1
327
+ if visited_nodes > MAX_DER_NODES:
328
+ raise ValueError("OCSP DER structure exceeds the node-count limit")
329
+ _validate_der_primitive(tag, value)
330
+ if tag & 0x20:
331
+ pending.append((tag, value, depth + 1))
332
+
333
+
334
+ def _compare_der_set_of_encodings(left, right):
335
+ """Compare DER SET OF component encodings using X.690 11.6 zero-padding."""
336
+ width = max(len(left), len(right))
337
+ left_padded = bytes(left) + b"\x00" * (width - len(left))
338
+ right_padded = bytes(right) + b"\x00" * (width - len(right))
339
+ return (left_padded > right_padded) - (left_padded < right_padded)
340
+
341
+
342
+ def _validate_x509_name(name_value, field, require_nonempty=False):
343
+ """Validate Name/RDNSequence and canonical ordering of each RDN SET OF."""
344
+ previous_rdn_count = 0
345
+ for rdn_tag, rdn_value in _der_children(name_value):
346
+ previous_rdn_count += 1
347
+ if rdn_tag != 0x31:
348
+ raise ValueError(field + " RDNSequence contains a non-SET RDN")
349
+ attribute_count = 0
350
+ previous_encoding = None
351
+ for attribute_tag, attribute_value, encoded in _der_encoded_children(rdn_value):
352
+ attribute_count += 1
353
+ if attribute_tag != 0x30:
354
+ raise ValueError(field + " RDN contains a non-SEQUENCE AttributeTypeAndValue")
355
+ parts = list(_der_children(attribute_value))
356
+ if len(parts) != 2 or parts[0][0] != 0x06:
357
+ raise ValueError(field + " AttributeTypeAndValue has an invalid structure")
358
+ _validate_der_primitive(parts[0][0], parts[0][1])
359
+ _validate_der_primitive(parts[1][0], parts[1][1])
360
+ if (previous_encoding is not None
361
+ and _compare_der_set_of_encodings(previous_encoding, encoded) > 0):
362
+ raise ValueError(field + " RDN SET OF components are not in DER sort order")
363
+ previous_encoding = encoded
364
+ if attribute_count == 0:
365
+ raise ValueError(field + " RelativeDistinguishedName must not be empty")
366
+ if require_nonempty and previous_rdn_count == 0:
367
+ raise ValueError(field + " must not be an empty distinguished name")
368
+
369
+
370
+ def _validate_x509_certificate_names(certificate_value):
371
+ """Validate the Certificate/TBSCertificate field path needed to locate both Names."""
372
+ certificate_fields = list(_der_children(certificate_value))
373
+ if not (
374
+ len(certificate_fields) == 3
375
+ and certificate_fields[0][0] == 0x30
376
+ and certificate_fields[1][0] == 0x30
377
+ and certificate_fields[2][0] == 0x03
378
+ ):
379
+ raise ValueError("OCSP embedded Certificate has an invalid outer structure")
380
+ _validate_ocsp_algorithm_identifier(
381
+ certificate_fields[1][1], "embedded Certificate signatureAlgorithm"
382
+ )
383
+ _validate_der_primitive(certificate_fields[2][0], certificate_fields[2][1])
384
+
385
+ tbs_fields = list(_der_children(certificate_fields[0][1]))
386
+ index = 0
387
+ version_number = 0
388
+ if tbs_fields and tbs_fields[0][0] == 0xA0:
389
+ version_value = _require_single_der_value(
390
+ tbs_fields[0][1], 0x02, "embedded TBSCertificate version"
391
+ )
392
+ _validate_der_primitive(0x02, version_value)
393
+ if len(version_value) != 1 or version_value[0] not in (1, 2):
394
+ raise ValueError("embedded TBSCertificate has an explicit DEFAULT or unsupported version")
395
+ version_number = version_value[0]
396
+ index = 1
397
+
398
+ mandatory_tags = (0x02, 0x30, 0x30, 0x30, 0x30, 0x30)
399
+ if len(tbs_fields) < index + len(mandatory_tags) or any(
400
+ tbs_fields[index + offset][0] != expected
401
+ for offset, expected in enumerate(mandatory_tags)
402
+ ):
403
+ raise ValueError("embedded TBSCertificate has an invalid mandatory field structure")
404
+
405
+ issuer_index = index + 2
406
+ subject_index = index + 4
407
+ _validate_x509_name(
408
+ tbs_fields[issuer_index][1], "embedded TBSCertificate issuer", require_nonempty=True
409
+ )
410
+ _validate_x509_name(
411
+ tbs_fields[subject_index][1], "embedded TBSCertificate subject"
412
+ )
413
+
414
+ optional_fields = tbs_fields[index + len(mandatory_tags):]
415
+ allowed_order = {0x81: 1, 0x82: 2, 0xA3: 3}
416
+ last_optional = 0
417
+ for tag, value in optional_fields:
418
+ order = allowed_order.get(tag)
419
+ if order is None or order <= last_optional:
420
+ raise ValueError("embedded TBSCertificate has duplicate or misplaced optional fields")
421
+ last_optional = order
422
+ minimum_version = 2 if tag == 0xA3 else 1
423
+ if version_number < minimum_version:
424
+ raise ValueError("embedded TBSCertificate optional field requires a later version")
425
+ if tag in (0x81, 0x82):
426
+ # issuerUniqueID and subjectUniqueID are IMPLICIT BIT STRING values.
427
+ _validate_der_primitive(0x03, value)
428
+ else:
429
+ extensions = _require_single_der_value(
430
+ value, 0x30, "embedded TBSCertificate extensions"
431
+ )
432
+ if not list(_der_children(extensions)):
433
+ raise ValueError("embedded TBSCertificate extensions must not be empty")
434
+
435
+
436
+ def _validate_ocsp_explicit_value(tag, value, expected_tag, field):
437
+ if tag not in (0xA0, 0xA1, 0xA2):
438
+ raise ValueError(field + " incorrect explicit context-specific tag")
439
+ return _require_single_der_value(value, expected_tag, field)
440
+
441
+ def _validate_ocsp_algorithm_identifier(value, field):
442
+ fields = list(_der_children(value))
443
+ if not (len(fields) in (1, 2) and fields[0][0] == 0x06):
444
+ raise ValueError(field + " invalid AlgorithmIdentifier")
445
+ _validate_der_primitive(fields[0][0], fields[0][1])
446
+
447
+ def _validate_ocsp_cert_id(value):
448
+ fields = list(_der_children(value))
449
+ if not (len(fields) == 4 and fields[0][0] == 0x30 and
450
+ fields[1][0] == 0x04 and fields[2][0] == 0x04 and
451
+ fields[3][0] == 0x02):
452
+ raise ValueError("OCSP CertID structure invalid")
453
+ _validate_ocsp_algorithm_identifier(fields[0][1], "OCSP hashAlgorithm")
454
+ _validate_der_primitive(fields[3][0], fields[3][1])
455
+
456
+ def _validate_ocsp_extensions(tag, value, field):
457
+ sequence = _validate_ocsp_explicit_value(tag, value, 0x30, field)
458
+ extensions = list(_der_children(sequence))
459
+ if not extensions:
460
+ raise ValueError(field + " must contain at least one Extension")
461
+ seen = set()
462
+ for ext_tag, ext_value in extensions:
463
+ if ext_tag != 0x30:
464
+ raise ValueError(field + " contains non-SEQUENCE Extension")
465
+ parts = list(_der_children(ext_value))
466
+ if not ((len(parts) == 2 and parts[0][0] == 0x06 and parts[1][0] == 0x04) or
467
+ (len(parts) == 3 and parts[0][0] == 0x06 and
468
+ parts[1][0] == 0x01 and parts[2][0] == 0x04)):
469
+ raise ValueError(field + " contains invalid Extension structure")
470
+ _validate_der_primitive(parts[0][0], parts[0][1])
471
+ oid = bytes(parts[0][1])
472
+ if oid in seen:
473
+ raise ValueError(field + " contains duplicate extension OID")
474
+ seen.add(oid)
475
+ if len(parts) == 3:
476
+ _validate_der_primitive(parts[1][0], parts[1][1])
477
+ if parts[1][1][0] == 0:
478
+ raise ValueError(field + " explicitly encodes DEFAULT critical FALSE")
479
+ _validate_der_primitive(parts[-1][0], parts[-1][1])
480
+
481
+ def _validate_ocsp_revoked_info(value):
482
+ fields = list(_der_children(value))
483
+ if not fields or len(fields) > 2 or fields[0][0] != 0x18:
484
+ raise ValueError("OCSP revoked CertStatus has invalid implicit RevokedInfo")
485
+ _validate_generalized_time_value(fields[0][1])
486
+ if len(fields) == 2:
487
+ if fields[1][0] != 0xA0:
488
+ raise ValueError("OCSP revocationReason has an incorrect explicit tag")
489
+ reason = _validate_ocsp_explicit_value(fields[1][0], fields[1][1],
490
+ 0x0A, "OCSP revocationReason")
491
+ _validate_der_primitive(0x0A, reason)
492
+
493
+ def _validate_ocsp_single_response(value):
494
+ fields = list(_der_children(value))
495
+ if not (len(fields) >= 3 and fields[0][0] == 0x30 and fields[2][0] == 0x18):
496
+ raise ValueError("OCSP SingleResponse has invalid field structure")
497
+ _validate_ocsp_cert_id(fields[0][1])
498
+ status_tag, status_value = fields[1]
499
+ if status_tag in (0x80, 0x82):
500
+ if status_value:
501
+ label = "good" if status_tag == 0x80 else "unknown"
502
+ raise ValueError("OCSP " + label + " CertStatus IMPLICIT NULL must be empty")
503
+ elif status_tag == 0xA1:
504
+ _validate_ocsp_revoked_info(status_value)
505
+ else:
506
+ raise ValueError("OCSP SingleResponse has invalid CertStatus CHOICE tag")
507
+ _validate_generalized_time_value(fields[2][1])
508
+ index = 3
509
+ if index < len(fields) and fields[index][0] == 0xA0:
510
+ next_update = _validate_ocsp_explicit_value(fields[index][0], fields[index][1],
511
+ 0x18, "OCSP nextUpdate")
512
+ _validate_generalized_time_value(next_update)
513
+ index += 1
514
+ if index < len(fields) and fields[index][0] == 0xA1:
515
+ _validate_ocsp_extensions(fields[index][0], fields[index][1],
516
+ "OCSP singleExtensions")
517
+ index += 1
518
+ if index != len(fields):
519
+ raise ValueError("OCSP SingleResponse has duplicate or unexpected fields")
520
+
521
+ def _validate_ocsp_response_data(value):
522
+ fields = list(_der_children(value))
523
+ index = 0
524
+ if index < len(fields) and fields[index][0] == 0xA0:
525
+ version = _validate_ocsp_explicit_value(fields[index][0], fields[index][1],
526
+ 0x02, "OCSP ResponseData version")
527
+ _validate_der_primitive(0x02, version)
528
+ if bytes(version) == b"\x00":
529
+ raise ValueError("OCSP DEFAULT v1 version must be omitted in DER")
530
+ raise ValueError("OCSP ResponseData contains unsupported version")
531
+ if index >= len(fields):
532
+ raise ValueError("OCSP ResponseData missing ResponderID")
533
+ responder_tag, responder_value = fields[index]
534
+ if responder_tag == 0xA1:
535
+ responder_name = _validate_ocsp_explicit_value(
536
+ responder_tag, responder_value, 0x30, "OCSP ResponderID byName"
537
+ )
538
+ _validate_x509_name(responder_name, "OCSP ResponderID byName")
539
+ elif responder_tag == 0xA2:
540
+ _validate_ocsp_explicit_value(responder_tag, responder_value, 0x04,
541
+ "OCSP ResponderID byKey")
542
+ else:
543
+ raise ValueError("OCSP ResponseData has invalid ResponderID CHOICE tag")
544
+ index += 1
545
+ if index >= len(fields) or fields[index][0] != 0x18:
546
+ raise ValueError("OCSP producedAt missing or malformed")
547
+ _validate_generalized_time_value(fields[index][1])
548
+ index += 1
549
+ if index >= len(fields) or fields[index][0] != 0x30:
550
+ raise ValueError("OCSP responses missing SEQUENCE OF wrapper")
551
+ for tag, response in _der_children(fields[index][1]):
552
+ if tag != 0x30:
553
+ raise ValueError("OCSP responses contains non-SEQUENCE SingleResponse")
554
+ _validate_ocsp_single_response(response)
555
+ index += 1
556
+ if index < len(fields) and fields[index][0] == 0xA1:
557
+ _validate_ocsp_extensions(fields[index][0], fields[index][1],
558
+ "OCSP responseExtensions")
559
+ index += 1
560
+ if index != len(fields):
561
+ raise ValueError("OCSP ResponseData has duplicate or unexpected fields")
562
+
563
+
564
+ def validate_ocsp_generalized_time_profile(response_der: bytes) -> None:
565
+ """Enforce bounded DER and RFC 6960 structure/time rules for OCSP responses."""
566
+ if len(response_der) > MAX_OCSP_RESPONSE_BYTES:
567
+ raise ValueError(
568
+ "OCSP response exceeds the maximum supported size of "
569
+ + str(MAX_OCSP_RESPONSE_BYTES) + " bytes"
570
+ )
571
+ response_content = _require_single_der_value(
572
+ response_der, 0x30, "OCSPResponse"
573
+ )
574
+ response_fields = list(_der_children(response_content))
575
+ if not response_fields or response_fields[0][0] != 0x0A:
576
+ raise ValueError("OCSPResponse has an invalid responseStatus envelope")
577
+
578
+ status_bytes = response_fields[0][1]
579
+ _validate_der_primitive(0x0A, status_bytes)
580
+ if len(status_bytes) != 1 or status_bytes[0] not in (0, 1, 2, 3, 5, 6):
581
+ raise ValueError("OCSPResponse has an invalid responseStatus value")
582
+ response_status = status_bytes[0]
583
+
584
+ if len(response_fields) > 2 or (
585
+ len(response_fields) == 2 and response_fields[1][0] != 0xA0
586
+ ):
587
+ raise ValueError("OCSPResponse has unexpected responseStatus envelope fields")
588
+ if response_status != 0:
589
+ if len(response_fields) != 1:
590
+ raise ValueError("OCSP error response must not contain responseBytes")
591
+ return
592
+ if len(response_fields) != 2:
593
+ raise ValueError("successful OCSPResponse is missing responseBytes")
594
+
595
+ response_bytes_content = _require_single_der_value(
596
+ response_fields[1][1], 0x30, "OCSP responseBytes"
597
+ )
598
+ fields = list(_der_children(response_bytes_content))
599
+ if len(fields) != 2 or fields[0][0] != 0x06 or fields[1][0] != 0x04:
600
+ raise ValueError("OCSP responseBytes has an invalid structure")
601
+ _validate_der_primitive(fields[0][0], fields[0][1])
602
+ # id-pkix-ocsp-basic = 1.3.6.1.5.5.7.48.1.1
603
+ if fields[0][1] != bytes.fromhex("2b0601050507300101"):
604
+ return
605
+ basic_response = _require_single_der_value(
606
+ fields[1][1], 0x30, "BasicOCSPResponse"
607
+ )
608
+ basic_fields = list(_der_children(basic_response))
609
+ if not (
610
+ len(basic_fields) in (3, 4)
611
+ and basic_fields[0][0] == 0x30
612
+ and basic_fields[1][0] == 0x30
613
+ and basic_fields[2][0] == 0x03
614
+ and (len(basic_fields) == 3 or basic_fields[3][0] == 0xA0)
615
+ ):
616
+ raise ValueError("BasicOCSPResponse has an invalid structure")
617
+ _validate_ocsp_algorithm_identifier(
618
+ basic_fields[1][1], "BasicOCSPResponse signatureAlgorithm"
619
+ )
620
+ certificate_entries = []
621
+ if len(basic_fields) == 4:
622
+ certificates = _validate_ocsp_explicit_value(
623
+ basic_fields[3][0], basic_fields[3][1], 0x30,
624
+ "BasicOCSPResponse certs"
625
+ )
626
+ certificate_entries = list(_der_children(certificates))
627
+ if any(tag != 0x30 for tag, _ in certificate_entries):
628
+ raise ValueError("BasicOCSPResponse certs contains non-SEQUENCE Certificate")
629
+ # Apply the bounded whole-tree walk before the schema-specific parser so
630
+ # an input that exceeds depth/node/child budgets is rejected before the
631
+ # more detailed field parser allocates and processes its nested structures.
632
+ _validate_generalized_time_tree(basic_response)
633
+ _validate_ocsp_response_data(basic_fields[0][1])
634
+ for _, certificate_value in certificate_entries:
635
+ _validate_x509_certificate_names(certificate_value)
636
+
637
+
638
+
639
+ def validate_trust_anchor_bundle(path: Path) -> None:
640
+ """Restrict the OCSP trust store to unique, explicitly self-issued anchors."""
641
+ raw = _read_stable_ocsp_input(
642
+ path, "OCSP issuer-root bundle", MAX_OCSP_INPUT_BYTES
643
+ )
644
+ blocks = re.findall(rb"-----BEGIN CERTIFICATE-----.*?-----END CERTIFICATE-----", raw, re.DOTALL)
645
+ try:
646
+ certificates = ([x509.load_pem_x509_certificate(block) for block in blocks]
647
+ if blocks else [x509.load_der_x509_certificate(raw)])
648
+ except ValueError as exc:
649
+ raise ValueError("issuer-root bundle must contain parseable PEM or DER certificates") from exc
650
+ if not certificates:
651
+ raise ValueError("issuer-root bundle must contain at least one trust anchor")
652
+ seen: set[bytes] = set()
653
+ for certificate in certificates:
654
+ fingerprint = certificate.fingerprint(hashes.SHA256())
655
+ if fingerprint in seen:
656
+ raise ValueError("issuer-root bundle contains a duplicate certificate")
657
+ seen.add(fingerprint)
658
+ if certificate.subject != certificate.issuer:
659
+ raise ValueError("issuer-root bundle may contain only self-issued trust anchors; place intermediates in --intermediates")
660
+ try:
661
+ basic_constraints_ext = certificate.extensions.get_extension_for_class(x509.BasicConstraints)
662
+ except x509.ExtensionNotFound as exc:
663
+ raise ValueError("issuer-root certificates must contain critical BasicConstraints with CA:TRUE") from exc
664
+ if not basic_constraints_ext.critical or not basic_constraints_ext.value.ca:
665
+ raise ValueError("issuer-root certificates must contain critical BasicConstraints with CA:TRUE")
666
+ try:
667
+ key_usage_ext = certificate.extensions.get_extension_for_class(x509.KeyUsage)
668
+ except x509.ExtensionNotFound as exc:
669
+ raise ValueError("issuer-root certificates must contain KeyUsage with keyCertSign") from exc
670
+ if not key_usage_ext.value.key_cert_sign:
671
+ raise ValueError("issuer-root certificates must contain critical KeyUsage with keyCertSign")
672
+
673
+
674
+ def bind_responder_certificate(response_path: Path, certificate_path: Path,
675
+ expected_sha256: str) -> tuple[x509.Certificate, str]:
676
+ if not isinstance(expected_sha256, str) or not HEX256.fullmatch(expected_sha256):
677
+ raise ValueError("expected responder-certificate SHA-256 must be 64 lowercase hex characters")
678
+ certificate_bytes = _read_stable_ocsp_input(
679
+ certificate_path, "OCSP responder certificate", MAX_OCSP_INPUT_BYTES
680
+ )
681
+ digest = hashlib.sha256(certificate_bytes).hexdigest()
682
+ if digest != expected_sha256:
683
+ raise ValueError("OCSP responder-certificate SHA-256 pin mismatch")
684
+ try:
685
+ try:
686
+ certificate = x509.load_pem_x509_certificate(certificate_bytes)
687
+ except ValueError:
688
+ certificate = x509.load_der_x509_certificate(certificate_bytes)
689
+ response = ocsp.load_der_ocsp_response(_read_bounded_ocsp_response(response_path))
690
+ except ValueError as exc:
691
+ raise ValueError("could not parse OCSP response or responder certificate") from exc
692
+ if response.response_status is not ocsp.OCSPResponseStatus.SUCCESSFUL:
693
+ raise ValueError("OCSP response status is not successful")
694
+ if response.responder_name is not None:
695
+ matches = response.responder_name == certificate.subject
696
+ else:
697
+ spki = certificate.public_key().public_bytes(
698
+ serialization.Encoding.DER, serialization.PublicFormat.SubjectPublicKeyInfo
699
+ )
700
+ tag, sequence, end = _der_tlv(spki)
701
+ if tag != 0x30 or end != len(spki):
702
+ raise ValueError("invalid responder SubjectPublicKeyInfo")
703
+ _, _, offset = _der_tlv(sequence, 0)
704
+ bit_tag, bit_string, bit_end = _der_tlv(sequence, offset)
705
+ if bit_tag != 0x03 or bit_end != len(sequence) or not bit_string or bit_string[0] != 0:
706
+ raise ValueError("invalid responder subjectPublicKey BIT STRING")
707
+ matches = response.responder_key_hash == hashlib.sha1(bit_string[1:]).digest()
708
+ if not matches:
709
+ raise ValueError("pinned responder certificate does not match OCSP ResponderID")
710
+ return certificate, digest
711
+
712
+ def verify_ocsp_response(certificate: Path, issuer: Path, roots: Path, response: Path,
713
+ expected_roots_sha256: str, intermediates: Path | None = None,
714
+ now: datetime | None = None, skew_seconds: int = 300,
715
+ at_time: datetime | None = None,
716
+ responder_certificate: Path | None = None,
717
+ expected_responder_certificate_sha256: str | None = None) -> dict[str, Any]:
718
+ """Verify one immutable snapshot of every caller-supplied OCSP input."""
719
+ with tempfile.TemporaryDirectory(prefix="tsa-ocsp-inputs-") as temporary:
720
+ snapshot_dir = Path(temporary)
721
+
722
+ def snapshot(name: str, source: Path | None) -> Path | None:
723
+ if source is None:
724
+ return None
725
+ destination = snapshot_dir / name
726
+ raw = _read_stable_ocsp_input(
727
+ source, "OCSP " + name, MAX_OCSP_INPUT_BYTES
728
+ )
729
+ destination.write_bytes(raw)
730
+ return destination
731
+
732
+ return _verify_ocsp_response_snapshot(
733
+ snapshot("target-certificate", certificate),
734
+ snapshot("issuer-certificate", issuer),
735
+ snapshot("issuer-roots", roots),
736
+ snapshot("ocsp-response.der", response),
737
+ expected_roots_sha256,
738
+ snapshot("intermediates.pem", intermediates),
739
+ now=now,
740
+ skew_seconds=skew_seconds,
741
+ at_time=at_time,
742
+ responder_certificate=snapshot("responder-certificate", responder_certificate),
743
+ expected_responder_certificate_sha256=expected_responder_certificate_sha256,
744
+ )
745
+
746
+
747
+ def _verify_ocsp_response_snapshot(certificate: Path, issuer: Path, roots: Path, response: Path,
748
+ expected_roots_sha256: str, intermediates: Path | None = None,
749
+ now: datetime | None = None, skew_seconds: int = 300,
750
+ at_time: datetime | None = None,
751
+ responder_certificate: Path | None = None,
752
+ expected_responder_certificate_sha256: str | None = None) -> dict[str, Any]:
753
+ if not isinstance(expected_roots_sha256, str) or not HEX256.fullmatch(expected_roots_sha256):
754
+ raise ValueError("expected issuer-root SHA-256 must be 64 lowercase hex characters")
755
+ if isinstance(skew_seconds, bool) or not isinstance(skew_seconds, int) or not 0 <= skew_seconds <= 3600:
756
+ raise ValueError("clock skew must be an integer between 0 and 3600 seconds")
757
+ roots_digest = hashlib.sha256(roots.read_bytes()).hexdigest()
758
+ if roots_digest != expected_roots_sha256:
759
+ raise ValueError("issuer-root bundle SHA-256 pin mismatch")
760
+ validate_trust_anchor_bundle(roots)
761
+ # RFC 6960 §4.2.2.1 delegates OCSP GeneralizedTime syntax to RFC 5280
762
+ # §4.1.2.5.2, which requires whole-second UTC values without fractions.
763
+ validate_ocsp_generalized_time_profile(response.read_bytes())
764
+ executable = shutil.which("openssl")
765
+ if not executable:
766
+ raise ValueError("OpenSSL CLI is required for OCSP response verification")
767
+ responder_digest = None
768
+ pinned_responder_certificate = None
769
+ if (responder_certificate is None) != (expected_responder_certificate_sha256 is None):
770
+ raise ValueError("responder certificate and its SHA-256 pin must be supplied together")
771
+ if responder_certificate is not None:
772
+ pinned_responder_certificate, responder_digest = bind_responder_certificate(
773
+ response, responder_certificate, expected_responder_certificate_sha256 or ""
774
+ )
775
+ with tempfile.TemporaryDirectory(prefix="tsa-ocsp-") as temporary:
776
+ request_path = Path(temporary) / "request.der"
777
+ request_command = [executable, "ocsp", "-issuer", str(issuer), "-cert", str(certificate),
778
+ "-no_nonce", "-reqout", str(request_path)]
779
+ request_result = subprocess.run(request_command, capture_output=True, text=True, check=False)
780
+ if request_result.returncode:
781
+ detail = (request_result.stderr or request_result.stdout).strip()
782
+ raise ValueError("OpenSSL could not construct the certificate-bound OCSP request: " + detail[-2000:])
783
+ command = [executable, "ocsp", "-reqin", str(request_path),
784
+ "-respin", str(response), "-CAfile", str(roots), "-no-CApath", "-no-CAstore",
785
+ "-x509_strict", "-auth_level", "2", "-no_nonce"]
786
+ if responder_certificate is None:
787
+ # OpenSSL 3.5.x retries a failed -verify_other check with the -issuer
788
+ # certificates using OCSP_TRUSTOTHER, dropping OCSP_NOINTERN. In pinned
789
+ # mode that can re-select an embedded responder and bypass the pin.
790
+ # The request DER already carries the target CertID, so omit -issuer
791
+ # from response verification when the signer certificate is pinned.
792
+ command.extend(["-issuer", str(issuer)])
793
+ if responder_certificate is not None:
794
+ signer_bundle = Path(temporary) / "responder-signer-bundle.pem"
795
+ if pinned_responder_certificate is None:
796
+ raise ValueError("pinned OCSP responder certificate was not loaded")
797
+ signer_pem = pinned_responder_certificate.public_bytes(serialization.Encoding.PEM)
798
+ signer_bundle.write_bytes(signer_pem + (intermediates.read_bytes() if intermediates is not None else b""))
799
+ command.extend(["-no_intern", "-verify_other", str(signer_bundle)])
800
+ elif intermediates is not None:
801
+ command.extend(["-verify_other", str(intermediates)])
802
+ responder_chain_validation_times = (
803
+ list(verification_time_bounds(at_time)) if at_time is not None else []
804
+ )
805
+ commands = (
806
+ [[*command, "-attime", str(instant)] for instant in responder_chain_validation_times]
807
+ if responder_chain_validation_times else [command]
808
+ )
809
+ outputs = []
810
+ for verification_command in commands:
811
+ result = subprocess.run(
812
+ verification_command, capture_output=True, text=True, check=False
813
+ )
814
+ output = (result.stdout or "") + "\\n" + (result.stderr or "")
815
+ if result.returncode:
816
+ raise ValueError(
817
+ "OpenSSL OCSP verification failed: " + output.strip()[-2000:]
818
+ )
819
+ if not re.search(r"Response verify OK", output, re.I):
820
+ raise ValueError(
821
+ "OpenSSL did not confirm OCSP response signature and responder-chain verification"
822
+ )
823
+ outputs.append(output)
824
+ output = "\\n".join(outputs)
825
+ if not re.search(r"Response verify OK", output, re.I):
826
+ raise ValueError("OpenSSL did not confirm OCSP response signature and responder-chain verification")
827
+ try:
828
+ parsed_response = ocsp.load_der_ocsp_response(response.read_bytes())
829
+ except ValueError as exc:
830
+ raise ValueError("could not parse OCSP response") from exc
831
+ target_certificate = load_certificate(certificate, "target certificate")
832
+ issuer_certificate = load_certificate(issuer, "OCSP issuer certificate")
833
+ if parsed_response.response_status is not ocsp.OCSPResponseStatus.SUCCESSFUL:
834
+ raise ValueError("OCSP response status is not successful")
835
+ matching_responses = []
836
+ for single in parsed_response.responses:
837
+ request = (ocsp.OCSPRequestBuilder()
838
+ .add_certificate(target_certificate, issuer_certificate, single.hash_algorithm)
839
+ .build())
840
+ if (single.serial_number == request.serial_number
841
+ and single.issuer_name_hash == request.issuer_name_hash
842
+ and single.issuer_key_hash == request.issuer_key_hash
843
+ and single.hash_algorithm.name == request.hash_algorithm.name):
844
+ matching_responses.append(single)
845
+ if len(matching_responses) != 1:
846
+ raise ValueError("OCSP response must contain exactly one unambiguous CertID match for the target certificate")
847
+ target_response = matching_responses[0]
848
+ status = target_response.certificate_status.name.lower()
849
+ produced = parsed_response.produced_at
850
+ this_update = target_response.this_update
851
+ next_update = target_response.next_update
852
+ if next_update is None:
853
+ raise ValueError("OCSP target response lacks nextUpdate")
854
+ if produced.tzinfo is None:
855
+ produced = produced.replace(tzinfo=timezone.utc)
856
+ else:
857
+ produced = produced.astimezone(timezone.utc)
858
+ if this_update.tzinfo is None:
859
+ this_update = this_update.replace(tzinfo=timezone.utc)
860
+ else:
861
+ this_update = this_update.astimezone(timezone.utc)
862
+ if next_update.tzinfo is None:
863
+ next_update = next_update.replace(tzinfo=timezone.utc)
864
+ else:
865
+ next_update = next_update.astimezone(timezone.utc)
866
+ instant = at_time or now or datetime.now(timezone.utc)
867
+ if instant.tzinfo is None or instant.utcoffset() is None:
868
+ raise ValueError("validation clock must be timezone-aware")
869
+ instant = instant.astimezone(timezone.utc)
870
+ skew = timedelta(seconds=skew_seconds)
871
+ if at_time is not None:
872
+ # Historical status must cover the exact target instant. Do not let a
873
+ # current-time clock-skew allowance widen a historical evidence window.
874
+ # Keep this aligned with tsa_validation_report's historical OCSP contract.
875
+ if produced > instant:
876
+ raise ValueError("historical OCSP producedAt is later than target time")
877
+ if this_update > instant:
878
+ raise ValueError("historical OCSP thisUpdate is later than target time")
879
+ if next_update < instant:
880
+ raise ValueError("historical OCSP nextUpdate is stale: target time is later than nextUpdate")
881
+ else:
882
+ if produced > instant + skew:
883
+ raise ValueError("OCSP producedAt is in the future beyond allowed clock skew")
884
+ if this_update > instant + skew:
885
+ raise ValueError("OCSP thisUpdate is in the future beyond allowed clock skew")
886
+ if next_update < instant - skew:
887
+ raise ValueError("OCSP response is stale: nextUpdate has passed")
888
+ if next_update < this_update:
889
+ raise ValueError("OCSP nextUpdate precedes thisUpdate")
890
+ return {
891
+ "verified": True,
892
+ "status": status,
893
+ "validation_time": instant.isoformat().replace("+00:00", "Z"),
894
+ "certificate_sha256": hashlib.sha256(certificate.read_bytes()).hexdigest(),
895
+ "responder_certificate_sha256": responder_digest,
896
+ "responder_chain_validation_scope": (
897
+ "OpenSSL responder PKIX path validation at the exact floor/ceiling Unix-second bound(s) of historical validation_time"
898
+ if at_time is not None else
899
+ "OpenSSL responder PKIX path validation at the host wall-clock time"
900
+ ),
901
+ "responder_chain_validation_times": responder_chain_validation_times,
902
+ "responder_chain_validation_policy": (
903
+ "OpenSSL ocsp uses the SHA-256-pinned -CAfile, empty -CApath/-CAstore, -x509_strict, and -auth_level 2"
904
+ ),
905
+ "produced_at": produced.isoformat().replace("+00:00", "Z"),
906
+ "this_update": this_update.isoformat().replace("+00:00", "Z"),
907
+ "next_update": next_update.isoformat().replace("+00:00", "Z"),
908
+ "issuer_roots_sha256": roots_digest,
909
+ "issuer_intermediates_sha256": (
910
+ hashlib.sha256(intermediates.read_bytes()).hexdigest() if intermediates is not None else None
911
+ ),
912
+ "trust_anchor_policy": (
913
+ "issuer-roots bundle is SHA-256 pinned and restricted to self-issued CA certificates "
914
+ "with critical BasicConstraints and keyCertSign; optional responder "
915
+ "certificates/intermediates are supplied separately via -verify_other"
916
+ ),
917
+ "verification": (
918
+ "OpenSSL OCSP response signature and responder-chain validation uses pinned -CAfile, "
919
+ "empty -CApath/-CAstore, -x509_strict, and -auth_level 2; historical validation repeats "
920
+ "path verification at exact floor/ceiling Unix-second bound(s); Python verifies exact target CertID, status, and freshness"
921
+ ),
922
+ "response_sha256": hashlib.sha256(response.read_bytes()).hexdigest(),
923
+ "nonce_checked": False,
924
+ "scope": ("historical OCSP status validation at the supplied target time" if at_time is not None else
925
+ "current-time OCSP response validation; not a historical status determination"),
926
+ "historical_at_time": (instant.isoformat().replace("+00:00", "Z") if at_time is not None else None),
927
+ }
928
+
929
+ def main() -> int:
930
+ parser = argparse.ArgumentParser(description=__doc__)
931
+ parser.add_argument("--certificate", type=Path, required=True)
932
+ parser.add_argument("--issuer", type=Path, required=True)
933
+ parser.add_argument("--issuer-roots", type=Path, required=True)
934
+ parser.add_argument("--issuer-roots-sha256", required=True)
935
+ parser.add_argument("--response", type=Path, required=True)
936
+ parser.add_argument("--intermediates", type=Path)
937
+ parser.add_argument("--responder-certificate", type=Path,
938
+ help="explicit certificate expected to sign the BasicOCSPResponse")
939
+ parser.add_argument("--responder-certificate-sha256",
940
+ help="independently recorded SHA-256 pin for --responder-certificate")
941
+ parser.add_argument("--clock-skew-seconds", type=int, default=300)
942
+ parser.add_argument(
943
+ "--at-time",
944
+ help="historical RFC 3339 UTC instant ending in Z (up to six fractional digits)",
945
+ )
946
+ args = parser.parse_args()
947
+ try:
948
+ historical_time = parse_historical_at_time(args.at_time) if args.at_time is not None else None
949
+ result = verify_ocsp_response(args.certificate, args.issuer, args.issuer_roots,
950
+ args.response, args.issuer_roots_sha256,
951
+ args.intermediates, skew_seconds=args.clock_skew_seconds,
952
+ at_time=historical_time,
953
+ responder_certificate=args.responder_certificate,
954
+ expected_responder_certificate_sha256=args.responder_certificate_sha256)
955
+ except (OSError, ValueError, TypeError) as exc:
956
+ print("ERROR: " + str(exc), file=sys.stderr)
957
+ return 1
958
+ print(json.dumps(result, sort_keys=True, indent=2))
959
+ return 0
960
+
961
+ if __name__ == "__main__":
962
+ raise SystemExit(main())