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.
Key roles
Section titled “Key roles”| 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.
PKCS#12
Section titled “PKCS#12”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.
PKCS#11 and SoftHSM
Section titled “PKCS#11 and SoftHSM”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.
Optional issued document credentials
Section titled “Optional issued document credentials”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.
Failure behavior
Section titled “Failure behavior”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.
Rotation and backup
Section titled “Rotation and backup”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.