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 2.1 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 <https://www.gnu.org/licenses/> 20 * 21 */ 22 23 #ifndef GNUTLS_DANE_H 24 #define GNUTLS_DANE_H 25 26 #include <gnutls/gnutls.h> /* for gnutls_datum_t */ 27 28 /** 29 * dane_cert_usage_t: 30 * @DANE_CERT_USAGE_CA: CA constraint. The certificate/key 31 * presented must have signed the verified key. 32 * @DANE_CERT_USAGE_EE: The key or the certificate of the end 33 * entity. 34 * @DANE_CERT_USAGE_LOCAL_CA: The remote CA is local and possibly 35 * untrusted by the verifier. 36 * @DANE_CERT_USAGE_LOCAL_EE: The remote end-entity key is local 37 * and possibly untrusted by the verifier (not signed by a CA). 38 * 39 * Enumeration of different certificate usage types. 40 */ 41 typedef enum dane_cert_usage_t { 42 DANE_CERT_USAGE_CA = 0, 43 DANE_CERT_USAGE_EE = 1, 44 DANE_CERT_USAGE_LOCAL_CA = 2, 45 DANE_CERT_USAGE_LOCAL_EE = 3 46 } dane_cert_usage_t; 47 48 /** 49 * dane_cert_type_t: 50 * @DANE_CERT_X509: An X.509 certificate. 51 * @DANE_CERT_PK: A public key. 52 * 53 * Enumeration of different certificate types. 54 */ 55 typedef enum dane_cert_type_t { 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 DANE_MATCH_EXACT = 0, 70 DANE_MATCH_SHA2_256 = 1, 71 DANE_MATCH_SHA2_512 = 2 72 } dane_match_type_t; 73 74 /** 75 * dane_query_status_t: 76 * @DANE_QUERY_UNKNOWN: There was no query. 77 * @DANE_QUERY_DNSSEC_VERIFIED: The query was verified using DNSSEC. 78 * @DANE_QUERY_BOGUS: The query has wrong DNSSEC signature. 79 * @DANE_QUERY_NO_DNSSEC: The query has no DNSSEC data. 80 * 81 * Enumeration of different certificate types. 82 */ 83 typedef enum dane_query_status_t { 84 DANE_QUERY_UNKNOWN = 0, 85 DANE_QUERY_DNSSEC_VERIFIED, 86 DANE_QUERY_BOGUS, 87 DANE_QUERY_NO_DNSSEC 88 } dane_query_status_t; 89 90 typedef struct dane_state_st *dane_state_t; 91 typedef struct dane_query_st *dane_query_t; 92 93 /** 94 * dane_state_flags_t: 95 * @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. 96 * @DANE_F_INSECURE: Ignore any DNSSEC signature verification errors. 97 * @DANE_F_IGNORE_DNSSEC: Do not try to initialize DNSSEC as we will not use it (will then not try to load the DNSSEC root certificate). Useful if the TLSA data does not come from DNS. 98 * 99 * Enumeration of different verification flags. 100 */ 101 typedef enum dane_state_flags_t { 102 DANE_F_IGNORE_LOCAL_RESOLVER = 1, 103 DANE_F_INSECURE = 2, 104 DANE_F_IGNORE_DNSSEC = 4 105 } dane_state_flags_t; 106 107 int dane_state_init(dane_state_t * s, unsigned int flags); 108 int dane_state_set_dlv_file(dane_state_t s, const char *file); 109 void dane_state_deinit(dane_state_t s); 110 111 112 int dane_raw_tlsa(dane_state_t s, dane_query_t * r, char *const *dane_data, 113 const int *dane_data_len, int secure, int bogus); 114 115 int dane_query_tlsa(dane_state_t s, dane_query_t * r, const char *host, 116 const char *proto, unsigned int port); 117 118 dane_query_status_t dane_query_status(dane_query_t q); 119 unsigned int dane_query_entries(dane_query_t q); 120 int dane_query_data(dane_query_t q, unsigned int idx, 121 unsigned int *usage, unsigned int *type, 122 unsigned int *match, gnutls_datum_t * data); 123 int dane_query_to_raw_tlsa(dane_query_t q, unsigned int *data_entries, 124 char ***dane_data, int **dane_data_len, int *secure, int *bogus); 125 void dane_query_deinit(dane_query_t q); 126 127 const char *dane_cert_type_name(dane_cert_type_t type); 128 const char *dane_match_type_name(dane_match_type_t type); 129 const char *dane_cert_usage_name(dane_cert_usage_t usage); 130 131 /** 132 * dane_verify_flags_t: 133 * @DANE_VFLAG_FAIL_IF_NOT_CHECKED: If irrelevant to this certificate DANE entries are received fail instead of succeeding. 134 * @DANE_VFLAG_ONLY_CHECK_EE_USAGE: The provided certificates will be verified only against any EE field. Combine with %DANE_VFLAG_FAIL_IF_NOT_CHECKED to fail if EE entries are not present. 135 * @DANE_VFLAG_ONLY_CHECK_CA_USAGE: The provided certificates will be verified only against any CA field. Combine with %DANE_VFLAG_FAIL_IF_NOT_CHECKED to fail if CA entries are not present. 136 * 137 * Enumeration of different verification status flags. 138 */ 139 typedef enum dane_verify_flags_t { 140 DANE_VFLAG_FAIL_IF_NOT_CHECKED = 1, 141 DANE_VFLAG_ONLY_CHECK_EE_USAGE = 1 << 1, 142 DANE_VFLAG_ONLY_CHECK_CA_USAGE = 1 << 2, 143 } dane_verify_flags_t; 144 145 /** 146 * dane_verify_status_t: 147 * @DANE_VERIFY_CA_CONSTRAINTS_VIOLATED: The CA constraints were violated. 148 * @DANE_VERIFY_CERT_DIFFERS: The certificate obtained via DNS differs. 149 * @DANE_VERIFY_UNKNOWN_DANE_INFO: No known DANE data was found in the DNS record. 150 * 151 * Enumeration of different verification status flags. 152 */ 153 typedef enum dane_verify_status_t { 154 DANE_VERIFY_CA_CONSTRAINTS_VIOLATED = 1, 155 DANE_VERIFY_CERT_DIFFERS = 1 << 1, 156 DANE_VERIFY_UNKNOWN_DANE_INFO = 1 << 2, 157 } dane_verify_status_t; 158 159 #define DANE_VERIFY_CA_CONSTRAINS_VIOLATED DANE_VERIFY_CA_CONSTRAINTS_VIOLATED 160 #define DANE_VERIFY_NO_DANE_INFO DANE_VERIFY_UNKNOWN_DANE_INFO 161 162 int 163 dane_verification_status_print(unsigned int status, 164 gnutls_datum_t * out, unsigned int flags); 165 166 int dane_verify_crt_raw(dane_state_t s, 167 const gnutls_datum_t * chain, unsigned chain_size, 168 gnutls_certificate_type_t chain_type, 169 dane_query_t r, 170 unsigned int sflags, unsigned int vflags, 171 unsigned int *verify); 172 173 int dane_verify_crt(dane_state_t s, 174 const gnutls_datum_t * chain, unsigned chain_size, 175 gnutls_certificate_type_t chain_type, 176 const char *hostname, const char *proto, 177 unsigned int port, unsigned int sflags, 178 unsigned int vflags, unsigned int *verify); 179 180 int dane_verify_session_crt(dane_state_t s, 181 gnutls_session_t session, 182 const char *hostname, const char *proto, 183 unsigned int port, unsigned int sflags, 184 unsigned int vflags, unsigned int *verify); 185 186 const char *dane_strerror(int error); 187 188 #define DANE_E_SUCCESS 0 189 #define DANE_E_INITIALIZATION_ERROR -1 190 #define DANE_E_RESOLVING_ERROR -2 191 #define DANE_E_NO_DANE_DATA -3 192 #define DANE_E_RECEIVED_CORRUPT_DATA -4 193 #define DANE_E_INVALID_DNSSEC_SIG -5 194 #define DANE_E_NO_DNSSEC_SIG -6 195 #define DANE_E_MEMORY_ERROR -7 196 #define DANE_E_REQUESTED_DATA_NOT_AVAILABLE -8 197 #define DANE_E_INVALID_REQUEST -9 198 #define DANE_E_PUBKEY_ERROR -10 199 #define DANE_E_NO_CERT -11 200 #define DANE_E_FILE_ERROR -12 201 #define DANE_E_CERT_ERROR -13 202 #define DANE_E_UNKNOWN_DANE_DATA -14 203 204 #endif /* GNUTLS_DANE_H */ 205