DANE

class dane_discovery.dane.DANE

Abstract interactions involved in certificate retrieval.

classmethod authenticate_tlsa(dns_name, record)

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.

Returns

None if this identity can be cryptographically authenticated.

Raises

TLSAError if the identity can not be cryptographically authenticated. –

classmethod build_x509_object(certificate)

Wrap format determination and return an x509 object.

Parameters

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

Returns

cryptography.x509.Certificate object.

Raises

TLSAError if unable to parse. –

classmethod certificate_association_to_der(certificate_association)

Return DER bytes from a TLSA record’s certificate_association.

Parameters

certificate_association (str) – Certificate association information extracted from a TLSA record.

Returns

DER-formatted certificate.

Return type

bytes

classmethod der_to_pem(der_cert)

Return the PEM representation of a TLSA certificate_association.

Parameters

der (str) – A certificate in DER format.

Returns

PEM-formatted certificate.

Return type

bytes

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_authority_key_id_from_certificate(certificate)

Return the authorityKeyIdentifier for the certificate.

Parameters

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

classmethod get_ca_certificate_for_identity(identity_name, certificate)

Return the CA certificate for verifying identity_name.

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_dnsnames_from_cert(x5_obj)

Return the dnsnames from the certificate’s SAN.

Parameters

x5_obj (cryptography.x509) – Certificate object.

Returns

str: dNSNames from certificate SAN.

Return type

list

classmethod get_first_leaf_certificate(dnsname)

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.

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.

Returns

Keys are responses (list of string),

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

Return type

dict

classmethod get_subject_key_id_from_certificate(certificate)

Return the subjectKeyIdentifier for the certificate.

Parameters

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

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 validate_certificate(certificate)

Raise TLSAError if certificate does not parse, or return None.

Parameters

certificate (str) – Certificate association data from TLSA record.

Returns

None

Raises

TLSAError if parsing fails. –

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 verify_certificate_signature(entity_certificate, ca_certificate)

Return True if entity_certificate was signed by ca_certificate.

Parameters

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

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

Returns

True if the ca_certificate validates the entity_certificate.

Return type

bool

classmethod verify_dnsname(dns_name, certificate_der)

Return True if the first dNSName in the SAN matches.