doc/dane-api.texi

   1
   2 @subheading dane_cert_type_name
   3 @anchor{dane_cert_type_name}
   4 @deftypefun {const char *} {dane_cert_type_name} (dane_cert_type_t @var{type})
   5 @var{type}: is a DANE match type
   6
   7 Convert a @code{dane_cert_type_t}  value to a string.
   8
   9 @strong{Returns:} a string that contains the name of the specified
  10 type, or @code{NULL} .
  11 @end deftypefun
  12
  13 @subheading dane_cert_usage_name
  14 @anchor{dane_cert_usage_name}
  15 @deftypefun {const char *} {dane_cert_usage_name} (dane_cert_usage_t @var{usage})
  16 @var{usage}: -- undescribed --
  17
  18 Convert a @code{dane_cert_usage_t}  value to a string.
  19
  20 @strong{Returns:} a string that contains the name of the specified
  21 type, or @code{NULL} .
  22 @end deftypefun
  23
  24 @subheading dane_match_type_name
  25 @anchor{dane_match_type_name}
  26 @deftypefun {const char *} {dane_match_type_name} (dane_match_type_t @var{type})
  27 @var{type}: is a DANE match type
  28
  29 Convert a @code{dane_match_type_t}  value to a string.
  30
  31 @strong{Returns:} a string that contains the name of the specified
  32 type, or @code{NULL} .
  33 @end deftypefun
  34
  35 @subheading dane_query_data
  36 @anchor{dane_query_data}
  37 @deftypefun {int} {dane_query_data} (dane_query_t @var{q}, unsigned int @var{idx}, unsigned int * @var{usage}, unsigned int * @var{type}, unsigned int * @var{match}, gnutls_datum_t * @var{data})
  38 @var{q}: The query result structure
  39
  40 @var{idx}: The index of the query response.
  41
  42 @var{usage}: The certificate usage (see @code{dane_cert_usage_t} )
  43
  44 @var{type}: The certificate type (see @code{dane_cert_type_t} )
  45
  46 @var{match}: The DANE matching type (see @code{dane_match_type_t} )
  47
  48 @var{data}: The DANE data.
  49
  50 This function will provide the DANE data from the query
  51 response.
  52
  53 @strong{Returns:} On success, @code{DANE_E_SUCCESS}  (0) is returned, otherwise a
  54 negative error value.
  55 @end deftypefun
  56
  57 @subheading dane_query_deinit
  58 @anchor{dane_query_deinit}
  59 @deftypefun {void} {dane_query_deinit} (dane_query_t @var{q})
  60 @var{q}: The structure to be deinitialized
  61
  62 This function will deinitialize a DANE query result structure.
  63 @end deftypefun
  64
  65 @subheading dane_query_entries
  66 @anchor{dane_query_entries}
  67 @deftypefun {unsigned int} {dane_query_entries} (dane_query_t @var{q})
  68 @var{q}: The query result structure
  69
  70 This function will return the number of entries in a query.
  71
  72 @strong{Returns:} The number of entries.
  73 @end deftypefun
  74
  75 @subheading dane_query_status
  76 @anchor{dane_query_status}
  77 @deftypefun {dane_query_status_t} {dane_query_status} (dane_query_t @var{q})
  78 @var{q}: The query result structure
  79
  80 This function will return the status of the query response.
  81 See @code{dane_query_status_t}  for the possible types.
  82
  83 @strong{Returns:} The status type.
  84 @end deftypefun
  85
  86 @subheading dane_query_tlsa
  87 @anchor{dane_query_tlsa}
  88 @deftypefun {int} {dane_query_tlsa} (dane_state_t @var{s}, dane_query_t * @var{r}, const char * @var{host}, const char * @var{proto}, unsigned int @var{port})
  89 @var{s}: The DANE state structure
  90
  91 @var{r}: A structure to place the result
  92
  93 @var{host}: The host name to resolve.
  94
  95 @var{proto}: The protocol type (tcp, udp, etc.)
  96
  97 @var{port}: The service port number (eg. 443).
  98
  99 This function will query the DNS server for the TLSA (DANE)
 100 data for the given host.
 101
 102 @strong{Returns:} On success, @code{DANE_E_SUCCESS}  (0) is returned, otherwise a
 103 negative error value.
 104 @end deftypefun
 105
 106 @subheading dane_query_to_raw_tlsa
 107 @anchor{dane_query_to_raw_tlsa}
 108 @deftypefun {int} {dane_query_to_raw_tlsa} (dane_query_t @var{q}, unsigned int * @var{data_entries}, char *** @var{dane_data}, int ** @var{dane_data_len}, int * @var{secure}, int * @var{bogus})
 109 @var{q}: The query result structure
 110
 111 @var{data_entries}: Pointer set to the number of entries in the query
 112
 113 @var{dane_data}: Pointer to contain an array of DNS rdata items, terminated with a NULL pointer;
 114 caller must guarantee that the referenced data remains
 115 valid until @code{dane_query_deinit()}  is called.
 116
 117 @var{dane_data_len}: Pointer to contain the length n bytes of the dane_data items
 118
 119 @var{secure}: Pointer set true if the result is validated securely, false if
 120 validation failed or the domain queried has no security info
 121
 122 @var{bogus}: Pointer set true if the result was not secure due to a security failure
 123
 124 This function will provide the DANE data from the query
 125 response.
 126
 127 The pointers dane_data and dane_data_len are allocated with @code{gnutls_malloc()}
 128 to contain the data from the query result structure (individual
 129  @code{dane_data} items simply point to the original data and are not allocated separately).
 130 The returned  @code{dane_data} are only valid during the lifetime of  @code{q} .
 131
 132 @strong{Returns:} On success, @code{DANE_E_SUCCESS}  (0) is returned, otherwise a
 133 negative error value.
 134 @end deftypefun
 135
 136 @subheading dane_raw_tlsa
 137 @anchor{dane_raw_tlsa}
 138 @deftypefun {int} {dane_raw_tlsa} (dane_state_t @var{s}, dane_query_t * @var{r}, char *const * @var{dane_data}, const int * @var{dane_data_len}, int @var{secure}, int @var{bogus})
 139 @var{s}: The DANE state structure
 140
 141 @var{r}: A structure to place the result
 142
 143 @var{dane_data}: array of DNS rdata items, terminated with a NULL pointer;
 144 caller must guarantee that the referenced data remains
 145 valid until @code{dane_query_deinit()}  is called.
 146
 147 @var{dane_data_len}: the length n bytes of the dane_data items
 148
 149 @var{secure}: true if the result is validated securely, false if
 150 validation failed or the domain queried has no security info
 151
 152 @var{bogus}: if the result was not secure (secure = 0) due to a security failure,
 153 and the result is due to a security failure, bogus is true.
 154
 155 This function will fill in the TLSA (DANE) structure from
 156 the given raw DNS record data. The  @code{dane_data} must be valid
 157 during the lifetime of the query.
 158
 159 @strong{Returns:} On success, @code{DANE_E_SUCCESS}  (0) is returned, otherwise a
 160 negative error value.
 161 @end deftypefun
 162
 163 @subheading dane_state_deinit
 164 @anchor{dane_state_deinit}
 165 @deftypefun {void} {dane_state_deinit} (dane_state_t @var{s})
 166 @var{s}: The structure to be deinitialized
 167
 168 This function will deinitialize a DANE query structure.
 169 @end deftypefun
 170
 171 @subheading dane_state_init
 172 @anchor{dane_state_init}
 173 @deftypefun {int} {dane_state_init} (dane_state_t * @var{s}, unsigned int @var{flags})
 174 @var{s}: The structure to be initialized
 175
 176 @var{flags}: flags from the @code{dane_state_flags}  enumeration
 177
 178 This function will initialize a DANE query structure.
 179
 180 @strong{Returns:} On success, @code{DANE_E_SUCCESS}  (0) is returned, otherwise a
 181 negative error value.
 182 @end deftypefun
 183
 184 @subheading dane_state_set_dlv_file
 185 @anchor{dane_state_set_dlv_file}
 186 @deftypefun {int} {dane_state_set_dlv_file} (dane_state_t @var{s}, const char * @var{file})
 187 @var{s}: The structure to be deinitialized
 188
 189 @var{file}: The file holding the DLV keys.
 190
 191 This function will set a file with trusted keys
 192 for DLV  (DNSSEC  Lookaside  Validation).
 193 @end deftypefun
 194
 195 @subheading dane_strerror
 196 @anchor{dane_strerror}
 197 @deftypefun {const char *} {dane_strerror} (int @var{error})
 198 @var{error}: is a DANE error code, a negative error code
 199
 200 This function is similar to strerror.  The difference is that it
 201 accepts an error number returned by a gnutls function; In case of
 202 an unknown error a descriptive string is sent instead of @code{NULL} .
 203
 204 Error codes are always a negative error code.
 205
 206 @strong{Returns:} A string explaining the DANE error message.
 207 @end deftypefun
 208
 209 @subheading dane_verification_status_print
 210 @anchor{dane_verification_status_print}
 211 @deftypefun {int} {dane_verification_status_print} (unsigned int @var{status}, gnutls_datum_t * @var{out}, unsigned int @var{flags})
 212 @var{status}: The status flags to be printed
 213
 214 @var{out}: Newly allocated datum with (0) terminated string.
 215
 216 @var{flags}: should be zero
 217
 218 This function will pretty print the status of a verification
 219 process -- eg. the one obtained by @code{dane_verify_crt()} .
 220
 221 The output  @code{out} needs to be deallocated using @code{gnutls_free()} .
 222
 223 @strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
 224 negative error value.
 225 @end deftypefun
 226
 227 @subheading dane_verify_crt
 228 @anchor{dane_verify_crt}
 229 @deftypefun {int} {dane_verify_crt} (dane_state_t @var{s}, const gnutls_datum_t * @var{chain}, unsigned @var{chain_size}, gnutls_certificate_type_t @var{chain_type}, const char * @var{hostname}, const char * @var{proto}, unsigned int @var{port}, unsigned int @var{sflags}, unsigned int @var{vflags}, unsigned int * @var{verify})
 230 @var{s}: A DANE state structure (may be NULL)
 231
 232 @var{chain}: A certificate chain
 233
 234 @var{chain_size}: The size of the chain
 235
 236 @var{chain_type}: The type of the certificate chain
 237
 238 @var{hostname}: The hostname associated with the chain
 239
 240 @var{proto}: The protocol of the service connecting (e.g. tcp)
 241
 242 @var{port}: The port of the service connecting (e.g. 443)
 243
 244 @var{sflags}: Flags for the the initialization of  @code{s} (if NULL)
 245
 246 @var{vflags}: Verification flags; an OR'ed list of @code{dane_verify_flags_t} .
 247
 248 @var{verify}: An OR'ed list of @code{dane_verify_status_t} .
 249
 250 This function will verify the given certificate chain against the
 251 CA constrains and/or the certificate available via DANE.
 252 If no information via DANE can be obtained the flag @code{DANE_VERIFY_NO_DANE_INFO}
 253 is set. If a DNSSEC signature is not available for the DANE
 254 record then the verify flag @code{DANE_VERIFY_NO_DNSSEC_DATA}  is set.
 255
 256 Due to the many possible options of DANE, there is no single threat
 257 model countered. When notifying the user about DANE verification results
 258 it may be better to mention: DANE verification did not reject the certificate,
 259 rather than mentioning a successful DANE verication.
 260
 261 Note that this function is designed to be run in addition to
 262 PKIX - certificate chain - verification. To be run independently
 263 the @code{DANE_VFLAG_ONLY_CHECK_EE_USAGE}  flag should be specified;
 264 then the function will check whether the key of the peer matches the
 265 key advertized in the DANE entry.
 266
 267 @strong{Returns:} a negative error code on error and @code{DANE_E_SUCCESS}  (0)
 268 when the DANE entries were successfully parsed, irrespective of
 269 whether they were verified (see  @code{verify} for that information). If
 270 no usable entries were encountered @code{DANE_E_REQUESTED_DATA_NOT_AVAILABLE}
 271 will be returned.
 272 @end deftypefun
 273
 274 @subheading dane_verify_crt_raw
 275 @anchor{dane_verify_crt_raw}
 276 @deftypefun {int} {dane_verify_crt_raw} (dane_state_t @var{s}, const gnutls_datum_t * @var{chain}, unsigned @var{chain_size}, gnutls_certificate_type_t @var{chain_type}, dane_query_t @var{r}, unsigned int @var{sflags}, unsigned int @var{vflags}, unsigned int * @var{verify})
 277 @var{s}: A DANE state structure (may be NULL)
 278
 279 @var{chain}: A certificate chain
 280
 281 @var{chain_size}: The size of the chain
 282
 283 @var{chain_type}: The type of the certificate chain
 284
 285 @var{r}: DANE data to check against
 286
 287 @var{sflags}: Flags for the the initialization of  @code{s} (if NULL)
 288
 289 @var{vflags}: Verification flags; an OR'ed list of @code{dane_verify_flags_t} .
 290
 291 @var{verify}: An OR'ed list of @code{dane_verify_status_t} .
 292
 293 This function will verify the given certificate chain against the
 294 CA constrains and/or the certificate available via DANE.
 295 If no information via DANE can be obtained the flag @code{DANE_VERIFY_NO_DANE_INFO}
 296 is set. If a DNSSEC signature is not available for the DANE
 297 record then the verify flag @code{DANE_VERIFY_NO_DNSSEC_DATA}  is set.
 298
 299 Due to the many possible options of DANE, there is no single threat
 300 model countered. When notifying the user about DANE verification results
 301 it may be better to mention: DANE verification did not reject the certificate,
 302 rather than mentioning a successful DANE verication.
 303
 304 Note that this function is designed to be run in addition to
 305 PKIX - certificate chain - verification. To be run independently
 306 the @code{DANE_VFLAG_ONLY_CHECK_EE_USAGE}  flag should be specified;
 307 then the function will check whether the key of the peer matches the
 308 key advertized in the DANE entry.
 309
 310 If the  @code{q} parameter is provided it will be used for caching entries.
 311
 312 @strong{Returns:} a negative error code on error and @code{DANE_E_SUCCESS}  (0)
 313 when the DANE entries were successfully parsed, irrespective of
 314 whether they were verified (see  @code{verify} for that information). If
 315 no usable entries were encountered @code{DANE_E_REQUESTED_DATA_NOT_AVAILABLE}
 316 will be returned.
 317 @end deftypefun
 318
 319 @subheading dane_verify_session_crt
 320 @anchor{dane_verify_session_crt}
 321 @deftypefun {int} {dane_verify_session_crt} (dane_state_t @var{s}, gnutls_session_t @var{session}, const char * @var{hostname}, const char * @var{proto}, unsigned int @var{port}, unsigned int @var{sflags}, unsigned int @var{vflags}, unsigned int * @var{verify})
 322 @var{s}: A DANE state structure (may be NULL)
 323
 324 @var{session}: A gnutls session
 325
 326 @var{hostname}: The hostname associated with the chain
 327
 328 @var{proto}: The protocol of the service connecting (e.g. tcp)
 329
 330 @var{port}: The port of the service connecting (e.g. 443)
 331
 332 @var{sflags}: Flags for the the initialization of  @code{s} (if NULL)
 333
 334 @var{vflags}: Verification flags; an OR'ed list of @code{dane_verify_flags_t} .
 335
 336 @var{verify}: An OR'ed list of @code{dane_verify_status_t} .
 337
 338 This function will verify session's certificate chain against the
 339 CA constrains and/or the certificate available via DANE.
 340 See @code{dane_verify_crt()}  for more information.
 341
 342 This will not verify the chain for validity; unless the DANE
 343 verification is restricted to end certificates, this must be
 344 be performed separately using @code{gnutls_certificate_verify_peers3()} .
 345
 346 @strong{Returns:} a negative error code on error and @code{DANE_E_SUCCESS}  (0)
 347 when the DANE entries were successfully parsed, irrespective of
 348 whether they were verified (see  @code{verify} for that information). If
 349 no usable entries were encountered @code{DANE_E_REQUESTED_DATA_NOT_AVAILABLE}
 350 will be returned.
 351 @end deftypefun
 352