Skip to content

Signing

required

Under the signing config option the key management and signatures are configured.

In LightHouse >= 0.20.0 some options (like alg, rsa_key_len, and key_rotation) are stored in the database and can be managed via the Admin API. Use lhmigrate config2db to migrate these values from a config file.

kms

enum required LH_SIGNING_KMS

The kms option specifies which Key Management System to use for private key storage.

Supported values:

  • filesystem - Keys stored on the filesystem
  • pkcs11 - Keys stored in a Hardware Security Module (HSM) via PKCS#11
config.yaml 
signing:
    kms: filesystem
    filesystem:
        key_dir: /path/to/keys

pk_backend

enum db optional LH_SIGNING_PK_BACKEND

The pk_backend option specifies where public keys are stored.

Supported values:

  • db - Public keys stored in the database (default, recommended)
  • filesystem - Public keys stored on the filesystem
config.yaml 
signing:
    kms: filesystem
    pk_backend: db
    filesystem:
        key_dir: /path/to/keys

auto_generate_keys

boolean true optional LH_SIGNING_AUTO_GENERATE_KEYS

When set to true, LightHouse will automatically generate signing keys at startup if they don't exist. When set to false, LightHouse will exit with an error if the required private key is not present.

config.yaml 
signing:
    kms: filesystem
    auto_generate_keys: false
    filesystem:
        key_dir: /path/to/keys

filesystem

object / mapping required when kms=filesystem or pk_backend=filesystem

Configuration for the filesystem Key Management System.

config.yaml 
signing:
    kms: filesystem
    filesystem:
        key_dir: /var/lib/lighthouse/keys

key_dir

directory path required for kms=filesystem LH_SIGNING_FILESYSTEM_KEY_DIR

The key_dir option specifies the path to a directory that contains the private signing key(s). Keys are stored using the naming convention <kid>.pem.

config.yaml 
signing:
    kms: filesystem
    filesystem:
        key_dir: /var/lib/lighthouse/keys

key_file

file path optional LH_SIGNING_FILESYSTEM_KEY_FILE

The key_file option can be used as an alternative to key_dir if only a single signing key is used and no key rotation happens. We recommend to use key_dir instead.

pkcs11

object / mapping required when kms=pkcs11

Configuration for PKCS#11 Hardware Security Module (HSM) integration.

config.yaml 
signing:
    kms: pkcs11
    pkcs11:
        module_path: /usr/lib/softhsm/libsofthsm2.so
        token_label: lighthouse
        pin: "1234"
        storage_dir: /var/lib/lighthouse/pkcs11

module_path

file path required LH_SIGNING_PKCS11_MODULE_PATH

Path to the PKCS#11 module (shared library) provided by your HSM vendor.

Common paths:

  • SoftHSM2: /usr/lib/softhsm/libsofthsm2.so
  • AWS CloudHSM: /opt/cloudhsm/lib/libcloudhsm_pkcs11.so
  • YubiHSM: /usr/lib/x86_64-linux-gnu/pkcs11/yubihsm_pkcs11.so

token_label

string required (one of token_label, token_serial, or token_slot) LH_SIGNING_PKCS11_TOKEN_LABEL

Selects the HSM token by its label.

token_serial

string required (one of token_label, token_serial, or token_slot) LH_SIGNING_PKCS11_TOKEN_SERIAL

Selects the HSM token by its serial number.

token_slot

integer required (one of token_label, token_serial, or token_slot) LH_SIGNING_PKCS11_TOKEN_SLOT

Selects the HSM token by its slot number.

pin

string required (unless no_login is true) LH_SIGNING_PKCS11_PIN

The user PIN for authenticating to the HSM token.

storage_dir

directory path optional LH_SIGNING_PKCS11_STORAGE_DIR

Directory for storing PKCS#11-related metadata.

max_sessions

integer optional LH_SIGNING_PKCS11_MAX_SESSIONS

Maximum number of concurrent PKCS#11 sessions to open. Must be at least 2 if specified.

user_type

integer optional LH_SIGNING_PKCS11_USER_TYPE

User type for PKCS#11 login. Usually left at default.

no_login

boolean false optional LH_SIGNING_PKCS11_NO_LOGIN

Set to true for HSM tokens that do not support or require login.

label_prefix

string optional LH_SIGNING_PKCS11_LABEL_PREFIX

Optional prefix for object labels inside the HSM.

load_labels

list of strings optional LH_SIGNING_PKCS11_LOAD_LABELS

HSM object labels to load into this KMS even if they are not yet present in the public key storage.

For environment variables, use comma-separated values: LH_SIGNING_PKCS11_LOAD_LABELS="key1,key2"

Database-Managed Options

The following options are stored in the database and can be managed via the Admin API. These config file options are deprecated and ignored at runtime. Use lhmigrate config2db to migrate values from your config file to the database.

alg

enum ES512 deprecated

The signing algorithm to use.

Supported values:

  • ES256, ES384, ES512 (ECDSA)
  • EdDSA (Ed25519)
  • RS256, RS384, RS512 (RSA PKCS#1)
  • PS256, PS384, PS512 (RSA PSS)

Deprecated - Database-managed

This config file option is deprecated and ignored at runtime. Use:

  • lhmigrate config2db --only=alg to migrate from config file
  • Admin API to view/change the value

rsa_key_len

integer 2048 deprecated

The RSA key length when generating RSA-based signing keys.

Deprecated - Database-managed

This config file option is deprecated and ignored at runtime. Use:

  • lhmigrate config2db --only=rsa_key_len to migrate from config file
  • Admin API to view/change the value

key_rotation

object / mapping deprecated

Configuration for automatic key rotation.

Deprecated - Database-managed

This config file option is deprecated and ignored at runtime. Use:

  • lhmigrate config2db --only=key_rotation to migrate from config file
  • Admin API to view/change the value
Legacy config.yaml (for migration only) 
signing:
    key_rotation:
        enabled: true
        interval: 30d
        overlap: 1h

enabled

boolean false

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

interval

duration ~1 week

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

Note

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, LightHouse transitions to using the new key while the old key's public key is still published.

Complete Examples

Filesystem KMS with database public keys (Recommended) 
signing:
    kms: filesystem
    pk_backend: db
    auto_generate_keys: true
    filesystem:
        key_dir: /var/lib/lighthouse/keys
PKCS#11 HSM (SoftHSM2) 
signing:
    kms: pkcs11
    pk_backend: db
    auto_generate_keys: true
    pkcs11:
        module_path: /usr/lib/softhsm/libsofthsm2.so
        token_label: lighthouse
        pin: "1234"
        storage_dir: /var/lib/lighthouse/pkcs11