From: George Thessalonikefs Date: Sat, 5 Aug 2023 18:00:37 +0000 (+0200) Subject: - For #762: Cleaner manpage text and uniform use of the term DNS X-Git-Tag: release-1.18.0rc1~14^2~10 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=fbc02568256f936380fa817008d2e689d4311e12;p=thirdparty%2Funbound.git - For #762: Cleaner manpage text and uniform use of the term DNS Cookies. --- diff --git a/daemon/acl_list.h b/daemon/acl_list.h index 8aece11bf..9da43bef3 100644 --- a/daemon/acl_list.h +++ b/daemon/acl_list.h @@ -64,9 +64,11 @@ enum acl_access { acl_allow, /** allow full access for all queries, recursion and cache snooping */ acl_allow_snoop, - /** allow full access for recursion queries and set RD flag regardless of request */ + /** allow full access for recursion queries and set RD flag regardless + * of request */ acl_allow_setrd, - /** allow full access if valid cookie present or stateful transport */ + /** allow full access for recursion (+RD) queries if valid cookie + * present or stateful transport */ acl_allow_cookie }; diff --git a/doc/unbound.conf.5.in b/doc/unbound.conf.5.in index 53923ac2b..3736eeb6b 100644 --- a/doc/unbound.conf.5.in +++ b/doc/unbound.conf.5.in @@ -686,15 +686,15 @@ The netblock is given as an IP4 or IP6 address with /size appended for a classless network block. The action can be \fIdeny\fR, \fIrefuse\fR, \fIallow\fR, \fIallow_setrd\fR, \fIallow_snoop\fR, \fIallow_cookie\fR, \fIdeny_non_local\fR or \fIrefuse_non_local\fR. -The most specific netblock match is used, if none match \fIdeny\fR is used. +The most specific netblock match is used, if none match \fIrefuse\fR is used. The order of the access\-control statements therefore does not matter. .IP -The action \fIdeny\fR stops queries from hosts from that netblock. +The \fIdeny\fR action stops queries from hosts from that netblock. .IP -The action \fIrefuse\fR stops queries too, but sends a DNS rcode REFUSED +The \fIrefuse\fR action stops queries too, but sends a DNS rcode REFUSED error message back. .IP -The action \fIallow\fR gives access to clients from that netblock. +The \fIallow\fR action gives access to clients from that netblock. It gives only access for recursion clients (which is what almost all clients need). Nonrecursive queries are refused. .IP @@ -714,20 +714,22 @@ may be useful if another DNS server must forward requests for specific zones to a resolver DNS server, but only supports stub domains and sends queries to the resolver DNS server with the RD bit cleared. .IP -The action \fIallow_snoop\fR gives nonrecursive access too. This give +The \fIallow_snoop\fR action gives nonrecursive access too. This give both recursive and non recursive access. The name \fIallow_snoop\fR refers to cache snooping, a technique to use nonrecursive queries to examine the cache contents (for malicious acts). However, nonrecursive queries can also be a valuable debugging tool (when you want to examine the cache contents). In that case use \fIallow_snoop\fR for your administration host. .IP -When the \fBanswer\-cookie\fR option is enabled, the \fIallow_cookie\fR action -will allow access to UDP queries that contain a valid Server Cookie as -specified in RFC 7873 and RFC9018. UDP queries containing only a Client Cookie -and no Server Cookie, will receive a BADCOOKIE response including a Server -Cookie, allow clients to retry with that Server Cookie. The \fIallow_cookie\fR -will also accept requests over statefull transports, regardless of the precence -of a Cookie and regardless the \fBanswer\-cookie\fR setting. +The \fIallow_cookie\fR action allows access to UDP queries that contain a +valid DNS Cookie as specified in RFC 7873 and RFC 9018, when the +\fBanswer\-cookie\fR option is enabled. +UDP queries containing only a DNS Client Cookie and no Server Cookie, or an +invalid DNS Cookie, will receive a BADCOOKIE response including a newly +generated DNS Cookie, allowing clients to retry with that DNS Cookie. +The \fIallow_cookie\fR action will also accept requests over stateful +transports, regardless of the presence of an DNS Cookie and regardless of the +\fBanswer\-cookie\fR setting. .IP By default only localhost is \fIallow\fRed, the rest is \fIrefuse\fRd. The default is \fIrefuse\fRd, because that is protocol\-friendly. The DNS @@ -1844,14 +1846,17 @@ use the fastest specified number of servers with the fast\-server\-permil option, that turns this on or off. The default is to use the fastest 3 servers. .TP 5 .B answer\-cookie: \fI -Enable to answer to requests containig DNS Cookies as specified in RFC7873 and -RFC9018. Default is no. +If enabled, Unbound will answer to requests containing DNS Cookies as +specified in RFC 7873 and RFC 9018. +Default is no. .TP 5 .B cookie\-secret: \fI<128 bit hex string> -Server's in an Anycast deployment need to be able to verify each other's -Server Cookies. For this they need to share the secret used to construct -and verify the Server Cookies. +Server's secret for DNS Cookie generation. +Useful to explicitly set for servers in an anycast deployment that need to +share the secret in order to verify each other's Server Cookies. +An example hex string would be "000102030405060708090a0b0c0d0e0f". Default is a 128 bits random secret generated at startup time. +.TP 5 .B edns\-client\-string: \fI Include an EDNS0 option containing configured ascii string in queries with destination address matching the configured IP netblock. This configuration diff --git a/testcode/testpkts.c b/testcode/testpkts.c index b9b740a48..22d846d2b 100644 --- a/testcode/testpkts.c +++ b/testcode/testpkts.c @@ -954,7 +954,7 @@ extract_ede(uint8_t* pkt, size_t len) return sldns_read_uint16(buf); } -/** Snips the EDNS Cookie option out of the OPT record and puts it in the +/** Snips the DNS Cookie option out of the OPT record and puts it in the * provided cookie buffer (should be at least 24 octets). * Returns the length of the cookie if found, else -1. */ static int @@ -1566,17 +1566,17 @@ find_match(struct entry* entries, uint8_t* query_pkt, size_t len, int cookie_len = extract_cookie(query_pkt, len, cookie); if(cookie_len == -1) { - verbose(3, "bad EDNS Cookie. " + verbose(3, "bad DNS Cookie. " "Expected but not found\n"); continue; } else if(p->match_client_cookie && cookie_len != 8) { - verbose(3, "bad EDNS Cookie. Expected client " + verbose(3, "bad DNS Cookie. Expected client " "cookie of length 8."); continue; } else if((p->match_server_cookie) && cookie_len != 24) { - verbose(3, "bad EDNS Cookie. Expected server " + verbose(3, "bad DNS Cookie. Expected server " "cookie of length 24."); continue; } diff --git a/testcode/testpkts.h b/testcode/testpkts.h index 3c0a44054..c6a3725f3 100644 --- a/testcode/testpkts.h +++ b/testcode/testpkts.h @@ -64,13 +64,13 @@ struct sldns_file_parse_state; ; 'ede=any' makes the query match any EDNS EDE info-code. ; It also snips the EDE record out of the packet to facilitate ; other matches. - ; 'client_cookie' makes the query match any EDNS Cookie option with + ; 'client_cookie' makes the query match any DNS Cookie option with ; with a length of 8 octets. - ; It also snips the EDNS Cookie record out of the packet to + ; It also snips the DNS Cookie record out of the packet to ; facilitate other matches. - ; 'server_cookie' makes the query match any EDNS Cookie option with + ; 'server_cookie' makes the query match any DNS Cookie option with ; with a length of 24 octets. - ; It also snips the EDNS Cookie record out of the packet to + ; It also snips the DNS Cookie record out of the packet to ; facilitate other matches. MATCH [opcode] [qtype] [qname] [serial=] [all] [ttl] MATCH [UDP|TCP] DO @@ -222,9 +222,9 @@ struct entry { uint8_t match_noedns; /** match edns data field given in hex */ uint8_t match_ednsdata_raw; - /** match an EDNS cookie of length 8 */ + /** match an DNS cookie of length 8 */ uint8_t match_client_cookie; - /** match an EDNS cookie of length 24 */ + /** match an DNS cookie of length 24 */ uint8_t match_server_cookie; /** match query serial with this value. */ uint32_t ixfr_soa_serial; diff --git a/testcode/unitmain.c b/testcode/unitmain.c index 4111b3e98..6309dbcd3 100644 --- a/testcode/unitmain.c +++ b/testcode/unitmain.c @@ -716,11 +716,11 @@ edns_cookie_rfc9018_a1(void) unit_assert(memcmp(server_cookie, buf, 24) == 0); } -/** test interoperable EDNS cookies (RFC9018) */ +/** test interoperable DNS cookies (RFC9018) */ static void edns_cookie_test(void) { - unit_show_feature("interoperable edns cookies"); + unit_show_feature("interoperable dns cookies"); /* Check RFC9018 appendix test vectors */ edns_cookie_rfc9018_a1(); edns_cookie_rfc9018_a2(); diff --git a/testdata/edns_downstream_cookies.rpl b/testdata/edns_downstream_cookies.rpl index e745f584a..44391b8cb 100644 --- a/testdata/edns_downstream_cookies.rpl +++ b/testdata/edns_downstream_cookies.rpl @@ -8,7 +8,7 @@ server: CONFIG_END -SCENARIO_BEGIN Test downstream EDNS Cookies +SCENARIO_BEGIN Test downstream DNS Cookies ; Note: When a valid hash was required, it was generated by running this test ; with an invalid one and checking the output for the valid one. diff --git a/util/config_file.c b/util/config_file.c index cb890f31b..57beeae50 100644 --- a/util/config_file.c +++ b/util/config_file.c @@ -89,7 +89,7 @@ struct config_parser_state* cfg_parser = 0; static void init_outgoing_availports(int* array, int num); /** init cookie with random data */ -static void init_cookie_secret(uint8_t* cookie_secret,size_t cookie_secret_len); +static void init_cookie_secret(uint8_t* cookie_secret, size_t cookie_secret_len); struct config_file* config_create(void) diff --git a/util/configparser.y b/util/configparser.y index 1c36ee2a1..2a4c1f3f3 100644 --- a/util/configparser.y +++ b/util/configparser.y @@ -3722,8 +3722,8 @@ server_cookie_secret: VAR_COOKIE_SECRET STRING_ARG size_t secret_len = sizeof(secret); OUTYY(("P(server_cookie_secret:%s)\n", $2)); - if (sldns_str2wire_hex_buf($2, secret, &secret_len) - || ( secret_len != 16)) + if(sldns_str2wire_hex_buf($2, secret, &secret_len) + || (secret_len != 16)) yyerror("expected 128 bit hex string"); else { cfg_parser->cfg->cookie_secret_len = secret_len; diff --git a/util/edns.h b/util/edns.h index 021b500df..190e69634 100644 --- a/util/edns.h +++ b/util/edns.h @@ -107,7 +107,7 @@ edns_string_addr_lookup(rbtree_type* tree, struct sockaddr_storage* addr, socklen_t addrlen); /** - * Compute the interoperable EDNS cookie (RFC9018) hash. + * Compute the interoperable DNS cookie (RFC9018) hash. * @param in: buffer input for the hash generation. It needs to be: * Client Cookie | Version | Reserved | Timestamp | Client-IP * @param secret: the server secret; implicit length of 16 octets. @@ -119,7 +119,7 @@ uint8_t* edns_cookie_server_hash(const uint8_t* in, const uint8_t* secret, int v4, uint8_t* hash); /** - * Write an interoperable EDNS server cookie (RFC9018). + * Write an interoperable DNS server cookie (RFC9018). * @param buf: buffer to write to. It should have a size of at least 32 octets * as it doubles as the output buffer and the hash input buffer. * The first 8 octets are expected to be the Client Cookie and will be @@ -140,7 +140,7 @@ void edns_cookie_server_write(uint8_t* buf, const uint8_t* secret, int v4, uint32_t timestamp); /** - * Validate an interoperable EDNS cookie (RFC9018). + * Validate an interoperable DNS cookie (RFC9018). * @param cookie: pointer to the cookie data. * @param cookie_len: the length of the cookie data. * @param secret: pointer to the server secret.