Challenge-Response Call-Home Authentication

Challenge-response authentication allows edge hosts to prove their identity during the initial call-home (host-init). The edge host proves possession of a private key by signing a server-issued nonce.

The host presents an x509 certificate issued by the Control Tower's Strongbox TLS CA. The Control Tower verifies the certificate chain, checks that neither the host certificate nor the intermediate CA certificate has been revoked, and then verifies the nonce signature.

This decouples credential issuance from installation time: you generate a credential before shipping the host, install it alongside supd.conf, and the host uses it for the very first call-home. After the initial call-home succeeds, the credential is no longer needed.

Server-side configuration

Enable x509 challenge-response in the call-home settings:

supctl create system call-home settings <<EOF
host-authentication:
  enabled: true
EOF

The verify controls how the certificate identity is matched to the host-id (default: host-id):

Policy	Description
host-id	Certificate CN or SAN must match the host-id
site	Certificate CN or SAN must match the site name
system-ca	Any certificate valid against the CA is accepted

Issuing credentials

supctl do system call-home issue-call-home-cert --host-id <host-id> <ttl>

Example for host d6785b90-df4c-4008-888d-2d56e68decdf with a 4-day TTL:

supctl do system call-home issue-call-home-cert --host-id \
  d6785b90-df4c-4008-888d-2d56e68decdf 4d

The output contains a b64-tar-package with two files:

File	Contents
cert.pem	The signed certificate (leaf + intermediate)
cert.key	The corresponding private key

Unpack the package:

echo "<b64-tar-package>" | base64 -d | tar xfz -

The output also contains a serial field (a hex string) that identifies the certificate in the issuing CA's revocation list. The serial is recorded in the system:audit-trail-log.

Revoking credentials

To prevent a specific credential from being accepted at call-home, revoke it by serial number. The issuing CA is the intermediate CA of the Control Tower, named <control-tower-name>-api-inter:

supctl do system call-home revoke-call-home-cert \
  --reason keyCompromise <serial>

For example, to revoke a certificate with serial 9b:39:33:e2:1c:80:1a:32:02:e0:9d:67:24:37:09:2e:31:19 on a Control Tower named topdc:

supctl do system call-home revoke-call-home-cert \
  --reason keyCompromise \
  9b:39:33:e2:1c:80:1a:32:02:e0:9d:67:24:37:09:2e:31:19

Revocation takes effect immediately. The next host-init attempt by a host presenting the revoked certificate will be rejected with a 403 response. A new credential can be issued to replace it at any time.

Available revocation reasons are: unspecified, keyCompromise, cACompromise, affiliationChanged, superseded, cessationOfOperation, certificateHold, privilegeWithdrawn, aACompromise.

Edge host configuration

Using the install script

Pass the b64-tar-package value to the install script with --cert. The script extracts the files to the state directory and appends the correct auth-authentication block to supd.conf automatically:

curl -s https://api.example.your-company.avassa.net/install | \
  sudo /bin/sh -s -- --cert "<b64-tar-package>"

Manual configuration

If you are not using the install script, copy the credential files to the edge host and reference them in supd.conf. The files can be placed anywhere readable by supd; /var/lib/supd/state/ is the conventional location.

You also need the API CA certificate so the host can verify the Control Tower's identity. Fetch it with:

supctl -S do strongbox tls ca api-root get-ca-cert | jq -r '.cert' > api-ca.pem

supd.conf for x509 credentials

host-id: "d6785b90-df4c-4008-888d-2d56e68decdf"
initial-site-config:
  call-home-servers:
    - api.example.your-company.avassa.net
  api-ca-cert: |
    -----BEGIN CERTIFICATE-----
    <contents of api-ca.pem>
    -----END CERTIFICATE-----
  host-authentication:
    x509-cert-file: /var/lib/supd/state/cert.pem
    x509-key-file: /var/lib/supd/state/cert.key

Security properties

Certificate revocation checking

The Control Tower validates the full certificate chain against current Certificate Revocation Lists (CRLs) on every host-init request:

• The intermediate CA certificate submitted in the chain is checked against the api-root CA's CRL.
• The host certificate is checked against the intermediate CA's CRL (<control-tower-name>-api-inter).

If any certificate in the chain is revoked, or if the relevant CRL cannot be retrieved from Strongbox, the host-init request is rejected with 403.

Credential theft protection

Each credential is bound to a specific host-id, so a stolen credential cannot be used to onboard a host with a different identity. The host-id is not stored directly in the certificate, insead a hash of the host-id is stored in base64 encoded form. This is to prevent someone gaining access to a certificate from also knowing the host-id.

With the default verify: host-id, the certificate's CN and SAN are set to the the hashed host-id. The Control Tower verifies that the certificate identity matches the host-id in the host-init request. The host must also prove possession of the private key by signing the server-issued nonce, so the credential alone is not sufficient — the private key must be compromised too.

note

The site and certificate-only identity policies provide weaker host binding: any host in the same site, or any host with a valid CA-issued certificate, can use the credential. Use host-id (the default) when each host should have its own credential.

Notes

• TTL: Use the shortest TTL convenient for your deployment pipeline. It is always possible to reissue credentials if the host has not yet called home.
• Serial number: The serial field in the issue-call-home-cert output is the certificate's serial number in the issuing CA's revocation list. It is recorded in the system:audit-trail-log Volga topic.
• Retry behaviour: If the Control Tower rejects the challenge (for example because the credential has expired or been revoked), the host will wait and then retry with fresh credentials read from disk. You can replace credential files while supd is running and the new credentials will be picked up on the next retry.