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