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_oid(asn1crypto_class: Type[ObjectIdentifier], id_string, param_name)
- pyhanko.config.api.process_oids(asn1crypto_class: Type[ObjectIdentifier], strings, param_name)
- pyhanko.config.api.process_bit_string_flags(asn1crypto_class: Type[BitString], 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 notNone
, 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 notNone
, 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.StdLogOutput(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
Bases:
Enum
- STDERR = 1
- STDOUT = 2
- 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
pyhanko.config.pkcs11 module
- 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.
- class pyhanko.config.pkcs11.PKCS11PinEntryMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
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.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)
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
andcert_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 andkey_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
isTrue
.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 setprompt_pin
toFalse
.
- prompt_pin: PKCS11PinEntryMode = 1
Set PIN entry and PKCS #11 login behaviour.
Note
If
user_pin
is notNone
, 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. IfFalse
, fetch the requested certs one by one. Default value isTrue
, unlessother_certs_to_pull
has one or fewer elements, in which case it is always treated asFalse
.
- 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.
- 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.
pyhanko.config.trust module
- pyhanko.config.trust.init_validation_context_kwargs(*, trust: Iterable[str] | str, trust_replace: bool, other_certs: Iterable[str] | str, retroactive_revinfo: bool = False, time_tolerance: timedelta | int | None = None) Dict[str, Any]
- pyhanko.config.trust.parse_trust_config(trust_config, time_tolerance, retroactive_revinfo) dict