Home | History | Annotate | Line # | Download | only in dns 
      1 /*	$NetBSD: ede.h,v 1.2 2025/05/21 14:48:04 christos Exp $	*/
      2 
      3 /*
      4  * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
      5  *
      6  * SPDX-License-Identifier: MPL-2.0
      7  *
      8  * This Source Code Form is subject to the terms of the Mozilla Public
      9  * License, v. 2.0. If a copy of the MPL was not distributed with this
     10  * file, you can obtain one at https://mozilla.org/MPL/2.0/.
     11  *
     12  * See the COPYRIGHT file distributed with this work for additional
     13  * information regarding copyright ownership.
     14  */
     15 
     16 #pragma once
     17 
     18 #include <isc/mem.h>
     19 
     20 #include <dns/message.h>
     21 
     22 /*%< EDNS0 extended DNS errors */
     23 #define DNS_EDE_OTHER		     0	/*%< Other Error */
     24 #define DNS_EDE_DNSKEYALG	     1	/*%< Unsupported DNSKEY Algorithm */
     25 #define DNS_EDE_DSDIGESTTYPE	     2	/*%< Unsupported DS Digest Type */
     26 #define DNS_EDE_STALEANSWER	     3	/*%< Stale Answer */
     27 #define DNS_EDE_FORGEDANSWER	     4	/*%< Forged Answer */
     28 #define DNS_EDE_DNSSECINDETERMINATE  5	/*%< DNSSEC Indeterminate */
     29 #define DNS_EDE_DNSSECBOGUS	     6	/*%< DNSSEC Bogus */
     30 #define DNS_EDE_SIGNATUREEXPIRED     7	/*%< Signature Expired */
     31 #define DNS_EDE_SIGNATURENOTYETVALID 8	/*%< Signature Not Yet Valid */
     32 #define DNS_EDE_DNSKEYMISSING	     9	/*%< DNSKEY Missing */
     33 #define DNS_EDE_RRSIGSMISSING	     10 /*%< RRSIGs Missing */
     34 #define DNS_EDE_NOZONEKEYBITSET	     11 /*%< No Zone Key Bit Set */
     35 #define DNS_EDE_NSECMISSING	     12 /*%< NSEC Missing */
     36 #define DNS_EDE_CACHEDERROR	     13 /*%< Cached Error */
     37 #define DNS_EDE_NOTREADY	     14 /*%< Not Ready */
     38 #define DNS_EDE_BLOCKED		     15 /*%< Blocked */
     39 #define DNS_EDE_CENSORED	     16 /*%< Censored */
     40 #define DNS_EDE_FILTERED	     17 /*%< Filtered */
     41 #define DNS_EDE_PROHIBITED	     18 /*%< Prohibited */
     42 #define DNS_EDE_STALENXANSWER	     19 /*%< Stale NXDomain Answer */
     43 #define DNS_EDE_NOTAUTH		     20 /*%< Not Authoritative */
     44 #define DNS_EDE_NOTSUPPORTED	     21 /*%< Not Supported */
     45 #define DNS_EDE_NOREACHABLEAUTH	     22 /*%< No Reachable Authority */
     46 #define DNS_EDE_NETWORKERROR	     23 /*%< Network Error */
     47 #define DNS_EDE_INVALIDDATA	     24 /*%< Invalid Data */
     48 
     49 #define DNS_EDE_MAX_CODE DNS_EDE_INVALIDDATA
     50 
     51 /*
     52  * From RFC 8914:
     53  * Because long EXTRA-TEXT fields may trigger truncation (which is undesirable
     54  * given the supplemental nature of EDE), implementers and operators creating
     55  * EDE options SHOULD avoid lengthy EXTRA-TEXT contents.
     56  *
     57  * Following this advice we limit the EXTRA-TEXT length to 64 characters.
     58  */
     59 #define DNS_EDE_EXTRATEXT_LEN 64
     60 
     61 #define DNS_EDE_MAX_ERRORS 3
     62 
     63 typedef struct dns_edectx dns_edectx_t;
     64 struct dns_edectx {
     65 	int	       magic;
     66 	isc_mem_t     *mctx;
     67 	dns_ednsopt_t *ede[DNS_EDE_MAX_ERRORS];
     68 	uint32_t       edeused;
     69 	size_t	       nextede;
     70 };
     71 /*%<
     72  * Multiple extended DNS errors (EDE) (defined in RFC 8914) can be raised during
     73  * a DNS resolution and in various area of the code base. "dns_edectx_t" object
     74  * abstract and holds pending EDE and the set of dns_ede_ API enable to
     75  * manipulate its state (adding EDE, transfer to another context, etc.). EDE are
     76  * internally stored in the wire format, so it can be directly consumed to build
     77  * the response client message.
     78  */
     79 
     80 void
     81 dns_ede_init(isc_mem_t *mctx, dns_edectx_t *edectx);
     82 /*%<
     83  * Initialize "edectx" so it is valid to use. Can be called after
     84  * dns_ede_invalidate" is being called to reuse the object.
     85  *
     86  * Requires:
     87  *
     88  * \li "mctx" to be valid
     89  * \li "edectx" to be valid
     90  */
     91 
     92 void
     93 dns_ede_reset(dns_edectx_t *edectx);
     94 /*%<
     95  * Reset "edectx" internal state and free all its EDE from memory. "edectx" is
     96  * still valid to use, in the same state than after dns_ede_init is called.
     97  *
     98  * Requires:
     99  *
    100  * \li "edectx" to be valid
    101  */
    102 
    103 void
    104 dns_ede_invalidate(dns_edectx_t *edectx);
    105 /*%<
    106  * Reset "edectx" and remove its memory context as well as its magic number. It
    107  * is not valid to use anymore.
    108  *
    109  * Requires:
    110  *
    111  * \li "edectx" to be valid
    112  */
    113 
    114 void
    115 dns_ede_add(dns_edectx_t *edectx, uint16_t code, const char *text);
    116 /*%<
    117  * Add a new extended error in "edectx". "code" must be one of the INFO-CODE
    118  * values defined in RFC8914, see DNS_EDE_ macros above. "text" is optional, it
    119  * is immediately copied internally if provided.
    120  *
    121  * Rules:
    122  *
    123  * \li If "text" is non NULL, it must be NULL terminated. If its length is more
    124  * than DNS_EDE_EXTRATEXT_LEN, it is trucated.
    125  *
    126  * \li If an EDE with the same code has already been added to "edectx", the
    127  * following ones with the same code are ignored.
    128  *
    129  * \li If more than DNS_EDE_MAX_ERRORS EDE have been already added to this
    130  * context, the following ones are ignored.
    131  *
    132  * Requires:
    133  *
    134  * \li "edectx" to be valid
    135  * \li "code" to be one of the INFO-CODE defied in RFC8914, see DNS_EDE_ macros.
    136  */
    137 
    138 void
    139 dns_ede_copy(dns_edectx_t *edectx_to, const dns_edectx_t *edectx_from);
    140 /*%<
    141  * Copy all EDE from "edectx_from" into "edectx_to". If "edectx_to" reaches the
    142  * maximum number of EDE (see DNS_EDE_MAX_ERRORS), the copy stops and
    143  * remaining EDE in "edectx_from" are not copied.
    144  *
    145  * Rules defined in "dns_ede_add" applies.
    146  *
    147  * Requires:
    148  *
    149  * \li "edectx_from" to be valid
    150  * \li "edectx_to" to be valid
    151  */
    152