Config file location
PyHanko reads its configuration from a YAML file.
By default, if a file named
pyhanko.yml exists in the current directory,
pyHanko will attempt to read and process it.
You can manually specify a configuration file location via the
Note that a configuration file is usually not required, although some of pyHanko’s behaviour cannot be fully customised using command line options. In these cases, the configuration must be sourced from a config file.
logging key in the configuration file, you can set up the
configuration for Python’s logging module.
Here’s an example.
logging: root-level: ERROR root-output: stderr by-module: pyhanko_certvalidator: level: DEBUG output: pyhanko_certvalidator.log pyhanko.sign: level: DEBUG
root-ouput allow you to set the log level
and the output stream (respectively) for the root logger.
The default log level is
INFO, and the default output stream is
The keys under
by-module allow you to specify more granular
per-module logging configuration. The
level key is mandatory in this case.
pyhanko is invoked with
--verbose, the root logger will have its
log level set to
DEBUG, irrespective of the value specified
in the configuration.
Named validation contexts
Validation contexts can be configured under the
The example below defines two validation configs named
validation-contexts: default: other-certs: some-cert.pem.cert special-setup: trust: customca.pem.cert trust-replace: true other-certs: some-cert.pem.cert
The parameters are the same as those used to define validation contexts in the CLI. This is how they are interpreted:
trust: One or more paths to trust anchor(s) to be used.
trust-replace: Flag indicating whether the
trustsetting should override the system trust (default
other-certs: One or more paths to other certificate(s) that may be needed to validate an end entity certificate.
The certificates should be specified in DER or PEM-encoded form. Currently, pyHanko can only read trust information from files on disk, not from other sources.
Selecting a named validation context from the CLI can be done using the
Applied to the example from here, this is how
pyhanko sign addsig --field Sig1 --timestamp-url http://tsa.example.com \ --with-validation-info --validation-context special-setup \ --use-pades pemder --key key.pem --cert cert.pem input.pdf output.pdf
In general, you’re free to choose whichever names you like.
However, if a validation context named
default exists in the configuration
file, it will be used implicitly if
--validation-context is absent.
You can override the name of the default validation context using
default-validation-context top-level key, like so:
default-validation-context: setup-a validation-contexts: setup-a: trust: customca.pem.cert trust-replace: true other-certs: some-cert.pem.cert setup-b: trust: customca.pem.cert trust-replace: false
Time drift tolerance
Changed in version 0.5.0: Allow overriding the global value locally.
By default, pyHanko allows a drift of 10 seconds when comparing times.
This value can be overridden in two ways: using the top-level
configuration option, or by setting
time-tolerance in a
named validation context.
Given the example config below, using
setup-a would set the time drift
tolerance to 180 seconds. Since the global
is set to 30 seconds, this value would be used with
setup-b, or with
any trust settings specified on the command line.
time-tolerance: 30 validation-contexts: setup-a: time-tolerance: 180 trust: customca.pem.cert trust-replace: true other-certs: some-cert.pem.cert setup-b: trust: customca.pem.cert trust-replace: false
Allow revocation information to apply retroactively
New in version 0.5.0.
pyhanko-certvalidator applies OCSP and CRL validity windows
very strictly. For an OCSP response or a CRL to be considered valid,
the validation time must fall within this window. In other words, with the
default settings, an OCSP response fetched at some later date does not count
for the purposes of establishing the revocation status of a certificate used
with an earlier signature.
However, pyHanko’s conservative default position is often more strict than
what’s practically useful, so this behaviour can be overridden with a
configuration setting (or the
--retroactive-revinfo command line flag).
In the example config below,
retroactive-revinfo is set to
globally, but to
In either case, the
--retroactive-revinfo flag can override this setting.
retroactive-revinfo: true validation-contexts: setup-a: retroactive-revinfo: false trust: customca.pem.cert trust-replace: true other-certs: some-cert.pem.cert setup-b: trust: customca.pem.cert trust-replace: false
Named PKCS#11 setups
New in version 0.7.0.
Since the CLI parameters for signing files with a PKCS#11 token can get quite verbose, you might
want to put the parameters in the configuration file. You can declare named PKCS#11 setups under the
pkcs11-setups top-level key in pyHanko’s configuration. Here’s a minimal example:
pkcs11-setups: test-setup: module-path: /usr/lib/libsofthsm2.so token-criteria: label: testrsa cert-label: signer
If you need to, you can also put the user PIN right in the configuration:
pkcs11-setups: test-setup: module-path: /usr/lib/libsofthsm2.so token-criteria: label: testrsa cert-label: signer user-pin: 1234
If you do this, you should obviously take care to keep your configuration file in a safe place.
To use a named PKCS#11 configuration from the command line, invoke pyHanko like this:
pyhanko sign addsig pkcs11 --p11-setup test-setup input.pdf output.pdf
Named PKCS#11 setups also allow you to access certain advanced features that otherwise aren’t available from the CLI directly. Here is an example.
pkcs11-setups: test-setup: module-path: /path/to/module.so token-criteria: serial: 17aa21784b9f cert-id: 1382391af78ac390 key-id: 1382391af78ac390
This configuration will select a token based on the serial number instead of the label, and use PKCS#11 object IDs to select the certificate and the private key. All of these are represented as hex strings.
For a full overview of the parameters you can set on a PKCS#11 configuration, see the API reference
--p11-setup argument to
pkcs11 will cause pyHanko to ignore all other
parameters to the
pkcs11 subcommand. In other words, you have to put everything in the
Named setups for on-disk key material
New in version 0.8.0.
Starting from version 0.8.0, you can also put parameters for on-disk key material into the
configuration file in much the same way as for PKCS#11 tokens (see Named PKCS#11 setups above).
This is done using the
pemder-setups top-level keys, depending on whether
the key material is made available as a PKCS#12 file, or as individual PEM/DER-encoded files.
Here are some examples.
pkcs12-setups: foo: pfx-file: path/to/signer.pfx other-certs: path/to/more/certs.chain.pem pemder-setups: bar: key-file: path/to/signer.key.pem cert-file: path/to/signer.cert.pem other-certs: path/to/more/certs.chain.pem
For non-interactive use, you can also put the passphrase into the configuration file (again, take care to set up your file access permissions correctly).
pkcs12-setups: foo: pfx-file: path/to/signer.pfx other-certs: path/to/more/certs.chain.pem pfx-passphrase: secret pemder-setups: bar: key-file: path/to/signer.key.pem cert-file: path/to/signer.cert.pem other-certs: path/to/more/certs.chain.pem key-passphrase: secret
On the command line, you can use these named setups like this:
pyhanko sign addsig pkcs12 --p12-setup foo input.pdf output.pdf pyhanko sign addsig pemder --pemder-setup bar input.pdf output.pdf
For a full overview of the parameters you can set in these configuration dictionaries,
see the API reference documentation for
Key usage settings
New in version 0.5.0.
There are two additional keys that can be added to a named validation context:
signer-extd-key-usage. Both either take a string argument, or an array of strings.
These define the necessary key usage (resp. extended key usage) extensions that need to be present
in signer certificates.
signer-key-usage, the possible values are as follows:
We refer to § 126.96.36.199 in RFC 5280 for an explanation of what these values mean. By default,
pyHanko requires signer certificates to have at least the
non_repudiation extension, but you may
want to change that depending on your requirements.
Values for extended key usage extensions can be specified as human-readable names, or as OIDs.
The human-readable names are derived from the names in
asn1crypto. If you need a key usage extension that doesn’t appear in the list, you can specify
it as a dotted OID value instead. By default, pyHanko does not require any specific extended key
usage extensions to be present on the signer’s certificate.
This is an example showcasing key usage settings for a validation context named
validation-contexts: setup-a: trust: customca.pem.cert trust-replace: true other-certs: some-cert.pem.cert signer-key-usage: ["digital_signature", "non_repudiation"] signer-extd-key-usage: ["code_signing", "2.999"]
These key usage settings are mainly intended for use with validation, but are also checked when signing with an active validation context.
Styles for stamping and signature appearances
In order to use a style other than the default for a PDF stamp or (visible)
signature, you’ll have to write some configuration.
New styles can be defined under the
stamp-styles top-level key.
Here are some examples:
stamp-styles: default: type: text background: __stamp__ stamp-text: "Signed by %(signer)s\nTimestamp: %(ts)s" text-box-style: font: NotoSerif-Regular.otf noto-qr: type: qr background: background.png stamp-text: "Signed by %(signer)s\nTimestamp: %(ts)s\n%(url)s" text-box-style: font: NotoSerif-Regular.otf leading: 13
To select a named style at runtime, pass the
--style-name parameter to
addsig (when signing) or
stamp (when stamping).
As was the case for validation contexts, the style named
default will be
chosen if the
--style-name parameter is absent.
Similarly, the default style’s name can be overridden using the
default-stamp-style top-level key.
Let us now briefly go over the configuration parameters in the above example. All parameters have sane defaults.
type: This can be either
qr, for a simple text box or a stamp with a QR code, respectively. The default is
text. Note that QR stamps require the
--stamp-urlparameter on the command line.
background: Here, you can specify any of the following:
a path to a bitmap image;
a path to a PDF file (the first page will be used as the stamp background);
the special value
__stamp__, which will render a simplified version of the pyHanko logo in the background of the stamp (using PDF graphics operators directly).
When using bitmap images, any file format natively supported by Pillow should be OK. If not specified, the stamp will not have a background.
stamp-text: A template string that will be used to render the text inside the stamp’s text box. Currently, the following variables can be used:
signer: the signer’s name (only for signatures);
ts: the time of signing/stamping;
url: the URL associated with the stamp (only for QR stamps).
text-box-style: With this parameter, you can fine-tune the text box’s style parameters. The most important one is
font, which allows you to specify an OTF font that will be used to render the text. If not specified, pyHanko will use a standard monospaced Courier font. See
TextBoxStylein the API reference for other customisable parameters.
The parameters used in the example styles shown above are not the only ones. The dynamic configuration mechanism used by pyHanko automatically exposes virtually all styling settings that are available to users of the (high-level) library API. For example, to use a stamp style where the text box is shifted to the right, and the background image is displayed on the left with custom margins, you could write something like the following:
stamp-styles: more-complex-demo: type: text stamp-text: "Test Test Test\n%(ts)s" background: image.png background-opacity: 1 background-layout: x-align: left margins: left: 10 top: 10 bottom: 10 inner-content-layout: x-align: right margins: right: 10
These settings are documented in the API reference documentation for
BaseStampStyle and its subclasses.
In general, the following rules apply when working with these “autoconfigurable” classes from within YAML.
Underscores in field names (at the Python level) can be replaced with hyphens in YAML.
In other cases, custom logic is provided to initialise certain fields, which is then documented on the (overridden)
process_entries()method of the relevant class.