unbound/iterator/iter_delegpt.h

/*
 * iterator/iter_delegpt.h - delegation point with NS and address information.
 *
 * Copyright (c) 2007, NLnet Labs. All rights reserved.
 *
 * This software is open source.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * Redistributions of source code must retain the above copyright notice,
 * this list of conditions and the following disclaimer.
 *
 * Redistributions in binary form must reproduce the above copyright notice,
 * this list of conditions and the following disclaimer in the documentation
 * and/or other materials provided with the distribution.
 *
 * Neither the name of the NLNET LABS nor the names of its contributors may
 * be used to endorse or promote products derived from this software without
 * specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

/**
 * \file
 *
 * This file implements the Delegation Point. It contains a list of name servers
 * and their addresses if known.
 */

#ifndef ITERATOR_ITER_DELEGPT_H
#define ITERATOR_ITER_DELEGPT_H
#include "util/log.h"
struct regional;
struct delegpt_ns;
struct delegpt_addr;
struct dns_msg;
struct ub_packed_rrset_key;
struct msgreply_entry;

/**
 * Delegation Point.
 * For a domain name, the NS rrset, and the A and AAAA records for those.
 */
struct delegpt {
	/** the domain name of the delegation point. */
	uint8_t* name;
	/** length of the delegation point name */
	size_t namelen;
	/** number of labels in delegation point */
	int namelabs;

	/** the nameservers, names from the NS RRset rdata. */
	struct delegpt_ns* nslist;
	/** the target addresses for delegation */
	struct delegpt_addr* target_list;
	/** the list of usable targets; subset of target_list
	 * the items in this list are not part of the result list.  */
	struct delegpt_addr* usable_list;
	/** the list of returned targets; subset of target_list */
	struct delegpt_addr* result_list;

	/** if true, the NS RRset was bogus. All info is bad. */
	int bogus;
	/** if true, the parent-side NS record has been applied:
	 * its names have been added and their addresses can follow later.
	 * Also true if the delegationpoint was created from a delegation
	 * message and thus contains the parent-side-info already. */
	uint8_t has_parent_side_NS;
	/** for assertions on type of delegpt */
	uint8_t dp_type_mlc;
	/** use SSL for upstream query */
	uint8_t ssl_upstream;
	/** delegpt from authoritative zone that is locally hosted */
	uint8_t auth_dp;
	/*** no cache */
	int no_cache;
};

/**
 * Nameservers for a delegation point.
 */
struct delegpt_ns {
	/** next in list */
	struct delegpt_ns* next;
	/** name of nameserver */
	uint8_t* name;
	/** length of name */
	size_t namelen;
	/**
	 * If the name has been resolved. false if not queried for yet.
	 * true if the A, AAAA queries have been generated.
	 * marked true if those queries fail.
	 * and marked true if got4 and got6 are both true.
	 */
	int resolved;
	/** if the ipv4 address is in the delegpt */
	uint8_t got4;
	/** if the ipv6 address is in the delegpt */
	uint8_t got6;
	/**
	 * If the name is parent-side only and thus dispreferred.
	 * Its addresses become dispreferred as well
	 */
	uint8_t lame;
	/** if the parent-side ipv4 address has been looked up (last resort).
	 * Also enabled if a parent-side cache entry exists, or a parent-side
	 * negative-cache entry exists. */
	uint8_t done_pside4;
	/** if the parent-side ipv6 address has been looked up (last resort).
	 * Also enabled if a parent-side cache entry exists, or a parent-side
	 * negative-cache entry exists. */
	uint8_t done_pside6;
};

/**
 * Address of target nameserver in delegation point.
 */
struct delegpt_addr {
	/** next delegation point in results */
	struct delegpt_addr* next_result;
	/** next delegation point in usable list */
	struct delegpt_addr* next_usable;
	/** next delegation point in all targets list */
	struct delegpt_addr* next_target;

	/** delegation point address */
	struct sockaddr_storage addr;
	/** length of addr */
	socklen_t addrlen;
	/** number of attempts for this addr */
	int attempts;
	/** rtt stored here in the selection algorithm */
	int sel_rtt;
	/** if true, the A or AAAA RR was bogus, so this address is bad.
	 * Also check the dp->bogus to see if everything is bogus. */
	uint8_t bogus;
	/** if true, this address is dispreferred: it is a lame IP address */
	uint8_t lame;
	/** if the address is dnsseclame, but this cannot be cached, this
	 * option is useful to mark the address dnsseclame.
	 * This value is not copied in addr-copy and dp-copy. */
	uint8_t dnsseclame;
	/** the TLS authentication name, (if not NULL) to use. */
	char* tls_auth_name;
};

/**
 * Create new delegation point.
 * @param regional: where to allocate it.
 * @return new delegation point or NULL on error.
 */
struct delegpt* delegpt_create(struct regional* regional);

/**
 * Create a copy of a delegation point.
 * @param dp: delegation point to copy.
 * @param regional: where to allocate it.
 * @return new delegation point or NULL on error.
 */
struct delegpt* delegpt_copy(struct delegpt* dp, struct regional* regional);

/**
 * Set name of delegation point.
 * @param dp: delegation point.
 * @param regional: where to allocate the name copy.
 * @param name: name to use.
 * @return false on error.
 */
int delegpt_set_name(struct delegpt* dp, struct regional* regional,
	uint8_t* name);

/**
 * Add a name to the delegation point.
 * @param dp: delegation point.
 * @param regional: where to allocate the info.
 * @param name: domain name in wire format.
 * @param lame: name is lame, disprefer it.
 * @return false on error.
 */
int delegpt_add_ns(struct delegpt* dp, struct regional* regional,
	uint8_t* name, uint8_t lame);

/**
 * Add NS rrset; calls add_ns repeatedly.
 * @param dp: delegation point.
 * @param regional: where to allocate the info.
 * @param ns_rrset: NS rrset.
 * @param lame: rrset is lame, disprefer it.
 * @return 0 on alloc error.
 */
int delegpt_rrset_add_ns(struct delegpt* dp, struct regional* regional,
	struct ub_packed_rrset_key* ns_rrset, uint8_t lame);

/**
 * Add target address to the delegation point.
 * @param dp: delegation point.
 * @param regional: where to allocate the info.
 * @param name: name for which target was found (must be in nslist).
 *	This name is marked resolved.
 * @param namelen: length of name.
 * @param addr: the address.
 * @param addrlen: the length of addr.
 * @param bogus: security status for the address, pass true if bogus.
 * @param lame: address is lame.
 * @return false on error.
 */
int delegpt_add_target(struct delegpt* dp, struct regional* regional,
	uint8_t* name, size_t namelen, struct sockaddr_storage* addr,
	socklen_t addrlen, uint8_t bogus, uint8_t lame);

/**
 * Add A RRset to delegpt.
 * @param dp: delegation point.
 * @param regional: where to allocate the info.
 * @param rrset: RRset A to add.
 * @param lame: rrset is lame, disprefer it.
 * @return 0 on alloc error.
 */
int delegpt_add_rrset_A(struct delegpt* dp, struct regional* regional,
	struct ub_packed_rrset_key* rrset, uint8_t lame);

/**
 * Add AAAA RRset to delegpt.
 * @param dp: delegation point.
 * @param regional: where to allocate the info.
 * @param rrset: RRset AAAA to add.
 * @param lame: rrset is lame, disprefer it.
 * @return 0 on alloc error.
 */
int delegpt_add_rrset_AAAA(struct delegpt* dp, struct regional* regional,
	struct ub_packed_rrset_key* rrset, uint8_t lame);

/**
 * Add any RRset to delegpt.
 * Does not check for duplicates added.
 * @param dp: delegation point.
 * @param regional: where to allocate the info.
 * @param rrset: RRset to add, NS, A, AAAA.
 * @param lame: rrset is lame, disprefer it.
 * @return 0 on alloc error.
 */
int delegpt_add_rrset(struct delegpt* dp, struct regional* regional,
	struct ub_packed_rrset_key* rrset, uint8_t lame);

/**
 * Add address to the delegation point. No servername is associated or checked.
 * @param dp: delegation point.
 * @param regional: where to allocate the info.
 * @param addr: the address.
 * @param addrlen: the length of addr.
 * @param bogus: if address is bogus.
 * @param lame: if address is lame.
 * @param tls_auth_name: TLS authentication name (or NULL).
 * @return false on error.
 */
int delegpt_add_addr(struct delegpt* dp, struct regional* regional,
	struct sockaddr_storage* addr, socklen_t addrlen,
	uint8_t bogus, uint8_t lame, char* tls_auth_name);

/**
 * Find NS record in name list of delegation point.
 * @param dp: delegation point.
 * @param name: name of nameserver to look for, uncompressed wireformat.
 * @param namelen: length of name.
 * @return the ns structure or NULL if not found.
 */
struct delegpt_ns* delegpt_find_ns(struct delegpt* dp, uint8_t* name,
	size_t namelen);

/**
 * Find address record in total list of delegation point.
 * @param dp: delegation point.
 * @param addr: address
 * @param addrlen: length of addr
 * @return the addr structure or NULL if not found.
 */
struct delegpt_addr* delegpt_find_addr(struct delegpt* dp,
	struct sockaddr_storage* addr, socklen_t addrlen);

/**
 * Print the delegation point to the log. For debugging.
 * @param v: verbosity value that is needed to emit to log.
 * @param dp: delegation point.
 */
void delegpt_log(enum verbosity_value v, struct delegpt* dp);

/** count NS and number missing for logging */
void delegpt_count_ns(struct delegpt* dp, size_t* numns, size_t* missing);

/** count addresses, and number in result and available lists, for logging */
void delegpt_count_addr(struct delegpt* dp, size_t* numaddr, size_t* numres,
	size_t* numavail);

/**
 * Add all usable targets to the result list.
 * @param dp: delegation point.
 */
void delegpt_add_unused_targets(struct delegpt* dp);

/**
 * Count number of missing targets. These are ns names with no resolved flag.
 * @param dp: delegation point.
 * @return number of missing targets (or 0).
 */
size_t delegpt_count_missing_targets(struct delegpt* dp);

/** count total number of targets in dp */
size_t delegpt_count_targets(struct delegpt* dp);

/**
 * Create new delegation point from a dns message
 *
 * Note that this method does not actually test to see if the message is an
 * actual referral. It really is just checking to see if it can construct a
 * delegation point, so the message could be of some other type (some ANSWER
 * messages, some CNAME messages, generally.) Note that the resulting
 * DelegationPoint will contain targets for all "relevant" glue (i.e.,
 * address records whose ownernames match the target of one of the NS
 * records), so if policy dictates that some glue should be discarded beyond
 * that, discard it before calling this method. Note that this method will
 * find "glue" in either the ADDITIONAL section or the ANSWER section.
 *
 * @param msg: the dns message, referral.
 * @param regional: where to allocate delegation point.
 * @return new delegation point or NULL on alloc error, or if the
 *         message was not appropriate.
 */
struct delegpt* delegpt_from_message(struct dns_msg* msg,
	struct regional* regional);

/**
 * Add negative message to delegation point.
 * @param dp: delegation point.
 * @param msg: the message added, marks off A or AAAA from an NS entry.
 */
void delegpt_add_neg_msg(struct delegpt* dp, struct msgreply_entry* msg);

/**
 * Register the fact that there is no ipv6 and thus AAAAs are not going
 * to be queried for or be useful.
 * @param dp: the delegation point. Updated to reflect no ipv6.
 */
void delegpt_no_ipv6(struct delegpt* dp);

/**
 * Register the fact that there is no ipv4 and thus As are not going
 * to be queried for or be useful.
 * @param dp: the delegation point. Updated to reflect no ipv4.
 */
void delegpt_no_ipv4(struct delegpt* dp);

/**
 * create malloced delegation point, with the given name
 * @param name: uncompressed wireformat of delegpt name.
 * @return NULL on alloc failure
 */
struct delegpt* delegpt_create_mlc(uint8_t* name);

/**
 * free malloced delegation point.
 * @param dp: must have been created with delegpt_create_mlc, free'd.
 */
void delegpt_free_mlc(struct delegpt* dp);

/**
 * Set name of delegation point.
 * @param dp: delegation point. malloced.
 * @param name: name to use.
 * @return false on error.
 */
int delegpt_set_name_mlc(struct delegpt* dp, uint8_t* name);

/**
 * add a name to malloced delegation point.
 * @param dp: must have been created with delegpt_create_mlc.
 * @param name: the name to add.
 * @param lame: the name is lame, disprefer.
 * @return false on error.
 */
int delegpt_add_ns_mlc(struct delegpt* dp, uint8_t* name, uint8_t lame);

/**
 * add an address to a malloced delegation point.
 * @param dp: must have been created with delegpt_create_mlc.
 * @param addr: the address.
 * @param addrlen: the length of addr.
 * @param bogus: if address is bogus.
 * @param lame: if address is lame.
 * @param tls_auth_name: TLS authentication name (or NULL).
 * @return false on error.
 */
int delegpt_add_addr_mlc(struct delegpt* dp, struct sockaddr_storage* addr,
	socklen_t addrlen, uint8_t bogus, uint8_t lame, char* tls_auth_name);

/**
 * Add target address to the delegation point.
 * @param dp: must have been created with delegpt_create_mlc.
 * @param name: name for which target was found (must be in nslist).
 *	This name is marked resolved.
 * @param namelen: length of name.
 * @param addr: the address.
 * @param addrlen: the length of addr.
 * @param bogus: security status for the address, pass true if bogus.
 * @param lame: address is lame.
 * @return false on error.
 */
int delegpt_add_target_mlc(struct delegpt* dp, uint8_t* name, size_t namelen,
	struct sockaddr_storage* addr, socklen_t addrlen, uint8_t bogus,
	uint8_t lame);

/** get memory in use by dp */
size_t delegpt_get_mem(struct delegpt* dp);

#endif /* ITERATOR_ITER_DELEGPT_H */