Skip to content

Database-Managed Signing Options

The following signing options are stored in the database and managed via the Admin API, lhsetup, or lhmigrate config2db. They are not set in the config file.

The static signing options (KMS, public key backend, filesystem/PKCS#11 configuration) remain in the config file.

Signing Algorithm (alg)

enum ES512

The signing algorithm to use for Entity Configurations, Entity Statements, and Trust Marks.

Supported Values

ECDSA

  • ES256, ES384, ES512

secp256k1

  • ES256K

EdDSA (RFC 9864)

  • Ed25519 (curve-specific, recommended over EdDSA)
  • Ed448
  • EdDSA (deprecated polymorphic form; resolves to Ed25519 — prefer Ed25519)

RSA

  • RS256, RS384, RS512 (RSASSA-PKCS1-v1_5)
  • PS256, PS384, PS512 (RSASSA-PSS)

ML-DSA (FIPS 204, post-quantum)

  • ML-DSA-44, ML-DSA-65, ML-DSA-87

Composite (PQC-hybrid) signatures

  • ML-DSA-44-ES256, ML-DSA-65-ES256, ML-DSA-87-ES384 (ML-DSA + ECDSA)
  • ML-DSA-44-Ed25519, ML-DSA-65-Ed25519, ML-DSA-87-Ed448 (ML-DSA + EdDSA)

Management

Tool Command
Admin API GET /api/v1/admin/kms (KMS info) | PUT /api/v1/admin/kms/alg
lhsetup lhsetup --only=alg
config2db lhmigrate config2db --only=alg

RSA Key Length (rsa_key_len)

integer 2048

The RSA key length (in bits) used when generating RSA-based signing keys. Only relevant when the signing algorithm is RSA-based (RS* or PS*).

Management

Tool Command
Admin API GET /api/v1/admin/kms (KMS info) | PUT /api/v1/admin/kms/rsa-key-len
lhsetup lhsetup --only=rsa_key_len
config2db lhmigrate config2db --only=rsa_key_len

Key Rotation (key_rotation)

object / mapping

Configuration for automatic signing key rotation. When enabled, LightHouse generates new signing keys according to the configured interval and publishes both current and next public keys.

enabled

boolean false

Enables automatic key rotation.

interval

duration ~1 week

The interval at which keys are rotated. This defines the lifetime of each key.

Warning

The interval should not be smaller than the lifetime of Entity Configurations, Entity Statements, Trust Marks, or other JWTs signed with the federation key.

overlap

duration 1 hour

The overlap period between the current and next key. During this window both keys will be valid, and LightHouse transitions to using the new key (somewhere in the middle of the period).

key_announcement_lead_time

duration max(5 × entity configuration lifetime, 24h)

The key announcement lead time controls how far in advance a new key is published in the JWKS before it becomes the active signing key. This gives clients time to fetch the updated entity configuration and cache the new key before the old key is retired.

The effective lead time is resolved as follows:

  1. If key_announcement_lead_time_ec_multiplier > 0: multiplier × entity configuration lifetime.
  2. If key_announcement_lead_time > 0: the fixed duration.
  3. Default: max(5 × entity configuration lifetime, 24h).

The result is clamped to a minimum of the entity configuration lifetime; if the configured value is shorter, the EC lifetime is used instead and a warning is logged.

Info

In the past the key announcement lead time was set to one entity configuration lifetime. This is only enough if all clients always fetch the entity configuration as soon as it expires — an unrealistic assumption. Set the lead time to a larger value in production.

key_announcement_lead_time_ec_multiplier

float 0

Multiplier for the entity configuration lifetime to compute the announcement lead time. Takes precedence over key_announcement_lead_time if set (> 0).

Management

Tool Command
Admin API GET/PUT/PATCH /api/v1/admin/kms/rotation
Admin API POST /api/v1/admin/kms/rotate (manual trigger)
lhsetup lhsetup --only=key_rotation
config2db lhmigrate config2db --only=key_rotation