Documentation
¶
Overview ¶
Package tunnel provides QUIC-backed raw net.Listeners for Go servers.
Dial requires an existing identity approved by the server. ListenRaw returns unmodified public bytes; the application owns TLS. Storage and persisted Ed25519 credentials and signed RequestJoin bootstrap are included. Listen performs local ACME TLS; ListenTLS uses application-provided certificates. ListenHTTP opts into one-shot plain HTTP. EnsureJoined and EnsureJoinedAndListen support a join-then-wait workflow for administrator approval, with optional event callbacks. Clients reconnect automatically without replaying in-flight requests. CloseGracefully unadvertises and drains allocated streams within a caller-supplied context.
Index ¶
- Variables
- func FormatJoinEvent(event JoinEvent) string
- func LoadTransportTLS(storage Storage, addr, serverName string) (*tls.Config, error)
- type Client
- func (c *Client) Close() error
- func (c *Client) CloseGracefully(ctx context.Context) error
- func (c *Client) Listen(ctx context.Context, name string) (net.Listener, error)
- func (c *Client) ListenHTTP(ctx context.Context, name string) (net.Listener, error)
- func (c *Client) ListenPrivate(ctx context.Context, name string) (net.Listener, error)
- func (c *Client) ListenPrivateWithClientAuth(ctx context.Context, name string, auth *ClientAuthConfig) (net.Listener, error)
- func (c *Client) ListenRaw(ctx context.Context, name string) (net.Listener, error)
- func (c *Client) ListenTLS(ctx context.Context, name string, config *tls.Config) (net.Listener, error)
- func (c *Client) ListenWithClientAuth(ctx context.Context, name string, auth *ClientAuthConfig) (net.Listener, error)
- func (c *Client) Listening() []string
- func (c *Client) Routes() []string
- func (c *Client) Status() string
- type ClientAuthConfig
- type Credentials
- type JoinEvent
- type JoinEventType
- type JoinRequest
- type JoinWaitOptions
- type ListenFunc
- type Option
- type Storage
- type TransportTrust
- type TrustRequest
Constants ¶
This section is empty.
Variables ¶
var ErrIdentityNotApproved = errors.New("identity is not approved for forwarding")
var ErrIdentityRevoked = errors.New("identity revoked")
var ErrJoinExpired = fmt.Errorf("join request expired: %w", ErrIdentityNotApproved)
ErrJoinExpired means the pending request expired; call EnsureJoined again to submit a new request. It also matches ErrIdentityNotApproved.
Functions ¶
func FormatJoinEvent ¶
func LoadTransportTLS ¶
LoadTransportTLS loads saved endpoint-local trust for JoinRequest.TLSConfig or WithTLSConfig. It does not fall back to system roots when a saved CA is used. For IP endpoints pass the certified DNS name as serverName.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
func Dial ¶
Dial retries transient connection failures until ctx expires. ctx bounds setup; the returned Client reconnects independently until explicitly closed/denied.
func EnsureJoinedAndListen ¶
func EnsureJoinedAndListen(ctx context.Context, addr string, options JoinWaitOptions, listen ListenFunc, dialOptions ...Option) (net.Listener, *Client, error)
EnsureJoinedAndListen combines EnsureJoined, Dial, and listener creation. The listen callback selects the desired listener mode, for example:
listener, client, err := tunnel.EnsureJoinedAndListen(ctx, addr, opts,
func(ctx context.Context, c *tunnel.Client) (net.Listener, error) { return c.Listen(ctx, name) })
func (*Client) CloseGracefully ¶
CloseGracefully removes all pool members, allows allocated streams to be accepted and finish, then closes the transport. Deadline/cancellation aborts the remainder. No reconnect or new listeners are started during draining.
func (*Client) Listen ¶
Listen terminates TLS locally using on-demand ACME certificates. It accepts the configured CA's terms of service. By default the CA is Let's Encrypt and only TLS-ALPN-01 is used; DNS must resolve to the daemon on public TCP 443. Credential storage also stores the ACME account and cached certificates.
func (*Client) ListenHTTP ¶
ListenHTTP opts into one-shot plaintext HTTP, independently of TLS listeners.
func (*Client) ListenPrivate ¶
ListenPrivate terminates public TLS locally using certificates issued by the daemon's constrained CA. Browsers must separately trust that CA. Local keys never leave credential storage. Each authorized descendant is issued an exact name certificate on demand; renewal happens at subsequent handshakes with less than 24 hours remaining. No wildcard certificates or ACME are used.
func (*Client) ListenPrivateWithClientAuth ¶
func (c *Client) ListenPrivateWithClientAuth(ctx context.Context, name string, auth *ClientAuthConfig) (net.Listener, error)
ListenPrivateWithClientAuth is ListenPrivate with public client authentication.
func (*Client) ListenTLS ¶
func (c *Client) ListenTLS(ctx context.Context, name string, config *tls.Config) (net.Listener, error)
ListenTLS terminates public TLS locally with an application-provided config. Accepted connections have completed TLS handshakes. The daemon never sees this configuration or its certificate private keys.
func (*Client) ListenWithClientAuth ¶
func (c *Client) ListenWithClientAuth(ctx context.Context, name string, auth *ClientAuthConfig) (net.Listener, error)
ListenWithClientAuth is Listen with public client authentication. ACME TLS-ALPN-01 challenge connections are exempt and never reach Accept.
type ClientAuthConfig ¶
type ClientAuthConfig struct {
ClientAuth tls.ClientAuthType
ClientCAs *x509.CertPool
VerifyConnection func(tls.ConnectionState) error
}
ClientAuthConfig configures public client-certificate authentication, separate from tunnel transport credentials. VerifyConnection also runs on resumption.
type Credentials ¶
type Credentials struct {
// contains filtered or unexported fields
}
Credentials holds an Ed25519 identity, not proof of route approval. Its private key is intentionally unexported; it never goes to the daemon. Credentials must not be logged or serialized. A zero value is invalid.
func EnsureJoined ¶
func EnsureJoined(ctx context.Context, addr string, options JoinWaitOptions) (Credentials, error)
EnsureJoined makes sure a local identity has a submitted join request and then waits until an administrator approves it. The wait is canceled by ctx.
If credential storage already contains an approved identity, no new join is submitted. If an identity exists but is not approved, EnsureJoined submits a fresh join request before waiting.
func LoadCredentials ¶
func LoadCredentials(storage Storage) (Credentials, error)
LoadCredentials loads an existing identity without creating a new one. Missing keys return an error wrapping fs.ErrNotExist. Malformed keys return an ordinary error and are never silently replaced. Keys are persisted as PKCS#8 DER, unencrypted; storage access controls protect the private key.
func RequestJoin ¶
func RequestJoin(ctx context.Context, addr string, request JoinRequest) (Credentials, error)
RequestJoin returns persisted credentials after durable pending submission, not after human approval. A new Dial is required once an admin approves it.
func (Credentials) GoString ¶
func (c Credentials) GoString() string
func (Credentials) Identity ¶
func (c Credentials) Identity() string
Identity returns the full lowercase SHA-256 public-key identifier, or an empty string for invalid credentials.
func (Credentials) PublicKey ¶
func (c Credentials) PublicKey() ed25519.PublicKey
PublicKey returns a copy of the identity's public key, or nil for invalid credentials. Renewing a transport certificate does not change this identity.
func (Credentials) String ¶
func (c Credentials) String() string
String and GoString redact private material in ordinary formatted output.
type JoinEventType ¶
type JoinEventType string
const ( JoinEventLoadedIdentity JoinEventType = "loaded_identity" JoinEventJoinSubmitted JoinEventType = "join_submitted" JoinEventWaiting JoinEventType = "waiting" JoinEventApproved JoinEventType = "approved" JoinEventCheckFailed JoinEventType = "check_failed" JoinEventRevoked JoinEventType = "revoked" )
type JoinRequest ¶
type JoinWaitOptions ¶
type JoinWaitOptions struct {
JoinRequest JoinRequest
PollInterval time.Duration
OnEvent func(JoinEvent)
}
type Option ¶
type Option func(*dialOptions) error
func WithACMEClient ¶
WithACMEClient selects an alternate ACME directory/HTTP transport (e.g. a staging CA). The client is copied; a nil account Key uses persisted storage. Supply this before Dial. Only TLS-ALPN-01 is enabled, regardless of CA offers.
func WithACMEEmail ¶
func WithACMEErrorHandler ¶
WithACMEErrorHandler reports certificate acquisition errors that otherwise only fail the incoming TLS handshake. The handler may be called concurrently and should return promptly. A nil handler disables reporting.
func WithCredentials ¶
func WithCredentials(c Credentials) Option
func WithTLSConfig ¶
WithTLSConfig supplies server trust roots/ServerName. Verification is required.
type Storage ¶
type Storage interface {
Get(key string) ([]byte, error)
Put(key string, value []byte) error
Delete(key string) error
}
Storage stores private credentials and ACME state. Get must return an error wrapping fs.ErrNotExist for absent keys. Delete is idempotent. Put replaces a value atomically. Implementations must support concurrent callers and must not retain or expose mutable aliases to the supplied/returned byte slices. There is no compare-and-swap: initialize an identity before sharing its store between processes. Treat all stored data as secret.
func FileStorage ¶
FileStorage returns a store rooted at dir. Initialization errors are reported by the first operation, preserving the brief's FileStorage(dir) Storage API. New directories use 0700 and value files use 0600. Existing directory modes are not changed; callers must choose a private, trusted directory. Writes sync a temporary file, rename it atomically, then sync its parent directory. A sync failure can occur after a replacement has already become visible. Symlink traversal cannot escape the root (os.Root); untrusted users must not be permitted to modify the root itself. Stores under /tmp are not durable.
func MemoryStorage ¶
func MemoryStorage() Storage
MemoryStorage returns an independent, concurrency-safe, non-durable store.
type TransportTrust ¶
TransportTrust describes the saved CA without exposing any private material.
func BootstrapTrust ¶
func BootstrapTrust(ctx context.Context, addr string, request TrustRequest) (TransportTrust, error)
BootstrapTrust downloads the constrained CA from the QUIC TLS certificate chain, verifies a supplied fingerprint or explicitly accepts TOFU, verifies hostname/chain, then persists the CA. It sends no Join or forwarding request. Existing trust is never overwritten, including when TOFU is selected again.
func FetchTransportTrust ¶
func FetchTransportTrust(ctx context.Context, addr, serverName string) (TransportTrust, error)
FetchTransportTrust downloads the constrained transport CA from the QUIC TLS chain and returns its public metadata without persisting it.
type TrustRequest ¶
type TrustRequest struct {
Storage Storage
ServerName string
Fingerprint string // lowercase SHA-256 hex of CA DER, printed by tunneld
TOFU bool // explicit acceptance of interception risk on first contact
}
TrustRequest explicitly selects fingerprint verification or first-use trust. ServerName is required when addr is an IP but the certificate is DNS-only. Storage must be durable in real deployments. Do not bootstrap a shared store concurrently across processes: Storage does not support compare-and-swap.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
hello
command
hello is a minimal HTTP application exposed using the tunnel Go API.
|
hello is a minimal HTTP application exposed using the tunnel Go API. |
|
tunnelctl
command
|
|
|
tunneld
command
|
|
|
tunnelproxy
command
tunnelproxy exposes a loopback TCP service through an approved tunnel identity.
|
tunnelproxy exposes a loopback TCP service through an approved tunnel identity. |
|
internal
|
|
|
cli
Package cli provides shared command-line helpers for the tunnel tools.
|
Package cli provides shared command-line helpers for the tunnel tools. |
|
names
Package names contains shared DNS-label validation and subtree matching.
|
Package names contains shared DNS-label validation and subtree matching. |
|
server
Package server implements the daemon's tunnel-facing control plane.
|
Package server implements the daemon's tunnel-facing control plane. |
|
streamconn
Package streamconn adapts QUIC bidirectional streams to net.Conn.
|
Package streamconn adapts QUIC bidirectional streams to net.Conn. |
|
transportpki
Package transportpki manages the daemon's private transport PKI, not public TLS.
|
Package transportpki manages the daemon's private transport PKI, not public TLS. |
|
wire
Package wire implements the bounded JSON frames in PROTOCOL.md.
|
Package wire implements the bounded JSON frames in PROTOCOL.md. |