diff --git a/src/anchor.c b/src/anchor.c index 8da59bba..d37cdec4 100644 --- a/src/anchor.c +++ b/src/anchor.c @@ -733,7 +733,7 @@ void _getdns_context_equip_with_anchor( X509 *x = NULL; X509_STORE *store = NULL; - if ((r = getdns_context_get_trust_anchor_verify_CA( + if ((r = getdns_context_get_trust_anchors_verify_CA( context, &verify_CA))) DEBUG_ANCHOR("ERROR %s(): Getting trust anchor verify" " CA: \"%s\"\n", __FUNC__ @@ -743,7 +743,7 @@ void _getdns_context_equip_with_anchor( DEBUG_ANCHOR("NOTICE: Trust anchor verification explicitely " "disabled by empty verify CA\n"); - else if ((r = getdns_context_get_trust_anchor_verify_email( + else if ((r = getdns_context_get_trust_anchors_verify_email( context, &verify_email))) DEBUG_ANCHOR("ERROR %s(): Getting trust anchor verify email " "address: \"%s\"\n", __FUNC__ @@ -1016,7 +1016,7 @@ static void tas_doc_read(getdns_context *context, tas_connection *a) p7s_bd.data = a->tcp.read_buf; p7s_bd.size = a->tcp.read_buf_len; - if ((r = getdns_context_get_trust_anchor_verify_CA( + if ((r = getdns_context_get_trust_anchors_verify_CA( context, (const char **)&verify_CA.data))) DEBUG_ANCHOR("ERROR %s(): Getting trust anchor verify" " CA: \"%s\"\n", __FUNC__ @@ -1025,7 +1025,7 @@ static void tas_doc_read(getdns_context *context, tas_connection *a) else if (!(verify_CA.size = strlen((const char *)verify_CA.data))) ; /* pass */ - else if ((r = getdns_context_get_trust_anchor_verify_email( + else if ((r = getdns_context_get_trust_anchors_verify_email( context, &verify_email))) DEBUG_ANCHOR("ERROR %s(): Getting trust anchor verify" " email address: \"%s\"\n", __FUNC__ @@ -1264,7 +1264,7 @@ static getdns_return_t _getdns_get_tas_url_hostname( char *next_slash; size_t s; - if ((r = getdns_context_get_trust_anchor_url(context, &url))) + if ((r = getdns_context_get_trust_anchors_url(context, &url))) return r; if ((next_slash = strchr(url + 7 /* "http://" */, '/'))) { @@ -1522,7 +1522,7 @@ void _getdns_start_fetching_ta(getdns_context *context, getdns_eventloop *loop) , getdns_get_errorstr_by_id(r)); return; - } else if ((r = getdns_context_get_trust_anchor_verify_CA( + } else if ((r = getdns_context_get_trust_anchors_verify_CA( context, &verify_CA))) { DEBUG_ANCHOR("ERROR %s(): Could not get verify CA" ": \"%s\"", __FUNC__ @@ -1534,7 +1534,7 @@ void _getdns_start_fetching_ta(getdns_context *context, getdns_eventloop *loop) "disabled by empty verify CA\n"); return; - } else if ((r = getdns_context_get_trust_anchor_verify_email( + } else if ((r = getdns_context_get_trust_anchors_verify_email( context, &verify_email))) { DEBUG_ANCHOR("ERROR %s(): Could not get verify email address" ": \"%s\"", __FUNC__ diff --git a/src/const-info.c b/src/const-info.c index df319b4f..2c582ed1 100644 --- a/src/const-info.c +++ b/src/const-info.c @@ -82,9 +82,9 @@ static struct const_info consts_info[] = { { 622, "GETDNS_CONTEXT_CODE_ROUND_ROBIN_UPSTREAMS", GETDNS_CONTEXT_CODE_ROUND_ROBIN_UPSTREAMS_TEXT }, { 623, "GETDNS_CONTEXT_CODE_TLS_BACKOFF_TIME", GETDNS_CONTEXT_CODE_TLS_BACKOFF_TIME_TEXT }, { 624, "GETDNS_CONTEXT_CODE_TLS_CONNECTION_RETRIES", GETDNS_CONTEXT_CODE_TLS_CONNECTION_RETRIES_TEXT }, - { 625, "GETDNS_CONTEXT_CODE_TRUST_ANCHOR_URL", GETDNS_CONTEXT_CODE_TRUST_ANCHOR_URL_TEXT }, - { 626, "GETDNS_CONTEXT_CODE_TRUST_ANCHOR_VERIFY_CA", GETDNS_CONTEXT_CODE_TRUST_ANCHOR_VERIFY_CA_TEXT }, - { 627, "GETDNS_CONTEXT_CODE_TRUST_ANCHOR_VERIFY_EMAIL", GETDNS_CONTEXT_CODE_TRUST_ANCHOR_VERIFY_EMAIL_TEXT }, + { 625, "GETDNS_CONTEXT_CODE_TRUST_ANCHORS_URL", GETDNS_CONTEXT_CODE_TRUST_ANCHORS_URL_TEXT }, + { 626, "GETDNS_CONTEXT_CODE_TRUST_ANCHORS_VERIFY_CA", GETDNS_CONTEXT_CODE_TRUST_ANCHORS_VERIFY_CA_TEXT }, + { 627, "GETDNS_CONTEXT_CODE_TRUST_ANCHORS_VERIFY_EMAIL", GETDNS_CONTEXT_CODE_TRUST_ANCHORS_VERIFY_EMAIL_TEXT }, { 628, "GETDNS_CONTEXT_CODE_APPDATA_DIR", GETDNS_CONTEXT_CODE_APPDATA_DIR_TEXT }, { 700, "GETDNS_CALLBACK_COMPLETE", GETDNS_CALLBACK_COMPLETE_TEXT }, { 701, "GETDNS_CALLBACK_CANCEL", GETDNS_CALLBACK_CANCEL_TEXT }, @@ -179,9 +179,9 @@ static struct const_name_info consts_name_info[] = { { "GETDNS_CONTEXT_CODE_TLS_BACKOFF_TIME", 623 }, { "GETDNS_CONTEXT_CODE_TLS_CONNECTION_RETRIES", 624 }, { "GETDNS_CONTEXT_CODE_TLS_QUERY_PADDING_BLOCKSIZE", 620 }, - { "GETDNS_CONTEXT_CODE_TRUST_ANCHOR_URL", 625 }, - { "GETDNS_CONTEXT_CODE_TRUST_ANCHOR_VERIFY_CA", 626 }, - { "GETDNS_CONTEXT_CODE_TRUST_ANCHOR_VERIFY_EMAIL", 627 }, + { "GETDNS_CONTEXT_CODE_TRUST_ANCHORS_URL", 625 }, + { "GETDNS_CONTEXT_CODE_TRUST_ANCHORS_VERIFY_CA", 626 }, + { "GETDNS_CONTEXT_CODE_TRUST_ANCHORS_VERIFY_EMAIL", 627 }, { "GETDNS_CONTEXT_CODE_UPSTREAM_RECURSIVE_SERVERS", 603 }, { "GETDNS_DNSSEC_BOGUS", 401 }, { "GETDNS_DNSSEC_INDETERMINATE", 402 }, diff --git a/src/context.c b/src/context.c index 85176c3c..8f200e8a 100644 --- a/src/context.c +++ b/src/context.c @@ -1364,11 +1364,11 @@ static void _getdns_check_expired_pending_netreqs_cb(void *arg) _getdns_check_expired_pending_netreqs((getdns_context *)arg, &now_ms); } -static const char *_getdns_default_trust_anchor_url = +static const char *_getdns_default_trust_anchors_url = "http://data.iana.org/root-anchors/root-anchors.xml"; /* The ICANN CA fetched at 24 Sep 2010. Valid to 2028 */ -static const char *_getdns_default_trust_anchor_verify_CA = +static const char *_getdns_default_trust_anchors_verify_CA = "-----BEGIN CERTIFICATE-----\n" "MIIDdzCCAl+gAwIBAgIBATANBgkqhkiG9w0BAQsFADBdMQ4wDAYDVQQKEwVJQ0FO\n" "TjEmMCQGA1UECxMdSUNBTk4gQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxFjAUBgNV\n" @@ -1391,7 +1391,7 @@ static const char *_getdns_default_trust_anchor_verify_CA = "j/Br5BZw3X/zd325TvnswzMC1+ljLzHnQGGk\n" "-----END CERTIFICATE-----\n"; -static const char *_getdns_default_trust_anchor_verify_email = +static const char *_getdns_default_trust_anchors_verify_email = "dnssec@iana.org"; @@ -1496,9 +1496,9 @@ getdns_context_create_with_extended_memory_functions( result->trust_anchors_source = GETDNS_TASRC_NONE; result->can_write_appdata = PROP_UNKNOWN; - result->trust_anchor_url = NULL; - result->trust_anchor_verify_email = NULL; - result->trust_anchor_verify_CA = NULL; + result->trust_anchors_url = NULL; + result->trust_anchors_verify_email = NULL; + result->trust_anchors_verify_CA = NULL; result->appdata_dir = NULL; (void) memset(&result->root_ksk, 0, sizeof(result->root_ksk)); @@ -1766,14 +1766,14 @@ getdns_context_destroy(struct getdns_context *context) getdns_dict_destroy(context->header); getdns_dict_destroy(context->add_opt_parameters); - if (context->trust_anchor_url) - GETDNS_FREE(context->mf, context->trust_anchor_url); - if (context->trust_anchor_verify_CA) + if (context->trust_anchors_url) + GETDNS_FREE(context->mf, context->trust_anchors_url); + if (context->trust_anchors_verify_CA) GETDNS_FREE( context->mf - , context->trust_anchor_verify_CA); - if (context->trust_anchor_verify_email) + , context->trust_anchors_verify_CA); + if (context->trust_anchors_verify_email) GETDNS_FREE( context->mf - , context->trust_anchor_verify_email); + , context->trust_anchors_verify_email); if (context->appdata_dir) GETDNS_FREE(context->mf, context->appdata_dir); @@ -3884,12 +3884,12 @@ _get_context_settings(getdns_context* context) } (void) _getdns_get_appdata(context, appdata_dir); (void) getdns_dict_util_set_string(result, "appdata_dir", appdata_dir); - if (!getdns_context_get_trust_anchor_url(context, &str_value) && str_value) - (void) getdns_dict_util_set_string(result, "trust_anchor_url", str_value); - if (!getdns_context_get_trust_anchor_verify_CA(context, &str_value) && str_value) - (void) getdns_dict_util_set_string(result, "trust_anchor_verify_CA", str_value); - if (!getdns_context_get_trust_anchor_verify_email(context, &str_value) && str_value) - (void) getdns_dict_util_set_string(result, "trust_anchor_verify_email", str_value); + if (!getdns_context_get_trust_anchors_url(context, &str_value) && str_value) + (void) getdns_dict_util_set_string(result, "trust_anchors_url", str_value); + if (!getdns_context_get_trust_anchors_verify_CA(context, &str_value) && str_value) + (void) getdns_dict_util_set_string(result, "trust_anchors_verify_CA", str_value); + if (!getdns_context_get_trust_anchors_verify_email(context, &str_value) && str_value) + (void) getdns_dict_util_set_string(result, "trust_anchors_verify_email", str_value); return result; error: @@ -4582,9 +4582,9 @@ _getdns_context_config_setting(getdns_context *context, CONTEXT_SETTING_INT(tls_backoff_time) CONTEXT_SETTING_INT(tls_connection_retries) CONTEXT_SETTING_INT(tls_query_padding_blocksize) - CONTEXT_SETTING_STRING(trust_anchor_url) - CONTEXT_SETTING_STRING(trust_anchor_verify_CA) - CONTEXT_SETTING_STRING(trust_anchor_verify_email) + CONTEXT_SETTING_STRING(trust_anchors_url) + CONTEXT_SETTING_STRING(trust_anchors_verify_CA) + CONTEXT_SETTING_STRING(trust_anchors_verify_email) CONTEXT_SETTING_STRING(appdata_dir) /**************************************/ @@ -4904,7 +4904,7 @@ int _getdns_context_can_write_appdata(getdns_context *context) } getdns_return_t -getdns_context_set_trust_anchor_url( +getdns_context_set_trust_anchors_url( getdns_context *context, const char *url) { const char *path; @@ -4933,84 +4933,84 @@ getdns_context_set_trust_anchor_url( || path[path_len - 1] == 'L'))) return GETDNS_RETURN_NOT_IMPLEMENTED; } - if (context->trust_anchor_url) - GETDNS_FREE(context->mf, context->trust_anchor_url); - context->trust_anchor_url = _getdns_strdup(&context->mf, url); + if (context->trust_anchors_url) + GETDNS_FREE(context->mf, context->trust_anchors_url); + context->trust_anchors_url = _getdns_strdup(&context->mf, url); - dispatch_updated(context, GETDNS_CONTEXT_CODE_TRUST_ANCHOR_URL); + dispatch_updated(context, GETDNS_CONTEXT_CODE_TRUST_ANCHORS_URL); return GETDNS_RETURN_GOOD; } getdns_return_t -getdns_context_get_trust_anchor_url( +getdns_context_get_trust_anchors_url( getdns_context *context, const char **url) { if (!context || !url) return GETDNS_RETURN_INVALID_PARAMETER; - *url = context && context->trust_anchor_url - ? context->trust_anchor_url - : _getdns_default_trust_anchor_url; + *url = context && context->trust_anchors_url + ? context->trust_anchors_url + : _getdns_default_trust_anchors_url; return GETDNS_RETURN_GOOD; } getdns_return_t -getdns_context_set_trust_anchor_verify_CA( +getdns_context_set_trust_anchors_verify_CA( getdns_context *context, const char *verify_CA) { if (!context) return GETDNS_RETURN_INVALID_PARAMETER; - if (context->trust_anchor_verify_CA) - GETDNS_FREE(context->mf, context->trust_anchor_verify_CA); - context->trust_anchor_verify_CA = + if (context->trust_anchors_verify_CA) + GETDNS_FREE(context->mf, context->trust_anchors_verify_CA); + context->trust_anchors_verify_CA = _getdns_strdup(&context->mf, verify_CA); dispatch_updated( context - , GETDNS_CONTEXT_CODE_TRUST_ANCHOR_VERIFY_CA); + , GETDNS_CONTEXT_CODE_TRUST_ANCHORS_VERIFY_CA); return GETDNS_RETURN_GOOD; } getdns_return_t -getdns_context_get_trust_anchor_verify_CA( +getdns_context_get_trust_anchors_verify_CA( getdns_context *context, const char **verify_CA) { if (!verify_CA) return GETDNS_RETURN_INVALID_PARAMETER; - *verify_CA = context && context->trust_anchor_verify_CA - ? context->trust_anchor_verify_CA - : _getdns_default_trust_anchor_verify_CA; + *verify_CA = context && context->trust_anchors_verify_CA + ? context->trust_anchors_verify_CA + : _getdns_default_trust_anchors_verify_CA; return GETDNS_RETURN_GOOD; } getdns_return_t -getdns_context_set_trust_anchor_verify_email( +getdns_context_set_trust_anchors_verify_email( getdns_context *context, const char *verify_email) { if (!context) return GETDNS_RETURN_INVALID_PARAMETER; - if (context->trust_anchor_verify_email) - GETDNS_FREE(context->mf, context->trust_anchor_verify_email); - context->trust_anchor_verify_email = + if (context->trust_anchors_verify_email) + GETDNS_FREE(context->mf, context->trust_anchors_verify_email); + context->trust_anchors_verify_email = _getdns_strdup(&context->mf, verify_email); dispatch_updated( context - , GETDNS_CONTEXT_CODE_TRUST_ANCHOR_VERIFY_EMAIL); + , GETDNS_CONTEXT_CODE_TRUST_ANCHORS_VERIFY_EMAIL); return GETDNS_RETURN_GOOD; } getdns_return_t -getdns_context_get_trust_anchor_verify_email( +getdns_context_get_trust_anchors_verify_email( getdns_context *context, const char **verify_email) { if (!verify_email) return GETDNS_RETURN_INVALID_PARAMETER; - *verify_email = context && context->trust_anchor_verify_email - ? context->trust_anchor_verify_email - : _getdns_default_trust_anchor_verify_email; + *verify_email = context && context->trust_anchors_verify_email + ? context->trust_anchors_verify_email + : _getdns_default_trust_anchors_verify_email; return GETDNS_RETURN_GOOD; } diff --git a/src/context.h b/src/context.h index e9b05117..1be44ed2 100644 --- a/src/context.h +++ b/src/context.h @@ -337,9 +337,9 @@ struct getdns_context { tas_connection aaaa; uint8_t tas_hdr_spc[512]; - char *trust_anchor_url; - char *trust_anchor_verify_CA; - char *trust_anchor_verify_email; + char *trust_anchors_url; + char *trust_anchors_verify_CA; + char *trust_anchors_verify_email; _getdns_ksks root_ksk; diff --git a/src/getdns/getdns_extra.h.in b/src/getdns/getdns_extra.h.in index 392ab295..2ef7133d 100644 --- a/src/getdns/getdns_extra.h.in +++ b/src/getdns/getdns_extra.h.in @@ -80,12 +80,12 @@ extern "C" { #define GETDNS_CONTEXT_CODE_TLS_CONNECTION_RETRIES 624 #define GETDNS_CONTEXT_CODE_TLS_CONNECTION_RETRIES_TEXT "Change related to getdns_context_set_tls_connection_retries" -#define GETDNS_CONTEXT_CODE_TRUST_ANCHOR_URL 625 -#define GETDNS_CONTEXT_CODE_TRUST_ANCHOR_URL_TEXT "Change related to getdns_context_set_trust_anchor_url" -#define GETDNS_CONTEXT_CODE_TRUST_ANCHOR_VERIFY_CA 626 -#define GETDNS_CONTEXT_CODE_TRUST_ANCHOR_VERIFY_CA_TEXT "Change related to getdns_context_set_trust_anchor_verify_ca" -#define GETDNS_CONTEXT_CODE_TRUST_ANCHOR_VERIFY_EMAIL 627 -#define GETDNS_CONTEXT_CODE_TRUST_ANCHOR_VERIFY_EMAIL_TEXT "Change related to getdns_context_set_trust_anchor_verify_email" +#define GETDNS_CONTEXT_CODE_TRUST_ANCHORS_URL 625 +#define GETDNS_CONTEXT_CODE_TRUST_ANCHORS_URL_TEXT "Change related to getdns_context_set_trust_anchors_url" +#define GETDNS_CONTEXT_CODE_TRUST_ANCHORS_VERIFY_CA 626 +#define GETDNS_CONTEXT_CODE_TRUST_ANCHORS_VERIFY_CA_TEXT "Change related to getdns_context_set_trust_anchors_verify_ca" +#define GETDNS_CONTEXT_CODE_TRUST_ANCHORS_VERIFY_EMAIL 627 +#define GETDNS_CONTEXT_CODE_TRUST_ANCHORS_VERIFY_EMAIL_TEXT "Change related to getdns_context_set_trust_anchors_verify_email" #define GETDNS_CONTEXT_CODE_APPDATA_DIR 628 #define GETDNS_CONTEXT_CODE_APPDATA_DIR_TEXT "Change related to getdns_context_set_appdata_dir" @@ -541,39 +541,145 @@ typedef void (*getdns_logfunc_type) (void *userarg, uint64_t log_systems, getdns_loglevel_type, const char *, va_list ap); /** - * + * Register a function that will be called when there is something to log + * equally or more severe than the given level for the given system. + * @param[in] context The context from which to get the setting + * @param[in] userarg A user defined argument to be passed to the + * log function. + * @param[in] system A bitwise ORed collection of systems for which the log + * function should be called. Currently only logging + * information about upstream statistics is available; + * i.e.: GETDNS_LOG_UPSTREAM_STATS + * @param[in] level A severity level. The log function will be called + * only for messages with an equal or more severe level. + * More severe has a lower value. + * @param[in] func The log function to call with the user argument, + * the system for which the log message, the severity + * level, a printf style format string and the arguments + * for the format string, as parameter. + * @see getdns_loglevel_type + * @see getdns_logfunc_type + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL. */ getdns_return_t getdns_context_set_logfunc(getdns_context *context, void *userarg, uint64_t system, getdns_loglevel_type level, getdns_logfunc_type func); /** - * - */ -getdns_return_t -getdns_context_set_trust_anchor_url(getdns_context *context, const char *url); - -/** - * - */ -getdns_return_t -getdns_context_set_trust_anchor_verify_CA( - getdns_context *context, const char *verify_CA); - -/** - * - */ -getdns_return_t -getdns_context_set_trust_anchor_verify_email( - getdns_context *context, const char *verify_email); - -/** - * + * Define the location for storing library specific data. The location should + * be writable for the current user using the application with which the + * library is linked. Currently this is only used for storing data concerning + * zero configuration dnssec. + * @param[in] context The context from which to get the setting + * @param[in] appdata_dir A user writable location in which the library can + * store data. The last element of the path is tried + * to be created if it does not exist. When NULL is + * given, the default location is used which is + * ${HOME}/.getdns/ on Unix line systems (Linux, BSD's, + * MacOS), and %AppData%\getnds\ on Windows. + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL. */ getdns_return_t getdns_context_set_appdata_dir( getdns_context *context, const char *appdata_dir); +/** + * Sets the url for the location of the XML file from which to fetch the + * trust anchors with Zero configuration DNSSEC. The url should be for + * http, and the file should have the .xml extension. + * + * Alongside the XML file, also the S/MIME signature that will be used to + * validate the XML file, will be fetched from the url with the .xml extension + * replaced by .p7s. + * + * When successfully validated with the verify Certificate Authority and the + * verify email address, the context will be equipped with the DNSSEC trust + * anchors defined within the XML file as described in RFC7958. + * The XML file will also be stored together with the .p7s file in the + * appdata directory with the names "root-anchors.xml" and "root-anchors.p7s" + * respectively. + * + * When the trust-anchors from the XML file are used, the root DNSKEY is + * tracked and stored in the appdata directory too as "root.key" + * + * Trust anchors from the XML file will be tried when: + * - There were no other trust anchors provided, either by the default + * trust anchor file "@TRUST_ANCHOR_FILE@", or set with the + * getdns_context_set_dnssec_trust_anchors() function. + * - or the available trust anchors (from the default location or set by + * the application) caused the root DNSKEY rrset to be BOGUS. + * + * Trust anchors from the XML file will be read from the root-anchors.xml + * file in appdata directory and will only be used when validation with the + * S/MIME signatures in root-anchors.p7s succeeds with the verification + * Certificate Authority and the verification email address. + * + * A (new) version of "root-anchors.xml" and "root-anchors.p7s" will be + * fetched when: + * - The appdata directory is writeable by the current used, but the + * "root-anchors.xml" or "root-anchors.p7s" files were not available. + * - or there is a new root DNSKEY RRset (or signature) and it contains + * key_ids which were not in "root-anchors.xml." + * + * @see getdns_context_get_trust_anchors_url + * @see getdns_context_set_trust_anchors_verify_CA + * @see getdns_context_set_trust_anchors_verify_email + * @param[in] context The context to configure + * @param[in] url The url including the XML file from which the + * trust anchors (and the S/MIME signature) will be + * fetched. Default is: + * http://data.iana.org/root-anchors/root-anchors.xml + * When NULL is given, the default will be used. + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL. + */ +getdns_return_t +getdns_context_set_trust_anchors_url(getdns_context *context, const char *url); + +/** + * Sets the public certificate for the Certificate Authority with which to + * validate the XML file with the S/MIME signatures fetch from the url + * given with the getdns_context_set_trust_anchors_url() function. + * @see getdns_context_get_trust_anchors_verify_CA + * @see getdns_context_set_trust_anchors_url + * @see getdns_context_set_trust_anchors_verify_email + * @param[in] context The context to configure + * @param[in] verify_CA The certificate of the Certificate Authority with + * which to validate the XML trust anchors. + * The default is the ICANN Root CA, which is valid + * till Dec 18 2029. + * When NULL is given, the default will be used. + * When an empty string is given, Zero configuration + * DNSSEC will be disabled. + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL. + */ +getdns_return_t +getdns_context_set_trust_anchors_verify_CA( + getdns_context *context, const char *verify_CA); + +/** + * Sets the email address for the Subject of the signer's certificate from the + * p7s signature file with which to validate the XML file fetched from the url + * given with the getdns_context_set_trust_anchors_url() function. + * @see getdns_context_get_trust_anchors_verify_email + * @see getdns_context_set_trust_anchors_url + * @see getdns_context_set_trust_anchors_verify_CA + * @param[in] context The context to configure + * @param[in] verify_email Only signatures from this name are allowed. + * The default dnssec@iana.org. + * When NULL is given, the default will be used. + * When an empty string is given, Zero configuration + * DNSSEC will be disabled. + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL. + */ +getdns_return_t +getdns_context_set_trust_anchors_verify_email( + getdns_context *context, const char *verify_email); + /** * Get the current resolution type setting from this context. * @see getdns_context_set_resolution_type @@ -939,25 +1045,93 @@ getdns_return_t getdns_context_get_update_callback(getdns_context *context, void **userarg, void (**value) (getdns_context *, getdns_context_code_t, void *)); + /** + * Gets the url for the location of the XML file from which to fetch the + * trust anchors with Zero configuration DNSSEC. * + * Alongside the XML file, also the S/MIME signature that will be used to + * validate the XML file, will be fetched from the url with the .xml extension + * replaced by .p7s. + * + * When successfully validated with the verify Certificate Authority and the + * verify email address, the context will be equipped with the DNSSEC trust + * anchors defined within the XML file as described in RFC7958. + * The XML file will also be stored together with the .p7s file in the + * appdata directory with the names "root-anchors.xml" and "root-anchors.p7s" + * respectively. + * + * When the trust-anchors from the XML file are used, the root DNSKEY is + * tracked and stored in the appdata directory too as "root.key" + * + * Trust anchors from the XML file will be tried when: + * - There were no other trust anchors provided, either by the default + * trust anchor file "@TRUST_ANCHOR_FILE@", or set with the + * getdns_context_set_dnssec_trust_anchors() function. + * - or the available trust anchors (from the default location or set by + * the application) caused the root DNSKEY rrset to be BOGUS. + * + * Trust anchors from the XML file will be read from the root-anchors.xml + * file in appdata directory and will only be used when validation with the + * S/MIME signatures in root-anchors.p7s succeeds with the verification + * Certificate Authority and the verification email address. + * + * A (new) version of "root-anchors.xml" and "root-anchors.p7s" will be + * fetched when: + * - The appdata directory is writeable by the current used, but the + * "root-anchors.xml" or "root-anchors.p7s" files were not available. + * - or there is a new root DNSKEY RRset (or signature) and it contains + * key_ids which were not in "root-anchors.xml." + * + * @see getdns_context_set_trust_anchors_url + * @see getdns_context_get_trust_anchors_verify_CA + * @see getdns_context_get_trust_anchors_verify_email + * @param[in] context The context to configure + * @param[out] url The url including the XML file, from which the + * trust anchors (and the S/MIME signature) will be + * fetched. Default is: + * http://data.iana.org/root-anchors/root-anchors.xml + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL. */ getdns_return_t -getdns_context_get_trust_anchor_url( +getdns_context_get_trust_anchors_url( getdns_context *context, const char **url); /** - * + * Gets the public certificate for the Certificate Authority with which to + * validate the XML file with the S/MIME signatures fetch from the url + * given with the getdns_context_set_trust_anchors_url() function. + * @see getdns_context_set_trust_anchors_verify_CA + * @see getdns_context_get_trust_anchors_url + * @see getdns_context_get_trust_anchors_verify_email + * @param[in] context The context to configure + * @param[out] verify_CA The certificate of the Certificate Authority with + * which to validate the XML trust anchors. + * The default is the ICANN Root CA, which is valid + * till Dec 18 2029. + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL. */ getdns_return_t -getdns_context_get_trust_anchor_verify_CA( +getdns_context_get_trust_anchors_verify_CA( getdns_context *context, const char **verify_CA); /** - * + * Gets the email address for the Subject of the signer's certificate from the + * p7s signature file with which to validate the XML file fetched from the url + * given with the getdns_context_set_trust_anchors_url() function. + * @see getdns_context_set_trust_anchors_verify_email + * @see getdns_context_get_trust_anchors_url + * @see getdns_context_get_trust_anchors_verify_CA + * @param[in] context The context to configure + * @param[out] verify_email Only signatures from this name are allowed. + * The default dnssec@iana.org. + * @return GETDNS_RETURN_GOOD when successful + * @return GETDNS_RETURN_INVALID_PARAMETER when context was NULL. */ getdns_return_t -getdns_context_get_trust_anchor_verify_email( +getdns_context_get_trust_anchors_verify_email( getdns_context *context, const char **verify_email); diff --git a/src/libgetdns.symbols b/src/libgetdns.symbols index c9bda9e7..9d190406 100644 --- a/src/libgetdns.symbols +++ b/src/libgetdns.symbols @@ -33,9 +33,9 @@ getdns_context_get_tls_authentication getdns_context_get_tls_backoff_time getdns_context_get_tls_connection_retries getdns_context_get_tls_query_padding_blocksize -getdns_context_get_trust_anchor_url -getdns_context_get_trust_anchor_verify_CA -getdns_context_get_trust_anchor_verify_email +getdns_context_get_trust_anchors_url +getdns_context_get_trust_anchors_verify_CA +getdns_context_get_trust_anchors_verify_email getdns_context_get_update_callback getdns_context_get_upstream_recursive_servers getdns_context_process_async @@ -71,9 +71,9 @@ getdns_context_set_tls_authentication getdns_context_set_tls_backoff_time getdns_context_set_tls_connection_retries getdns_context_set_tls_query_padding_blocksize -getdns_context_set_trust_anchor_url -getdns_context_set_trust_anchor_verify_CA -getdns_context_set_trust_anchor_verify_email +getdns_context_set_trust_anchors_url +getdns_context_set_trust_anchors_verify_CA +getdns_context_set_trust_anchors_verify_email getdns_context_set_update_callback getdns_context_set_upstream_recursive_servers getdns_context_set_use_threads @@ -167,6 +167,5 @@ getdns_wire2rr_dict getdns_wire2rr_dict_buf getdns_wire2rr_dict_scan getdns_yaml2dict -getdns_yaml2list plain_mem_funcs_user_arg priv_getdns_context_mf