Skip to content

Signing

required

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

Some signing options (signing algorithm, RSA key length, key rotation, and key announcement lead time) are stored in the database and managed via the Admin API, lhsetup, or lhmigrate config2db. See Database-Managed Signing Options for details.

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
  • db - Keys stored in the database
Filesystem KMS (default) 
signing:
    kms: filesystem
    filesystem:
        key_dir: /path/to/keys
Database-backed KMS 
signing:
    kms: db
    pk_backend: db
    auto_generate_keys: true

Migration from Filesystem KMS

To migrate existing filesystem-based private keys to the database, use: 

lhmigrate pem-to-db --source /path/to/kms/dir --type federation --db-dsn /path/to/db.sqlite

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"

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