libdane/includes/gnutls/dane.h

   1 /* -*- c -*-
   2  * Copyright (C) 2012 KU Leuven
   3  *
   4  * Author: Nikos Mavrogiannopoulos
   5  *
   6  * This file is part of libdane.
   7  *
   8  * libdane is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Lesser General Public License
  10  * as published by the Free Software Foundation; either version 3 of
  11  * the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful, but
  14  * WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Lesser General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public License
  19  * along with this program.  If not, see <http://www.gnu.org/licenses/>
  20  *
  21  */
  22
  23
  24 #include <gnutls/gnutls.h> /* for gnutls_datum_t */
  25
  26 /**
  27  * dane_cert_usage_t:
  28  * @DANE_CERT_USAGE_CA: CA constraint. The certificate/key
  29  *   presented must have signed the verified key.
  30  * @DANE_CERT_USAGE_EE: The key or the certificate of the end
  31  *   entity.
  32  * @DANE_CERT_USAGE_LOCAL_CA: The remote CA is local and possibly
  33  *   untrusted by the verifier.
  34  * @DANE_CERT_USAGE_LOCAL_EE: The remote end-entity key is local
  35  *   and possibly untrusted by the verifier (not signed by a CA).
  36  *
  37  * Enumeration of different certificate usage types.
  38  */
  39 typedef enum dane_cert_usage_t
  40 {
  41   DANE_CERT_USAGE_CA = 0,
  42   DANE_CERT_USAGE_EE = 1,
  43   DANE_CERT_USAGE_LOCAL_CA = 2,
  44   DANE_CERT_USAGE_LOCAL_EE = 3
  45 } dane_cert_usage_t;
  46
  47 /**
  48  * dane_cert_type_t:
  49  * @DANE_CERT_X509: An X.509 certificate.
  50  * @DANE_CERT_PK: A public key.
  51  *
  52  * Enumeration of different certificate types.
  53  */
  54 typedef enum dane_cert_type_t
  55 {
  56   DANE_CERT_X509 = 0,
  57   DANE_CERT_PK = 1
  58 } dane_cert_type_t;
  59
  60 /**
  61  * dane_match_type_t:
  62  * @DANE_MATCH_EXACT: The full content.
  63  * @DANE_MATCH_SHA2_256: A SHA-256 hash of the content.
  64  * @DANE_MATCH_SHA2_512: A SHA-512 hash of the content.
  65  *
  66  * Enumeration of different content matching types.
  67  */
  68 typedef enum dane_match_type_t
  69 {
  70   DANE_MATCH_EXACT = 0,
  71   DANE_MATCH_SHA2_256 = 1,
  72   DANE_MATCH_SHA2_512 = 2
  73 } dane_match_type_t;
  74
  75 /**
  76  * dane_query_status_t:
  77  * @DANE_QUERY_UNKNOWN: There was no query.
  78  * @DANE_QUERY_DNSSEC_VERIFIED: The query was verified using DNSSEC.
  79  * @DANE_QUERY_BOGUS: The query has wrong DNSSEC signature.
  80  * @DANE_QUERY_NO_DNSSEC: The query has no DNSSEC data.
  81  *
  82  * Enumeration of different certificate types.
  83  */
  84 typedef enum dane_query_status_t
  85 {
  86   DANE_QUERY_UNKNOWN = 0,
  87   DANE_QUERY_DNSSEC_VERIFIED,
  88   DANE_QUERY_BOGUS,
  89   DANE_QUERY_NO_DNSSEC
  90 } dane_query_status_t;
  91
  92 typedef struct dane_state_st *dane_state_t;
  93 typedef struct dane_query_st *dane_query_t;
  94
  95 /**
  96  * dane_state_flags_t:
  97  * @DANE_F_IGNORE_LOCAL_RESOLVER: Many systems are not DNSSEC-ready. In that case the local resolver is ignored, and a direct recursive resolve occurs.
  98  *
  99  * Enumeration of different verification flags.
 100  */
 101 typedef enum dane_state_flags_t
 102 {
 103   DANE_F_IGNORE_LOCAL_RESOLVER = 1,
 104 } dane_state_flags_t;
 105
 106 int dane_state_init (dane_state_t* s, unsigned int flags);
 107 void dane_state_deinit (dane_state_t s);
 108
 109 int dane_query_tlsa(dane_state_t s, dane_query_t *r, const char* host, const char* proto, unsigned int port);
 110
 111 dane_query_status_t dane_query_status(dane_query_t q);
 112 unsigned int dane_query_entries(dane_query_t q);
 113 int dane_query_data(dane_query_t q, unsigned int idx,
 114                         unsigned int *usage, unsigned int *type,
 115                         unsigned int *match, gnutls_datum_t * data);
 116 void dane_query_deinit(dane_query_t q);
 117
 118 const char* dane_cert_type_name(dane_cert_type_t type);
 119 const char* dane_match_type_name(dane_match_type_t type);
 120 const char* dane_cert_usage_name(dane_cert_usage_t usage);
 121
 122 /**
 123  * dane_verify_status_t:
 124  * @DANE_VERIFY_CA_CONSTRAINS_VIOLATED: The CA constrains was violated.
 125  * @DANE_VERIFY_CERT_DIFFERS: The certificate obtained via DNS differs.
 126  * @DANE_VERIFY_NO_DANE_INFO: No DANE data were found in the DNS record.
 127  *
 128  * Enumeration of different verification status flags.
 129  */
 130 typedef enum dane_verify_status_t
 131 {
 132   DANE_VERIFY_CA_CONSTRAINS_VIOLATED = 1,
 133   DANE_VERIFY_CERT_DIFFERS = 1<<1,
 134   DANE_VERIFY_NO_DANE_INFO = 1<<2,
 135 } dane_verify_status_t;
 136
 137 int
 138 dane_verification_status_print (unsigned int status,
 139                        gnutls_datum_t * out, unsigned int flags);
 140
 141 int dane_verify_crt (dane_state_t s,
 142         const gnutls_datum_t *chain, unsigned chain_size,
 143         gnutls_certificate_type_t chain_type,
 144         const char * hostname, const char* proto, unsigned int port,
 145         unsigned int sflags, unsigned int vflags,
 146         unsigned int *verify);
 147
 148 int dane_verify_session_crt (
 149         dane_state_t s,
 150         gnutls_session_t session,
 151         const char * hostname, const char* proto, unsigned int port,
 152         unsigned int sflags, unsigned int vflags,
 153         unsigned int *verify);
 154
 155 const char * dane_strerror (int error);
 156
 157 #define DANE_E_SUCCESS 0
 158 #define DANE_E_INITIALIZATION_ERROR -1
 159 #define DANE_E_RESOLVING_ERROR -2
 160 #define DANE_E_NO_DANE_DATA -3
 161 #define DANE_E_RECEIVED_CORRUPT_DATA -4
 162 #define DANE_E_INVALID_DNSSEC_SIG -5
 163 #define DANE_E_NO_DNSSEC_SIG -6
 164 #define DANE_E_MEMORY_ERROR -7
 165 #define DANE_E_REQUESTED_DATA_NOT_AVAILABLE -8
 166 #define DANE_E_INVALID_REQUEST -9
 167 #define DANE_E_PUBKEY_ERROR -10
 168 #define DANE_E_NO_CERT -11
 169