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 PKIX-CD 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

classmethod get_cert_meta(cert_der)

Return a dictionary containing certificate metadata.

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

classmethod load_private_key(private_key)

Return a private key.

Wraps cryptography.hazmat.primitives.serialization.load_pem_private_key and returns the appropriate type.

Parameters

private_key (str) – Private key in PEM format.

Returns

Private key object, or None if private_key arg is None.

Raises

ValueError if there's an error loading the key. –

classmethod parse_extension(x509_ext)

Return a dictionary representation of the x509 extension.

classmethod process_tlsa(tlsa_record)

Return a dictionary describing the TLSA record’s contents.

Parameters

tlsa_record (dict) – Dictionary describing TLSA record contents.

Dictionary keys:

tlsa_fields: TLSA record parsed into a list.

tlsa_parsed: A dictionary of parsed TLSA record fields.

certificate_usage: Text description of the TLSA field.

matching_type: Text description of the TLSA field.

selector: Text description of the TLSA field.

certificate_metadata: Metadata parsed from the certificate.

public_key_object: If the TLSA record contains a public key, this will be the same object as generated by cryptography.hazmat.primitives.serialization.load_der_public_key()

certificate_object: If the TLSA record conatins a certificate, this will be a cryptography.x509.Certificate object.

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, resolver_override)

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)

Validate certificate against DANE identity records in DNS.

This method returns two valufes, 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