Identity

class dane_discovery.identity.Identity(dnsname, private_key=None, resolver_override=None)

Represent a DANE identity.

get_all_certificates(filters=[])

Return a dictionary of all EE certificates for this identity.

This method uses available methods for validating certificates retrieved from TLSA records associated with the identity’s DNS name.

For DANE-EE, we really just care that it parses and it was delivered with DNSSEC.

For PKIX-EE, we require delivery to be protected by DNSSEC. In the future, when the Python cryptography library supports full PKIX validation, we will also include PKIX validation. https://github.com/pyca/cryptography/issues/2381

For PKIX-CD, we require that the trust chain be represented out-of-band in accordance with the proposed standard for certificate and trust chain discovery.

Keyword Arguments

filters (list) – List of filters for specific DANE certificate usages. Valid filters are: “DANE-EE”, “PKIX-EE”, “PKIX-CD”.

Returns

Dictionary key is ${DNSNAME}-${CERTHASH}, and the value is the

the PEM-encoded certificate.

Return type

dict

get_first_entity_certificate(strict=True)

Return the first entity certificate for the identity.

Keyword Arguments

strict (bool) – Raise TLSAError if certificate was not retrieved with the benefit of DNSSEC, or in the case of PKIX-CD, if the certificate can not be validated via PKI.

Raises

  • TLSAError – If strict is set to True and the certificate cannot be validated by carrying a DNSSEC RRSIG. If certificate_usage is set to 4, PKIX validation may be attempted in lieu of DNSSEC.

  • ValueError – If cert_type is unsupported.

Returns

Certificate object as parsed

from TLSA record.

Return type

cryptography.x509.Certificate

get_first_entity_certificate_by_type(cert_type, strict=True)

Return the first certificate of cert_type for the identity.

Supported certificate types:

PKIX-EE: Corresponds with certificate_usage 1. DANE-EE: Corresponds with certificate_usage 3. PKIX-CD: Corresponds with certificate_usage 4.

Keyword Arguments

strict (bool) – Raise TLSAError if certificate was not retrieved with the benefit of DNSSEC, or in the case of PKIX-CD, if the certificate can not be validated via PKI.

Raises

  • TLSAError – If strict is set to True and the certificate cannot be validated by carrying a DNSSEC RRSIG. If certificate_usage is set to 4, PKIX validation may be attempted in lieu of DNSSEC.

  • ValueError – If cert_type is unsupported.

Returns

Certificate object as parsed

from TLSA record.

Return type

cryptography.x509.Certificate

get_pkix_cd_trust_chain(certificate, max_levels=100)

Return a dictionary with entire discovered trust chain.

Parameters

  • certificate (str) – EE certificate to begin trust chain discovery with.

  • max_levels (int) – Maximum number of parent certificates to discover. Default: 3.

Returns

Dictionary with integer keys for entity cert (0) and intermediate CA certificates.

The root certificate key is root.

Return type

dict

report()

Return a report for the identity.

Prints the query context (DNSSEC, etc) as well as information about the TLSA records stored at the identity’s name.

set_dane_credentials(dnsname)

Get public credentials from DNS and set DNS retrieval context.

Parameters

  • dnsname (str) – Name of DNS-based identity.

  • resolver_override (str) – Optional. Override the default resolver IP address.

validate_certificate(certificate)

Return True, None if the certificate is valid for the identity.

This method returns two values, success and status.

This method only checks against TLSA records with certificate_usage 4, or PKIX-CD.

Parameters

certificate (str) – Certificate in PEM or DER format.

Returns

True if successful, False if validation fails. str: Status indicating why validation passed or failed.

Return type

bool

validate_pkix_cd(cert_obj, credential)

Validate a certificate with certificate_usage 4.

PKIX-CD expects selector 0 and matching type 0. This method will not validate configuration which differs from this expectation.

Parameters

  • cert_obj (cryptography.x509) – Certificate object.

  • credential (dict) – Parsed credential from DNS.

Returns

True or False for validation string: Reason for validation pass/fail.

Return type

bool