diff options
Diffstat (limited to 'ldns/dane.h')
| -rw-r--r-- | ldns/dane.h | 74 |
1 files changed, 59 insertions, 15 deletions
diff --git a/ldns/dane.h b/ldns/dane.h index 6adecd575c51..142afb8d21b5 100644 --- a/ldns/dane.h +++ b/ldns/dane.h @@ -22,7 +22,6 @@ #ifndef LDNS_DANE_H #define LDNS_DANE_H -#if LDNS_BUILD_CONFIG_USE_DANE #include <ldns/common.h> #include <ldns/rdata.h> @@ -42,13 +41,19 @@ extern "C" { enum ldns_enum_tlsa_certificate_usage { /** CA constraint */ - LDNS_TLSA_USAGE_CA_CONSTRAINT = 0, + LDNS_TLSA_USAGE_PKIX_TA = 0, + LDNS_TLSA_USAGE_CA_CONSTRAINT = 0, /** Sevice certificate constraint */ - LDNS_TLSA_USAGE_SERVICE_CERTIFICATE_CONSTRAINT = 1, + LDNS_TLSA_USAGE_PKIX_EE = 1, + LDNS_TLSA_USAGE_SERVICE_CERTIFICATE_CONSTRAINT = 1, /** Trust anchor assertion */ - LDNS_TLSA_USAGE_TRUST_ANCHOR_ASSERTION = 2, + LDNS_TLSA_USAGE_DANE_TA = 2, + LDNS_TLSA_USAGE_TRUST_ANCHOR_ASSERTION = 2, /** Domain issued certificate */ - LDNS_TLSA_USAGE_DOMAIN_ISSUED_CERTIFICATE = 3 + LDNS_TLSA_USAGE_DANE_EE = 3, + LDNS_TLSA_USAGE_DOMAIN_ISSUED_CERTIFICATE = 3, + /** Reserved for Private Use */ + LDNS_TLSA_USAGE_PRIVCERT = 255 }; typedef enum ldns_enum_tlsa_certificate_usage ldns_tlsa_certificate_usage; @@ -61,13 +66,18 @@ enum ldns_enum_tlsa_selector * Full certificate: the Certificate binary structure * as defined in [RFC5280] */ - LDNS_TLSA_SELECTOR_FULL_CERTIFICATE = 0, + LDNS_TLSA_SELECTOR_CERT = 0, + LDNS_TLSA_SELECTOR_FULL_CERTIFICATE = 0, /** * SubjectPublicKeyInfo: DER-encoded binary structure * as defined in [RFC5280] */ - LDNS_TLSA_SELECTOR_SUBJECTPUBLICKEYINFO = 1 + LDNS_TLSA_SELECTOR_SPKI = 1, + LDNS_TLSA_SELECTOR_SUBJECTPUBLICKEYINFO = 1, + + /** Reserved for Private Use */ + LDNS_TLSA_SELECTOR_PRIVSEL = 255 }; typedef enum ldns_enum_tlsa_selector ldns_tlsa_selector; @@ -77,11 +87,16 @@ typedef enum ldns_enum_tlsa_selector ldns_tlsa_selector; enum ldns_enum_tlsa_matching_type { /** Exact match on selected content */ - LDNS_TLSA_MATCHING_TYPE_NO_HASH_USED = 0, + LDNS_TLSA_MATCHING_TYPE_FULL = 0, + LDNS_TLSA_MATCHING_TYPE_NO_HASH_USED = 0, /** SHA-256 hash of selected content [RFC6234] */ - LDNS_TLSA_MATCHING_TYPE_SHA256 = 1, + LDNS_TLSA_MATCHING_TYPE_SHA2_256 = 1, + LDNS_TLSA_MATCHING_TYPE_SHA256 = 1, /** SHA-512 hash of selected content [RFC6234] */ - LDNS_TLSA_MATCHING_TYPE_SHA512 = 2 + LDNS_TLSA_MATCHING_TYPE_SHA2_512 = 2, + LDNS_TLSA_MATCHING_TYPE_SHA512 = 2, + /** Reserved for Private Use */ + LDNS_TLSA_MATCHING_TYPE_PRIVMATCH = 255 }; typedef enum ldns_enum_tlsa_matching_type ldns_tlsa_matching_type; @@ -100,6 +115,7 @@ enum ldns_enum_dane_transport typedef enum ldns_enum_dane_transport ldns_dane_transport; +#if LDNS_BUILD_CONFIG_USE_DANE /** * Creates a dname consisting of the given name, prefixed by the service port * and type of transport: _<EM>port</EM>._<EM>transport</EM>.<EM>name</EM>. @@ -107,7 +123,7 @@ typedef enum ldns_enum_dane_transport ldns_dane_transport; * \param[out] tlsa_owner The created dname. * \param[in] name The dname that should be prefixed. * \param[in] port The service port number for wich the name should be created. - * \param[in] transport The transport for wich the name should be created. + * \param[in] transport The transport for which the name should be created. * \return LDNS_STATUS_OK on success or an error code otherwise. */ ldns_status ldns_dane_create_tlsa_owner(ldns_rdf** tlsa_owner, @@ -117,7 +133,7 @@ ldns_status ldns_dane_create_tlsa_owner(ldns_rdf** tlsa_owner, #if LDNS_BUILD_CONFIG_HAVE_SSL /** - * Creates a LDNS_RDF_TYPE_HEX type rdf based on the binary data choosen by + * Creates a LDNS_RDF_TYPE_HEX type rdf based on the binary data chosen by * the selector and encoded using matching_type. * * \param[out] rdf The created created rdf of type LDNS_RDF_TYPE_HEX. @@ -146,7 +162,7 @@ ldns_status ldns_dane_cert2rdf(ldns_rdf** rdf, X509* cert, * "CA constraint" or "Service Certificate Constraint" to * validate the certificate and, in case of "CA constraint", * select the CA. - * When pkix_validation_store is NULL, validation is explicitely + * When pkix_validation_store is NULL, validation is explicitly * turned off and the behaviour is then the same as for "Trust * anchor assertion" and "Domain issued certificate" respectively. * \param[in] cert_usage Which certificate to use and how to validate. @@ -185,6 +201,15 @@ ldns_status ldns_dane_create_tlsa_rr(ldns_rr** tlsa, X509* cert); /** + * BEWARE! We strongly recommend to use OpenSSL 1.1.0 dane verification + * functions instead of the ones provided by ldns. When OpenSSL 1.1.0 was + * available ldns will use the OpenSSL 1.1.0 dane verification functions + * under the hood. When ldns was linked with OpenSSL < 1.1.0, this function + * will not be able to verify TLSA records with DANE-TA usage types. + * + * BEWARE! The ldns dane verification functions do *not* do server name + * checks. The user has to perform additional server name checks themselves! + * * Verify if the given TLSA resource record matches the given certificate. * Reporting on a TLSA rr mismatch (LDNS_STATUS_DANE_TLSA_DID_NOT_MATCH) * is preferred over PKIX failure (LDNS_STATUS_DANE_PKIX_DID_NOT_VALIDATE). @@ -192,6 +217,11 @@ ldns_status ldns_dane_create_tlsa_rr(ldns_rr** tlsa, * but the TLSA data does not match, LDNS_STATUS_DANE_TLSA_DID_NOT_MATCH * is returned whether the PKIX validated or not. * + * When ldns is linked with OpenSSL < 1.1.0 and this function is available, + * then the DANE-TA usage type will not be verified, and on a tlsa_rr with + * this usage type, + * LDNS_STATUS_DANE_NEED_OPENSSL_GE_1_1_FOR_DANE_TA will be returned. + * * \param[in] tlsa_rr The resource record that specifies what and how to * match the certificate. With tlsa_rr == NULL, regular PKIX * validation is performed. @@ -203,6 +233,8 @@ ldns_status ldns_dane_create_tlsa_rr(ldns_rr** tlsa, * validate the certificate. * * \return LDNS_STATUS_OK on success, + * LDNS_STATUS_DANE_NEED_OPENSSL_GE_1_1_FOR_DANE_TA when the + * provided TLSA had the DANE-TA usage type, * LDNS_STATUS_DANE_TLSA_DID_NOT_MATCH on TLSA data mismatch, * LDNS_STATUS_DANE_PKIX_DID_NOT_VALIDATE when TLSA matched, * but the PKIX validation failed, or other ldns_status errors. @@ -212,6 +244,15 @@ ldns_status ldns_dane_verify_rr(const ldns_rr* tlsa_rr, X509_STORE* pkix_validation_store); /** + * BEWARE! We strongly recommend to use OpenSSL 1.1.0 dane verification + * functions instead of the ones provided by ldns. When OpenSSL 1.1.0 was + * available ldns will use the OpenSSL 1.1.0 dane verification functions + * under the hood. When ldns was linked with OpenSSL < 1.1.0, this function + * will not be able to verify TLSA records with DANE-TA usage types. + * + * BEWARE! The ldns dane verification functions do *not* do server name + * checks. The user has to perform additional server name checks themselves! + * * Verify if any of the given TLSA resource records matches the given * certificate. * @@ -227,20 +268,23 @@ ldns_status ldns_dane_verify_rr(const ldns_rr* tlsa_rr, * validate the certificate. * * \return LDNS_STATUS_OK on success, + * LDNS_STATUS_DANE_NEED_OPENSSL_GE_1_1_FOR_DANE_TA when at least one + * of the TLSA's had usage type DANE-TA and none of the TLSA's matched + * or PKIX validated, * LDNS_STATUS_DANE_PKIX_DID_NOT_VALIDATE when one of the TLSA's * matched but the PKIX validation failed, * LDNS_STATUS_DANE_TLSA_DID_NOT_MATCH when none of the TLSA's matched, * or other ldns_status errors. */ -ldns_status ldns_dane_verify(ldns_rr_list* tlsas, +ldns_status ldns_dane_verify(const ldns_rr_list* tlsas, X509* cert, STACK_OF(X509)* extra_certs, X509_STORE* pkix_validation_store); #endif /* LDNS_BUILD_CONFIG_HAVE_SSL */ +#endif /* LDNS_BUILD_CONFIG_USE_DANE */ #ifdef __cplusplus } #endif -#endif /* LDNS_BUILD_CONFIG_USE_DANE */ #endif /* LDNS_DANE_H */ |