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,627 @@
1
+ """Combine independently verified TSA CRL and OCSP results without overstating their scope."""
2
+ from __future__ import annotations
3
+ import argparse
4
+ import hashlib
5
+ import json
6
+ import re
7
+ import sys
8
+ from datetime import datetime
9
+ from pathlib import Path
10
+ from typing import Any
11
+
12
+ HEX256 = re.compile(r"^[0-9a-f]{64}$")
13
+ UTC = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$")
14
+
15
+ def parse_utc_parts(value: str, field: str) -> tuple[datetime, str]:
16
+ """Parse UTC seconds separately from the arbitrary-precision GeneralizedTime fraction."""
17
+ match = re.fullmatch(
18
+ r"(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(?:\.(\d+))?Z",
19
+ value if isinstance(value, str) else "",
20
+ )
21
+ if not match:
22
+ raise ValueError(field + " must be an RFC 3339 UTC timestamp ending in Z")
23
+ try:
24
+ whole_second = datetime.fromisoformat(match.group(1) + "+00:00")
25
+ except ValueError as exc:
26
+ raise ValueError(field + " is not a valid UTC timestamp") from exc
27
+ return whole_second, match.group(2) or ""
28
+
29
+
30
+ def parse_rfc3161_gen_time(value: str, field: str = "gen_time") -> tuple[datetime, str]:
31
+ """Enforce the RFC 3161 DER GeneralizedTime fractional-seconds form."""
32
+ whole_second, fraction = parse_utc_parts(value, field)
33
+ if fraction.endswith("0"):
34
+ raise ValueError(field + " fractional seconds must omit trailing zeros")
35
+ return whole_second, fraction
36
+
37
+
38
+ def compare_utc_values(left: str, right: str, field: str = "UTC timestamp") -> int:
39
+ """Compare two UTC timestamps without truncating or rounding fractional digits."""
40
+ left_second, left_fraction = parse_utc_parts(left, field + " left value")
41
+ right_second, right_fraction = parse_utc_parts(right, field + " right value")
42
+ if left_second < right_second:
43
+ return -1
44
+ if left_second > right_second:
45
+ return 1
46
+ width = max(len(left_fraction), len(right_fraction))
47
+ left_digits = left_fraction.ljust(width, "0")
48
+ right_digits = right_fraction.ljust(width, "0")
49
+ return (left_digits > right_digits) - (left_digits < right_digits)
50
+
51
+
52
+ def parse_utc(value: str, field: str) -> datetime:
53
+ """Parse values that fit datetime's microsecond precision; reject silent truncation."""
54
+ whole_second, fraction = parse_utc_parts(value, field)
55
+ if len(fraction) > 6:
56
+ raise ValueError(field + " exceeds the supported six fractional digits")
57
+ microseconds = int((fraction + "000000")[:6]) if fraction else 0
58
+ return whole_second.replace(microsecond=microseconds)
59
+
60
+
61
+ CRL_PATH_VALIDATION_SCOPE = (
62
+ "OpenSSL target certificate PKIX path validation at the exact floor/ceiling "
63
+ "Unix-second bound(s) of RFC 3161 genTime"
64
+ )
65
+ CRL_VERIFICATION_METHOD = (
66
+ "OpenSSL path auth_level 2 and CRL signature validation plus direct-CRL issuer, "
67
+ "CA/keyCertSign/cRLSign, issuer validity at CRL thisUpdate, target certificate "
68
+ "PKIX path validation at exact floor/ceiling Unix-second bound(s), AKI, scope, "
69
+ "freshness, signature-policy and entry-semantic preflight"
70
+ )
71
+
72
+
73
+ def utc_unix_second_bounds(value: str, field: str = "UTC timestamp") -> list[int]:
74
+ """Return floor/ceiling Unix seconds without losing arbitrary fraction precision."""
75
+ whole_second, fraction = parse_utc_parts(value, field)
76
+ epoch = datetime(1970, 1, 1, tzinfo=whole_second.tzinfo)
77
+ delta = whole_second - epoch
78
+ floor_second = delta.days * 86400 + delta.seconds
79
+ if any(digit != "0" for digit in fraction):
80
+ return [floor_second, floor_second + 1]
81
+ return [floor_second]
82
+
83
+ def validate_crl_issuer_validity(value: Any, field: str, gen_time: str) -> dict[str, Any]:
84
+ if not isinstance(value, dict):
85
+ raise ValueError(field + " evidence is missing")
86
+ parse_rfc3161_gen_time(gen_time, "gen_time")
87
+ required = ("crl_this_update", "not_before", "not_after")
88
+ times = {name: parse_utc(value.get(name), field + "." + name) for name in required}
89
+ if not (times["not_before"] <= times["crl_this_update"] <= times["not_after"]):
90
+ raise ValueError(field + " does not establish issuer validity at CRL thisUpdate")
91
+ if compare_utc_values(
92
+ value.get("crl_this_update"), gen_time, field + " CRL thisUpdate vs genTime"
93
+ ) > 0:
94
+ raise ValueError(field + " CRL thisUpdate is later than the historical target time")
95
+ for flag in ("valid_at_this_update", "basic_constraints_ca", "key_cert_sign", "crl_sign"):
96
+ if value.get(flag) is not True:
97
+ raise ValueError(field + " must affirm " + flag)
98
+ if value.get("time_basis") != "CRL issuer certificate validity and CA/keyCertSign/cRLSign authorization are checked at CRL thisUpdate; OpenSSL validates the full target certificate PKIX path, including the issuer path to the pinned trust anchor, at RFC3161 genTime bounds":
99
+ raise ValueError(field + " time-basis declaration is missing or unsupported")
100
+ return value
101
+ def load_json(path: Path, expected_sha256: str) -> tuple[dict[str, Any], str]:
102
+ raw = path.read_bytes()
103
+ digest = hashlib.sha256(raw).hexdigest()
104
+ require_digest(expected_sha256, str(path) + " expected SHA-256")
105
+ if digest != expected_sha256:
106
+ raise ValueError(str(path) + " SHA-256 does not match the independently supplied pin")
107
+ value = json.loads(raw.decode("utf-8"))
108
+ if not isinstance(value, dict):
109
+ raise ValueError(str(path) + " must contain a JSON object")
110
+ return value, digest
111
+
112
+ def require_digest(value: Any, field: str) -> str:
113
+ if not isinstance(value, str) or not HEX256.fullmatch(value):
114
+ raise ValueError(field + " must be a lowercase SHA-256 digest")
115
+ return value
116
+
117
+ def _build_limitations(ocsp: dict[str, Any], responder: dict[str, Any]) -> list[str]:
118
+ """Describe only the evidence gaps that remain for this report configuration."""
119
+ limitations = [
120
+ "This report does not independently verify the RFC 3161 token or derive genTime; it only compares caller-supplied genTime with the timestamp and CRL result records.",
121
+ "genTime provenance is caller-asserted. This report does not authenticate the source of the supplied time or independently verify the timestamp token.",
122
+ "The TSA CRL finding covers only the supplied certificate path and CRL. It does not prove that all applicable revocation sources, trust policies, or CRL partitions were supplied.",
123
+ "The supported CRL verifier is limited to direct CRLs without certificate CRLDistributionPoints; delta, indirect, named issuing-distribution-point, and partial-reason coverage are not assessed.",
124
+ "Result JSON files are accepted only when their byte digests match caller-supplied pins; this report checks byte equality but does not authenticate the pin source.",
125
+ "A caller must obtain and retain each pin through a separately trusted channel. The report cannot establish that separation, identify who produced the result JSON, or prove which verifier binary executed.",
126
+ "This report is an aggregation record, not a digital signature or an independent trust anchor.",
127
+ ]
128
+ if not ocsp.get("provided"):
129
+ limitations.append(
130
+ "No OCSP response was supplied; neither current-time nor historical OCSP status was assessed."
131
+ )
132
+ limitations.append(
133
+ "OCSP responder certificate revocation at genTime was not assessed because no OCSP responder identity and historical response were supplied."
134
+ )
135
+ else:
136
+ if ocsp.get("historical_status_claim"):
137
+ limitations.append(
138
+ "The supplied OCSP response is assessed only at RFC 3161 genTime; it does not establish the responder's current-time status."
139
+ )
140
+ else:
141
+ limitations.append(
142
+ "The supplied OCSP response is current-time evidence only; it cannot establish certificate status at RFC 3161 genTime."
143
+ )
144
+ limitations.append(
145
+ "The OCSP verifier does not check a request nonce; nonce_checked is false."
146
+ )
147
+ if responder.get("status") == "not_assessed":
148
+ limitations.append(
149
+ "OCSP responder certificate revocation at genTime was not assessed. A historical OCSP status result and a separately pinned CRL result for the exact responder certificate, bound to genTime, are required."
150
+ )
151
+ else:
152
+ limitations.append(
153
+ "The OCSP responder non-revocation finding covers only the supplied responder certificate path and direct CRL; it does not prove complete responder revocation-source or trust-policy coverage."
154
+ )
155
+ return limitations
156
+
157
+
158
+ def _build_overall_assessment(ocsp: dict[str, Any]) -> str:
159
+ """Derive the summary strictly from the declared OCSP scope and status."""
160
+ if not isinstance(ocsp, dict) or type(ocsp.get("provided")) is not bool:
161
+ raise ValueError("OCSP assessment must declare a boolean provided field")
162
+ if not ocsp["provided"]:
163
+ if ocsp.get("assessment") != "not_provided" or ocsp.get("historical_status_claim") is not False:
164
+ raise ValueError("omitted OCSP evidence must be classified not_provided with no historical claim")
165
+ return "historical_crl_passed_ocsp_not_provided_with_scope_limitations"
166
+ status = ocsp.get("assessment")
167
+ if status not in ("good", "revoked", "unknown"):
168
+ raise ValueError("provided OCSP assessment must be good, revoked, or unknown")
169
+ historical = ocsp.get("historical_status_claim")
170
+ if type(historical) is not bool:
171
+ raise ValueError("OCSP historical_status_claim must be a boolean")
172
+ if historical:
173
+ return {
174
+ "good": "historical_crl_passed_and_historical_ocsp_good_with_scope_limitations",
175
+ "revoked": "historical_crl_passed_but_historical_ocsp_reports_revoked",
176
+ "unknown": "historical_crl_passed_but_historical_ocsp_status_unknown",
177
+ }[status]
178
+ return {
179
+ "good": "historical_crl_passed_current_ocsp_good_with_scope_limitations",
180
+ "revoked": "historical_crl_passed_but_current_ocsp_reports_revoked",
181
+ "unknown": "historical_crl_passed_but_current_ocsp_status_unknown",
182
+ }[status]
183
+
184
+
185
+ def validate_timestamp_scope(result: dict[str, Any]) -> tuple[dict[str, str], list[str]]:
186
+ """Validate and preserve the explicit verification scope and limitations."""
187
+ scope = result.get("verification_scope")
188
+ required = {
189
+ "cms_signature", "request_imprint", "response_imprint",
190
+ "request_response_binding", "nonce_binding",
191
+ "tsa_pkix_chain_at_gen_time", "tsa_signer_certificate_profile",
192
+ "tsa_signer_validity_at_gen_time",
193
+ }
194
+ if not isinstance(scope, dict) or set(scope) != required:
195
+ raise ValueError("timestamp verification scope is missing or malformed")
196
+ for field in required - {"nonce_binding"}:
197
+ if scope[field] != "verified":
198
+ raise ValueError("timestamp verification scope does not establish " + field)
199
+ if type(result.get("nonce_present")) is not bool:
200
+ raise ValueError("timestamp nonce_present must be an explicit boolean")
201
+ expected_nonce = "verified" if result["nonce_present"] else "not_requested"
202
+ if scope["nonce_binding"] != expected_nonce:
203
+ raise ValueError("timestamp nonce scope contradicts nonce_present")
204
+ limitations = result.get("not_established")
205
+ if (not isinstance(limitations, list) or not limitations
206
+ or any(not isinstance(item, str) or not item.strip() for item in limitations)):
207
+ raise ValueError("timestamp not_established must be a non-empty list of descriptions")
208
+ return dict(scope), list(limitations)
209
+
210
+
211
+ def build_validation_report(gen_time: str, crl_result: dict[str, Any],
212
+ crl_result_sha256: str, ocsp_result: dict[str, Any] | None = None,
213
+ ocsp_result_sha256: str | None = None,
214
+ responder_revocation_result: dict[str, Any] | None = None,
215
+ responder_revocation_result_sha256: str | None = None,
216
+ timestamp_result: dict[str, Any] | None = None,
217
+ timestamp_result_sha256: str | None = None) -> dict[str, Any]:
218
+ gen_whole_second, gen_fraction = parse_rfc3161_gen_time(gen_time, "gen_time")
219
+ effective_second = gen_whole_second
220
+ if any(digit != "0" for digit in gen_fraction):
221
+ from datetime import timedelta
222
+ effective_second += timedelta(seconds=1)
223
+ expected_effective_at_time = effective_second.isoformat(timespec="seconds").replace("+00:00", "Z")
224
+ if crl_result.get("effective_at_time") != expected_effective_at_time:
225
+ raise ValueError("CRL effective_at_time must conservatively ceil genTime to a whole second")
226
+ if crl_result.get("time_rounding") != "ceil_to_next_whole_second_for_conservative_historical_evaluation":
227
+ raise ValueError("CRL result does not declare conservative whole-second time rounding")
228
+ expected_crl_path_validation_times = utc_unix_second_bounds(gen_time, "gen_time")
229
+ crl_path_validation_times = crl_result.get("path_validation_times")
230
+ if crl_path_validation_times != expected_crl_path_validation_times:
231
+ raise ValueError("CRL target certificate path must be checked at exact floor/ceiling Unix-second bounds")
232
+ if crl_result.get("path_validation_scope") != CRL_PATH_VALIDATION_SCOPE:
233
+ raise ValueError("CRL target certificate path-validation scope is missing or unsupported")
234
+ require_digest(crl_result_sha256, "crl_result_sha256")
235
+ if crl_result.get("verified") is not True:
236
+ raise ValueError("CRL result is not explicitly verified")
237
+ if crl_result.get("status") != "not_revoked_at_validation_time":
238
+ raise ValueError("CRL result does not assert a non-revoked status")
239
+ if crl_result.get("at_time") != gen_time:
240
+ raise ValueError("CRL validation time does not exactly match RFC 3161 genTime")
241
+ if timestamp_result is None:
242
+ raise ValueError("verified RFC 3161 timestamp result is required")
243
+ require_digest(timestamp_result_sha256, "timestamp_result_sha256")
244
+ if timestamp_result.get("verified") is not True:
245
+ raise ValueError("RFC 3161 timestamp result is not explicitly verified")
246
+ timestamp_verification_scope, timestamp_not_established = validate_timestamp_scope(timestamp_result)
247
+ if timestamp_result.get("gen_time") != gen_time:
248
+ raise ValueError("timestamp result genTime does not exactly match report genTime")
249
+ timestamp_certificate_digest = require_digest(
250
+ timestamp_result.get("tsa_signer_certificate_sha256"),
251
+ "timestamp tsa_signer_certificate_sha256",
252
+ )
253
+ # Accept only the complete, versioned output contract emitted by
254
+ # evidence_timestamp.verify_timestamp; a hand-written "verified": true
255
+ # flag without the underlying evidence identifiers is insufficient.
256
+ for field in ("signature_sha256", "request_sha256", "response_sha256", "tsa_ca_sha256"):
257
+ require_digest(timestamp_result.get(field), "timestamp " + field)
258
+ if "tsa_chain_sha256" not in timestamp_result:
259
+ raise ValueError("timestamp TSA intermediate-chain digest must be explicitly present (null when no chain was supplied)")
260
+ timestamp_chain_digest = timestamp_result.get("tsa_chain_sha256")
261
+ if timestamp_chain_digest is not None:
262
+ require_digest(timestamp_chain_digest, "timestamp tsa_chain_sha256")
263
+ for field in ("policy_oid", "serial_number", "tsa_signer_serial_number"):
264
+ value = timestamp_result.get(field)
265
+ if not isinstance(value, str) or not value.strip():
266
+ raise ValueError("timestamp " + field + " is missing or invalid")
267
+ if timestamp_result.get("verification") != (
268
+ "OpenSSL RFC 3161 CMS signature, request/response imprint, nonce (when requested), and TSA chain verification"
269
+ ):
270
+ raise ValueError("timestamp verification method provenance is missing or unsupported")
271
+ if timestamp_result.get("tsa_chain_valid_at_gen_time") is not True:
272
+ raise ValueError("timestamp TSA chain validation is not explicitly verified at genTime")
273
+ if timestamp_result.get("tsa_chain_validation_time") != gen_time:
274
+ raise ValueError("timestamp TSA chain validation time does not exactly match genTime")
275
+ if timestamp_result.get("tsa_chain_validation_scope") != (
276
+ "PKIX path validation at the floor/ceiling Unix-second bounds of genTime; RFC 3161 Accuracy is reported separately and does not widen the -attime interval"
277
+ ):
278
+ raise ValueError("timestamp TSA chain validation scope is missing or unsupported")
279
+ if timestamp_result.get("tsa_chain_validation_policy") != (
280
+ "OpenSSL ts -verify uses the caller-pinned -CAfile and explicit empty -CApath/-CAstore, -auth_level 2, -purpose timestampsign, and -x509_strict at the exact floor/ceiling Unix-second bound(s) of genTime; pathLenConstraint and Name Constraints enforced by OpenSSL"
281
+ ):
282
+ raise ValueError("timestamp TSA chain validation policy is missing or unsupported")
283
+ if type(timestamp_result.get("ordering")) is not bool or type(timestamp_result.get("nonce_present")) is not bool:
284
+ raise ValueError("timestamp ordering and nonce_present must be explicit booleans")
285
+ accuracy = timestamp_result.get("accuracy")
286
+ if accuracy is not None:
287
+ allowed_accuracy_fields = {"seconds", "millis", "micros"}
288
+ if not isinstance(accuracy, dict) or not accuracy or set(accuracy) - allowed_accuracy_fields:
289
+ raise ValueError("timestamp accuracy must be null or a non-empty RFC 3161 accuracy object")
290
+ for field, value in accuracy.items():
291
+ if type(value) is not int or value < 0:
292
+ raise ValueError("timestamp accuracy components must be non-negative integers")
293
+ if field in {"millis", "micros"} and not 1 <= value <= 999:
294
+ raise ValueError("timestamp millis and micros must be between 1 and 999")
295
+ if timestamp_result.get("tsa_signer_valid_at_gen_time") is not True:
296
+ raise ValueError("timestamp signer certificate is not established valid at genTime")
297
+ if timestamp_result.get("tsa_signer_identity_source") != "CMS SignerInfo certificate selected by OpenSSL cms -verify -signer":
298
+ raise ValueError("timestamp signer identity is not bound to the CMS SignerInfo certificate")
299
+ certificate_digest = require_digest(crl_result.get("certificate_sha256"), "CRL certificate_sha256")
300
+ if certificate_digest != timestamp_certificate_digest:
301
+ raise ValueError("CRL certificate fingerprint differs from verified timestamp CMS signer")
302
+ crl_digest = require_digest(crl_result.get("crl_sha256"), "CRL crl_sha256")
303
+ crl_roots_digest = require_digest(crl_result.get("issuer_roots_sha256"), "CRL issuer_roots_sha256")
304
+ crl_intermediates_digest = crl_result.get("issuer_intermediates_sha256")
305
+ if crl_intermediates_digest is not None:
306
+ crl_intermediates_digest = require_digest(crl_intermediates_digest, "CRL issuer_intermediates_sha256")
307
+ if crl_result.get("trust_anchor_policy") != "issuer-roots bundle contains only self-issued trust-anchor certificates; CRL issuer CA/keyCertSign/cRLSign are checked independently; intermediates are supplied separately via -untrusted":
308
+ raise ValueError("CRL trust-anchor/intermediate separation policy is missing or unsupported")
309
+ crl_signer_digest = require_digest(crl_result.get("crl_issuer_certificate_sha256"), "CRL crl_issuer_certificate_sha256")
310
+ if crl_result.get("crl_scope") != "direct_only; certificate CRLDistributionPoints unsupported":
311
+ raise ValueError("CRL result does not declare the supported strict direct-CRL scope")
312
+ if not isinstance(crl_result.get("crl_signature_algorithm_oid"), str) or not crl_result.get("crl_signature_algorithm_oid"):
313
+ raise ValueError("CRL signature algorithm identity is missing")
314
+ if crl_result.get("crl_signature_policy") != "RSA/DSA >= 2048 bits or EC >= 256 bits with SHA-256/384/512; Ed25519/Ed448 allowed":
315
+ raise ValueError("CRL signature policy evidence is missing or unsupported")
316
+ if crl_result.get("verification") != CRL_VERIFICATION_METHOD:
317
+ raise ValueError("CRL verification provenance is missing or unsupported")
318
+ crl_issuer_validity = validate_crl_issuer_validity(
319
+ crl_result.get("crl_issuer_certificate_validity"), "CRL issuer validity", gen_time)
320
+ entry = crl_result.get("revocation_entry")
321
+ if not isinstance(entry, dict) or entry.get("status_at_time") not in ("not_listed", "not_yet_revoked"):
322
+ raise ValueError("CRL entry evidence does not establish a non-revoked status at genTime")
323
+ if entry.get("present") is True and entry.get("status_at_time") != "not_yet_revoked":
324
+ raise ValueError("CRL entry presence contradicts the non-revoked assessment")
325
+ if entry.get("present") is False and entry.get("status_at_time") != "not_listed":
326
+ raise ValueError("CRL entry absence contradicts the not-listed assessment")
327
+ ocsp_section: dict[str, Any] = {
328
+ "provided": False,
329
+ "assessment": "not_provided",
330
+ "historical_status_claim": False,
331
+ }
332
+ responder_revocation_section: dict[str, Any] = {
333
+ "status": "not_assessed",
334
+ "reason": "No CRL result bound to the exact OCSP responder certificate was supplied.",
335
+ }
336
+ if ocsp_result is not None:
337
+ require_digest(ocsp_result_sha256, "ocsp_result_sha256")
338
+ if ocsp_result.get("verified") is not True:
339
+ raise ValueError("OCSP result is not explicitly verified")
340
+ scope = ocsp_result.get("scope")
341
+ current_scope = "current-time OCSP response validation; not a historical status determination"
342
+ historical_scope = "historical OCSP status validation at the supplied target time"
343
+ if scope not in (current_scope, historical_scope):
344
+ raise ValueError("OCSP result scope is missing or unsupported")
345
+ if ocsp_result.get("nonce_checked") is not False:
346
+ raise ValueError("OCSP nonce status must be explicit; this verifier currently requires nonce_checked=false")
347
+ ocsp_certificate = require_digest(ocsp_result.get("certificate_sha256"), "OCSP certificate_sha256")
348
+ if ocsp_certificate != certificate_digest:
349
+ raise ValueError("CRL and OCSP results refer to different TSA certificates")
350
+ status = ocsp_result.get("status")
351
+ if status not in ("good", "revoked", "unknown"):
352
+ raise ValueError("OCSP status must be good, revoked, or unknown")
353
+ validation_time = ocsp_result.get("validation_time")
354
+ produced_at = ocsp_result.get("produced_at")
355
+ this_update = ocsp_result.get("this_update")
356
+ next_update = ocsp_result.get("next_update")
357
+ validation_dt = parse_utc(validation_time, "OCSP validation_time")
358
+ produced_dt = parse_utc(produced_at, "OCSP produced_at")
359
+ this_dt = parse_utc(this_update, "OCSP this_update")
360
+ next_dt = parse_utc(next_update, "OCSP next_update")
361
+ if next_dt < this_dt:
362
+ raise ValueError("OCSP response time ordering is invalid")
363
+ if validation_dt < this_dt or validation_dt > next_dt:
364
+ raise ValueError("OCSP response validity interval does not cover its validation_time")
365
+ responder_chain_policy = (
366
+ "OpenSSL ocsp uses the SHA-256-pinned -CAfile, empty -CApath/-CAstore, -x509_strict, and -auth_level 2"
367
+ )
368
+ if ocsp_result.get("responder_chain_validation_policy") != responder_chain_policy:
369
+ raise ValueError("OCSP responder-chain validation policy is missing or unsupported")
370
+ responder_chain_validation_times = ocsp_result.get("responder_chain_validation_times")
371
+ if not isinstance(responder_chain_validation_times, list) or any(type(value) is not int for value in responder_chain_validation_times):
372
+ raise ValueError("OCSP responder-chain validation times must be a list of Unix-second integers")
373
+ historical_at_time = ocsp_result.get("historical_at_time")
374
+ if scope == historical_scope:
375
+ gen_whole_second, gen_fraction = parse_rfc3161_gen_time(gen_time, "gen_time")
376
+ if len(gen_fraction) > 6:
377
+ raise ValueError(
378
+ "historical OCSP cannot represent genTime with more than six fractional digits"
379
+ )
380
+ if compare_utc_values(historical_at_time, gen_time, "historical OCSP target time") != 0:
381
+ raise ValueError("historical OCSP target time does not exactly match RFC 3161 genTime")
382
+ if compare_utc_values(validation_time, gen_time, "historical OCSP validation_time") != 0:
383
+ raise ValueError("historical OCSP validation_time must exactly match RFC 3161 genTime")
384
+ if compare_utc_values(produced_at, gen_time, "historical OCSP producedAt") > 0:
385
+ raise ValueError("historical OCSP producedAt is later than RFC 3161 genTime")
386
+ if (compare_utc_values(this_update, gen_time, "historical OCSP thisUpdate") > 0
387
+ or compare_utc_values(next_update, gen_time, "historical OCSP nextUpdate") < 0):
388
+ raise ValueError("historical OCSP signed validity interval does not cover RFC 3161 genTime")
389
+ epoch = datetime(1970, 1, 1, tzinfo=gen_whole_second.tzinfo)
390
+ delta = gen_whole_second - epoch
391
+ floor_second = delta.days * 86400 + delta.seconds
392
+ has_fraction = any(digit != "0" for digit in gen_fraction)
393
+ expected_chain_times = (
394
+ [floor_second, floor_second + 1] if has_fraction else [floor_second]
395
+ )
396
+ if responder_chain_validation_times != expected_chain_times:
397
+ raise ValueError("historical OCSP responder path must be checked at floor/ceiling Unix-second bounds")
398
+ if ocsp_result.get("responder_chain_validation_scope") != (
399
+ "OpenSSL responder PKIX path validation at the exact floor/ceiling Unix-second bound(s) of historical validation_time"
400
+ ):
401
+ raise ValueError("historical OCSP responder-chain validation scope is missing or unsupported")
402
+ else:
403
+ if responder_chain_validation_times:
404
+ raise ValueError("current-time OCSP result must not claim explicit historical responder-path timestamps")
405
+ if ocsp_result.get("responder_chain_validation_scope") != (
406
+ "OpenSSL responder PKIX path validation at the host wall-clock time"
407
+ ):
408
+ raise ValueError("current-time OCSP responder-chain validation scope is missing or unsupported")
409
+ responder_digest = ocsp_result.get("responder_certificate_sha256")
410
+ if responder_digest is not None:
411
+ responder_digest = require_digest(responder_digest, "OCSP responder_certificate_sha256")
412
+ ocsp_digest = require_digest(ocsp_result.get("response_sha256"), "OCSP response_sha256")
413
+ ocsp_roots_digest = require_digest(ocsp_result.get("issuer_roots_sha256"), "OCSP issuer_roots_sha256")
414
+ ocsp_intermediates_digest = ocsp_result.get("issuer_intermediates_sha256")
415
+ if ocsp_intermediates_digest is not None:
416
+ ocsp_intermediates_digest = require_digest(
417
+ ocsp_intermediates_digest, "OCSP issuer_intermediates_sha256"
418
+ )
419
+ if ocsp_result.get("trust_anchor_policy") != (
420
+ "issuer-roots bundle is SHA-256 pinned and restricted to self-issued CA certificates "
421
+ "with critical BasicConstraints and keyCertSign; optional responder "
422
+ "certificates/intermediates are supplied separately via -verify_other"
423
+ ):
424
+ raise ValueError("OCSP trust-anchor/intermediate separation policy is missing or unsupported")
425
+ if ocsp_result.get("verification") != (
426
+ "OpenSSL OCSP response signature and responder-chain validation uses pinned -CAfile, "
427
+ "empty -CApath/-CAstore, -x509_strict, and -auth_level 2; historical validation repeats "
428
+ "path verification at exact floor/ceiling Unix-second bound(s); Python verifies exact target CertID, status, and freshness"
429
+ ):
430
+ raise ValueError("OCSP verification method provenance is missing or unsupported")
431
+ ocsp_section = {
432
+ "provided": True,
433
+ "assessment": status,
434
+ "historical_status_claim": scope == historical_scope,
435
+ "validation_time": validation_time,
436
+ "historical_at_time": historical_at_time,
437
+ "scope": scope,
438
+ "responder_chain_validation_scope": ocsp_result["responder_chain_validation_scope"],
439
+ "responder_chain_validation_times": responder_chain_validation_times,
440
+ "responder_chain_validation_policy": responder_chain_policy,
441
+ "produced_at": produced_at,
442
+ "this_update": this_update,
443
+ "next_update": next_update,
444
+ "nonce_checked": False,
445
+ "response_sha256": ocsp_digest,
446
+ "issuer_roots_sha256": ocsp_roots_digest,
447
+ "issuer_intermediates_sha256": ocsp_intermediates_digest,
448
+ "trust_anchor_policy": ocsp_result["trust_anchor_policy"],
449
+ "verification": ocsp_result["verification"],
450
+ "responder_certificate_sha256": responder_digest,
451
+ "result_file_sha256": ocsp_result_sha256,
452
+ }
453
+ if responder_revocation_result is not None:
454
+ if ocsp_result is None or scope != historical_scope:
455
+ raise ValueError("responder revocation evidence requires historical OCSP result")
456
+ if responder_digest is None:
457
+ raise ValueError("OCSP result does not bind an explicit responder certificate fingerprint")
458
+ require_digest(responder_revocation_result_sha256, "responder_revocation_result_sha256")
459
+ if responder_revocation_result.get("verified") is not True:
460
+ raise ValueError("OCSP responder CRL result is not explicitly verified")
461
+ if responder_revocation_result.get("status") != "not_revoked_at_validation_time":
462
+ raise ValueError("OCSP responder CRL result does not assert non-revocation")
463
+ if responder_revocation_result.get("crl_scope") != "direct_only; certificate CRLDistributionPoints unsupported":
464
+ raise ValueError("OCSP responder CRL result does not declare the supported strict direct-CRL scope")
465
+ responder_crl_issuer_digest = require_digest(
466
+ responder_revocation_result.get("crl_issuer_certificate_sha256"),
467
+ "responder CRL issuer certificate SHA-256",
468
+ )
469
+ responder_crl_algorithm = responder_revocation_result.get("crl_signature_algorithm_oid")
470
+ if not isinstance(responder_crl_algorithm, str) or not responder_crl_algorithm.strip():
471
+ raise ValueError("OCSP responder CRL signature algorithm identity is missing")
472
+ responder_crl_policy = responder_revocation_result.get("crl_signature_policy")
473
+ if responder_crl_policy != "RSA/DSA >= 2048 bits or EC >= 256 bits with SHA-256/384/512; Ed25519/Ed448 allowed":
474
+ raise ValueError("OCSP responder CRL signature policy evidence is missing or unsupported")
475
+ if responder_revocation_result.get("path_validation_times") != expected_crl_path_validation_times:
476
+ raise ValueError("OCSP responder CRL target certificate path must be checked at exact floor/ceiling Unix-second bounds")
477
+ if responder_revocation_result.get("path_validation_scope") != CRL_PATH_VALIDATION_SCOPE:
478
+ raise ValueError("OCSP responder CRL path-validation scope is missing or unsupported")
479
+ if responder_revocation_result.get("verification") != CRL_VERIFICATION_METHOD:
480
+ raise ValueError("OCSP responder CRL verification provenance is missing or unsupported")
481
+ responder_issuer_validity = validate_crl_issuer_validity(
482
+ responder_revocation_result.get("crl_issuer_certificate_validity"), "OCSP responder CRL issuer validity", gen_time)
483
+ responder_entry = responder_revocation_result.get("revocation_entry")
484
+ if not isinstance(responder_entry, dict) or responder_entry.get("status_at_time") not in ("not_listed", "not_yet_revoked"):
485
+ raise ValueError("OCSP responder CRL entry evidence does not establish non-revocation")
486
+ if responder_revocation_result.get("at_time") != gen_time:
487
+ raise ValueError("OCSP responder CRL validation time does not exactly match RFC 3161 genTime")
488
+ if require_digest(responder_revocation_result.get("certificate_sha256"), "responder CRL certificate_sha256") != responder_digest:
489
+ raise ValueError("responder CRL result refers to a different certificate than the OCSP signer")
490
+ if responder_revocation_result.get("trust_anchor_policy") != "issuer-roots bundle contains only self-issued trust-anchor certificates; CRL issuer CA/keyCertSign/cRLSign are checked independently; intermediates are supplied separately via -untrusted":
491
+ raise ValueError("responder CRL trust-anchor/intermediate separation policy is missing or unsupported")
492
+ if responder_revocation_result.get("trust_anchor_policy") != "issuer-roots bundle contains only self-issued trust-anchor certificates; CRL issuer CA/keyCertSign/cRLSign are checked independently; intermediates are supplied separately via -untrusted":
493
+ raise ValueError("responder CRL trust-anchor/intermediate separation policy is missing or unsupported")
494
+ responder_revocation_section = {
495
+ "status": "not_revoked_at_gen_time",
496
+ "validation_time": gen_time,
497
+ "path_validation_times": responder_revocation_result["path_validation_times"],
498
+ "path_validation_scope": responder_revocation_result["path_validation_scope"],
499
+ "responder_certificate_sha256": responder_digest,
500
+ "crl_sha256": require_digest(responder_revocation_result.get("crl_sha256"), "responder CRL crl_sha256"),
501
+ "issuer_roots_sha256": require_digest(responder_revocation_result.get("issuer_roots_sha256"), "responder CRL issuer_roots_sha256"),
502
+ "issuer_intermediates_sha256": (require_digest(responder_revocation_result.get("issuer_intermediates_sha256"), "responder CRL issuer_intermediates_sha256") if responder_revocation_result.get("issuer_intermediates_sha256") is not None else None),
503
+ "trust_anchor_policy": responder_revocation_result.get("trust_anchor_policy"),
504
+ "crl_issuer_certificate_sha256": responder_crl_issuer_digest,
505
+ "crl_issuer_certificate_validity": responder_issuer_validity,
506
+ "crl_signature_algorithm_oid": responder_crl_algorithm,
507
+ "crl_signature_policy": responder_crl_policy,
508
+ "revocation_entry": responder_entry,
509
+ "verification": responder_revocation_result["verification"],
510
+ "result_file_sha256": responder_revocation_result_sha256,
511
+ }
512
+ overall_assessment = _build_overall_assessment(ocsp_section)
513
+ return {
514
+ "schema_version": 1,
515
+ "report_type": "tsa_long_term_validation_evidence",
516
+ "gen_time": gen_time,
517
+ "gen_time_source": "caller_asserted_from_external_timestamp_verification",
518
+ "gen_time_provenance": {
519
+ "source": "caller_supplied_gen_time_argument",
520
+ "independently_verified_by_this_report": False,
521
+ },
522
+ "tsa_certificate_sha256": certificate_digest,
523
+ "timestamp_result_sha256": timestamp_result_sha256,
524
+ "timestamp_verification_scope": timestamp_verification_scope,
525
+ "timestamp_chain_validation": {
526
+ "status": "verified",
527
+ "validation_time": timestamp_result["tsa_chain_validation_time"],
528
+ "scope": timestamp_result["tsa_chain_validation_scope"],
529
+ "policy": timestamp_result["tsa_chain_validation_policy"],
530
+ "intermediates_sha256": timestamp_chain_digest,
531
+ },
532
+ "timestamp_not_established": timestamp_not_established,
533
+ "result_digest_policy": "caller_supplied_sha256_pins_checked_for_byte_equality_only",
534
+ "result_digest_pin_provenance": {
535
+ "source": "caller_supplied_command_line_arguments",
536
+ "independently_authenticated_by_this_report": False,
537
+ },
538
+ "timestamp_signer_serial_number": timestamp_result.get("tsa_signer_serial_number"),
539
+ "historical_revocation_assessment": {
540
+ "source": "verified_crl",
541
+ "status": "not_revoked_at_gen_time",
542
+ "claim_scope": {
543
+ "meaning": "The target certificate was not listed as revoked in the single supplied, verified direct CRL at genTime.",
544
+ "crl_coverage": "supplied_crl_only",
545
+ "distribution_points": "not_evaluated",
546
+ "all_applicable_crl_sources": "not_established",
547
+ "all_chain_certificates": "not_assessed",
548
+ "complete_revocation_status": False,
549
+ },
550
+ "validation_time": gen_time,
551
+ "evaluation_time_upper_bound": expected_effective_at_time,
552
+ "path_validation_times": crl_path_validation_times,
553
+ "path_validation_scope": crl_result["path_validation_scope"],
554
+ "crl_sha256": crl_digest,
555
+ "issuer_roots_sha256": crl_roots_digest,
556
+ "issuer_intermediates_sha256": crl_intermediates_digest,
557
+ "trust_anchor_policy": crl_result["trust_anchor_policy"],
558
+ "crl_issuer_certificate_sha256": crl_signer_digest,
559
+ "crl_issuer_certificate_validity": crl_issuer_validity,
560
+ "crl_signature_algorithm_oid": crl_result["crl_signature_algorithm_oid"],
561
+ "crl_signature_policy": crl_result["crl_signature_policy"],
562
+ "verification": crl_result["verification"],
563
+ "revocation_entry": entry,
564
+ "result_file_sha256": crl_result_sha256,
565
+ },
566
+ "current_ocsp_assessment": ocsp_section,
567
+ "historical_ocsp_responder_revocation_assessment": responder_revocation_section,
568
+ "overall_assessment": overall_assessment,
569
+ "limitations": _build_limitations(ocsp_section, responder_revocation_section) + timestamp_not_established,
570
+ }
571
+
572
+ def write_report(output: Path, report: dict[str, Any]) -> str:
573
+ encoded = (json.dumps(report, sort_keys=True, separators=(",", ":"), ensure_ascii=False) + "\n").encode("utf-8")
574
+ with output.open("xb") as stream:
575
+ stream.write(encoded)
576
+ return hashlib.sha256(encoded).hexdigest()
577
+
578
+ def main() -> int:
579
+ parser = argparse.ArgumentParser(description=__doc__)
580
+ parser.add_argument("--gen-time", required=True,
581
+ help="caller-asserted UTC genTime; obtain it from an independently verified RFC 3161 token")
582
+ parser.add_argument("--timestamp-result", type=Path, required=True)
583
+ parser.add_argument("--timestamp-result-sha256", required=True,
584
+ help="caller-supplied SHA-256 pin for timestamp result JSON; pin provenance is not authenticated here")
585
+ parser.add_argument("--crl-result", type=Path, required=True)
586
+ parser.add_argument("--crl-result-sha256", required=True,
587
+ help="caller-supplied SHA-256 pin for CRL result JSON; pin provenance is not authenticated here")
588
+ parser.add_argument("--ocsp-result", type=Path)
589
+ parser.add_argument("--ocsp-result-sha256",
590
+ help="caller-supplied SHA-256 pin for OCSP result JSON; pin provenance is not authenticated here")
591
+ parser.add_argument("--ocsp-responder-revocation-result", type=Path)
592
+ parser.add_argument("--ocsp-responder-revocation-result-sha256",
593
+ help="caller-supplied SHA-256 pin for responder CRL result JSON; pin provenance is not authenticated here")
594
+ parser.add_argument("--output", type=Path, required=True)
595
+ args = parser.parse_args()
596
+ try:
597
+ if bool(args.ocsp_result) != bool(args.ocsp_result_sha256):
598
+ raise ValueError("--ocsp-result and --ocsp-result-sha256 must be supplied together")
599
+ if bool(args.ocsp_responder_revocation_result) != bool(args.ocsp_responder_revocation_result_sha256):
600
+ raise ValueError("--ocsp-responder-revocation-result and its SHA-256 pin must be supplied together")
601
+ timestamp_result, timestamp_digest = load_json(args.timestamp_result, args.timestamp_result_sha256)
602
+ crl_result, crl_digest = load_json(args.crl_result, args.crl_result_sha256)
603
+ if args.ocsp_result:
604
+ ocsp_result, ocsp_digest = load_json(args.ocsp_result, args.ocsp_result_sha256)
605
+ else:
606
+ ocsp_result, ocsp_digest = None, None
607
+ if args.ocsp_responder_revocation_result:
608
+ responder_result, responder_digest = load_json(
609
+ args.ocsp_responder_revocation_result, args.ocsp_responder_revocation_result_sha256)
610
+ else:
611
+ responder_result, responder_digest = None, None
612
+ report = build_validation_report(args.gen_time, crl_result, crl_digest,
613
+ ocsp_result, ocsp_digest, responder_result, responder_digest,
614
+ timestamp_result, timestamp_digest)
615
+ report_digest = write_report(args.output, report)
616
+ except (OSError, UnicodeError, json.JSONDecodeError, ValueError, TypeError) as exc:
617
+ print("ERROR: " + str(exc), file=sys.stderr)
618
+ return 1
619
+ print(json.dumps({"created": True, "report_sha256": report_digest,
620
+ "historical_status": report["historical_revocation_assessment"]["status"],
621
+ "ocsp_assessment": report["current_ocsp_assessment"]["assessment"],
622
+ "ocsp_responder_revocation": report["historical_ocsp_responder_revocation_assessment"]["status"]},
623
+ sort_keys=True, indent=2))
624
+ return 0
625
+
626
+ if __name__ == "__main__":
627
+ raise SystemExit(main())