alkdev/alktls
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e86b8ba1b59052afb0167077be26fcbdc465abb9
alktls/docs/architecture/open-questions.md
T
glm-5.3-flash e86b8ba1b5 task 1: S-1 remediation — no-pop posture doc + OQ-TLS-09 + permanent impersonation pin 
- AcceptAnyCertVerifier doc: the presented CertificateVerify signature
  is not verified (no proof-of-possession) — the server-extracted
  fingerprint is attacker-suppliable from observed public cert/SPKI
  bytes; states the two safe patterns (auth-layer challenge-response /
  a verifying verifier) and points at OQ-TLS-09
- FingerprintPinVerifier doc (N-1): fixed the "stolen-but-stale
  fingerprint" phrasing (the cert is presented fresh each handshake;
  the signature check defeats a stolen/observed cert used by a party
  without the private key) and added the server-verifier cross-reference
- OQ-TLS-09 recorded (open, high): which layer owns server-path
  proof-of-possession — three options; deferral noted (needs the
  auth-layer design or an API call before the first consumer)
- tests/impersonation_posture.rs (tcp-gated): the S-1 probe made
  permanent, both variants — X.509 victim cert + attacker key and RFC
  7250 victim SPKI + attacker key complete the handshake, application
  data flows, and the server extracts the victim's fingerprint; any
  future pop change must fail/update this test with the doc + OQ
- server.md / client.md synced with the same posture
- task note: the review's N-4 parenthetical ("alknet's client resolver
  offers both types") is inaccurate — rustls 0.23.41/0.23.44 offer
  [RawPublicKey] iff the resolver's only_raw_public_keys() is true;
  task 6 should write N-4 from the rustls sources

Verified: cargo test 68 default / 77 all-features (+2) green; clippy
-D warnings clean (default + all-features); fmt clean; cargo doc
--no-deps warning-free
2026-09-10 22:00:57 +00:00

7.7 KiB
Raw Blame History

status, last_updated
status last_updated
draft 2026-09-10

Open Questions

Centralized tracker for alktls. Promoted from Phase 0 (docs/research/phase-0.md OQ-TLS-01..08) on 2026-09-10. Statuses here are authoritative; the Phase 0 doc's statuses are the historical record.

Statuses at a glance

OQ Topic Status Priority
OQ-TLS-01 Config-type ownership resolved (ADR-005) high
OQ-TLS-02 SelfSigned on the client path resolved (documented behavior kept) low
OQ-TLS-03 for_tcp_tls() adoption resolved (ADR-004) medium
OQ-TLS-04 Accessor borrow-vs-consume resolved (ADR-004) medium
OQ-TLS-05 Test surface resolved (ADR-006) low
OQ-TLS-06 ACME task shutdown surface resolved (detached-only for v1) low
OQ-TLS-07 iroh key surface resolved (ADR-005, byte access pinned) low
OQ-TLS-08 quinn → noq feature rename resolved (ADR-003) high
OQ-TLS-09 Server-path proof-of-possession open high

Identity & types

OQ-TLS-01: Where do the config types live, and what moves?

  • Origin: docs/research/phase-0.md §Gaps #3
  • Status: resolved (2026-09-10)
  • Priority: high
  • Resolution: alktls owns the identity types (TlsIdentity, Ed25519SecretKey, AcmeDirectory), the credential bundle (ConnectionCredentials, RemoteIdentity), and the fingerprint helpers. The auth layer (PeerEntry, AuthPolicy, IdentityProvider) stays out — peer-level identity is not TLS. Decision recorded in ADR-005.
  • Cross-references: ADR-001, ADR-005

OQ-TLS-02: SelfSigned on the client path — encode or document?

  • Origin: docs/research/phase-0.md §Gaps #4
  • Status: resolved (2026-09-10)
  • Priority: low
  • Resolution: keep the current behavior (present nothing via NoClientCertResolver) and document it on the identity type and in the client spec. Type-level enforcement (config error, like Acme) was rejected: SelfSigned as a local identity meaning "present nothing" is coherent — the dev cert exists for the server side, and presenting a self-signed client cert would add nothing the fingerprint path uses.
  • Consequences: a future dev client-auth use case would need a type-level change (additive, not a one-way door).
  • Cross-references: ADR-001 (identity model), client spec

OQ-TLS-07: iroh relationship in the rewrite

  • Origin: docs/research/phase-0.md OQ-TLS-07
  • Status: resolved (2026-09-10)
  • Priority: low
  • Resolution: the requirement is pinned and verified — Ed25519SecretKey keeps 32-byte raw access (from_bytes / as_bytes) with the same byte-level surface iroh's iroh_base::SecretKey consumes (from_bytes / to_bytes; 32 raw bytes in/out — verified against iroh 1.1 in Phase 0). iroh stays key-not-config; no for_iroh(). The rewrite's iroh dial consumes the type alktls owns (ADR-005); no alktls-side work remains.
  • Cross-references: ADR-003, ADR-005

API surface

OQ-TLS-03: for_tcp_tls() — adopt the spec accessor?

  • Origin: docs/research/phase-0.md §Gaps #2
  • Status: resolved (2026-09-10)
  • Priority: medium
  • Resolution: adopted — for_tcp_tls(&self) -> tokio_rustls::TlsAcceptor, feature-gated on tcp, infallible. Decision and rationale in ADR-004.
  • Cross-references: ADR-004

OQ-TLS-04: for_quinn() — self or &self?

  • Origin: docs/research/phase-0.md OQ-TLS-04
  • Status: resolved (2026-09-10)
  • Priority: medium
  • Resolution: server accessors take &self (one config feeds N transports — the ADR-082 story, directly expressible); client accessors consume self (per-dial build, zero-cost into_rustls_config). Full rationale in ADR-004.
  • Cross-references: ADR-003, ADR-004

OQ-TLS-08: quinn feature vs noq feature — and the MSRV floor

  • Origin: docs/research/phase-0.md §Prior art: noq
  • Status: resolved (2026-09-10)
  • Priority: high
  • Resolution: the feature is noq (no quinn feature ever published; rename is pre-consumer and free). noq 1.2 pinned ("1.2", default-features off, rustls feature), bump deliberately. The MSRV half of the OQ was separately resolved the same day (ecosystem floor 1.88; time pin dropped). Decision in ADR-003.
  • Cross-references: ADR-002, ADR-003, ADR-004

OQ-TLS-09: Which layer owns proof-of-possession on the server path?

  • Origin: docs/reviews/001-implementation-review.md §S-1 (the impersonation probe: a handshake with the victim's cert bytes + an attacker signer completes, and the server extracts the victim's fingerprint)
  • Status: open (recorded 2026-09-10)
  • Priority: high
  • Question: AcceptAnyCertVerifier never checks the client's CertificateVerify signature — the presented identity is spoofable by anyone holding the public cert/SPKI bytes, and the auth layer cannot detect it (the fingerprint it is handed is the victim's). alknet ADR-034 inherited the request-but-don't-require shape without recording this property. Who enforces possession?
  • Options:
    • (a) Keep request-but-don't-require; the auth layer owns challenge-response over the established channel, bound to the presented public key. No crate change; the S-1 doc note on AcceptAnyCertVerifier is the honest description until then.
    • (b) Add a VerifyPresentedCertVerifier sibling (request-and-verify): same nine-scheme list, permissive verify_client_cert, signature methods delegate to rustls::crypto::verify_tls{12,13}_signature(_with_raw_key) — the routing the client-side FingerprintPinVerifier already implements. Additive; must land before the first consumer (an API shape decision).
    • (c) Make the auth layer's fingerprint resolution possession-checked (a possession proof accompanies each fingerprint resolution). Cross-crate; the auth layer does not exist yet.
  • Constraints: the spoofable posture is pinned by tests/impersonation_posture.rs (both cert types) — any decision must fail or update that test together with the AcceptAnyCertVerifier doc note.
  • Cross-references: src/server.rs (AcceptAnyCertVerifier), src/client.rs (FingerprintPinVerifier), docs/reviews/001-implementation-review.md §S-1, alknet ADR-034

Quality / process

OQ-TLS-05: Test surface for the invariants

  • Origin: docs/research/phase-0.md §Gaps #5
  • Status: resolved (2026-09-10)
  • Priority: low
  • Resolution: port the in-module seed tests AND add tests/ integration tests for the cross-module surfaces; pin the exact nine-scheme list (regression-proof). Decision in ADR-006.
  • Cross-references: ADR-006

OQ-TLS-06: Does the ACME state machine need a shutdown surface?

  • Origin: docs/research/phase-0.md OQ-TLS-06
  • Status: resolved (2026-09-10)
  • Priority: low
  • Resolution: detached-only — the handle is stored (keeping TlsServerConfig non-Clone) and never aborted; the ACME task runs for the process lifetime. Documented on the type.
  • Consequences: a shutdown() (abort + await) surface would be additive and cheap if the rewrite's graceful-shutdown design wants one later — not a one-way door.
  • Cross-references: ADR-001 (one-ACME-machine rule), server.md

Deferred / Blocked

  • OQ-TLS-09 (server-path proof-of-possession): open by design — the decision needs the rewrite's auth-layer design in hand (option (c)) or an API-shape call before the first consumer (option (b)).
Reference in New Issue View Git Blame Copy Permalink