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,782 @@
1
+ """Verify historical certificate status against one constrained direct CRL."""
2
+ from __future__ import annotations
3
+
4
+ import argparse
5
+ import base64
6
+ import hashlib
7
+ import json
8
+ import os
9
+ import re
10
+ import stat
11
+ import shutil
12
+ import subprocess
13
+ import sys
14
+ import tempfile
15
+ from datetime import datetime, timezone
16
+ from pathlib import Path
17
+ from typing import Any
18
+
19
+ from cryptography import x509
20
+ from cryptography.hazmat.primitives import hashes, serialization
21
+ from cryptography.hazmat.primitives.asymmetric import dsa, ec, ed25519, ed448, rsa
22
+ from cryptography.x509.oid import CRLEntryExtensionOID, ExtensionOID
23
+
24
+ HEX256 = re.compile(r"^[0-9a-f]{64}$")
25
+ UTC = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$")
26
+
27
+
28
+ def parse_utc_epoch_bounds(value: str) -> tuple[int, ...]:
29
+ """Return exact floor/ceiling Unix-second bounds for a UTC historical instant."""
30
+ if not isinstance(value, str) or not UTC.fullmatch(value):
31
+ raise ValueError("at-time must be an RFC 3339 UTC timestamp ending in Z")
32
+ try:
33
+ parsed = datetime.fromisoformat(value[:-1] + "+00:00")
34
+ except ValueError as exc:
35
+ raise ValueError("at-time is not a valid UTC timestamp") from exc
36
+ whole_second = parsed.replace(microsecond=0)
37
+ delta = whole_second - datetime(1970, 1, 1, tzinfo=timezone.utc)
38
+ floor_second = delta.days * 86400 + delta.seconds
39
+ fraction = re.search(r"\.(\d+)Z$", value)
40
+ has_fractional_time = fraction is not None and any(digit != "0" for digit in fraction.group(1))
41
+ return (floor_second, floor_second + 1) if has_fractional_time else (floor_second,)
42
+
43
+
44
+ def parse_utc_epoch(value: str) -> int:
45
+ """Return the conservative ceiling second used for CRL status evaluation."""
46
+ return parse_utc_epoch_bounds(value)[-1]
47
+
48
+
49
+ def load_certificates(path: Path) -> list[x509.Certificate]:
50
+ raw = path.read_bytes()
51
+ # OpenSSL -CAfile also accepts PEM trusted-certificate blocks with auxiliary
52
+ # trust attributes. cryptography's ordinary PEM loader does not expose those
53
+ # attributes, so accepting such blocks would make the preflight's certificate
54
+ # set differ from the trust store OpenSSL actually uses.
55
+ if b"-----BEGIN TRUSTED CERTIFICATE-----" in raw:
56
+ raise ValueError("trust-anchor bundle must not contain TRUSTED CERTIFICATE PEM blocks")
57
+ blocks = re.findall(rb"-----BEGIN CERTIFICATE-----.*?-----END CERTIFICATE-----", raw, re.DOTALL)
58
+ if blocks:
59
+ return [x509.load_pem_x509_certificate(block) for block in blocks]
60
+ try:
61
+ return [x509.load_der_x509_certificate(raw)]
62
+ except ValueError as exc:
63
+ raise ValueError(f"no parseable certificate found in {path}") from exc
64
+
65
+
66
+
67
+ def validate_trust_anchor_bundle(certificates: list[x509.Certificate]) -> None:
68
+ """Keep OpenSSL's -CAfile restricted to explicitly self-issued CA anchors."""
69
+ if not certificates:
70
+ raise ValueError("trust-anchor bundle must contain at least one certificate")
71
+ seen = set()
72
+ for certificate in certificates:
73
+ fingerprint = certificate.fingerprint(hashes.SHA256())
74
+ if fingerprint in seen:
75
+ raise ValueError("trust-anchor bundle contains a duplicate certificate")
76
+ seen.add(fingerprint)
77
+ if certificate.subject != certificate.issuer:
78
+ raise ValueError("trust-anchor bundle may contain only self-issued certificates; place intermediates in --intermediates")
79
+ try:
80
+ constraints = certificate.extensions.get_extension_for_oid(ExtensionOID.BASIC_CONSTRAINTS)
81
+ except x509.ExtensionNotFound as exc:
82
+ raise ValueError("trust-anchor certificate lacks basicConstraints CA authorization") from exc
83
+ if not constraints.critical or not constraints.value.ca:
84
+ raise ValueError("trust-anchor certificate must have critical basicConstraints with CA=true")
85
+ try:
86
+ usage = certificate.extensions.get_extension_for_oid(ExtensionOID.KEY_USAGE)
87
+ except x509.ExtensionNotFound as exc:
88
+ raise ValueError("trust-anchor certificate lacks explicit keyUsage with keyCertSign") from exc
89
+ if not usage.critical or not usage.value.key_cert_sign:
90
+ raise ValueError("trust-anchor certificate must have critical keyUsage with keyCertSign")
91
+ try:
92
+ ski = certificate.extensions.get_extension_for_oid(ExtensionOID.SUBJECT_KEY_IDENTIFIER)
93
+ except x509.ExtensionNotFound as exc:
94
+ raise ValueError("trust-anchor CA certificate lacks subjectKeyIdentifier") from exc
95
+ if ski.critical:
96
+ raise ValueError("trust-anchor subjectKeyIdentifier must be non-critical")
97
+
98
+ def validate_crl_number_value(value: int) -> None:
99
+ """Enforce the ASN.1 CRLNumber INTEGER lower bound independently of parsing."""
100
+ if value < 0:
101
+ raise ValueError("CRLNumber must be a non-negative integer")
102
+
103
+
104
+ def _read_der_tlv(data: bytes, offset: int) -> tuple[int, int, int, int]:
105
+ """Return tag, value start, value end, and next offset for one definite-length DER TLV."""
106
+ if offset >= len(data):
107
+ raise ValueError("truncated DER value")
108
+ tag = data[offset]
109
+ cursor = offset + 1
110
+ if cursor >= len(data):
111
+ raise ValueError("truncated DER length")
112
+ first_length = data[cursor]
113
+ cursor += 1
114
+ if first_length < 0x80:
115
+ length = first_length
116
+ else:
117
+ count = first_length & 0x7F
118
+ if count == 0 or count > 4 or cursor + count > len(data):
119
+ raise ValueError("invalid DER length")
120
+ if data[cursor] == 0:
121
+ raise ValueError("non-minimal DER length")
122
+ length = int.from_bytes(data[cursor:cursor + count], "big")
123
+ if length < 0x80:
124
+ raise ValueError("non-minimal DER length")
125
+ cursor += count
126
+ end = cursor + length
127
+ if end > len(data):
128
+ raise ValueError("truncated DER value")
129
+ return tag, cursor, end, end
130
+
131
+
132
+
133
+ def _validate_crl_time_der(tag: int, encoded: bytes, field: str) -> None:
134
+ """Require canonical RFC 5280 UTC syntax and a valid calendar date."""
135
+ if tag == 0x17 and re.fullmatch(rb"[0-9]{12}Z", encoded):
136
+ year = int(encoded[:2])
137
+ year += 2000 if year <= 49 else 1900
138
+ value = f"{year:04d}".encode("ascii") + encoded[2:-1]
139
+ elif tag == 0x18 and re.fullmatch(rb"[0-9]{14}Z", encoded):
140
+ value = encoded[:-1]
141
+ else:
142
+ raise ValueError(
143
+ f"{field} must use UTC time with seconds and a trailing Z; GeneralizedTime must not use fractional seconds"
144
+ )
145
+ # datetime.strptime() rejects year 0000, while OpenSSL's ASN1_TIME
146
+ # representation supports GeneralizedTime years 0000 through 9999.
147
+ digits = value.decode("ascii")
148
+ year, month, day = int(digits[0:4]), int(digits[4:6]), int(digits[6:8])
149
+ hour, minute, second = int(digits[8:10]), int(digits[10:12]), int(digits[12:14])
150
+ leap_year = year % 4 == 0 and (year % 100 != 0 or year % 400 == 0)
151
+ month_days = (31, 29 if leap_year else 28, 31, 30, 31, 30,
152
+ 31, 31, 30, 31, 30, 31)
153
+ if not (
154
+ 1 <= month <= 12
155
+ and 1 <= day <= month_days[month - 1]
156
+ and 0 <= hour <= 23
157
+ and 0 <= minute <= 59
158
+ and 0 <= second <= 59
159
+ ):
160
+ raise ValueError(f"{field} must contain a valid calendar date and time")
161
+
162
+
163
+ def validate_invalidity_date_der_encoding(raw: bytes, tbs_start: int, tbs_end: int) -> None:
164
+ """Validate original DER time encodings in CRL fields and entry extensions."""
165
+ def read_child(offset: int, parent_end: int) -> tuple[int, int, int, int]:
166
+ tag, value_start, value_end, next_offset = _read_der_tlv(raw, offset)
167
+ if next_offset > parent_end:
168
+ raise ValueError("DER child exceeds its enclosing CRL structure")
169
+ return tag, value_start, value_end, next_offset
170
+
171
+ cursor = tbs_start
172
+ tag, _, _, next_cursor = read_child(cursor, tbs_end)
173
+ if tag == 0x02: # optional v2 version
174
+ cursor = next_cursor
175
+ for expected in (0x30, 0x30): # signature and issuer
176
+ tag, _, _, cursor = read_child(cursor, tbs_end)
177
+ if tag != expected:
178
+ raise ValueError("malformed TBSCertList while locating CRL times")
179
+ time_tag, time_start, time_end, cursor = read_child(cursor, tbs_end)
180
+ _validate_crl_time_der(time_tag, raw[time_start:time_end], "thisUpdate")
181
+
182
+ # nextUpdate is optional in ASN.1, though RFC 5280 profile issuers must include it.
183
+ if cursor < tbs_end:
184
+ tag, value_start, value_end, next_cursor = read_child(cursor, tbs_end)
185
+ if tag in (0x17, 0x18):
186
+ _validate_crl_time_der(tag, raw[value_start:value_end], "nextUpdate")
187
+ cursor = next_cursor
188
+
189
+ # revokedCertificates is optional and precedes [0] EXPLICIT crlExtensions.
190
+ if cursor >= tbs_end:
191
+ return
192
+ tag, entries_start, entries_end, entries_next = read_child(cursor, tbs_end)
193
+ if tag != 0x30:
194
+ return
195
+ entry_cursor = entries_start
196
+ while entry_cursor < entries_end:
197
+ entry_tag, entry_start, entry_end, entry_next = read_child(entry_cursor, entries_end)
198
+ if entry_tag != 0x30:
199
+ raise ValueError("malformed revokedCertificates entry")
200
+ field_cursor = entry_start
201
+ serial_tag, _, _, field_cursor = read_child(field_cursor, entry_end)
202
+ date_tag, date_start, date_end, field_cursor = read_child(field_cursor, entry_end)
203
+ if serial_tag != 0x02:
204
+ raise ValueError("malformed CRL entry serial number")
205
+ _validate_crl_time_der(date_tag, raw[date_start:date_end], "revocationDate")
206
+
207
+ if field_cursor < entry_end:
208
+ extensions_tag, extensions_start, extensions_end, extensions_next = read_child(field_cursor, entry_end)
209
+ if extensions_tag != 0x30 or extensions_next != entry_end:
210
+ raise ValueError("malformed CRL entry extensions")
211
+ extension_cursor = extensions_start
212
+ while extension_cursor < extensions_end:
213
+ ext_tag, ext_start, ext_end, ext_next = read_child(extension_cursor, extensions_end)
214
+ if ext_tag != 0x30:
215
+ raise ValueError("malformed CRL entry extension")
216
+ oid_tag, oid_start, oid_end, ext_field = read_child(ext_start, ext_end)
217
+ if oid_tag != 0x06:
218
+ raise ValueError("malformed CRL entry extension OID")
219
+ oid = raw[oid_start:oid_end]
220
+ if ext_field < ext_end:
221
+ maybe_tag, _, _, maybe_next = read_child(ext_field, ext_end)
222
+ if maybe_tag == 0x01:
223
+ ext_field = maybe_next
224
+ value_tag, value_start, value_end, value_next = read_child(ext_field, ext_end)
225
+ if value_tag != 0x04 or value_next != ext_end:
226
+ raise ValueError("malformed CRL entry extension value")
227
+ if oid == b"\x55\x1d\x18":
228
+ time_tag, time_start, time_end, time_next = read_child(value_start, value_end)
229
+ if time_next != value_end or time_tag != 0x18:
230
+ raise ValueError("invalidityDate must be a single GeneralizedTime value")
231
+ try:
232
+ _validate_crl_time_der(time_tag, raw[time_start:time_end], "invalidityDate")
233
+ except ValueError as exc:
234
+ raise ValueError(
235
+ "invalidityDate must be GeneralizedTime with UTC seconds and a trailing Z, without fractions"
236
+ ) from exc
237
+ extension_cursor = ext_next
238
+ entry_cursor = entry_next
239
+
240
+ def validate_crl_der_profile(raw: bytes, crl: x509.CertificateRevocationList) -> None:
241
+ """Enforce RFC 5280 CRL version and inner/outer signature AlgorithmIdentifier equality."""
242
+ tag, outer_start, outer_end, outer_next = _read_der_tlv(raw, 0)
243
+ if tag != 0x30 or outer_next != len(raw):
244
+ raise ValueError("CRL DER must be one complete SEQUENCE")
245
+ tbs_tag, tbs_start, tbs_end, tbs_next = _read_der_tlv(raw, outer_start)
246
+ if tbs_tag != 0x30 or tbs_next > outer_end:
247
+ raise ValueError("CRL DER lacks a bounded TBSCertList SEQUENCE")
248
+ validate_invalidity_date_der_encoding(raw, tbs_start, tbs_end)
249
+ cursor = tbs_start
250
+ first_tag, first_start, first_end, first_next = _read_der_tlv(raw, cursor)
251
+ if first_next > tbs_end:
252
+ raise ValueError("TBSCertList field exceeds its enclosing SEQUENCE")
253
+ version_present = first_tag == 0x02
254
+ if version_present:
255
+ if raw[first_start:first_end] != b"\x01":
256
+ raise ValueError("CRL version must be v2")
257
+ cursor = first_next
258
+ inner_tag, inner_start, inner_end, inner_next = _read_der_tlv(raw, cursor)
259
+ if inner_tag != 0x30 or inner_next > tbs_end:
260
+ raise ValueError("TBSCertList lacks a bounded signature AlgorithmIdentifier")
261
+ outer_alg_tag, outer_alg_start, outer_alg_end, outer_alg_next = _read_der_tlv(raw, tbs_next)
262
+ if outer_alg_tag != 0x30 or outer_alg_next > outer_end:
263
+ raise ValueError("CertificateList lacks a bounded signatureAlgorithm")
264
+ signature_tag, signature_start, signature_end, signature_next = _read_der_tlv(raw, outer_alg_next)
265
+ if signature_tag != 0x03 or signature_next != outer_end:
266
+ raise ValueError("CertificateList lacks a complete signature BIT STRING")
267
+ signature_bits = raw[signature_start:signature_end]
268
+ if not signature_bits or signature_bits[0] > 7:
269
+ raise ValueError("CRL signature BIT STRING has an invalid unused-bit count")
270
+ unused_bits = signature_bits[0]
271
+ if len(signature_bits) == 1 and unused_bits:
272
+ raise ValueError("empty CRL signature BIT STRING must have zero unused bits")
273
+ if unused_bits and signature_bits[-1] & ((1 << unused_bits) - 1):
274
+ raise ValueError("CRL signature BIT STRING has nonzero padding bits")
275
+ if raw[cursor:inner_next] != raw[tbs_next:outer_alg_next]:
276
+ raise ValueError("CRL inner and outer signature AlgorithmIdentifiers must match exactly")
277
+ has_extensions = bool(crl.extensions) or any(bool(entry.extensions) for entry in crl)
278
+ if has_extensions and not version_present:
279
+ raise ValueError("CRL extensions require an explicit v2 version")
280
+
281
+
282
+ def load_crl(path: Path) -> x509.CertificateRevocationList:
283
+ raw = path.read_bytes()
284
+ pem_match = re.fullmatch(
285
+ rb"\s*-----BEGIN X509 CRL-----\s*(.*?)\s*-----END X509 CRL-----\s*",
286
+ raw, re.DOTALL,
287
+ )
288
+ if pem_match:
289
+ try:
290
+ der = base64.b64decode(re.sub(rb"\s+", b"", pem_match.group(1)), validate=True)
291
+ crl = x509.load_pem_x509_crl(raw)
292
+ except (ValueError, base64.binascii.Error) as exc:
293
+ raise ValueError("CRL must be a parseable PEM or DER X.509 CRL") from exc
294
+ else:
295
+ der = raw
296
+ try:
297
+ crl = x509.load_der_x509_crl(raw)
298
+ except ValueError as exc:
299
+ raise ValueError("CRL must be a parseable PEM or DER X.509 CRL") from exc
300
+ validate_crl_der_profile(der, crl)
301
+ return crl
302
+
303
+
304
+
305
+ def validate_crl_signature_policy(crl: x509.CertificateRevocationList, signer: x509.Certificate) -> str:
306
+ """Apply a modern algorithm/key-strength floor; OpenSSL still verifies the signature."""
307
+ public_key = signer.public_key()
308
+ algorithm = crl.signature_hash_algorithm
309
+ if isinstance(public_key, rsa.RSAPublicKey):
310
+ if public_key.key_size < 2048:
311
+ raise ValueError("CRL RSA signing key must be at least 2048 bits")
312
+ if algorithm is None or algorithm.name.lower() not in {"sha256", "sha384", "sha512"}:
313
+ raise ValueError("CRL RSA signature must use SHA-256, SHA-384, or SHA-512")
314
+ elif isinstance(public_key, ec.EllipticCurvePublicKey):
315
+ if public_key.key_size < 256:
316
+ raise ValueError("CRL elliptic-curve signing key must be at least 256 bits")
317
+ if algorithm is None or algorithm.name.lower() not in {"sha256", "sha384", "sha512"}:
318
+ raise ValueError("CRL ECDSA signature must use SHA-256, SHA-384, or SHA-512")
319
+ elif isinstance(public_key, dsa.DSAPublicKey):
320
+ if public_key.key_size < 2048:
321
+ raise ValueError("CRL DSA signing key must be at least 2048 bits")
322
+ if algorithm is None or algorithm.name.lower() not in {"sha256", "sha384", "sha512"}:
323
+ raise ValueError("CRL DSA signature must use SHA-256, SHA-384, or SHA-512")
324
+ elif isinstance(public_key, (ed25519.Ed25519PublicKey, ed448.Ed448PublicKey)):
325
+ if algorithm is not None:
326
+ raise ValueError("EdDSA CRL signatures must use the algorithm's intrinsic hash")
327
+ else:
328
+ raise ValueError("unsupported CRL issuer public-key algorithm")
329
+ return crl.signature_algorithm_oid.dotted_string
330
+
331
+
332
+ def assess_crl_entry(certificate: x509.Certificate, crl: x509.CertificateRevocationList,
333
+ at_time: datetime) -> dict[str, Any]:
334
+ """Interpret the target serial's CRL entry conservatively at a historical instant."""
335
+ for entry in crl:
336
+ try:
337
+ entry.extensions.get_extension_for_oid(CRLEntryExtensionOID.CERTIFICATE_ISSUER)
338
+ except x509.ExtensionNotFound:
339
+ continue
340
+ raise ValueError("certificateIssuer CRL entries require indirect-CRL processing, which is unsupported")
341
+ matches = [entry for entry in crl if entry.serial_number == certificate.serial_number]
342
+ if len(matches) > 1:
343
+ raise ValueError("CRL contains duplicate entries for the target certificate serial number")
344
+ if not matches:
345
+ return {"present": False, "status_at_time": "not_listed"}
346
+ entry = matches[0]
347
+ known = {"2.5.29.21", "2.5.29.24"}
348
+ for extension in entry.extensions:
349
+ if extension.critical and extension.oid.dotted_string not in known:
350
+ raise ValueError("CRL entry contains an unsupported critical extension: " + extension.oid.dotted_string)
351
+ reason = "unspecified"
352
+ try:
353
+ ext = entry.extensions.get_extension_for_class(x509.CRLReason)
354
+ if ext.critical:
355
+ raise ValueError("CRL reasonCode must be non-critical")
356
+ reason = ext.value.reason.name
357
+ except x509.ExtensionNotFound:
358
+ pass
359
+ if reason == "remove_from_crl":
360
+ raise ValueError("removeFromCRL is invalid in the supported complete-CRL-only profile")
361
+ allowed = {"unspecified", "key_compromise", "ca_compromise", "affiliation_changed",
362
+ "superseded", "cessation_of_operation", "certificate_hold",
363
+ "privilege_withdrawn", "aa_compromise"}
364
+ if reason not in allowed:
365
+ raise ValueError("CRL entry contains an unsupported reasonCode")
366
+ revoked_at = entry.revocation_date_utc
367
+ invalidity = None
368
+ try:
369
+ ext = entry.extensions.get_extension_for_class(x509.InvalidityDate)
370
+ if ext.critical:
371
+ raise ValueError("invalidityDate must be non-critical")
372
+ invalidity = ext.value.invalidity_date_utc
373
+ except x509.ExtensionNotFound:
374
+ pass
375
+ effective = min(revoked_at, invalidity) if invalidity is not None else revoked_at
376
+ effective = effective if effective.tzinfo is not None else effective.replace(tzinfo=timezone.utc)
377
+ revoked_at = revoked_at if revoked_at.tzinfo is not None else revoked_at.replace(tzinfo=timezone.utc)
378
+ invalidity = invalidity if invalidity is None or invalidity.tzinfo is not None else invalidity.replace(tzinfo=timezone.utc)
379
+ return {
380
+ "present": True, "reason": reason,
381
+ "revocation_date": revoked_at.isoformat().replace("+00:00", "Z"),
382
+ "invalidity_date": invalidity.isoformat().replace("+00:00", "Z") if invalidity else None,
383
+ "effective_revocation_date": effective.isoformat().replace("+00:00", "Z"),
384
+ "status_at_time": "revoked" if effective <= at_time else "not_yet_revoked",
385
+ "historical_rule": "earlier_of_revocationDate_and_invalidityDate_when_present",
386
+ }
387
+
388
+
389
+ def validate_direct_crl_scope(
390
+ certificate: x509.Certificate,
391
+ issuer_certificates: list[x509.Certificate],
392
+ crl: x509.CertificateRevocationList,
393
+ target_time: datetime,
394
+ evaluation_time: datetime,
395
+ ) -> tuple[str, dict[str, Any]]:
396
+ """Validate supported CRL applicability; OpenSSL subsequently verifies signatures/path."""
397
+ if certificate.issuer != crl.issuer:
398
+ raise ValueError("CRL issuer does not match certificate issuer")
399
+
400
+ if any(ext.oid == ExtensionOID.DELTA_CRL_INDICATOR for ext in crl.extensions):
401
+ raise ValueError("delta CRLs are unsupported")
402
+
403
+ try:
404
+ idp_ext = crl.extensions.get_extension_for_oid(ExtensionOID.ISSUING_DISTRIBUTION_POINT)
405
+ except x509.ExtensionNotFound:
406
+ idp_ext = None
407
+ idp = idp_ext.value if idp_ext is not None else None
408
+ if idp is not None:
409
+ if not idp_ext.critical:
410
+ raise ValueError("IssuingDistributionPoint must be critical")
411
+ if not any((idp.full_name is not None, idp.relative_name is not None,
412
+ idp.only_contains_user_certs, idp.only_contains_ca_certs,
413
+ idp.only_some_reasons is not None, idp.indirect_crl,
414
+ idp.only_contains_attribute_certs)):
415
+ raise ValueError("IssuingDistributionPoint must not be an empty scope")
416
+ if idp.indirect_crl:
417
+ raise ValueError("indirect CRLs are unsupported")
418
+ if idp.full_name is not None or idp.relative_name is not None:
419
+ raise ValueError("named issuing distribution points are unsupported")
420
+ if idp.only_some_reasons is not None:
421
+ raise ValueError("partial-reason CRL scope is unsupported")
422
+ try:
423
+ is_ca = certificate.extensions.get_extension_for_oid(ExtensionOID.BASIC_CONSTRAINTS).value.ca
424
+ except x509.ExtensionNotFound:
425
+ is_ca = False
426
+ if idp.only_contains_attribute_certs:
427
+ raise ValueError("attribute-certificate CRLs cannot cover an X.509 public-key certificate")
428
+ if (idp.only_contains_user_certs or idp.only_contains_ca_certs) and certificate.version != x509.Version.v3:
429
+ raise ValueError("user-only or CA-only CRL scopes cannot cover X.509 v1/v2 certificates")
430
+ if idp.only_contains_ca_certs and not is_ca:
431
+ raise ValueError("CRL scope excludes end-entity certificates")
432
+ if idp.only_contains_user_certs and is_ca:
433
+ raise ValueError("CRL scope excludes CA certificates")
434
+
435
+ try:
436
+ certificate.extensions.get_extension_for_oid(ExtensionOID.CRL_DISTRIBUTION_POINTS)
437
+ except x509.ExtensionNotFound:
438
+ pass
439
+ else:
440
+ raise ValueError("certificate CRLDistributionPoints matching is unsupported")
441
+
442
+ try:
443
+ aki_ext = crl.extensions.get_extension_for_oid(ExtensionOID.AUTHORITY_KEY_IDENTIFIER)
444
+ except x509.ExtensionNotFound as exc:
445
+ raise ValueError("CRL lacks the mandatory AuthorityKeyIdentifier extension") from exc
446
+ aki = aki_ext.value
447
+ if aki.key_identifier is None:
448
+ raise ValueError("CRL AuthorityKeyIdentifier must use the key identifier method")
449
+
450
+ try:
451
+ crl_number_ext = crl.extensions.get_extension_for_oid(ExtensionOID.CRL_NUMBER)
452
+ except x509.ExtensionNotFound as exc:
453
+ raise ValueError("CRL lacks the mandatory CRLNumber extension") from exc
454
+ if crl_number_ext.critical:
455
+ raise ValueError("CRLNumber must be non-critical")
456
+ validate_crl_number_value(crl_number_ext.value.crl_number)
457
+
458
+ candidates = [item for item in issuer_certificates if item.subject == crl.issuer]
459
+
460
+ # Resolve the target certificate's issuer independently of the CRL AKI.
461
+ # Otherwise a CRL AKI could select an alternate cross-certificate that the
462
+ # target certificate's own path builder would not select.
463
+ try:
464
+ certificate_aki = certificate.extensions.get_extension_for_oid(
465
+ ExtensionOID.AUTHORITY_KEY_IDENTIFIER
466
+ ).value
467
+ except x509.ExtensionNotFound:
468
+ certificate_aki = None
469
+ target_issuer_candidates = list(candidates)
470
+ if certificate_aki is not None:
471
+ if certificate_aki.key_identifier is not None:
472
+ matched = []
473
+ for item in target_issuer_candidates:
474
+ try:
475
+ ski = item.extensions.get_extension_for_oid(
476
+ ExtensionOID.SUBJECT_KEY_IDENTIFIER
477
+ ).value
478
+ except x509.ExtensionNotFound:
479
+ continue
480
+ if certificate_aki.key_identifier == ski.digest:
481
+ matched.append(item)
482
+ target_issuer_candidates = matched
483
+ issuer_names = certificate_aki.authority_cert_issuer
484
+ serial = certificate_aki.authority_cert_serial_number
485
+ if (issuer_names is None) != (serial is None):
486
+ raise ValueError("certificate AKI authorityCertIssuer and authorityCertSerialNumber must appear together")
487
+ if issuer_names is not None:
488
+ directory_names = [
489
+ name.value for name in issuer_names
490
+ if isinstance(name, x509.DirectoryName)
491
+ ]
492
+ target_issuer_candidates = [
493
+ item for item in target_issuer_candidates
494
+ if item.issuer in directory_names and item.serial_number == serial
495
+ ]
496
+ if not target_issuer_candidates:
497
+ raise ValueError("target certificate AuthorityKeyIdentifier does not match any supplied issuer certificate")
498
+ if len(target_issuer_candidates) != 1:
499
+ raise ValueError("target certificate AuthorityKeyIdentifier does not uniquely identify its issuer certificate")
500
+
501
+ if aki is not None:
502
+ if aki.key_identifier is not None:
503
+ matched = []
504
+ for item in candidates:
505
+ try:
506
+ ski = item.extensions.get_extension_for_oid(ExtensionOID.SUBJECT_KEY_IDENTIFIER).value
507
+ except x509.ExtensionNotFound:
508
+ continue
509
+ if aki.key_identifier == ski.digest:
510
+ matched.append(item)
511
+ if not matched:
512
+ raise ValueError("CRL AuthorityKeyIdentifier does not match any supplied issuer SubjectKeyIdentifier")
513
+ candidates = matched
514
+ issuer_names = aki.authority_cert_issuer
515
+ serial = aki.authority_cert_serial_number
516
+ if (issuer_names is None) != (serial is None):
517
+ raise ValueError("CRL AKI authorityCertIssuer and authorityCertSerialNumber must appear together")
518
+ if issuer_names is not None:
519
+ directory_names = [name.value for name in issuer_names if isinstance(name, x509.DirectoryName)]
520
+ if len(directory_names) != 1:
521
+ raise ValueError("CRL AKI authorityCertIssuer must contain exactly one DirectoryName")
522
+ candidates = [
523
+ item for item in candidates
524
+ if item.issuer == directory_names[0] and item.serial_number == serial
525
+ ]
526
+
527
+ if certificate_aki is not None:
528
+ target_fingerprints = {
529
+ item.fingerprint(hashes.SHA256()) for item in target_issuer_candidates
530
+ }
531
+ candidates = [
532
+ item for item in candidates
533
+ if item.fingerprint(hashes.SHA256()) in target_fingerprints
534
+ ]
535
+ if not candidates:
536
+ raise ValueError("CRL issuer certificate does not match the target certificate AuthorityKeyIdentifier")
537
+ if len(candidates) != 1:
538
+ raise ValueError("CRL issuer certificate must resolve to exactly one supplied certificate after AKI matching")
539
+ signer = candidates[0]
540
+
541
+ try:
542
+ constraints_ext = signer.extensions.get_extension_for_oid(ExtensionOID.BASIC_CONSTRAINTS)
543
+ except x509.ExtensionNotFound as exc:
544
+ raise ValueError("CRL issuer certificate lacks basicConstraints CA authorization") from exc
545
+ if not constraints_ext.critical or not constraints_ext.value.ca:
546
+ raise ValueError("CRL issuer certificate must have critical basicConstraints with CA=true")
547
+ try:
548
+ key_usage = signer.extensions.get_extension_for_oid(ExtensionOID.KEY_USAGE).value
549
+ except x509.ExtensionNotFound as exc:
550
+ raise ValueError("CRL issuer certificate lacks explicit keyUsage with cRLSign") from exc
551
+ if not key_usage.crl_sign:
552
+ raise ValueError("CRL issuer certificate is not authorized for cRLSign")
553
+ if not key_usage.key_cert_sign:
554
+ raise ValueError("CRL issuer certificate is not authorized for keyCertSign")
555
+
556
+ crl_issued_at = crl.last_update_utc
557
+ issuer_not_before = signer.not_valid_before_utc
558
+ issuer_not_after = signer.not_valid_after_utc
559
+ if not issuer_not_before <= crl_issued_at <= issuer_not_after:
560
+ raise ValueError("CRL issuer certificate was not valid at CRL thisUpdate")
561
+ issuer_validity = {
562
+ "crl_this_update": crl_issued_at.isoformat(timespec="seconds").replace("+00:00", "Z"),
563
+ "not_before": issuer_not_before.isoformat(timespec="seconds").replace("+00:00", "Z"),
564
+ "not_after": issuer_not_after.isoformat(timespec="seconds").replace("+00:00", "Z"),
565
+ "valid_at_this_update": True, "basic_constraints_ca": True,
566
+ "key_cert_sign": True, "crl_sign": True,
567
+ "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",
568
+ }
569
+
570
+ if crl.last_update_utc > target_time:
571
+ raise ValueError("CRL thisUpdate is later than the historical validation time")
572
+ if crl.next_update_utc is None or crl.next_update_utc < evaluation_time:
573
+ raise ValueError("CRL nextUpdate does not cover the historical validation time")
574
+
575
+ validate_crl_signature_policy(crl, signer)
576
+ return hashlib.sha256(signer.public_bytes(serialization.Encoding.DER)).hexdigest(), issuer_validity
577
+
578
+
579
+ def _require_supported_openssl(executable: str) -> str:
580
+ """Require the CLI version that supports every verification option we use."""
581
+ result = subprocess.run(
582
+ [executable, "version"], capture_output=True, text=True, check=False,
583
+ )
584
+ detail = "\n".join(part for part in (result.stdout, result.stderr) if part).strip()
585
+ if result.returncode:
586
+ raise ValueError("unable to determine OpenSSL CLI version: " + detail[-1000:])
587
+ match = re.match(r"^OpenSSL\s+(\d+)\.(\d+)\.(\d+)\b", detail)
588
+ if match is None:
589
+ raise ValueError("OpenSSL 3.0.0 or newer is required; unrecognized version output: " + detail[-1000:])
590
+ version = tuple(int(part) for part in match.groups())
591
+ if version < (3, 0, 0):
592
+ raise ValueError("OpenSSL 3.0.0 or newer is required; found " + ".".join(match.groups()))
593
+ return ".".join(match.groups())
594
+
595
+
596
+ def _verify_crl_status_with_snapshot(
597
+ certificate: Path,
598
+ issuer_roots: Path,
599
+ crl: Path,
600
+ at_time: str,
601
+ expected_roots_sha256: str,
602
+ intermediates: Path | None = None,
603
+ expected_crl_sha256: str | None = None,
604
+ ) -> dict[str, Any]:
605
+ path_validation_times = parse_utc_epoch_bounds(at_time)
606
+ epoch = path_validation_times[-1]
607
+ target_instant = datetime.fromisoformat(at_time[:-1] + "+00:00")
608
+ instant = datetime.fromtimestamp(epoch, timezone.utc)
609
+ effective_at_time = instant.isoformat(timespec="seconds").replace("+00:00", "Z")
610
+ if not isinstance(expected_roots_sha256, str) or not HEX256.fullmatch(expected_roots_sha256):
611
+ raise ValueError("expected issuer-root SHA-256 must be 64 lowercase hex characters")
612
+
613
+ roots_bytes = issuer_roots.read_bytes()
614
+ roots_digest = hashlib.sha256(roots_bytes).hexdigest()
615
+ if roots_digest != expected_roots_sha256:
616
+ raise ValueError("issuer-root bundle SHA-256 pin mismatch")
617
+
618
+ crl_bytes = crl.read_bytes()
619
+ crl_digest = hashlib.sha256(crl_bytes).hexdigest()
620
+ if expected_crl_sha256 is not None:
621
+ if not isinstance(expected_crl_sha256, str) or not HEX256.fullmatch(expected_crl_sha256):
622
+ raise ValueError("expected CRL SHA-256 must be 64 lowercase hex characters")
623
+ if crl_digest != expected_crl_sha256:
624
+ raise ValueError("CRL SHA-256 pin mismatch")
625
+
626
+ cert_bytes = certificate.read_bytes()
627
+ try:
628
+ try:
629
+ cert = x509.load_pem_x509_certificate(cert_bytes)
630
+ except ValueError:
631
+ cert = x509.load_der_x509_certificate(cert_bytes)
632
+ trust_anchors = load_certificates(issuer_roots)
633
+ validate_trust_anchor_bundle(trust_anchors)
634
+ intermediate_certs = load_certificates(intermediates) if intermediates is not None else []
635
+ anchor_fingerprints = {item.fingerprint(hashes.SHA256()) for item in trust_anchors}
636
+ if any(item.fingerprint(hashes.SHA256()) in anchor_fingerprints for item in intermediate_certs):
637
+ raise ValueError("intermediate bundle must not duplicate a certificate in the trust-anchor bundle")
638
+ issuer_certs = trust_anchors + intermediate_certs
639
+ parsed_crl = load_crl(crl)
640
+ signer_digest, issuer_validity = validate_direct_crl_scope(cert, issuer_certs, parsed_crl, target_instant, instant)
641
+ entry_assessment = assess_crl_entry(cert, parsed_crl, instant)
642
+ if entry_assessment["status_at_time"] == "revoked":
643
+ raise ValueError("target certificate is revoked at the historical validation time")
644
+ except (ValueError, x509.DuplicateExtension) as exc:
645
+ raise ValueError("CRL applicability preflight failed: " + str(exc)) from exc
646
+
647
+ executable = shutil.which("openssl")
648
+ if not executable:
649
+ raise ValueError("OpenSSL CLI is required for CRL historical validation")
650
+ executable = os.path.abspath(executable)
651
+ openssl_version = _require_supported_openssl(executable)
652
+ command = [
653
+ executable, "verify", "-verbose", "-crl_check",
654
+ "-CRLfile", str(crl), "-CAfile", str(issuer_roots), "-no-CApath", "-no-CAstore", "-auth_level", "2", "-x509_strict",
655
+ ]
656
+ if intermediates is not None:
657
+ command.extend(["-untrusted", str(intermediates)])
658
+ command.append(str(certificate))
659
+ for validation_time in path_validation_times:
660
+ # Validate the entire enclosing second, not only its upper bound.
661
+ # The CRL entry/freshness assessment remains conservatively evaluated
662
+ # at the upper bound, while PKIX validity must also hold at the lower.
663
+ verification_command = [
664
+ *command[:3], "-attime", str(validation_time), *command[3:]
665
+ ]
666
+ result = subprocess.run(
667
+ verification_command, capture_output=True, text=True, check=False
668
+ )
669
+ detail = (result.stdout or result.stderr).strip()
670
+ if result.returncode:
671
+ raise ValueError(
672
+ "historical certificate/CRL validation failed at Unix second "
673
+ + str(validation_time) + ": " + detail[-2000:]
674
+ )
675
+ if not detail or not re.search(r":\s*OK(?:\s|$)", detail):
676
+ raise ValueError("OpenSSL did not return an explicit successful certificate verification")
677
+
678
+ return {
679
+ "verified": True,
680
+ "status": "not_revoked_at_validation_time",
681
+ "openssl_version": openssl_version,
682
+ "at_time": at_time,
683
+ "effective_at_time": effective_at_time,
684
+ "time_rounding": "ceil_to_next_whole_second_for_conservative_historical_evaluation",
685
+ "path_validation_times": list(path_validation_times),
686
+ "path_validation_scope": "OpenSSL target certificate PKIX path validation at the exact floor/ceiling Unix-second bound(s) of RFC 3161 genTime",
687
+ "certificate_sha256": hashlib.sha256(cert_bytes).hexdigest(),
688
+ "issuer_roots_sha256": roots_digest,
689
+ "issuer_intermediates_sha256": hashlib.sha256(intermediates.read_bytes()).hexdigest() if intermediates is not None else None,
690
+ "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",
691
+ "crl_sha256": crl_digest,
692
+ "crl_issuer_certificate_sha256": signer_digest,
693
+ "crl_issuer_certificate_validity": issuer_validity,
694
+ "crl_scope": "direct_only; certificate CRLDistributionPoints unsupported",
695
+ "crl_signature_algorithm_oid": parsed_crl.signature_algorithm_oid.dotted_string,
696
+ "crl_signature_policy": "RSA/DSA >= 2048 bits or EC >= 256 bits with SHA-256/384/512; Ed25519/Ed448 allowed",
697
+ "revocation_entry": entry_assessment,
698
+ "verification": "OpenSSL path auth_level 2 and CRL signature validation plus direct-CRL issuer, CA/keyCertSign/cRLSign, issuer validity at CRL thisUpdate, target certificate PKIX path validation at exact floor/ceiling Unix-second bound(s), AKI, scope, freshness, signature-policy and entry-semantic preflight",
699
+ }
700
+
701
+
702
+
703
+ def _read_stable_input(source: Path) -> bytes:
704
+ """Read one regular-file input and reject detectable concurrent mutation."""
705
+ # Descriptor metadata brackets the read, avoiding a second pathname lookup.
706
+ with source.open("rb") as handle:
707
+ before = os.fstat(handle.fileno())
708
+ if not stat.S_ISREG(before.st_mode):
709
+ raise ValueError(f"verification input is not a regular file: {source}")
710
+ data = handle.read()
711
+ after = os.fstat(handle.fileno())
712
+
713
+ identity_before = (
714
+ before.st_dev, before.st_ino, before.st_size,
715
+ before.st_mtime_ns, before.st_ctime_ns,
716
+ )
717
+ identity_after = (
718
+ after.st_dev, after.st_ino, after.st_size,
719
+ after.st_mtime_ns, after.st_ctime_ns,
720
+ )
721
+ if identity_before != identity_after or len(data) != after.st_size:
722
+ raise ValueError(f"verification input changed while being snapshotted: {source}")
723
+ return data
724
+
725
+
726
+ def verify_crl_status(
727
+ certificate: Path,
728
+ issuer_roots: Path,
729
+ crl: Path,
730
+ at_time: str,
731
+ expected_roots_sha256: str,
732
+ intermediates: Path | None = None,
733
+ expected_crl_sha256: str | None = None,
734
+ ) -> dict[str, Any]:
735
+ """Verify snapshots of all inputs consistently across preflight and OpenSSL."""
736
+ # Snapshot every file consumed by Python preflight or the OpenSSL child.
737
+ # This binds the pinned/parsed objects to the exact paths OpenSSL receives.
738
+ with tempfile.TemporaryDirectory(prefix="tsa-inputs-") as directory:
739
+ snapshot_dir = Path(directory)
740
+
741
+ def snapshot_input(source: Path, label: str) -> Path:
742
+ target = snapshot_dir / f"{label}{source.suffix}"
743
+ target.write_bytes(_read_stable_input(source))
744
+ return target
745
+
746
+ certificate_snapshot = snapshot_input(certificate, "certificate")
747
+ roots_snapshot = snapshot_input(issuer_roots, "issuer-roots")
748
+ crl_snapshot = snapshot_input(crl, "crl")
749
+ intermediates_snapshot = (
750
+ snapshot_input(intermediates, "intermediates") if intermediates is not None else None
751
+ )
752
+ return _verify_crl_status_with_snapshot(
753
+ certificate_snapshot, roots_snapshot, crl_snapshot, at_time,
754
+ expected_roots_sha256, intermediates=intermediates_snapshot,
755
+ expected_crl_sha256=expected_crl_sha256,
756
+ )
757
+
758
+
759
+ def main() -> int:
760
+ parser = argparse.ArgumentParser(description=__doc__)
761
+ parser.add_argument("--certificate", type=Path, required=True)
762
+ parser.add_argument("--issuer-roots", type=Path, required=True)
763
+ parser.add_argument("--issuer-roots-sha256", required=True)
764
+ parser.add_argument("--crl", type=Path, required=True)
765
+ parser.add_argument("--crl-sha256")
766
+ parser.add_argument("--at-time", required=True)
767
+ parser.add_argument("--intermediates", type=Path)
768
+ args = parser.parse_args()
769
+ try:
770
+ result = verify_crl_status(
771
+ args.certificate, args.issuer_roots, args.crl, args.at_time,
772
+ args.issuer_roots_sha256, args.intermediates, args.crl_sha256,
773
+ )
774
+ except (OSError, ValueError, TypeError) as exc:
775
+ print("ERROR: " + str(exc), file=sys.stderr)
776
+ return 1
777
+ print(json.dumps(result, sort_keys=True, indent=2))
778
+ return 0
779
+
780
+
781
+ if __name__ == "__main__":
782
+ raise SystemExit(main())