Cryptographic Material

Some Unifiers, which finalize the successful execution of the pipeline, can generated signed objects, like a JWT, to be forwarded to the upstream services. In such cases Heimdall acts as an issuer of such objects and needs at least corresponding key material.

Configuration

The configuration related to the issuance of signed objects can be done using the signer property, which resides on the top level of heimdall’s configuration and supports the following properties.

name: string (optional)
The name used to specify the issuer. E.g. if a JWT is generated, this value is used to set the iss claim. If not set, the value heimdall is used.
key_store: string (optional)
Path to a file in PEM format, containing the cryptographic material for signature creation purposes. If this file is specified, at least one private key must be present.
If the PEM file contains X.509 certificates in addition to the keys, heimdall will try to identify a certificate (incl its chain) for each private key (the order of the certificates doesn’t matter). If heimdall was able to identify the certificate chain, the chain is validated, which includes cryptographic validity, time validity, as well as whther the certificate attributes the private key for creation of digital signatures.
PKCS#1, as well as PKCS#8 encodings are supported for private keys. If key_store is not specified, heimdall generates an RSA key on startup.
While loading cryptographic material from the given key store file, heimdall ensures uniqueness of key ids and rejects key store files which violate this condition (see also Key-Id Lookup).
password: string (optional)
If the key material is protected with a password, this property can be set to decipher it.
Password protection is only supported for PKCS#8 encoded keys.
If the PEM file contains multiple keys and these keys are password protected, same password must be used for all of these.
key_id: string (optional)
If the key_store references a PEM file, containing multiple keys, this property can be used to specify the key to use (see also Key-Id Lookup). If not specified, the first key is used. If specified, but there is no key for the given key id present, an error is raised.

Example 1. Possible configuration

Imagine you have a PEM file located in /opt/heimdall/keystore.pem with the following contents:

Then you can configure heimdall to use it like follows:

signer:
  name: foobar
  key_store: /opt/heimdall/keystore.pem
  key_id: foo

Last updated on Dec 23, 2022

Rule Providers

Configuration Types