2 * dane.h -- defines for the DNS-Based Authentication of Named Entities (DANE)
3 * Transport Layer Security (TLS) Protocol: TLSA
5 * Copyright (c) 2012, NLnet Labs. All rights reserved.
7 * See LICENSE for the license.
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).
18 * Since those functions heavily rely op cryptographic operations,
19 * this module is dependent on openssl.
25 #if LDNS_BUILD_CONFIG_USE_DANE
27 #include <ldns/common.h>
28 #include <ldns/rdata.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 */
40 * The different "Certificate usage" rdata field values for a TLSA RR.
42 enum ldns_enum_tlsa_certificate_usage
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
53 typedef enum ldns_enum_tlsa_certificate_usage ldns_tlsa_certificate_usage;
56 * The different "Selector" rdata field values for a TLSA RR.
58 enum ldns_enum_tlsa_selector
61 * Full certificate: the Certificate binary structure
62 * as defined in [RFC5280]
64 LDNS_TLSA_SELECTOR_FULL_CERTIFICATE = 0,
67 * SubjectPublicKeyInfo: DER-encoded binary structure
68 * as defined in [RFC5280]
70 LDNS_TLSA_SELECTOR_SUBJECTPUBLICKEYINFO = 1
72 typedef enum ldns_enum_tlsa_selector ldns_tlsa_selector;
75 * The different "Matching type" rdata field values for a TLSA RR.
77 enum ldns_enum_tlsa_matching_type
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
86 typedef enum ldns_enum_tlsa_matching_type ldns_tlsa_matching_type;
89 * Known transports to use with TLSA owner names.
91 enum ldns_enum_dane_transport
94 LDNS_DANE_TRANSPORT_TCP = 0,
96 LDNS_DANE_TRANSPORT_UDP = 1,
98 LDNS_DANE_TRANSPORT_SCTP = 2
100 typedef enum ldns_enum_dane_transport ldns_dane_transport;
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>.
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.
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);
118 #if LDNS_BUILD_CONFIG_HAVE_SSL
120 * Creates a LDNS_RDF_TYPE_HEX type rdf based on the binary data choosen by
121 * the selector and encoded using matching_type.
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.
130 ldns_status ldns_dane_cert2rdf(ldns_rdf** rdf, X509* cert,
131 ldns_tlsa_selector selector,
132 ldns_tlsa_matching_type matching_type);
136 * Selects the certificate from cert, extra_certs or the pkix_validation_store
137 * based on the value of cert_usage and index.
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",
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
161 * \return LDNS_STATUS_OK on success or an error code otherwise.
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);
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.
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
179 * \return LDNS_STATUS_OK on success or an error code otherwise.
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,
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.
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.
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.
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);
215 * Verify if any of the given TLSA resource records matches the given
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.
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.
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 */
244 #endif /* LDNS_BUILD_CONFIG_USE_DANE */
245 #endif /* LDNS_DANE_H */