Matrix Signing Key Rotation Needs Publishing and Retention

Matrix homeservers sign events and federation requests with a server signing key. Rotation is not only a file replacement. Other servers need to learn the new public key, and during a transition they may still need an older key to verify events that were signed before the change.

The signing key has two jobs

Synapse documentation identifies the signing key as the material used to sign events and federation requests. The matching public key is published for verification. A new key changes the identity material that remote servers use when they validate your server's traffic.

If the old public key disappears from the published set too early, a peer may reject a valid historical event. If the new key is published before the private key is used consistently, the server can advertise a key it does not yet sign with. Either state makes federation failures look like a remote server problem when the local key lifecycle is the cause.

Plan the overlap

Record the current key identifier and public key before the change. Decide how long old keys remain available for verification. Include events already in the room history and requests that may be in transit. Coordinate the change with the people who operate federation endpoints and backups.

Synapse's configuration documentation describes verify_keys for explicitly trusted verification keys and the relationship between that setting and the key server. A deployment that uses certificate verification or a custom trust configuration should be tested against the same path it uses in production. Do not assume that a key fetched from a server is trusted merely because the TLS connection succeeded.

Inspect the effective configuration

Run the configuration parser for the installed Synapse version and confirm which signing key path is active. Check that the file is readable by the service account and not by unrelated users. Back it up with access controls appropriate to a private key.

After the new key is active, inspect the server key endpoint from a remote test host. Confirm that the new public key is present and that the old key remains available for the planned overlap. Test a new event and an existing event that was signed earlier if the deployment has a safe way to do so.

Use the documented operational tools

The admin API's background-update documentation lists an event_resign operation for re-signing locally sent events with the current signing key after rotation. Treat that as a high-impact maintenance action. Review the command against the installed version, back up the database and configuration, and test on a copy first.

A re-sign job needs a documented compatibility reason. Establish whether your federation peers need old keys for verification, how long the event history must remain compatible, and whether any clients or bridges cache key material.

Failure signs

Watch federation logs for signature verification failures after the change. A remote server that cannot fetch the new key may return a key-server error. A local server that cannot load the private key may fail at startup. A partial rollout across workers can produce a period where different workers sign with different material.

Use one recorded change window, one test peer, and one clear rollback file. After the overlap period, remove old keys only when the retention decision is documented. The endpoint should publish the minimum set needed for current and historical verification, and the private key should never appear in a public endpoint or diagnostic dump.

References

• Synapse configuration documentation
• Synapse background updates