DANE

class dane_discovery.dane.DANE

Abstract interactions involved in certificate retrieval.

classmethod authenticate_tlsa(dns_name, record, nsaddr=None)

Return None if the identity is authenticated, or raise ValueError.

This method authenticates a TLSA record as follows:

Any record with a certificate usage of 0-4, which is correctly-formatted and delivered with DNSSEC will pass authentication.

Any record delivered without DNSSEC must have: certificate_usage = 4, selector = 0, and matching_type = 0. Additionally, the certificate_association field must contain a certificate which bears a signature which can be authenticated by the certificate found at https://${IDTYPE}.${DOMAIN}/ca/${AKI}.pem. The IDTYPE and DOMAIN variables are extracted from the entity’s DNS name, and the AKI is extracted from the TLSA record’s certificate_associattion field.

Any TLSA RRs having certificate_usage == 4 must only have selector == 0 and matching_type == 0. Any deviation will cause validation failure.

Parameters

  • dns_name (str) – DNS name associated with the TLSA record.

  • record (dict) – Keys for certificate_usage, selector, matching_type, certificate_association, and dnssec.

  • nsaddr (str) – Name server override.

Returns

None if this identity can be cryptographically authenticated.

Raises

TLSAError if the identity can not be cryptographically authenticated. –

classmethod generate_authority_hostname(identity_name)

Return the hostname for an entity’s authority server.

This assumes the first underscore label found while parsing from TLD toward hostname ( ._device. for devices, or ._service., or ._whatever.) to be the anchor label for constructing the URL where we expect to find the signing certificate.

Parameters

identity_name (str) – DNS name of identity.

Raises

ValueError if no underscore label in identity_name. –

Returns

Authority server hostname.

classmethod generate_sha_by_selector(certificate, sha, selector)

Return the SHA value appropriate for the selector.

Parameters

  • certificate (bytes) – Certificate in PEM or DER format.

  • sha (str) – Valid values: sha256, sha512.

  • selector (int) – Valid values: 0, 1. If 0, we generate a SHA for the entire certificate. If 1, we generate a SHA only on the public key in the certificate.

Returns

Base64 representation of SHA.

Return type

bytes

classmethod generate_tlsa_record(certificate_usage, selector, matching_type, certificate)

Return the bytes for a TLSA record.

Detailed information on the fields of the TLSA record can be found here

Parameters

  • certificate_usage (int) – Certificate usage variable (0-3).

  • selector (int) – Selector (0|1).

  • matching_type (int) – Matching type. Only support 0 for certificate discovery.

  • certificate (bytes) – Certificate in PEM or DER format.

Returns

TLSA record in bytes.

Return type

bytes

Raises

TLSAError if unsupported options are used. –

classmethod generate_url_for_ca_certificate(authority_hostname, authority_key_id)

Return a URL for the identity’s ca certificate.

An identity conforming to DANE PKIX-CD must have the signing CA certificate available at a known location in DNS, relative to the identity itself.

The URL is composed from the authority server’s hostname and the authorityKeyId from the certificate that’s being authenticated.

Parameters

  • identity_hostname (str) – DNS name of the identity.

  • authority_key_id (str) – AuthorityKeyId from entity certificate.

Returns

URL where a CA certificate should be found.

Return type

str

classmethod get_a_record(dnsname, nsaddr=None)

Get the first A record.

classmethod get_ca_certificate_for_identity(identity_name, certificate)

Return the CA certificate for verifying identity_name.

DEPRECATED. USE get_ca_certificates_for_identity

Returns the PEM representation of the CA certificate used for verifying any DANE PKIX-CD certificate associated with identity_name.

Parameters

  • identity_name (str) – DNS name of identity.

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

Raises

ValueError if no CA certificate is found or the – certificate is not parseable.

Returns

PEM of CA signing certificate.

Return type

str

classmethod get_ca_certificates_for_identity(identity_name, certificate, max_levels=100, nsaddr=None)

Return the CA certificates for verifying identity_name.

Returns the PEM representation of the CA certificates used for verifying any DANE PKIX-CD certificate associated with identity_name.

Parameters

  • identity_name (str) – DNS name of identity.

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

  • max_levels (int) – Only retrieve this many parent certificates.

Raises

ValueError if no CA certificate is found or the – certificate is not parseable.

Returns

CA certificates which authenticate identity certificate.

Return type

list

classmethod get_first_leaf_certificate(dnsname, nsaddr=None)

Return the first leaf certificate from TLSA records at dnsname.

This method essentially wraps get_tlsa_records(), and returns the first TLSA record with certificate_usage equal to 1, 3, or 4 and matching_type of 0.

Parameters

  • dnsname (str) – DNS name to query for certificate.

  • nsaddr (str) – Override system resolver.

Returns

Dictionary with keys for certificate_usage, selector,

matching_type, certificate_association. If no leaf certificate is found, None is returned.

Return type

dict

classmethod get_responses(dnsname, rr_type, nsaddr=None)

Return a list of dicts containing DNS RRs and security context.

Parameters

  • dnsname (str) – DNS name for query.

  • rr_type (str) – RR type to query. Defaults to TLSA.

  • nsaddr (str) – Nameserver override address.

Returns

Keys are responses (list of string),

dnssec (bool), tls (bool), tcp (bool).

Return type

dict

classmethod get_tlsa_records(dnsname, nsaddr=None)

TLSA records in a list of dictionaries.

This method retrieves and parses the TLSA records from DNS for a given DNS name.

Parameters

  • dnsname (str) – DNS name to query for TLSA record.

  • nsaddr (str) – Nameserver address.

Returns

Dictionaries with the following keys:

certificate_usage, selector, matching_type, certificate_association, dnssec, tls, tcp.

Return type

list of dict

classmethod process_response(response)

Return the TLSA record, parsed into a dictionary.

Parameters

response (str) – Response from DNS query.

Returns

dict with keys for name, ttl, class,

type, certificate_usage, selector, matching_types, certificate_association.

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 contains a certificate, this will be a cryptography.x509.Certificate object.

classmethod validate_tlsa_fields(tlsa_fields)

Validate the fields that come from DNS.

Parameters

tlsa_fields (dict) – Must contain the following keys: certificate_usage, selector, matching_type, certificate_association.

Returns

None

Raises

TLSAError if record is malformed. –

classmethod wrap_requests(url, nsaddr=None)

Wrap requests for nameserver override.