Edge Configuration

The edge reads all of its configuration from environment variables at startup. Restart it after any change.

Settings

The edge serves HTTPS only when both EDGE_TLS_CERT_FILE and EDGE_TLS_KEY_FILE are set. Without them it serves plain HTTP, which browsers will refuse to use from an HTTPS page. It accepts TLS 1.2 and 1.3, with modern AEAD cipher suites only. From v1.6.0 it serves HTTP/2 to browsers that offer it, and HTTP/1.1 to the rest. There is nothing to configure. It loads the certificate at startup, so restart it after each renewal.

Mutual TLS

The edge connects to Octet only over mutual TLS. It refuses to start if EDGE_CLIENT_CERT_FILE or EDGE_CLIENT_KEY_FILE is unset, or if OCTET_URL isn't https://. The one exception is an OCTET_URL on a loopback address, which is for local development. The log line names what is missing, for example OCTET_URL must be https:// (mTLS to octet is required). To get the certificate, see Deploy the Edge.

Octet's server certificate is a public certificate, so the edge verifies it with the host's system trust store. You don't need Octet's client CA certificate. Set OCTET_CA_FILE only if your security policy requires pinning Octet's server certificate to a specific CA.

The edge loads the client certificate and key at startup, so restart it after you renew them.

Edge signature

With EDGE_SIGNING_KEY set, the edge signs each session it forwards to Octet. The signature covers the collection and everything the edge adds about the connection. At startup the edge logs the key's kid and public key:

[octet-edge] S2 signing on: kid=edge-… ed25519 public key=… (register it in the licence portal)

Register both in your license's Edge configuration tab in the Octet portal, under Signing keys. If the value isn't a base64 32-byte key, the edge exits and logs EDGE_SIGNING_KEY must be a base64 32-byte Ed25519 seed.

Octet refuses a session whose signature fails its check. From v1.5.0, Octet also refuses an unsigned session, or one signed by a key that isn't registered for your license. The reason codes are in Errors. The signing key and the client certificate are separate credentials, and the edge needs both. See Credentials.

Where to keep the signing key

Anyone who has the signing key can sign sessions for your license until you revoke it. From v1.7.0 the edge can read it from three places. Set only one:

Keep the client certificate's key, EDGE_CLIENT_KEY_FILE, under the same protection as the signing key. Octet needs both, so protecting only one protects less than it seems. EDGE_CLIENT_KEY_FILE and EDGE_TLS_KEY_FILE are paths too, so they can be systemd credentials as well.

A key sealed to the TPM. This needs systemd 250 or later and a TPM 2.0. On cloud VMs that means a GCP Shielded VM, AWS NitroTPM or Azure Trusted Launch. The encrypted file can't be used on any other machine. As root on the edge host:

mkdir -p /etc/credstore.encrypted
openssl rand -base64 32 | systemd-creds encrypt --with-key=tpm2 --name=edge-s2-key - /etc/credstore.encrypted/edge-s2-key

Then remove the EDGE_SIGNING_KEY= line from the environment file, add this with systemctl edit octet-edge, and restart the edge:

[Service]
LoadCredentialEncrypted=edge-s2-key:/etc/credstore.encrypted/edge-s2-key
Environment=EDGE_SIGNING_KEY_FILE=edge-s2-key

The startup log shows S2 signing on (file …): kid=… ed25519 public key=…. A new key needs registering in the portal. A TPM reset or a new VM means a new key. Don't run systemd-creds decrypt on the host, because it prints the key.

A key in your cloud key service. The edge uses the instance's own identity:

• AWS KMS: create an asymmetric key with key spec ECC_NIST_EDWARDS25519 and usage SIGN_VERIFY, in the edge's region. Give the instance role kms:Sign and kms:GetPublicKey on it. Set EDGE_SIGNING_KMS=aws:arn:aws:kms:<region>:<account>:key/<id>.
• Google Cloud KMS: create a key with purpose ASYMMETRIC_SIGN and algorithm EC_SIGN_ED25519, in the edge's region. Give the VM's service account roles/cloudkms.signerVerifier on it. Set EDGE_SIGNING_KMS=gcp:projects/<p>/locations/<l>/keyRings/<r>/cryptoKeys/<k>/cryptoKeyVersions/<n>.

At startup the edge fetches the public key, checks that it is Ed25519 and that it may sign with it, and logs the kid and public key to register. Each session waits for one call to the key service, so keep the key in the edge's region. If a call fails or takes longer than 1 second, the edge answers the browser with 503 and edge_signing_failed, and sends nothing to Octet. It never forwards a session unsigned.

Prove you hold the signing key

From v1.7.0 the Octet portal asks you to prove each signing key you register. In your license's Edge configuration tab, under Signing keys, select Prove next to the key. The portal shows a one-time challenge, valid for 30 minutes. On the edge host, with the same key settings as the running edge, run:

octet-edge prove-key --challenge <the challenge from the portal>

It prints one line. Paste it into the portal. The command doesn't start the edge. It refuses a challenge for another key, or one that has expired, and says why. Keys you registered before v1.7.0 can be proven the same way.

Today a key that isn't proven still works. Octet will refuse sessions signed with an unproven key from a date it announces in advance, so prove each key now.

Testing only

The edge also reads two settings meant for testing. Leave both unset in production.

Endpoints

The edge serves every path at its root, so apiUrl is the edge's origin with no path, for example https://octet.example.com.

Ports and connections

The edge must accept the browser's TCP connection directly. See Deploy the Edge.

Binaries

Each release contains static Linux binaries with no runtime dependencies:

Check each binary against the release's SHA256SUMS before you install it. See Deploy the Edge. The edge runs only on Linux.