Rotate certificates and secrets

What	Lifetime	Rotation impact
NATS server certificate	2 years	New CA too; every agent downloads it again
NATS CA	10 years	Same
Token pepper	Until you change it	Two-step; no outage if done right
Device connect-secret	Until you re-enroll	One firewall at a time
Hourly device pass	1 hour	Automatic
API tokens	Your choice	Per token
Delegated signing key	External mode only	Restart pfCentral

NATS CA and server certificate

pfCentral does not keep the CA’s private key after it signs the server certificate. To renew the certificate you make a new CA, so agents must trust the new one.

Put a calendar reminder about a month before the server certificate expires:

openssl x509 -noout -enddate -in <state>/nats/tls/server.crt

1. Stop the server and delete state/nats/tls/.
2. If needed, update PFCENTRAL_NATS_TLS_HOSTS.
3. Start the server. It makes a new CA and certificate and serves the new CA at /nats-ca.crt.
4. On every firewall, open Services → pfCentral → Settings and click Save (with NATS CA on Automatic). The package downloads the new CA and restarts the agent. Firewalls are offline in pfCentral between steps 3 and 4.

To script step 4, run on each firewall:

fetch -o /usr/local/etc/nats-agent/ca.crt https://pf.example.com/nats-ca.crt && service nats_agent restart

Token pepper

The pepper is mixed into every stored hash: device connect-secrets, API tokens, and one-time tokens. pfCentral accepts every pepper listed in PFCENTRAL_TOKEN_PEPPER_VERSIONS when checking, and uses PFCENTRAL_TOKEN_PEPPER_CURRENT for new hashes.

Danger

Never remove the old pepper from _VERSIONS while devices or API tokens still use hashes made with it. If you do, every firewall and every API token stops authenticating at once.

To rotate:

1. Add the new value and make it current, keeping the old one in the list (separated by ;):

   PFCENTRAL_TOKEN_PEPPER_CURRENT=new-value
   PFCENTRAL_TOKEN_PEPPER_VERSIONS=old-value;new-value

2. Restart. Existing secrets keep working with the old pepper. Open one-time tokens (setup, enrollment, invite, reset links) stop working; issue new ones.

3. Over time, re-enroll firewalls and re-create API tokens so their hashes use the new pepper. Remove the old value from _VERSIONS only after all of them are done.

Device secrets

A firewall’s connect-secret changes when it enrolls again. Make an unbound token (pf-central admin enroll token), paste it in Services → pfCentral → Settings on the firewall, and Save. The firewall reconnects with the new secret within seconds.

API tokens

Create the new token, update your script, then Revoke the old token in API Tokens. A password reset revokes all of that member’s tokens.

Sessions

Disabling a member, or resetting their password, ends their sessions at their next request.