Skip to content

README.md

Latest commit

 

History

History
64 lines (50 loc) · 2.59 KB

README.md

File metadata and controls

64 lines (50 loc) · 2.59 KB
Raw

litebastion

litebastion is a public-service reverse proxy for witnesses that can't be exposed directly to the internet.

In short, a witness connects to a bastion over TLS with a Ed25519 client certificate, "reverses" the direction of the connection, and serves HTTP/2 requests over that connection. The bastion then proxies requests received at /<hex-encoded hash of Ed25519 key>/* to that witness.

-backends string
        file of accepted key hashes, one per line, reloaded on SIGHUP

The only configuration file of litebastion is the backends file, which lists the acceptable client/witness key hashes.

-listen string
        host and port to listen at (default "localhost:8443")
-cache string
        directory to cache ACME certificates at
-email string
        email address to register the ACME account with
-host string
        host to obtain ACME certificate for
-tls-cert string
        path to TLS certificate
-tls-key string
        path to TLS private key
-log-level string
        minimum severity level to log (default "info")

Since litebastion needs to operate at a lower level than HTTPS on the witness side, it can't be behind a reverse proxy, and needs to configure its own TLS certificate. Use the -cache, -email, and -host flags to configure the ACME client. The ALPN ACME challenge is used, so as long as the -listen port receives connections to the -host name at port 443, everything should just work.

Alternatively, if both -tls-cert and -tls-key are set, ACME is disabled and the provided certificate and private key are used instead. The certificate and key are reloaded on SIGHUP.

-obscurity
        enable obscurity mode (disable / and /logz endpoints)

-listen-http [HOST:]PORT
        only accept HTTP requests at http://HOST:PORT or http://localhost:PORT

If you intend to protect backends from unwanted traffic and not forward arbitrary requests from the internet, you can accept HTTP requests on a separate port. Backends will still be able to connect to the public -listen address. This is for example useful when running a bastion for your own log.

bastion as a library

It might be desirable to integrate bastion functionality in an existing binary, for example because there is only one IP address and hence only one port 443 to listen on.

In that case, you can use the filippo.io/torchwood/bastion package.

See pkg.go.dev for the documentation and in particular the package example.