1 /* 2 * dane.h -- defines for the DNS-Based Authentication of Named Entities (DANE) 3 * Transport Layer Security (TLS) Protocol: TLSA 4 * 5 * Copyright (c) 2012, NLnet Labs. All rights reserved. 6 * 7 * See LICENSE for the license. 8 * 9 */ 10 11 /** 12 * \file 13 * 14 * This module contains base functions for creating and verifying TLSA RR's 15 * with PKIX certificates, certificate chains and validation stores. 16 * (See RFC6394 and RFC6698). 17 * 18 * Since those functions heavily rely op cryptographic operations, 19 * this module is dependent on openssl. 20 */ 21 22 23 #ifndef LDNS_DANE_H 24 #define LDNS_DANE_H 25 26 #include <ldns/common.h> 27 #include <ldns/rdata.h> 28 #include <ldns/rr.h> 29 #if LDNS_BUILD_CONFIG_HAVE_SSL 30 #include <openssl/ssl.h> 31 #include <openssl/err.h> 32 #endif /* LDNS_BUILD_CONFIG_HAVE_SSL */ 33 34 #ifdef __cplusplus 35 extern "C" { 36 #endif 37 38 /** 39 * The different "Certificate usage" rdata field values for a TLSA RR. 40 */ 41 enum ldns_enum_tlsa_certificate_usage 42 { 43 /** CA constraint */ 44 LDNS_TLSA_USAGE_PKIX_TA = 0, 45 LDNS_TLSA_USAGE_CA_CONSTRAINT = 0, 46 /** Service certificate constraint */ 47 LDNS_TLSA_USAGE_PKIX_EE = 1, 48 LDNS_TLSA_USAGE_SERVICE_CERTIFICATE_CONSTRAINT = 1, 49 /** Trust anchor assertion */ 50 LDNS_TLSA_USAGE_DANE_TA = 2, 51 LDNS_TLSA_USAGE_TRUST_ANCHOR_ASSERTION = 2, 52 /** Domain issued certificate */ 53 LDNS_TLSA_USAGE_DANE_EE = 3, 54 LDNS_TLSA_USAGE_DOMAIN_ISSUED_CERTIFICATE = 3, 55 /** Reserved for Private Use */ 56 LDNS_TLSA_USAGE_PRIVCERT = 255 57 }; 58 typedef enum ldns_enum_tlsa_certificate_usage ldns_tlsa_certificate_usage; 59 60 /** 61 * The different "Selector" rdata field values for a TLSA RR. 62 */ 63 enum ldns_enum_tlsa_selector 64 { 65 /** 66 * Full certificate: the Certificate binary structure 67 * as defined in [RFC5280] 68 */ 69 LDNS_TLSA_SELECTOR_CERT = 0, 70 LDNS_TLSA_SELECTOR_FULL_CERTIFICATE = 0, 71 72 /** 73 * SubjectPublicKeyInfo: DER-encoded binary structure 74 * as defined in [RFC5280] 75 */ 76 LDNS_TLSA_SELECTOR_SPKI = 1, 77 LDNS_TLSA_SELECTOR_SUBJECTPUBLICKEYINFO = 1, 78 79 /** Reserved for Private Use */ 80 LDNS_TLSA_SELECTOR_PRIVSEL = 255 81 }; 82 typedef enum ldns_enum_tlsa_selector ldns_tlsa_selector; 83 84 /** 85 * The different "Matching type" rdata field values for a TLSA RR. 86 */ 87 enum ldns_enum_tlsa_matching_type 88 { 89 /** Exact match on selected content */ 90 LDNS_TLSA_MATCHING_TYPE_FULL = 0, 91 LDNS_TLSA_MATCHING_TYPE_NO_HASH_USED = 0, 92 /** SHA-256 hash of selected content [RFC6234] */ 93 LDNS_TLSA_MATCHING_TYPE_SHA2_256 = 1, 94 LDNS_TLSA_MATCHING_TYPE_SHA256 = 1, 95 /** SHA-512 hash of selected content [RFC6234] */ 96 LDNS_TLSA_MATCHING_TYPE_SHA2_512 = 2, 97 LDNS_TLSA_MATCHING_TYPE_SHA512 = 2, 98 /** Reserved for Private Use */ 99 LDNS_TLSA_MATCHING_TYPE_PRIVMATCH = 255 100 }; 101 typedef enum ldns_enum_tlsa_matching_type ldns_tlsa_matching_type; 102 103 /** 104 * Known transports to use with TLSA owner names. 105 */ 106 enum ldns_enum_dane_transport 107 { 108 /** TCP */ 109 LDNS_DANE_TRANSPORT_TCP = 0, 110 /** UDP */ 111 LDNS_DANE_TRANSPORT_UDP = 1, 112 /** SCTP */ 113 LDNS_DANE_TRANSPORT_SCTP = 2 114 }; 115 typedef enum ldns_enum_dane_transport ldns_dane_transport; 116 117 118 #if LDNS_BUILD_CONFIG_USE_DANE 119 /** 120 * Creates a dname consisting of the given name, prefixed by the service port 121 * and type of transport: _<EM>port</EM>._<EM>transport</EM>.<EM>name</EM>. 122 * 123 * \param[out] tlsa_owner The created dname. 124 * \param[in] name The dname that should be prefixed. 125 * \param[in] port The service port number for which the name should be created. 126 * \param[in] transport The transport for which the name should be created. 127 * \return LDNS_STATUS_OK on success or an error code otherwise. 128 */ 129 ldns_status ldns_dane_create_tlsa_owner(ldns_rdf** tlsa_owner, 130 const ldns_rdf* name, uint16_t port, 131 ldns_dane_transport transport); 132 133 134 #if LDNS_BUILD_CONFIG_HAVE_SSL 135 /** 136 * Creates a LDNS_RDF_TYPE_HEX type rdf based on the binary data chosen by 137 * the selector and encoded using matching_type. 138 * 139 * \param[out] rdf The created created rdf of type LDNS_RDF_TYPE_HEX. 140 * \param[in] cert The certificate from which the data is selected 141 * \param[in] selector The full certificate or the public key 142 * \param[in] matching_type The full data or the SHA256 or SHA512 hash 143 * of the selected data 144 * \return LDNS_STATUS_OK on success or an error code otherwise. 145 */ 146 ldns_status ldns_dane_cert2rdf(ldns_rdf** rdf, X509* cert, 147 ldns_tlsa_selector selector, 148 ldns_tlsa_matching_type matching_type); 149 150 151 /** 152 * Selects the certificate from cert, extra_certs or the pkix_validation_store 153 * based on the value of cert_usage and index. 154 * 155 * \param[out] selected_cert The selected cert. 156 * \param[in] cert The certificate to validate (or not) 157 * \param[in] extra_certs Intermediate certificates that might be necessary 158 * during validation. May be NULL, except when the certificate 159 * usage is "Trust Anchor Assertion" because the trust anchor has 160 * to be provided.(otherwise choose a "Domain issued certificate!" 161 * \param[in] pkix_validation_store Used when the certificate usage is 162 * "CA constraint" or "Service Certificate Constraint" to 163 * validate the certificate and, in case of "CA constraint", 164 * select the CA. 165 * When pkix_validation_store is NULL, validation is explicitly 166 * turned off and the behaviour is then the same as for "Trust 167 * anchor assertion" and "Domain issued certificate" respectively. 168 * \param[in] cert_usage Which certificate to use and how to validate. 169 * \param[in] index Used to select the trust anchor when certificate usage 170 * is "Trust Anchor Assertion". 0 is the last certificate in the 171 * validation chain. 1 the one but last, etc. When index is -1, 172 * the last certificate is used that MUST be self-signed. 173 * This can help to make sure that the intended (self signed) 174 * trust anchor is actually present in extra_certs (which is a 175 * DANE requirement). 176 * 177 * \return LDNS_STATUS_OK on success or an error code otherwise. 178 */ 179 ldns_status ldns_dane_select_certificate(X509** selected_cert, 180 X509* cert, STACK_OF(X509)* extra_certs, 181 X509_STORE* pkix_validation_store, 182 ldns_tlsa_certificate_usage cert_usage, int index); 183 184 /** 185 * Creates a TLSA resource record from the certificate. 186 * No PKIX validation is performed! The given certificate is used as data 187 * regardless the value of certificate_usage. 188 * 189 * \param[out] tlsa The created TLSA resource record. 190 * \param[in] certificate_usage The value for the Certificate Usage field 191 * \param[in] selector The value for the Selector field 192 * \param[in] matching_type The value for the Matching Type field 193 * \param[in] cert The certificate which data will be represented 194 * 195 * \return LDNS_STATUS_OK on success or an error code otherwise. 196 */ 197 ldns_status ldns_dane_create_tlsa_rr(ldns_rr** tlsa, 198 ldns_tlsa_certificate_usage certificate_usage, 199 ldns_tlsa_selector selector, 200 ldns_tlsa_matching_type matching_type, 201 X509* cert); 202 203 /** 204 * BEWARE! We strongly recommend to use OpenSSL 1.1.0 dane verification 205 * functions instead of the ones provided by ldns. When OpenSSL 1.1.0 was 206 * available ldns will use the OpenSSL 1.1.0 dane verification functions 207 * under the hood. When ldns was linked with OpenSSL < 1.1.0, this function 208 * will not be able to verify TLSA records with DANE-TA usage types. 209 * 210 * BEWARE! The ldns dane verification functions do *not* do server name 211 * checks. The user has to perform additional server name checks themselves! 212 * 213 * Verify if the given TLSA resource record matches the given certificate. 214 * Reporting on a TLSA rr mismatch (LDNS_STATUS_DANE_TLSA_DID_NOT_MATCH) 215 * is preferred over PKIX failure (LDNS_STATUS_DANE_PKIX_DID_NOT_VALIDATE). 216 * So when PKIX validation is required by the TLSA Certificate usage, 217 * but the TLSA data does not match, LDNS_STATUS_DANE_TLSA_DID_NOT_MATCH 218 * is returned whether the PKIX validated or not. 219 * 220 * When ldns is linked with OpenSSL < 1.1.0 and this function is available, 221 * then the DANE-TA usage type will not be verified, and on a tlsa_rr with 222 * this usage type, 223 * LDNS_STATUS_DANE_NEED_OPENSSL_GE_1_1_FOR_DANE_TA will be returned. 224 * 225 * \param[in] tlsa_rr The resource record that specifies what and how to 226 * match the certificate. With tlsa_rr == NULL, regular PKIX 227 * validation is performed. 228 * \param[in] cert The certificate to match (and validate) 229 * \param[in] extra_certs Intermediate certificates that might be necessary 230 * creating the validation chain. 231 * \param[in] pkix_validation_store Used when the certificate usage is 232 * "CA constraint" or "Service Certificate Constraint" to 233 * validate the certificate. 234 * 235 * \return LDNS_STATUS_OK on success, 236 * LDNS_STATUS_DANE_NEED_OPENSSL_GE_1_1_FOR_DANE_TA when the 237 * provided TLSA had the DANE-TA usage type, 238 * LDNS_STATUS_DANE_TLSA_DID_NOT_MATCH on TLSA data mismatch, 239 * LDNS_STATUS_DANE_PKIX_DID_NOT_VALIDATE when TLSA matched, 240 * but the PKIX validation failed, or other ldns_status errors. 241 */ 242 ldns_status ldns_dane_verify_rr(const ldns_rr* tlsa_rr, 243 X509* cert, STACK_OF(X509)* extra_certs, 244 X509_STORE* pkix_validation_store); 245 246 /** 247 * BEWARE! We strongly recommend to use OpenSSL 1.1.0 dane verification 248 * functions instead of the ones provided by ldns. When OpenSSL 1.1.0 was 249 * available ldns will use the OpenSSL 1.1.0 dane verification functions 250 * under the hood. When ldns was linked with OpenSSL < 1.1.0, this function 251 * will not be able to verify TLSA records with DANE-TA usage types. 252 * 253 * BEWARE! The ldns dane verification functions do *not* do server name 254 * checks. The user has to perform additional server name checks themselves! 255 * 256 * Verify if any of the given TLSA resource records matches the given 257 * certificate. 258 * 259 * \param[in] tlsas The resource records that specify what and how to 260 * match the certificate. One must match for this function 261 * to succeed. With tlsas == NULL or the number of TLSA records 262 * in tlsas == 0, regular PKIX validation is performed. 263 * \param[in] cert The certificate to match (and validate) 264 * \param[in] extra_certs Intermediate certificates that might be necessary 265 * creating the validation chain. 266 * \param[in] pkix_validation_store Used when the certificate usage is 267 * "CA constraint" or "Service Certificate Constraint" to 268 * validate the certificate. 269 * 270 * \return LDNS_STATUS_OK on success, 271 * LDNS_STATUS_DANE_NEED_OPENSSL_GE_1_1_FOR_DANE_TA when at least one 272 * of the TLSA's had usage type DANE-TA and none of the TLSA's matched 273 * or PKIX validated, 274 * LDNS_STATUS_DANE_PKIX_DID_NOT_VALIDATE when one of the TLSA's 275 * matched but the PKIX validation failed, 276 * LDNS_STATUS_DANE_TLSA_DID_NOT_MATCH when none of the TLSA's matched, 277 * or other ldns_status errors. 278 */ 279 ldns_status ldns_dane_verify(const ldns_rr_list* tlsas, 280 X509* cert, STACK_OF(X509)* extra_certs, 281 X509_STORE* pkix_validation_store); 282 #endif /* LDNS_BUILD_CONFIG_HAVE_SSL */ 283 #endif /* LDNS_BUILD_CONFIG_USE_DANE */ 284 285 #ifdef __cplusplus 286 } 287 #endif 288 289 #endif /* LDNS_DANE_H */ 290 291