Key Rotation

Overview

SemaFore uses two key rotation mechanisms to enforce periodicity and replenish ephemeral key material. Signed Pre-Key expiry is enforced by the server, and mobile clients rotate expired keys automatically. One-Time Pre-Key replenishment is asynchronous and preserves delivery when a device has been offline.

Signed Pre-Key (SPK) Rotation

Trigger

The SPK is rotated when it exceeds the permitted key age. The server enforces this maximum age for new session initiation.

Procedure

When rotation is triggered:

1. Device generates new key pair: The device creates a new Curve25519 key pair
2. Device signs the public key: Using its Identity Key private key, the device signs the new SPK public key with Ed25519
3. Device updates its key bundle: The device uploads the new public key and signature to the server
4. Server stores and retains old key: The server stores the new SPK as the current active key and retains the previous SPK in the database for a grace period

Grace Period

For a limited grace period after rotation, the previous SPK remains available in the server’s key bundle responses. This allows sessions already in progress to complete:

In-flight sessions: If a sender initiated an X3DH session with the recipient’s old SPK just before rotation occurred, the sender’s first message will reach the recipient using that old SPK in the header. The recipient’s Double Ratchet will process the message correctly because the SPK used in the X3DH computation is still available. Without the grace period, recipients would reject valid messages that used the previous SPK.

After the grace period expires, the previous SPK is deleted and no longer returned in key bundle lookups.

Expiry Enforcement

If a device’s SPK exceeds the permitted key age, the server refuses new session initiation and notifies the device that rotation is required. The mobile client generates and uploads a replacement SPK automatically. There is no manual key-management action, recovery code or portal step. Sessions that are already established continue through the Double Ratchet; new initiators retry after rotation.

One-Time Pre-Key (OPK) Replenishment

Trigger

The server monitors the supply of available OPK public keys for each device and requests replenishment when it runs low.

Notification and Response

The server notifies the device that more OPKs are needed. The device responds by:

1. Generating a new batch: The device creates a new batch of Curve25519 key pairs
2. Uploading public keys: The device calls the key-bundle publish endpoint to upload the new batch
3. Retaining keys until use: Private OPKs remain on the device until used, then are deleted

Replenishment is best-effort and asynchronous. If the device is offline, the notification is not queued—the device will receive it upon reconnection.

Graceful Degradation

If a device is offline and other users attempt to initiate sessions with it, the server will consume the device’s remaining OPKs. If the OPK supply is exhausted while the device remains offline:

• X3DH continues with 3 DH operations: Senders will establish sessions using only DH1, DH2, and DH3, omitting the DH4 operation with the missing OPK
• No message loss: Messages are delivered normally; X3DH simply uses the three-key variant
• Upon reconnection: The device receives a replenishment notification and uploads a new batch

This graceful degradation means offline devices do not accumulate a backlog of undelivered messages—messages are encrypted to the three-key variant and delivered immediately.

Summary

Both rotation mechanisms are transparent to users. The server enforces SPK rotation to ensure periodic re-keying; OPK replenishment is automatic and preserves delivery even if the device is offline.