Skip to content

One Ubuntu host runs both experimental services.

Run Freebird for testing only on one Ubuntu 24.04 host. This is the only supported network topology. nginx terminates HTTPS, and systemd runs one Issuer and one Origin that listen only on loopback. Use a single-tenant host because other local accounts can connect directly to the loopback HTTP ports.

Do not use this deployment for production authorization. It does not support replicas, failover, containers, a CDN, or a load balancer. The release gates apply, including independent cryptographic review.

client ── HTTPS ── nginx ── 127.0.0.1:8081 ── Issuer (private key, invitations)
                    └───── 127.0.0.1:8082 ── Origin (public key, spent tokens)

Set public identities in the service configuration. The services do not read Host, forwarding headers, or client addresses. Restrict hostnames and routes in nginx, and pass admission and authorization headers unchanged. Disable request caching and retries. Keep those headers and request bodies out of logs, although warnings and errors can contain client IP addresses.

An operator who runs both roles can correlate issuance and redemption by using network metadata. Blind signing does not prevent that correlation.

Prepare the host for local state and HTTPS.

Put /var/lib on local storage to support exclusive process locks and durable SQLite writes. Do not use NFS. Synchronize the system clock and check it with timedatectl status before starting either service. Startup is refused if the clock is behind the time recorded in durable state.

Install nginx, systemd, and a compiler toolchain that can build the checked-out source. Configure two distinct lowercase DNS names that point to this host. Names cannot include a trailing dot or a port. Replace issuer.example.org and origin.example.org in the nginx template and the environment file.

Obtain certificates for both names from your ACME provider before enabling the TLS server blocks. You may need a temporary HTTP-only configuration for ACME. The nginx template uses /etc/letsencrypt/live/<name>/fullchain.pem and privkey.pem. Install a renewal hook that runs nginx -t && systemctl reload nginx. Keep invitation and token headers out of your nginx logs, and leave debug logging disabled.

Build and install the binary from a reviewed checkout as root. Create separate service accounts and state directories for the two roles:

cargo build --release --locked -p freebird-privacy-pass-service \
  --bin freebird-privacy-pass-service --example loopback_client
install -o root -g root -m 0755 target/release/freebird-privacy-pass-service \
  /usr/local/bin/freebird-privacy-pass-service
useradd --system --user-group --no-create-home --home-dir /nonexistent \
  --shell /usr/sbin/nologin freebird-issuer
useradd --system --user-group --no-create-home --home-dir /nonexistent \
  --shell /usr/sbin/nologin freebird-origin
install -d -o root -g root -m 0755 /etc/freebird
install -o root -g root -m 0644 deploy/systemd/freebird.env.example \
  /etc/freebird/freebird.env
# Edit the two public names; do not put invitations or private keys in this file.
install -d -o freebird-issuer -g freebird-issuer -m 0700 /var/lib/freebird-issuer
install -d -o freebird-origin -g freebird-origin -m 0700 /var/lib/freebird-origin

Make the service binary readable by both role users. Before initializing the Origin, confirm that FREEBIRD_ISSUER_NAME and FREEBIRD_ORIGIN_NAME exactly match the nginx server_name directives and the certificate DNS names. The database pins the Origin's two names when it is first opened. A later change is refused. Configure the Issuer directory to advertise exactly https://<FREEBIRD_ISSUER_NAME>/private-token/issue, not a loopback URL. Proxy headers cannot change these identities.

Initialize both roles and create the first invitation.

Run offline maintenance commands, including status and provisioning, as the role user with its unit stopped. Each command takes an exclusive lock. Running it as root can leave root-owned SQLite or lock files that prevent startup. Do not delete .lock files. Before the first start, initialize fresh state subdirectories. Initialization refuses a directory that already exists:

bin=/usr/local/bin/freebird-privacy-pass-service
issuer=/var/lib/freebird-issuer/state
origin=/var/lib/freebird-origin/state
runuser -u freebird-issuer -- "$bin" init-issuer "$issuer"
key_id="$(runuser -u freebird-issuer -- "$bin" issuer-key-status "$issuer" |
  awk '$1=="active"{print $2}')"
# Verify the result is exactly one 64-character hexadecimal key ID.
test "${#key_id}" -eq 64
install -d -o freebird-issuer -g freebird-issuer -m 0700 /var/lib/freebird-issuer/transfer
runuser -u freebird-issuer -- "$bin" export-issuer-spki "$issuer" "$key_id" \
  /var/lib/freebird-issuer/transfer/genesis.der
# Copy public data into a fresh Origin-owned transfer directory, not its key store.
install -d -o freebird-origin -g freebird-origin -m 0700 /var/lib/freebird-origin/transfer
install -o freebird-origin -g freebird-origin -m 0600 \
  /var/lib/freebird-issuer/transfer/genesis.der /var/lib/freebird-origin/transfer/genesis.der
runuser -u freebird-origin -- "$bin" init-origin "$origin" \
  /var/lib/freebird-origin/transfer/genesis.der "$key_id"
runuser -u freebird-origin -- "$bin" origin-key-status "$origin"
rm /var/lib/freebird-issuer/transfer/genesis.der /var/lib/freebird-origin/transfer/genesis.der

Transfer only the public SPKI as root. Do not transfer the Issuer's database. Verify that the Origin status shows the same key ID as the Issuer's active key. Keep the original transfer directories private. Preserve a failed or partial initialization for inspection rather than overwriting it.

Create one invitation and capture it in a private file so that it does not appear in the journal or in shell arguments:

(umask 077; runuser -u freebird-issuer -- "$bin" provision "$issuer") \
  > /root/freebird-invitation

Protect the output file as a bearer secret. An invitation expires in 24 hours and can be used once. If output fails after provisioning, the invitation may be irretrievable. Do not assume that it is safe to retry.

Start both services and verify access through nginx.

Install the two units from deploy/systemd/ in /etc/systemd/system/ so that systemd can start the services. Put the edited deploy/nginx/freebird.conf in /etc/nginx/conf.d/, which is included in nginx's http context. Keep an existing default virtual host because the Freebird blocks are not default servers.

Create the external key catalog and first cold backup before enabling serving. Confirm that both roles are initialized and their names and keys agree. Check the certificate paths, names, and ports before activation:

systemctl daemon-reload
systemd-analyze verify /etc/systemd/system/freebird-{issuer,origin}.service
nginx -t
# Only after both roles are initialized, names/keys agree, and checks pass:
# Record the external key-history catalog and a cold backup first (recovery guide).
install -o root -g root -m 0644 /dev/null /etc/freebird/serving-enabled
sync -f /etc/freebird
systemctl enable --now freebird-issuer.service freebird-origin.service
systemctl is-active freebird-issuer.service freebird-origin.service
systemctl reload nginx
curl --fail --silent --show-error \
  https://issuer.example.org/.well-known/private-token-issuer-directory
curl -i https://origin.example.org/private-token/protected

Verify that the directory's issuer-request-uri is https://issuer.example.org/private-token/issue. The protected route returns 401 with one WWW-Authenticate header. nginx returns 404 for unknown paths. Port 80 redirects normal requests to HTTPS and does not proxy them to Freebird.

Keep /etc/freebird/serving-enabled present to allow systemd starts for both roles. If the file is absent, even a manual start is skipped. Check is-active and the listener because a skipped start can exit successfully. Removing the file does not stop running processes.

Run the end-to-end test with one fresh invitation. The test consumes it:

target/release/examples/loopback_client --tls-ca /path/to/trusted-ca.pem \
  --connect 127.0.0.1 https://issuer.example.org/ \
  https://origin.example.org/ < /root/freebird-invitation

Use a pinned CA that can validate both DNS names. The client prints only status codes: issuance: 200; redemption: 200; replay: 401; invitation retry: 403. For local tests, the client also accepts numeric loopback HTTP addresses. It cannot connect to a remote host and is not a general-purpose SDK.

Provision invitations without stopping the Issuer.

Run provision-live as the Issuer's service user to create invitations while the Issuer serves. The command uses the local control socket:

(umask 077; runuser -u freebird-issuer -- "$bin" provision-live "$issuer") \
  > /root/freebird-invitation

Connect as the Issuer's UID. Connections from root and other users are refused. Each successful call durably creates one single-use code before sending the reply. The code expires in 24 hours. If the reply is lost, the code remains unclaimed until it expires. It is not refunded or resent. Use offline provision while the Issuer is stopped.

Keep <state-dir>/control.sock within the Unix socket path limit of about 100 bytes to allow Issuer startup. The default state path, /var/lib/freebird-issuer/state, fits.

Use the optional browser puzzle for open admission or app admission to let application servers request codes for their users. Proof-of-work raises the cost of collecting tokens. It does not prove that each visitor is unique. WebAuthn, vouching, and multi-instance operation are unsupported.

Stop both roles to rotate keys or restore state.

Use the offline rotation procedure to stage, activate, or retire keys. Stop both services and run each command as its role user. Install the successor's public key on the Origin first. Compare statuses and activation times, then update the external key catalog and cold backup before releasing the hold. Status commands also require the role to be stopped.

Check journalctl -u freebird-issuer -u freebird-origin if a unit refuses to start. A state or configuration refusal exits with status 1 and does not trigger an automatic restart. Correct the cause, then run systemctl reset-failed and start the unit. Do not edit SQLite files or roll back the clock.

Use stopped recovery because a provider snapshot, disk image, or database copy can reopen spent tokens and invitations if you restart without invalidating them. The procedure checks key history for compatibility and invalidates old credentials before you restart. It is not automatic failover. Retain the state and the old binary until you validate an upgrade. Startup rejects older experimental schemas and does not migrate them.