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 #if LDNS_BUILD_CONFIG_USE_DANE 26 27 #include <ldns/common.h> 28 #include <ldns/rdata.h> 29 #include <ldns/rr.h> 30 #if LDNS_BUILD_CONFIG_HAVE_SSL 31 #include <openssl/ssl.h> 32 #include <openssl/err.h> 33 #endif /* LDNS_BUILD_CONFIG_HAVE_SSL */ 34 35 #ifdef __cplusplus 36 extern "C" { 37 #endif 38 39 /** 40 * The different "Certificate usage" rdata field values for a TLSA RR. 41 */ 42 enum ldns_enum_tlsa_certificate_usage 43 { 44 /** CA constraint */ 45 LDNS_TLSA_USAGE_CA_CONSTRAINT = 0, 46 /** Sevice certificate constraint */ 47 LDNS_TLSA_USAGE_SERVICE_CERTIFICATE_CONSTRAINT = 1, 48 /** Trust anchor assertion */ 49 LDNS_TLSA_USAGE_TRUST_ANCHOR_ASSERTION = 2, 50 /** Domain issued certificate */ 51 LDNS_TLSA_USAGE_DOMAIN_ISSUED_CERTIFICATE = 3 52 }; 53 typedef enum ldns_enum_tlsa_certificate_usage ldns_tlsa_certificate_usage; 54 55 /** 56 * The different "Selector" rdata field values for a TLSA RR. 57 */ 58 enum ldns_enum_tlsa_selector 59 { 60 /** 61 * Full certificate: the Certificate binary structure 62 * as defined in [RFC5280] 63 */ 64 LDNS_TLSA_SELECTOR_FULL_CERTIFICATE = 0, 65 66 /** 67 * SubjectPublicKeyInfo: DER-encoded binary structure 68 * as defined in [RFC5280] 69 */ 70 LDNS_TLSA_SELECTOR_SUBJECTPUBLICKEYINFO = 1 71 }; 72 typedef enum ldns_enum_tlsa_selector ldns_tlsa_selector; 73 74 /** 75 * The different "Matching type" rdata field values for a TLSA RR. 76 */ 77 enum ldns_enum_tlsa_matching_type 78 { 79 /** Exact match on selected content */ 80 LDNS_TLSA_MATCHING_TYPE_NO_HASH_USED = 0, 81 /** SHA-256 hash of selected content [RFC6234] */ 82 LDNS_TLSA_MATCHING_TYPE_SHA256 = 1, 83 /** SHA-512 hash of selected content [RFC6234] */ 84 LDNS_TLSA_MATCHING_TYPE_SHA512 = 2 85 }; 86 typedef enum ldns_enum_tlsa_matching_type ldns_tlsa_matching_type; 87 88 /** 89 * Known transports to use with TLSA owner names. 90 */ 91 enum ldns_enum_dane_transport 92 { 93 /** TCP */ 94 LDNS_DANE_TRANSPORT_TCP = 0, 95 /** UDP */ 96 LDNS_DANE_TRANSPORT_UDP = 1, 97 /** SCTP */ 98 LDNS_DANE_TRANSPORT_SCTP = 2 99 }; 100 typedef enum ldns_enum_dane_transport ldns_dane_transport; 101 102 103 /** 104 * Creates a dname consisting of the given name, prefixed by the service port 105 * and type of transport: _<EM>port</EM>._<EM>transport</EM>.<EM>name</EM>. 106 * 107 * \param[out] tlsa_owner The created dname. 108 * \param[in] name The dname that should be prefixed. 109 * \param[in] port The service port number for wich the name should be created. 110 * \param[in] transport The transport for wich the name should be created. 111 * \return LDNS_STATUS_OK on success or an error code otherwise. 112 */ 113 ldns_status ldns_dane_create_tlsa_owner(ldns_rdf** tlsa_owner, 114 const ldns_rdf* name, uint16_t port, 115 ldns_dane_transport transport); 116 117 118 #if LDNS_BUILD_CONFIG_HAVE_SSL 119 /** 120 * Creates a LDNS_RDF_TYPE_HEX type rdf based on the binary data choosen by 121 * the selector and encoded using matching_type. 122 * 123 * \param[out] rdf The created created rdf of type LDNS_RDF_TYPE_HEX. 124 * \param[in] cert The certificate from which the data is selected 125 * \param[in] selector The full certificate or the public key 126 * \param[in] matching_type The full data or the SHA256 or SHA512 hash 127 * of the selected data 128 * \return LDNS_STATUS_OK on success or an error code otherwise. 129 */ 130 ldns_status ldns_dane_cert2rdf(ldns_rdf** rdf, X509* cert, 131 ldns_tlsa_selector selector, 132 ldns_tlsa_matching_type matching_type); 133 134 135 /** 136 * Selects the certificate from cert, extra_certs or the pkix_validation_store 137 * based on the value of cert_usage and index. 138 * 139 * \param[out] selected_cert The selected cert. 140 * \param[in] cert The certificate to validate (or not) 141 * \param[in] extra_certs Intermediate certificates that might be necessary 142 * during validation. May be NULL, except when the certificate 143 * usage is "Trust Anchor Assertion" because the trust anchor has 144 * to be provided.(otherwise choose a "Domain issued certificate!" 145 * \param[in] pkix_validation_store Used when the certificate usage is 146 * "CA constraint" or "Service Certificate Constraint" to 147 * validate the certificate and, in case of "CA constraint", 148 * select the CA. 149 * When pkix_validation_store is NULL, validation is explicitely 150 * turned off and the behaviour is then the same as for "Trust 151 * anchor assertion" and "Domain issued certificate" respectively. 152 * \param[in] cert_usage Which certificate to use and how to validate. 153 * \param[in] index Used to select the trust anchor when certificate usage 154 * is "Trust Anchor Assertion". 0 is the last certificate in the 155 * validation chain. 1 the one but last, etc. When index is -1, 156 * the last certificate is used that MUST be self-signed. 157 * This can help to make sure that the intended (self signed) 158 * trust anchor is actually present in extra_certs (which is a 159 * DANE requirement). 160 * 161 * \return LDNS_STATUS_OK on success or an error code otherwise. 162 */ 163 ldns_status ldns_dane_select_certificate(X509** selected_cert, 164 X509* cert, STACK_OF(X509)* extra_certs, 165 X509_STORE* pkix_validation_store, 166 ldns_tlsa_certificate_usage cert_usage, int index); 167 168 /** 169 * Creates a TLSA resource record from the certificate. 170 * No PKIX validation is performed! The given certificate is used as data 171 * regardless the value of certificate_usage. 172 * 173 * \param[out] tlsa The created TLSA resource record. 174 * \param[in] certificate_usage The value for the Certificate Usage field 175 * \param[in] selector The value for the Selector field 176 * \param[in] matching_type The value for the Matching Type field 177 * \param[in] cert The certificate which data will be represented 178 * 179 * \return LDNS_STATUS_OK on success or an error code otherwise. 180 */ 181 ldns_status ldns_dane_create_tlsa_rr(ldns_rr** tlsa, 182 ldns_tlsa_certificate_usage certificate_usage, 183 ldns_tlsa_selector selector, 184 ldns_tlsa_matching_type matching_type, 185 X509* cert); 186 187 /** 188 * Verify if the given TLSA resource record matches the given certificate. 189 * Reporting on a TLSA rr mismatch (LDNS_STATUS_DANE_TLSA_DID_NOT_MATCH) 190 * is preferred over PKIX failure (LDNS_STATUS_DANE_PKIX_DID_NOT_VALIDATE). 191 * So when PKIX validation is required by the TLSA Certificate usage, 192 * but the TLSA data does not match, LDNS_STATUS_DANE_TLSA_DID_NOT_MATCH 193 * is returned whether the PKIX validated or not. 194 * 195 * \param[in] tlsa_rr The resource record that specifies what and how to 196 * match the certificate. With tlsa_rr == NULL, regular PKIX 197 * validation is performed. 198 * \param[in] cert The certificate to match (and validate) 199 * \param[in] extra_certs Intermediate certificates that might be necessary 200 * creating the validation chain. 201 * \param[in] pkix_validation_store Used when the certificate usage is 202 * "CA constraint" or "Service Certificate Constraint" to 203 * validate the certificate. 204 * 205 * \return LDNS_STATUS_OK on success, 206 * LDNS_STATUS_DANE_TLSA_DID_NOT_MATCH on TLSA data mismatch, 207 * LDNS_STATUS_DANE_PKIX_DID_NOT_VALIDATE when TLSA matched, 208 * but the PKIX validation failed, or other ldns_status errors. 209 */ 210 ldns_status ldns_dane_verify_rr(const ldns_rr* tlsa_rr, 211 X509* cert, STACK_OF(X509)* extra_certs, 212 X509_STORE* pkix_validation_store); 213 214 /** 215 * Verify if any of the given TLSA resource records matches the given 216 * certificate. 217 * 218 * \param[in] tlsas The resource records that specify what and how to 219 * match the certificate. One must match for this function 220 * to succeed. With tlsas == NULL or the number of TLSA records 221 * in tlsas == 0, regular PKIX validation is performed. 222 * \param[in] cert The certificate to match (and validate) 223 * \param[in] extra_certs Intermediate certificates that might be necessary 224 * creating the validation chain. 225 * \param[in] pkix_validation_store Used when the certificate usage is 226 * "CA constraint" or "Service Certificate Constraint" to 227 * validate the certificate. 228 * 229 * \return LDNS_STATUS_OK on success, 230 * LDNS_STATUS_DANE_PKIX_DID_NOT_VALIDATE when one of the TLSA's 231 * matched but the PKIX validation failed, 232 * LDNS_STATUS_DANE_TLSA_DID_NOT_MATCH when none of the TLSA's matched, 233 * or other ldns_status errors. 234 */ 235 ldns_status ldns_dane_verify(ldns_rr_list* tlsas, 236 X509* cert, STACK_OF(X509)* extra_certs, 237 X509_STORE* pkix_validation_store); 238 #endif /* LDNS_BUILD_CONFIG_HAVE_SSL */ 239 240 #ifdef __cplusplus 241 } 242 #endif 243 244 #endif /* LDNS_BUILD_CONFIG_USE_DANE */ 245 #endif /* LDNS_DANE_H */ 246 247