pyhanko.config package

Submodules

pyhanko.config.api module

This module contains utilities for allowing dataclasses to be populated by user-provided configuration (e.g. from a Yaml file).

Note

On naming conventions: this module converts hyphens in key names to underscores as a matter of course.

class pyhanko.config.api.ConfigurableMixin

Bases: object

General configuration mixin for dataclasses

classmethod process_entries(config_dict)

Hook method that can modify the configuration dictionary to overwrite or tweak some of their values (e.g. to convert string parameters into more complex Python objects)

Subclasses that override this method should call super().process_entries(), and leave keys that they do not recognise untouched.

Parameters:: config_dict – A dictionary containing configuration values.
Raises:: ConfigurationError – when there is a problem processing a relevant entry.

classmethod check_config_keys(keys_supplied: Set[str])

Check whether all supplied keys are meaningful.

Parameters:: keys_supplied – The keys supplied in the configuration.
Raises:: ConfigurationError – if at least one key does not make sense.

classmethod from_config(config_dict)

Attempt to instantiate an object of the class on which it is called, by means of the configuration settings passed in.

First, we check that the keys supplied in the dictionary correspond to data fields on the current class. Then, the dictionary is processed using the process_entries() method. The resulting dictionary is passed to the initialiser of the current class as a kwargs dict.

Parameters:: config_dict – A dictionary containing configuration values.
Returns:: An instance of the class on which it is called.
Raises:: ConfigurationError – when an unexpected configuration key is encountered or left unfilled, or when there is a problem processing one of the config values.

pyhanko.config.api.check_config_keys(config_name, expected_keys, supplied_keys)

pyhanko.config.api.process_bit_string_flags(asn1crypto_class: Type[BitString], strings, param_name)

pyhanko.config.api.process_oid(asn1crypto_class: Type[ObjectIdentifier], id_string, param_name)

pyhanko.config.api.process_oids(asn1crypto_class: Type[ObjectIdentifier], strings, param_name)

pyhanko.config.errors module

exception pyhanko.config.errors.ConfigurationError(msg: str)

Bases: ValueError

Signal configuration errors.

pyhanko.config.local_keys module

class pyhanko.config.local_keys.PKCS12SignatureConfig(pfx_file: str, other_certs: List[Certificate] | None = None, pfx_passphrase: bytes | None = None, prompt_passphrase: bool = True, prefer_pss: bool = False)

Bases: ConfigurableMixin

Configuration for a signature using key material on disk, contained in a PKCS#12 bundle.

pfx_file: str: Path to the PKCS#12 file.

other_certs: List[Certificate] | None = None: Other relevant certificates.

pfx_passphrase: bytes | None = None: PKCS#12 passphrase (if relevant).

prompt_passphrase: bool = True: Prompt for the PKCS#12 passphrase. Default is True.

Note

If key_passphrase is not None, this setting has no effect.

prefer_pss: bool = False: Prefer PSS to PKCS#1 v1.5 padding when creating RSA signatures.

classmethod process_entries(config_dict)

Hook method that can modify the configuration dictionary to overwrite or tweak some of their values (e.g. to convert string parameters into more complex Python objects)

Subclasses that override this method should call super().process_entries(), and leave keys that they do not recognise untouched.

Parameters:: config_dict – A dictionary containing configuration values.
Raises:: ConfigurationError – when there is a problem processing a relevant entry.

class pyhanko.config.local_keys.PemDerSignatureConfig(key_file: str, cert_file: str, other_certs: List[Certificate] | None = None, key_passphrase: bytes | None = None, prompt_passphrase: bool = True, prefer_pss: bool = False)

Bases: ConfigurableMixin

Configuration for a signature using PEM or DER-encoded key material on disk.

key_file: str: Signer’s private key.

cert_file: str: Signer’s certificate.

other_certs: List[Certificate] | None = None: Other relevant certificates.

key_passphrase: bytes | None = None: Signer’s key passphrase (if relevant).

prompt_passphrase: bool = True: Prompt for the key passphrase. Default is True.

Note

If key_passphrase is not None, this setting has no effect.

prefer_pss: bool = False: Prefer PSS to PKCS#1 v1.5 padding when creating RSA signatures.

classmethod process_entries(config_dict)

Hook method that can modify the configuration dictionary to overwrite or tweak some of their values (e.g. to convert string parameters into more complex Python objects)

Subclasses that override this method should call super().process_entries(), and leave keys that they do not recognise untouched.

Parameters:: config_dict – A dictionary containing configuration values.
Raises:: ConfigurationError – when there is a problem processing a relevant entry.

pyhanko.config.logging module

class pyhanko.config.logging.LogConfig(level: int | str, output: pyhanko.config.logging.StdLogOutput | str)

Bases: object

level: int | str: Logging level, should be one of the levels defined in the logging module.

output: StdLogOutput | str: Name of the output file, or a standard one.

static parse_output_spec(spec) → StdLogOutput | str

class pyhanko.config.logging.StdLogOutput(*values)

Bases: Enum

STDERR = 1

STDOUT = 2

pyhanko.config.logging.parse_logging_config(log_config_spec) → Dict[str | None, LogConfig]

pyhanko.config.pkcs11 module

class pyhanko.config.pkcs11.PKCS11PinEntryMode(*values)

Bases: Enum

Pin entry behaviour if the user PIN is not supplied as part of the config.

PROMPT = 1: Prompt for a PIN (the default).

Note

This value is only processed by the CLI, and ignored when the PKCS#11 signer is called from library code. In those cases, the default is effectively SKIP.

DEFER = 2: Let the PKCS #11 module handle its own authentication during login.

Note

This applies to some devices that have physical PIN pads, for example.

SKIP = 3: Skip the login process altogether.

Note

This applies to some devices that manage user authentication outside the scope of PKCS #11 entirely.

static parse_mode_setting(value: Any) → PKCS11PinEntryMode

class pyhanko.config.pkcs11.PKCS11SigningPinEntryMode(*values)

Bases: Enum

Pin entry behaviour for signing operations.

Note

If these options are not specific enough for your needs (e.g. because the authentication procedure depends on the data being signed in some form), then you also have the option to override the sign_kwargs() method in PKCS11Signer.

SKIP = 1: Do not attempt to reauthenticate prior to signing (the default).

Note

Some modules may of course perform their own authentication regardless.

PROMPT = 2: Prompt for a PIN.

Note

This value is only processed by the CLI, and ignored when the PKCS#11 signer is called from library code. In those cases, the behaviour is effectively the same as SKIP.

REAUTHENTICATE = 3: Reauthenticate prior to signing using the value of signing_pin. If undefined, use the login PIN.

static parse_mode_setting(value: Any) → PKCS11SigningPinEntryMode

class pyhanko.config.pkcs11.PKCS11SignatureConfig(module_path: str, cert_label: str | None = None, cert_id: bytes | None = None, signing_certificate: Certificate | None = None, token_criteria: TokenCriteria | None = None, other_certs: List[Certificate] | None = None, key_label: str | None = None, key_id: bytes | None = None, slot_no: int | None = None, user_pin: str | None = None, prompt_pin: PKCS11PinEntryMode = PKCS11PinEntryMode.PROMPT, other_certs_to_pull: Iterable[str] | None = (), bulk_fetch: bool = True, prefer_pss: bool = False, raw_mechanism: bool = False, only_resident_certs: bool = False, signature_mechanism: SignedDigestAlgorithm | None = None, signing_pin_mode: PKCS11SigningPinEntryMode = PKCS11SigningPinEntryMode.SKIP, signing_pin: str | None = None)

Bases: ConfigurableMixin

Configuration for a PKCS#11 signature.

This class is used to load PKCS#11 setup information from YAML configuration.

module_path: str: Path to the PKCS#11 module shared object.

cert_label: str | None = None: PKCS#11 label of the signer’s certificate.

cert_id: bytes | None = None: PKCS#11 ID of the signer’s certificate.

signing_certificate: Certificate | None = None: The signer’s certificate. If present, cert_id and cert_label will not be used to obtain the signer’s certificate from the PKCS#11 token.

Note

This can be useful in case the signer’s certificate is not available on the token, or if you would like to present a different certificate than the one provided on the token.

token_criteria: TokenCriteria | None = None: PKCS#11 token name

other_certs: List[Certificate] | None = None: Other relevant certificates.

key_label: str | None = None: PKCS#11 label of the signer’s private key. Defaults to cert_label if the latter is specified and key_id is not.

key_id: bytes | None = None: PKCS#11 key ID.

slot_no: int | None = None: Slot number of the PKCS#11 slot to use.

user_pin: str | None = None: The user’s PIN. If unspecified, the user will be prompted for a PIN if prompt_pin is True.

Warning

Some PKCS#11 tokens do not allow the PIN code to be communicated in this way, but manage their own authentication instead (the Belgian eID middleware is one such example). For such tokens, leave this setting set to None and additionally set prompt_pin to False.

prompt_pin: PKCS11PinEntryMode = 1: Set PIN entry and PKCS #11 login behaviour.

Note

If user_pin is not None, this setting has no effect.

other_certs_to_pull: Iterable[str] | None = (): List labels of other certificates to pull from the PKCS#11 device. Defaults to the empty tuple. If None, pull all certificates.

bulk_fetch: bool = True: Boolean indicating the fetching strategy. If True, fetch all certs and filter the unneeded ones. If False, fetch the requested certs one by one. Default value is True, unless other_certs_to_pull has one or fewer elements, in which case it is always treated as False.

prefer_pss: bool = False: Prefer PSS to PKCS#1 v1.5 padding when creating RSA signatures.

raw_mechanism: bool = False: Invoke the raw variant of the PKCS#11 signing operation.

Note

This is currently only supported for ECDSA signatures.

only_resident_certs: bool = False: Limit certificate searches to certificates that are marked as physically stored on the token, not generated on-the-fly.

Note

This corresponds to the TOKEN flag being set on the PKCS#11 object.

signature_mechanism: SignedDigestAlgorithm | None = None: Manually specify the signature mechanism in ASN.1 fully.

Note

The prototypical use case for this is a PKCS#11 interface that allows signing with RSASSA-PSS, but doesn’t accept pyHanko’s default choice of parameters.

signing_pin_mode: PKCS11SigningPinEntryMode = 1: Specify pre-sign PIN entry behaviour.

signing_pin: str | None = None: Signing PIN, used in accordance with signing_pin_mode.

classmethod check_config_keys(keys_supplied: Set[str])

Check whether all supplied keys are meaningful.

Parameters:: keys_supplied – The keys supplied in the configuration.
Raises:: ConfigurationError – if at least one key does not make sense.

classmethod process_entries(config_dict)

Hook method that can modify the configuration dictionary to overwrite or tweak some of their values (e.g. to convert string parameters into more complex Python objects)

Subclasses that override this method should call super().process_entries(), and leave keys that they do not recognise untouched.

Parameters:: config_dict – A dictionary containing configuration values.
Raises:: ConfigurationError – when there is a problem processing a relevant entry.

class pyhanko.config.pkcs11.TokenCriteria(label: str | None = None, serial: bytes | None = None)

Bases: ConfigurableMixin

Added in version 0.14.0.

Search criteria for a PKCS#11 token.

label: str | None = None: Label of the token to use. If None, there is no constraint.

serial: bytes | None = None: Serial number of the token to use. If None, there is no constraint.

classmethod process_entries(config_dict)

Hook method that can modify the configuration dictionary to overwrite or tweak some of their values (e.g. to convert string parameters into more complex Python objects)

Subclasses that override this method should call super().process_entries(), and leave keys that they do not recognise untouched.

Parameters:: config_dict – A dictionary containing configuration values.
Raises:: ConfigurationError – when there is a problem processing a relevant entry.