Skip to content

Fortified IDDocs

Key management

Configure PKCS#12 and PKCS#11 document keys, including SoftHSM, and keep the signing key separate from transport keys.

The document signing key is the key that signs on behalf of signers or the organization. It stays inside the selected crypto backend and is never exported. Supplied credentials, explicitly activated provisioned credentials and optional per-transaction dynamic credentials have separate lifecycles; the server never silently replaces a failed key or falls back to another backend.

Role Used for
Document key Signing documents.
TLS The server's HTTPS identity in direct mode.
SAML signing Signed requests to the identity provider.
SAML decryption Decrypting responses from the identity provider.
DSS envelope Signing responses to requesting systems.

All roles must be different keys. Startup compares the actual public keys, and different certificates for the same key do not count as separate. It also checks validity, usage, chain consistency, file permissions and a real signing operation with a random challenge before the listener binds.

Set signing.backend to pkcs12 and supply keystore (file, password_file, alias) and a credential reference. The credential name is what the bindings in the identity provider configuration refer to. It is never derived from a file or alias name.

Set signing.backend to pkcs11 for a key in a PKCS#11 token. The supported module is SoftHSM 2.7 in its non-FIPS form. Other modules, versions and hardware security modules need to be verified in your environment.

Property Description
module_file The native PKCS#11 module.
module_sha256 The lowercase SHA-256 of the exact module. The server refuses a module with a different hash.
configuration_file The protected SoftHSM configuration. SOFTHSM2_CONF for the service must be an absolute path to this same file.
token_label Exactly one initialized token must carry this label. The server never takes the first slot.
key_label The label of the signing key.
pin_file The protected file with the token PIN.
credential The credential reference used by the bindings.

The SoftHSM configuration uses an absolute directories.tokendir with the file object store, umask 0077, ERROR logging and non-removable slots. For a supplied static credential, initialize the token and generate the key with your own tooling. Optional enrollment and dynamic signing use their separately configured key-generation and lifecycle policies inside the crypto boundary.

Protect the configuration and PIN files with mode 0400 or 0600 and the token directories with 0700 and 0600, or equivalent Windows ACLs. The module and its parent directories must be owned by the service account or root and must not be writable by group or others. Symlinks and broadly writable modules are rejected. Stage the module and its native dependencies in a protected installation directory rather than loosening permissions on a package manager directory.

The token PIN is never passed in a command line, JSON or environment variable.

The provisioned selection uses an explicitly activated, pinned descriptor. The dynamic human selection creates a new key and certificate after verified identification for each transaction, with retirement and no cross-transaction reuse. These selections do not replace TLS, SAML or envelope keys. The selected XAdES/JAdES profiles require a preknown static leaf, and CSC accepts its configured supplied static directory. See External PKI and certificate issuance.

A missing or invalid configuration, PIN, module hash, token, key, chain or permission stops startup with a fixed code that contains no values. Readiness watches the module and configuration fingerprints, the token state and the key and certificate identity. If the native session is lost, signing becomes unavailable, and restarting with the correct protected setup recovers the service. Recovery never makes consumed signing authority usable again.

Back up the database, the configuration and the key or token material together, and record the public key identities first. A copy of a token alone does not prove that a restored database is current. To rotate a key, change the credential and the bindings through your approved procedure, and make sure that an old or inconsistent key and schema is not silently accepted.