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 #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