Configuration options

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 --config parameter to pyhanko.

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.

Configuration options

Logging options

Under the 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

The keys root-level and 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 stderr. The keys under by-module allow you to specify more granular per-module logging configuration. The level key is mandatory in this case.

Note

If 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 validation-contexts top-level key. The example below defines two validation configs named default and special-setup, respectively:

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 trust setting should override the system trust (default false).

  • 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 --validation-context parameter. Applied to the example from here, this is how it works:

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 the 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 time-tolerance 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 time-tolerance setting 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.

By default, 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 true globally, but to false in setup-a specifically. 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

Danger

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 documentation for PKCS11SignatureConfig.

Note

Using the --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 configuration.

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 pkcs12-setups and 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 PKCS12SignatureConfig and PemDerSignatureConfig.

Key usage settings

New in version 0.5.0.

There are two additional keys that can be added to a named validation context: signer-key-usage and 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. For signer-key-usage, the possible values are as follows:

  • digital_signature

  • non_repudiation

  • key_encipherment

  • data_encipherment

  • key_agreement

  • key_cert_sign

  • crl_sign

  • encipher_only

  • decipher_only

We refer to § 4.2.1.3 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.x509.KeyPurposeId 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 setup-a:

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"]

Note

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 text or 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-url parameter 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 TextBoxStyle in 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.

Note

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.

  • Some fields will in turn be of an autoconfigurable type, e.g. background_layout is a SimpleBoxLayoutRule, which can also be configured using a YAML dictionary (as shown in the example above).

  • 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.