pyhanko.sign.validation.qualified package

Submodules

pyhanko.sign.validation.qualified.assess module

class pyhanko.sign.validation.qualified.assess.QualificationAssessor(tsp_registry: TSPRegistry)

Bases: object

Assesses the qualification status of certificates against a particular TSPRegistry.

check_entity_cert_qualified(path: ValidationPath, moment: datetime | None = None) → QualificationResult

Evaluate the qualified status of a certificate (given a specific validation path).

Parameters:

• path – Validation path to scrutinise.

• moment – Evaluate the status against the service definitions valid at the time specified. If None, take the latest available service definitions.

Returns:

A QualificationResult instance.

exception pyhanko.sign.validation.qualified.assess.QualificationPolicyError(failure_message, ades_subindication: AdESSubIndic | None = None)

Bases: SignatureValidationError

Error triggered by a qualification policy violation.

pyhanko.sign.validation.qualified.assess.enforce_requirements(requirements: QualificationRequirements, qualification_result: QualificationResult, path: ValidationPath)

Internal method to enforce the requirements of a qualification policy during validation.

pyhanko.sign.validation.qualified.eutl_fetch module

pyhanko.sign.validation.qualified.eutl_fetch.EU_LOTL_LOCATION = 'https://ec.europa.eu/tools/lotl/eu-lotl.xml'

Location of the EU’s global list-of-the-lists (LOTL).

Note

At the time of writing, this URL appears to have remained constant since eIDAS’s inception, but in theory it is subject to change.

class pyhanko.sign.validation.qualified.eutl_fetch.FileSystemTLCache(cache_path: Path, expire_after: timedelta)

Bases: TLCache

reset()

class pyhanko.sign.validation.qualified.eutl_fetch.InMemoryTLCache

Bases: TLCache

Cache for trusted lists, intended to speed up downloading lists from a list-of-lists.

The cache is keyed by download URL and does not have any eviction mechanism.

class pyhanko.sign.validation.qualified.eutl_fetch.TLCache

Bases: object

Cache for trusted lists, intended to speed up downloading lists from a list-of-lists.

This is internal API.

async pyhanko.sign.validation.qualified.eutl_fetch.bootstrap_lotl_signers(latest_lotl_xml: str, client: ClientSession, bootstrap_lotl_tlso_certs: List[Certificate] | None = None, cache: TLCache | None = None) → List[Certificate]

Perform the bootstrapping process specified in Article 4 of Commission Implementing Decision (EU) 2015/1505 to determine the certificates that can be used to verify a list-of-the-lists signature.

The EC’s technical guidance on this topic is also of interest.

Warning

PyHanko bundles the both the initial set of list-of-the-lists signing certificates and the last-known set of such certificates. In principle, you only need to use this function if there have not been any pyHanko releases since the last change in the list-of-the-lists signers, or you cannot upgrade for some reason.

The process to fetch and process all relevant trust lists is rather slow, so this bootstrapping logic should be used judiciously.

Parameters:

• latest_lotl_xml – The XML content of the most recent list-of-the-lists.

• client – An aiohttp.ClientSession object to use for fetching pivot lists-of-the-lists.

• bootstrap_lotl_tlso_certs – Initial list of certificates. This defaults to the list published in OJ C 276, 16.8.2019, which is bundled with this library.

• cache – An optional TLCache to be used while fetching pivot lists-of-the-lists.

Returns:

The list of certificates that can be used to verify the most recent list-of-the-lists.

async pyhanko.sign.validation.qualified.eutl_fetch.fetch_lotl(client: ClientSession, cache: TLCache | None = None, url='https://ec.europa.eu/tools/lotl/eu-lotl.xml')

Fetch the EU list-of-the-lists (LOTL).

Parameters:

• client – An aiohttp.ClientSession object to use for fetching trust lists.

• cache – An optional TLCache to be used while fetching trust lists.

• url – The URL content of the list-of-the-lists. The default is the location specified in EU_LOTL_LOCATION.

Returns:

async pyhanko.sign.validation.qualified.eutl_fetch.lotl_to_registry(lotl_xml: str | None, client: ClientSession, lotl_tlso_certs: List[Certificate] | None = None, cache: TLCache | None = None, registry: TSPRegistry | None = None, only_territories: Set[str] | None = None) → Tuple[TSPRegistry, List[TSPServiceParsingError]]

Populate a TSPRegistry instance from a list-of-the-lists XML payload, validating the signatures on the trusted lists in the process.

Parameters:

• lotl_xml – The XML content of a list-of-the-lists. If None, it will be downloaded from the location specified in EU_LOTL_LOCATION.

• client – An aiohttp.ClientSession object to use for fetching trust lists.

• lotl_tlso_certs –

  List of certificates that can be used to validate the list-of-the-lists. If not specified, the list-of-the-lists will be validated against the last known set of list-of-the-lists signer certs bundled with this library.

  See bootstrap_lotl_signers() and validate_and_parse_lotl().

• cache – An optional TLCache to be used while fetching trust lists.

• registry – An optional TSPRegistry to be used to collect service definitions for trusted service providers. If not supplied, a registry will be instantiated.

• only_territories – Limit downloads to the territories specified (as two-letter ISO 3166-1 country codes). If None, no filtering is applied.

Returns:

A TSPRegistry instance populated with the fetched contents, in addition to any parsing errors encountered.

pyhanko.sign.validation.qualified.eutl_parse module

pyhanko.sign.validation.qualified.eutl_parse.latest_known_lotl_tlso_certs() → List[Certificate]

Retrieve the lastest known (at the time of the most recent pyHanko release) list of LOTL signer certs.

pyhanko.sign.validation.qualified.eutl_parse.ojeu_bootstrap_lotl_tlso_certs() → List[Certificate]

Retrieve the list of certificates published in OJ C 276, 16.8.2019, which is bundled with this library.

pyhanko.sign.validation.qualified.eutl_parse.parse_lotl_unsafe(lotl_xml: str) → LOTLParseResult

Parse a list-of-the-lists (LOTL).

Warning

This function does not include validating the signature on the LOTL.

Parameters:

lotl_xml – XML LOTL payload

Returns:

A parse result.

pyhanko.sign.validation.qualified.eutl_parse.read_qualified_service_definitions(tl_xml: str) → Generator[QualifiedServiceInformation, None, List[TSPServiceParsingError]]

Internal function to read qualified service definitions from a trusted list payload (does not include signature validation).

pyhanko.sign.validation.qualified.eutl_parse.trust_list_to_registry(tl_xml: str, tlso_certs: List[Certificate], registry: TSPRegistry | None = None) → Tuple[TSPRegistry, List[TSPServiceParsingError]]

Validate and parse a trusted list (ETSI TS 119 612) into a TSPRegistry.

Note

The TSLO certs are used in the validation of the trusted list, but are not validated by this function.

Parameters:

• tl_xml – XML payload describing the trusted list in the ETSI TS 119 612 format

• tlso_certs – The certificates containing the public keys with which the TL could be validated.

• registry – Registry to which the entries should be added. If not supplied, a new one will be created.

Raises:

SignatureValidationError – If the trusted list’s signature cannot be validated.

Returns:

pyhanko.sign.validation.qualified.eutl_parse.trust_list_to_registry_unsafe(tl_xml: str, registry: TSPRegistry | None = None) → Tuple[TSPRegistry, List[TSPServiceParsingError]]

Parse a trusted list (ETSI TS 119 612) into a TSPRegistry.

Warning

The XML signature on the trusted list is _not_ validated as part of this method. Currently, ensuring the integrity of the trusted list is the caller’s responsibility.

Parameters:

• tl_xml – XML payload describing the trusted list in the ETSI TS 119 612 format

• registry – Registry to which the entries should be added. If not supplied, a new one will be created.

Returns:

pyhanko.sign.validation.qualified.eutl_parse.validate_and_parse_lotl(lotl_xml: str, lotl_tlso_certs: List[Certificate] | None = None) → LOTLParseResult

Validate and parse a list-of-the-lists (LOTL).

Parameters:

• lotl_xml – XML LOTL payload

• lotl_tlso_certs –

  List of certificates that can be used to validate the list-of-the-lists. If not specified, the list-of-the-lists will be validated against the last known set of list-of-the-lists signer certs bundled with this library.

  See validate_and_parse_lotl().

Returns:

A parse result.

pyhanko.sign.validation.qualified.q_status module

class pyhanko.sign.validation.qualified.q_status.QcPrivateKeyManagementType(*values)

Bases: Enum

Description of the private key management methodology.

UNKNOWN = 0

Private key management methodology unknown/unspecified.

QSCD = 1

Declaration indicating that the private key resides in a qualified signature creation device (QSCD).

QSCD_DELEGATED = 2

Declaration indicating that the private key resides in a QSCD managed on behalf of the subject by another party.

QSCD_BY_POLICY = 3

QSCD declaration by pre-eIDAS certificate policy.

property is_qscd: bool

class pyhanko.sign.validation.qualified.q_status.QualificationResult(status: QualifiedStatus, service_definition: QualifiedServiceInformation | None)

Bases: object

Represents the result of a qualification evaluation.

status: QualifiedStatus

Status indicator.

service_definition: QualifiedServiceInformation | None

Service definition under which the tested object was considered qualified.

class pyhanko.sign.validation.qualified.q_status.QualifiedStatus(qualified: bool, qc_type: QcCertType, qc_key_security: QcPrivateKeyManagementType)

Bases: object

Represents the qualified status of a certificate.

qualified: bool

Indicates whether the certificate is to be considered qualified.

qc_type: QcCertType

Type of qualified certificate.

qc_key_security: QcPrivateKeyManagementType

Indicates whether the CA declares that the private key corresponding to this certificate resides in a qualified signature creation device (QSCD) or secure signature creation device (SSCD). It also indicates whether the QCSD is managed on behalf of the signer, if applicable.

Warning

These terms are functionally interchangeable, the only difference is that “SSCD” is pre-eIDAS terminology.

pyhanko.sign.validation.qualified.tsp module

class pyhanko.sign.validation.qualified.tsp.AdditionalServiceInformation(uri: str, critical: bool, textual_info: str | None)

Bases: object

uri: str

critical: bool

textual_info: str | None

class pyhanko.sign.validation.qualified.tsp.BaseServiceInformation(service_type: str, service_name: str, valid_from: datetime, valid_until: datetime | None, provider_certs: Tuple[Certificate, ...], additional_info_certificate_type: FrozenSet[QcCertType], other_additional_info: FrozenSet[AdditionalServiceInformation])

Bases: object

Common information about a trusted service.

service_type: str

The type of service, specified as a URI.

Note

Corresponds to the ServiceTypeIdentifier in the trusted list data.

service_name: str

Name of the trusted service.

valid_from: datetime

Start of the service definition’s validity window.

valid_until: datetime | None

End of the service definition’s validity window, if defined. If not, the service is presumed to be valid indefinitely.

provider_certs: Tuple[Certificate, ...]

Certificates linked to this service provider.

additional_info_certificate_type: FrozenSet[QcCertType]

If non-empty, narrows the scope of the specified service type to the types of certificate listed.

other_additional_info: FrozenSet[AdditionalServiceInformation]

Other information that qualifies the type of service.

class pyhanko.sign.validation.qualified.tsp.CAServiceInformation(base_info: BaseServiceInformation, qualifications: FrozenSet[Qualification], expired_certs_revocation_info: datetime | None)

Bases: QualifiedServiceInformation

Qualified CA service description.

expired_certs_revocation_info: datetime | None

See ETSI TS 119 612, 5.5.9.1.

Warning

This extension is not yet taken into account by certificate validation processes.

class pyhanko.sign.validation.qualified.tsp.CertSubjectDNCriterion(required_rdn_part_oids: FrozenSet[str])

Bases: Criterion

required_rdn_part_oids: FrozenSet[str]

matches(cert: Certificate) → bool

Evaluate a certificate against this criterion.

Parameters:

cert – The certificate to evaluate.

Returns:

True if the criterion matches, False otherwise.

class pyhanko.sign.validation.qualified.tsp.CriteriaCombination(*values)

Bases: Enum

Defines how to combine sub-criteria.

ALL = 'all'

All sub-criteria must match for the criterion to match.

AT_LEAST_ONE = 'atLeastOne'

At least one of the sub-criteria must match for the criterion to match.

NONE = 'none'

All of the sub-criteria must fail to match for the criterion to match.

class pyhanko.sign.validation.qualified.tsp.CriteriaList(combine_as: CriteriaCombination, criteria: FrozenSet[Criterion])

Bases: Criterion

Combine several criteria as one.

combine_as: CriteriaCombination

Logical operation to apply to the list of sub-criteria.

criteria: FrozenSet[Criterion]

Set of sub-criteria.

matches(cert: Certificate) → bool

Evaluate a certificate against this criterion.

Parameters:

cert – The certificate to evaluate.

Returns:

True if the criterion matches, False otherwise.

class pyhanko.sign.validation.qualified.tsp.Criterion

Bases: object

Criterion for a qualifier to apply to a certificate.

matches(cert: Certificate) → bool

Evaluate a certificate against this criterion.

Parameters:

cert – The certificate to evaluate.

Returns:

True if the criterion matches, False otherwise.

class pyhanko.sign.validation.qualified.tsp.KeyUsageCriterion(settings: KeyUsageConstraints)

Bases: Criterion

Criterion that matches certificates that meet the specified key usage constraints.

settings: KeyUsageConstraints

Key usage constraint to apply.

matches(cert: Certificate) → bool

Evaluate a certificate against this criterion.

Parameters:

cert – The certificate to evaluate.

Returns:

True if the criterion matches, False otherwise.

class pyhanko.sign.validation.qualified.tsp.PolicySetCriterion(required_policy_oids: FrozenSet[str])

Bases: Criterion

Criterion that matches certificates that meet the specified certificate policies.

required_policy_oids: FrozenSet[str]

Policies that must be applicable to the certificate.

Note

These OIDs are considered to be specified in the domain of the trust root, so they are subject to policy mapping in the sense of RFC 5280.

matches(cert: Certificate) → bool

Evaluate a certificate against this criterion.

Parameters:

cert – The certificate to evaluate.

Returns:

True if the criterion matches, False otherwise.

class pyhanko.sign.validation.qualified.tsp.QTSTServiceInformation(base_info: BaseServiceInformation, qualifications: FrozenSet[Qualification])

Bases: QualifiedServiceInformation

Qualified TSA service description.

class pyhanko.sign.validation.qualified.tsp.QcCertType(*values)

Bases: Enum

Type of qualified certificate.

QC_ESIGN = 'qct_esign'

Certificate qualified for eSignatures.

QC_ESEAL = 'qct_eseal'

Certificate qualified for eSeals.

QC_WEB = 'qct_web'

Qualified website authentication certificate (QWAC).

class pyhanko.sign.validation.qualified.tsp.Qualification(qualifiers: FrozenSet[Qualifier], criteria_list: CriteriaList)

Bases: object

Representation of a qualification in the sense of ETSI TS 119 612, 5.5.9.2.

qualifiers: FrozenSet[Qualifier]

Set of qualifiers to apply to the certificates matching the criteria.

criteria_list: CriteriaList

List of criteria to apply.

class pyhanko.sign.validation.qualified.tsp.QualifiedServiceInformation(base_info: BaseServiceInformation, qualifications: FrozenSet[Qualification])

Bases: object

Representation of a service with conditional qualifiers.

base_info: BaseServiceInformation

Basic information about the service.

qualifications: FrozenSet[Qualification]

Relevant qualifications.

class pyhanko.sign.validation.qualified.tsp.Qualifier(*values)

Bases: Enum

Qualifier as specified in ETSI TS 119 612, 5.5.9.2.

WITH_SSCD = 'QCWithSSCD'

NO_SSCD = 'QCNoSSCD'

SSCD_AS_IN_CERT = 'QCSSCDStatusAsInCert'

WITH_QSCD = 'QCWithQSCD'

NO_QSCD = 'QCNoQSCD'

QSCD_AS_IN_CERT = 'QCQSCDStatusAsInCert'

QSCD_MANAGED_ON_BEHALF = 'QCQSCDManagedOnBehalf'

LEGAL_PERSON = 'QCForLegalPerson'

FOR_ESIG = 'QCForESig'

FOR_ESEAL = 'QCForESeal'

FOR_WSA = 'QCForWSA'

NOT_QUALIFIED = 'NotQualified'

QC_STATEMENT = 'QCStatement'

property uri

class pyhanko.sign.validation.qualified.tsp.TSPRegistry

Bases: object

Registry of trusted service providers (TSPs), typically populated from a trust list.

Currently, a TSP registry can keep track of qualified CAs and TSAs (QTSTs).

register_ca(ca_service_info: CAServiceInformation)

Register a trusted certificate authority.

Parameters:

ca_service_info – Service information about the CA.

register_tst(qtst_service_info: QTSTServiceInformation)

Register a trusted time stamping authority.

Parameters:

qtst_service_info – Service information about the TSA.

applicable_service_definitions(authority: Authority, moment: datetime | None) → Iterable[QualifiedServiceInformation]

Retrieve the service definitions in this registry on behalf of which the specified authority might act.

Note

This includes all supported types of qualified services, not just certificate authorities.

Parameters:

• authority – Authority to evaluate.

• moment – Time at which to evaluate the service definitions. If none is specified, all matching service definitions will be returned, irrespective of their validity windows.

Returns:

List of service definitions matching the authority.

property known_certificate_authorities: Iterable[Authority]

List known certificate authorities identified by this registry.

property known_timestamp_authorities: Iterable[Authority]

List known time stamping authorities identified by this registry.

applicable_tsps_on_path(path: ValidationPath, moment: datetime) → Generator[QualifiedServiceInformation, None, None]

List applicable trusted service providers on the provided validation path.

Parameters:

• path – The validation path to evaluate.

• moment – Time at which to evaluate the service definitions. If none is specified, all matching service definitions will be returned, irrespective of their validity windows.

Returns:

A generator that yields any service definitions matching the authorities on the validation path.

exception pyhanko.sign.validation.qualified.tsp.TSPServiceParsingError

Bases: ValueError

class pyhanko.sign.validation.qualified.tsp.TSPTrustManager(tsp_registry: TSPRegistry)

Bases: TrustManager

Trust manager implementation based on a TSPRegistry.

as_trust_anchor(authority: Authority) → TrustAnchor | None

If the authority is a trust anchor, return its identity as such (with qualifications as applicable).

If the authority is not a trust anchor, return None.

Parameters:

authority – An authority object.

find_potential_issuers(cert: Certificate) → Generator[TrustAnchor, None, None]

Find potential issuers that might have (directly) issued a particular certificate.

Parameters:

cert – Issued certificate.

Returns:

An iterator with potentially relevant trust anchors.