From: Colin Vidal Date: Wed, 29 Jan 2025 21:32:33 +0000 (+0100) Subject: add lib/dns/ede.c documentation X-Git-Tag: v9.21.5~18^2~3 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7b01cbfb0413257318d534d2ee320e28a5dd52a4;p=thirdparty%2Fbind9.git add lib/dns/ede.c documentation Add documentation usage of EDE compilation unit as well as centralize all EDE-related macros in the same lib/dns/include/dns/ede.h header. --- diff --git a/lib/dns/include/dns/ede.h b/lib/dns/include/dns/ede.h index b14f16a7156..8f6cf3bf9a4 100644 --- a/lib/dns/include/dns/ede.h +++ b/lib/dns/include/dns/ede.h @@ -17,6 +17,35 @@ #include +/*%< EDNS0 extended DNS errors */ +#define DNS_EDE_OTHER 0 /*%< Other Error */ +#define DNS_EDE_DNSKEYALG 1 /*%< Unsupported DNSKEY Algorithm */ +#define DNS_EDE_DSDIGESTTYPE 2 /*%< Unsupported DS Digest Type */ +#define DNS_EDE_STALEANSWER 3 /*%< Stale Answer */ +#define DNS_EDE_FORGEDANSWER 4 /*%< Forged Answer */ +#define DNS_EDE_DNSSECINDETERMINATE 5 /*%< DNSSEC Indeterminate */ +#define DNS_EDE_DNSSECBOGUS 6 /*%< DNSSEC Bogus */ +#define DNS_EDE_SIGNATUREEXPIRED 7 /*%< Signature Expired */ +#define DNS_EDE_SIGNATURENOTYETVALID 8 /*%< Signature Not Yet Valid */ +#define DNS_EDE_DNSKEYMISSING 9 /*%< DNSKEY Missing */ +#define DNS_EDE_RRSIGSMISSING 10 /*%< RRSIGs Missing */ +#define DNS_EDE_NOZONEKEYBITSET 11 /*%< No Zone Key Bit Set */ +#define DNS_EDE_NSECMISSING 12 /*%< NSEC Missing */ +#define DNS_EDE_CACHEDERROR 13 /*%< Cached Error */ +#define DNS_EDE_NOTREADY 14 /*%< Not Ready */ +#define DNS_EDE_BLOCKED 15 /*%< Blocked */ +#define DNS_EDE_CENSORED 16 /*%< Censored */ +#define DNS_EDE_FILTERED 17 /*%< Filtered */ +#define DNS_EDE_PROHIBITED 18 /*%< Prohibited */ +#define DNS_EDE_STALENXANSWER 19 /*%< Stale NXDomain Answer */ +#define DNS_EDE_NOTAUTH 20 /*%< Not Authoritative */ +#define DNS_EDE_NOTSUPPORTED 21 /*%< Not Supported */ +#define DNS_EDE_NOREACHABLEAUTH 22 /*%< No Reachable Authority */ +#define DNS_EDE_NETWORKERROR 23 /*%< Network Error */ +#define DNS_EDE_INVALIDDATA 24 /*%< Invalid Data */ + +#define DNS_EDE_MAX_CODE DNS_EDE_INVALIDDATA + /* * From RFC 8914: * Because long EXTRA-TEXT fields may trigger truncation (which is undesirable @@ -35,21 +64,84 @@ struct dns_edectx { isc_mem_t *mctx; dns_ednsopt_t *ede[DNS_EDE_MAX_ERRORS]; }; +/*%< + * Multiple extended DNS errors (EDE) (defined in RFC 8914) can be raised during + * a DNS resolution and in various area of the code base. "dns_edectx_t" object + * abstract and holds pending EDE and the set of dns_ede_ API enable to + * manipulate its state (adding EDE, transfer to another context, etc.). EDE are + * internally stored in the wire format, so it can be directly consumed to build + * the response client message. + */ void dns_ede_init(isc_mem_t *mctx, dns_edectx_t *edectx); +/*%< + * Initialize "edectx" so it is valid to use. Can be called after + * dns_ede_invalidate" is being called to reuse the object. + * + * Requires: + * + * \li "mctx" to be valid + * \li "edectx" to be valid + */ void dns_ede_reset(dns_edectx_t *edectx); +/*%< + * Reset "edectx" internal state and free all its EDE from memory. "edectx" is + * still valid to use, in the same state than after dns_ede_init is called. + * + * Requires: + * + * \li "edectx" to be valid + */ void dns_ede_invalidate(dns_edectx_t *edectx); +/*%< + * Reset "edectx" and remove its memory context as well as its magic number. It + * is not valid to use anymore. + * + * Requires: + * + * \li "edectx" to be valid + */ void dns_ede_add(dns_edectx_t *edectx, uint16_t code, const char *text); /*%< - * Set extended error with INFO-CODE and EXTRA-TEXT . + * Add a new extended error in "edectx". "code" must be one of the INFO-CODE + * values defined in RFC8914, see DNS_EDE_ macros above. "text" is optional, it + * is immediately copied internally if provided. + * + * Rules: + * + * \li If "text" is non NULL, it must be NULL terminated. If its length is more + * than DNS_EDE_EXTRATEXT_LEN, it is trucated. + * + * \li If an EDE with the same code has already been added to "edectx", the + * following ones with the same code are ignored. + * + * \li If more than DNS_EDE_MAX_ERRORS EDE have been already added to this + * context, the following ones are ignored. + * + * Requires: + * + * \li "edectx" to be valid + * \li "code" to be one of the INFO-CODE defied in RFC8914, see DNS_EDE_ macros. */ void dns_ede_copy(dns_edectx_t *edectx_to, dns_edectx_t *edectx_from); +/*%< + * Copy all EDE from "edectx_from" into "edectx_to". If "edectx_to" reaches the + * maximum number of EDE (see DNS_EDE_MAX_ERRORS), the copy stops and + * remaining EDE in "edectx_from" are not copied. + * + * Rules defined in "dns_ede_add" applies. + * + * Requires: + * + * \li "edectx_from" to be valid + * \li "edectx_to" to be valid + */ diff --git a/lib/dns/include/dns/message.h b/lib/dns/include/dns/message.h index 18692e2bfdd..4e65d9414b4 100644 --- a/lib/dns/include/dns/message.h +++ b/lib/dns/include/dns/message.h @@ -24,6 +24,7 @@ #include #include +#include #include #include @@ -130,34 +131,6 @@ */ #define DNS_EDNSOPTIONS 8 + DNS_EDE_MAX_ERRORS -/*%< EDNS0 extended DNS errors */ -#define DNS_EDE_OTHER 0 /*%< Other Error */ -#define DNS_EDE_DNSKEYALG 1 /*%< Unsupported DNSKEY Algorithm */ -#define DNS_EDE_DSDIGESTTYPE 2 /*%< Unsupported DS Digest Type */ -#define DNS_EDE_STALEANSWER 3 /*%< Stale Answer */ -#define DNS_EDE_FORGEDANSWER 4 /*%< Forged Answer */ -#define DNS_EDE_DNSSECINDETERMINATE 5 /*%< DNSSEC Indeterminate */ -#define DNS_EDE_DNSSECBOGUS 6 /*%< DNSSEC Bogus */ -#define DNS_EDE_SIGNATUREEXPIRED 7 /*%< Signature Expired */ -#define DNS_EDE_SIGNATURENOTYETVALID 8 /*%< Signature Not Yet Valid */ -#define DNS_EDE_DNSKEYMISSING 9 /*%< DNSKEY Missing */ -#define DNS_EDE_RRSIGSMISSING 10 /*%< RRSIGs Missing */ -#define DNS_EDE_NOZONEKEYBITSET 11 /*%< No Zone Key Bit Set */ -#define DNS_EDE_NSECMISSING 12 /*%< NSEC Missing */ -#define DNS_EDE_CACHEDERROR 13 /*%< Cached Error */ -#define DNS_EDE_NOTREADY 14 /*%< Not Ready */ -#define DNS_EDE_BLOCKED 15 /*%< Blocked */ -#define DNS_EDE_CENSORED 16 /*%< Censored */ -#define DNS_EDE_FILTERED 17 /*%< Filtered */ -#define DNS_EDE_PROHIBITED 18 /*%< Prohibited */ -#define DNS_EDE_STALENXANSWER 19 /*%< Stale NXDomain Answer */ -#define DNS_EDE_NOTAUTH 20 /*%< Not Authoritative */ -#define DNS_EDE_NOTSUPPORTED 21 /*%< Not Supported */ -#define DNS_EDE_NOREACHABLEAUTH 22 /*%< No Reachable Authority */ -#define DNS_EDE_NETWORKERROR 23 /*%< Network Error */ -#define DNS_EDE_INVALIDDATA 24 /*%< Invalid Data */ -#define DNS_EDE_MAX_CODE DNS_EDE_INVALIDDATA - #define DNS_MESSAGE_REPLYPRESERVE (DNS_MESSAGEFLAG_RD | DNS_MESSAGEFLAG_CD) #define DNS_MESSAGEEXTFLAG_REPLYPRESERVE (DNS_MESSAGEEXTFLAG_DO)