Skip to content

Table: federation_user_keys

Per-user X25519 key pairs used for NaCl-box payload encryption in federation (ADR 0049). The private key is encrypted at rest with the host master key. Whether a given delivery is encrypted depends on what the peer has negotiated and on the recipient’s key being available; see ArchivePub.

This table references:

  • user(ref) via column user_ref
  • user(ref) via column rotated_by_user_ref
ColumnTypeNullableNotes
user_refbigintnoReferences user(ref)
versionintegerno-
algorithmtextnoDefault 'naclbox-x25519-v1'::text. Algorithm token. naclbox-x25519-v1 is the only value today; a new algorithm would add a token without a schema change.
public_keybyteano-
private_key_encbyteano-
is_currentbooleannoMarks the user’s current key. The partial unique index federation_user_keys_one_current_idx permits at most one current row per user (defined outside the CREATE TABLE statement below).
created_attimestampnoDefault now()
retained_untiltimestampyesHow long a rotated-out key is kept for decrypting inbound envelopes. NULL on the current key; set to the rotation time plus a grace period when a key is rotated out.
rotated_attimestampyesWhen the rotation that created or retired this row happened. Set on both the new current key and the key it replaced; NULL on rows created before rotations were recorded.
rotated_by_user_refbigintyesReferences user(ref). Who triggered the rotation: the account owner for a self-service rotation, or an administrator recovering a compromised key. NULL on rows created before rotations were recorded.
  • CONSTRAINT federation_user_keys_current_xor_retained CHECK ((((is_current = true) AND (retained_until IS NULL)) OR ((is_current = false) AND (retained_until IS NOT NULL))))
  • CONSTRAINT federation_user_keys_private_key_enc_check CHECK ((octet_length(private_key_enc) >= 13))
  • CONSTRAINT federation_user_keys_public_key_check CHECK ((octet_length(public_key) = 32))
  • CONSTRAINT federation_user_keys_version_check CHECK ((version >= 1))

This is the table’s CREATE TABLE statement. Constraints added with separate ALTER TABLE statements, including foreign-key ON DELETE rules, and indexes are defined elsewhere in the dump; see the complete app/schema.sql.

CREATE TABLE public.federation_user_keys (
user_ref bigint NOT NULL,
version integer NOT NULL,
algorithm text DEFAULT 'naclbox-x25519-v1'::text NOT NULL,
public_key bytea NOT NULL,
private_key_enc bytea NOT NULL,
is_current boolean NOT NULL,
created_at timestamp with time zone DEFAULT now() NOT NULL,
retained_until timestamp with time zone,
rotated_at timestamp with time zone,
rotated_by_user_ref bigint,
CONSTRAINT federation_user_keys_current_xor_retained CHECK ((((is_current = true) AND (retained_until IS NULL)) OR ((is_current = false) AND (retained_until IS NOT NULL)))),
CONSTRAINT federation_user_keys_private_key_enc_check CHECK ((octet_length(private_key_enc) >= 13)),
CONSTRAINT federation_user_keys_public_key_check CHECK ((octet_length(public_key) = 32)),
CONSTRAINT federation_user_keys_version_check CHECK ((version >= 1))
);

See the schema overview for context.