glm-5.1
13b0991fb8
Resolved all 11 open questions based on project guidance: Transport: - OQ-01/OQ-07: ACME/Let's Encrypt with domain + IP paths (ADR-008) - OQ-02: Default to n0 relay, --iroh-relay override (ADR-009) - OQ-05: Transport chaining supported natively (ADR-010) Client: - OQ-06: Programmatic-first API, no ~/.ssh/config (ADR-011) Server: - OQ-04: Ed25519 + OpenSSH cert-authority, no password auth (ADR-012) - OQ-08: fail2ban-friendly logging + built-in rate limiting (ADR-013) TUN: - OQ-03/OQ-09: Deferred entirely, recommend tun2proxy (ADR-014) - tun-shim.md marked deprecated NAPI: - OQ-10: Expose both connect() and serve() (ADR-016) - OQ-11: Use napi-rs for FFI bridge (ADR-015) Additional ADRs created during review: - ADR-006: No logging of tunnel destinations (was phantom reference) - ADR-017: Stealth mode protocol multiplexing - ADR-018: Control channel for pubsub over SSH Fixed: ADR-002 status → Superseded, ADR-007 title typo, WRAUTH_SERVER typo, ADR-005 stale wraith-tun refs, undefined ACL feature removed from server.md, --proxy semantic difference documented.
42 lines
2.7 KiB
Markdown
42 lines
2.7 KiB
Markdown
# ADR-012: Ed25519 Keys + OpenSSH Certificate Authority, No Password Auth
|
|
|
|
## Status
|
|
Accepted
|
|
|
|
## Context
|
|
SSH authentication has several options:
|
|
- **Ed25519 public key**: The default, already specified. Each user has a keypair; the server has an `authorized_keys` file.
|
|
- **Password authentication**: Convenient for quick setups but less secure (susceptible to brute force, credential reuse).
|
|
- **OpenSSH certificate authority (cert-authority)**: A CA signs user certificates. The server trusts the CA instead of individual keys. Much easier for multi-user setups — add one CA line to `authorized_keys` instead of every user's public key. Also supports certificate expiry and restrictions.
|
|
|
|
The question is which auth methods to support and prioritize.
|
|
|
|
## Decision
|
|
|
|
**Primary: Ed25519 public key** (already specified, no change).
|
|
|
|
**Important: OpenSSH certificate authority**. Support `cert-authority` entries in `authorized_keys` files. When a user presents a certificate signed by a trusted CA, the server validates the certificate (signature, expiry, permissions) and accepts it. This is critical for multi-user deployments where managing individual keys is impractical.
|
|
|
|
**Not supported: Password authentication over SSH channels.** Password auth over an SSH tunnel (i.e., the SOCKS5 proxy requiring a password) is not in scope. Password auth over SSH itself is rejected because:
|
|
- It's less secure than key-based auth
|
|
- It's susceptible to brute force (fail2ban can mitigate, but keys eliminate the problem)
|
|
- It's not needed when cert-authority provides easy multi-user management
|
|
- If a local SOCKS5 proxy is desired with its own auth, that's a separate concern
|
|
|
|
The server's `authorized_keys` file format follows OpenSSH conventions:
|
|
- Regular keys: `ssh-ed25519 AAAA... user@host`
|
|
- CA trusts: `cert-authority ssh-ed25519 AAAA... CA name`
|
|
- Principals: `cert-authority,permit-port-forwarding ssh-ed25519 AAAA... CA name`
|
|
|
|
## Consequences
|
|
- **Positive**: Multi-user deployments are manageable — one CA entry instead of N key entries.
|
|
- **Positive**: Certificates can carry expiry dates and restrictions (permit-port-forwarding, no-pty, source-address).
|
|
- **Positive**: No password brute force risk. fail2ban still needed for connection-level abuse, but not for auth-level password guessing.
|
|
- **Positive**: `russh` supports OpenSSH certificate verification natively.
|
|
- **Negative**: Setting up a CA requires initial key management tooling (`ssh-keygen -s`).
|
|
- **Negative**: Users who want a quick "just let me in" experience need to generate keys first. Not a significant barrier for the target audience (self-hosting, ops).
|
|
|
|
## References
|
|
- [client.md](../client.md)
|
|
- [server.md](../server.md)
|
|
- [OQ-04](../open-questions.md) — resolved by this ADR |