contrib/ldns/ldns/dane.h

   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