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