unbound: services/cache/dns.h File Reference

unbound 0.1

Data Structures | Macros | Functions
dns.h File Reference

This file contains the DNS cache. More...

`#include "util/storage/lruhash.h"`
`#include "util/data/msgreply.h"`

## Data Structures
struct | dns_msg
| Region allocated message reply. More...

## Macros
#define | DNSCACHE_STORE_ZEROTTL 0x100000
| Flags to control behavior of dns_cache_store() and dns_cache_store_msg().

## Functions
int | dns_cache_store (struct module_env *env, struct query_info *qinf, struct reply_info *rep, int is_referral, time_t leeway, int pside, struct regional *region, uint32_t flags, time_t qstarttime)
| Allocate a dns_msg with malloc/alloc structure and store in dns cache.
void | dns_cache_store_msg (struct module_env *env, struct query_info *qinfo, hashvalue_type hash, struct reply_info *rep, time_t leeway, int pside, struct reply_info *qrep, uint32_t flags, struct regional *region, time_t qstarttime)
| Store message in the cache.
struct delegpt * | dns_cache_find_delegation (struct module_env *env, uint8_t *qname, size_t qnamelen, uint16_t qtype, uint16_t qclass, struct regional *region, struct dns_msg **msg, time_t timenow, int noexpiredabove, uint8_t *expiretop, size_t expiretoplen)
| Find a delegation from the cache.
struct dns_msg * | tomsg (struct module_env *env, struct query_info *q, struct reply_info *r, struct regional *region, time_t now, int allow_expired, struct regional *scratch)
| generate dns_msg from cached message
struct dns_msg * | dns_msg_deepcopy_region (struct dns_msg *origin, struct regional *region)
| Deep copy a dns_msg to a region.
struct dns_msg * | dns_cache_lookup (struct module_env *env, uint8_t *qname, size_t qnamelen, uint16_t qtype, uint16_t qclass, uint16_t flags, struct regional *region, struct regional *scratch, int no_partial, uint8_t *dpname, size_t dpnamelen)
| Find cached message.
int | cache_fill_missing (struct module_env *env, uint16_t qclass, struct regional *region, struct delegpt *dp)
| find and add A and AAAA records for missing nameservers in delegpt
struct dns_msg * | dns_msg_create (uint8_t *qname, size_t qnamelen, uint16_t qtype, uint16_t qclass, struct regional *region, size_t capacity)
| Utility, create new, unpacked data structure for cache response.
int | dns_msg_authadd (struct dns_msg *msg, struct regional *region, struct ub_packed_rrset_key *rrset, time_t now)
| Add rrset to authority section in unpacked dns_msg message.
int | dns_msg_ansadd (struct dns_msg *msg, struct regional *region, struct ub_packed_rrset_key *rrset, time_t now)
| Add rrset to authority section in unpacked dns_msg message.
int | dns_cache_prefetch_adjust (struct module_env *env, struct query_info *qinfo, time_t adjust, uint16_t flags)
| Adjust the prefetch_ttl for a cached message.
struct msgreply_entry * | msg_cache_lookup (struct module_env *env, uint8_t *qname, size_t qnamelen, uint16_t qtype, uint16_t qclass, uint16_t flags, time_t now, int wr)
| lookup message in message cache the returned nonNULL entry is locked and has to be unlocked by the caller
void | msg_cache_remove (struct module_env *env, uint8_t *qname, size_t qnamelen, uint16_t qtype, uint16_t qclass, uint16_t flags)
| Remove entry from the message cache.

## Detailed Description

This file contains the DNS cache.

## Macro Definition Documentation

## ◆ DNSCACHE_STORE_ZEROTTL

#define DNSCACHE_STORE_ZEROTTL 0x100000

Flags to control behavior of dns_cache_store() and dns_cache_store_msg().

Must be an unsigned 32-bit value larger than 0xffff Allow caching a DNS message with a zero TTL.

Referenced by dns_cache_store_msg().

## Function Documentation

## ◆ dns_cache_store()

int dns_cache_store | ( | struct module_env * | env,
|  | struct query_info * | qinf,
|  | struct reply_info * | rep,
|  | int | is_referral,
|  | time_t | leeway,
|  | int | pside,
|  | struct regional * | region,
|  | uint32_t | flags,
|  | time_t | qstarttime )

Allocate a dns_msg with malloc/alloc structure and store in dns cache.

Parameters

  env | environment, with alloc structure and dns cache.
  qinf | query info, the query for which answer is stored. this is allocated in a region, and will be copied to malloc area before insertion.
  rep | reply in dns_msg from dns_alloc_msg for example. this is allocated in a region, and will be copied to malloc area before insertion.
  is_referral | If true, then the given message to be stored is a referral. The cache implementation may use this as a hint. It will store only the RRsets, not the message.
  leeway | TTL value, if not 0, other rrsets are considered expired that many seconds before actual TTL expiry.
  pside | if true, information came from a server which was fetched from the parentside of the zonecut. This means that the type NS can be updated to full TTL even in prefetch situations.
  region | region to allocate better entries from cache into. (used when is_referral is false).
  flags | flags with BIT_CD for AAAA queries in dns64 translation. The higher 16 bits are used internally to customize the cache policy. (See DNSCACHE_STORE_xxx flags).
  qstarttime | time when the query was started, and thus when the delegations were looked up.

Returns
  0 on alloc error (out of memory).

References module_env::alloc, BIT_AA, BIT_CD, BIT_QR, BIT_RA, lruhash_entry::data, dns_cache_store_msg(), ub_packed_rrset_key::entry, reply_info::flags, rrset_ref::id, ub_packed_rrset_key::id, rrset_ref::key, LDNS_RR_TYPE_NS, memdup(), module_env::now, packed_rrset_ttl_add(), query_info::qname, query_info::qname_len, query_info_hash(), reply_info_copy(), reply_info_delete(), reply_info_parsedelete(), ub_packed_rrset_key::rk, module_env::rrset_cache, rrset_cache_update(), reply_info::rrset_count, reply_info::rrsets, and packed_rrset_key::type.

Referenced by dns64_inform_super(), handle_event_moddone(), iter_dns_store(), load_msg(), processFinished(), and storeQueryInCache().

## ◆ dns_cache_store_msg()

void dns_cache_store_msg | ( | struct module_env * | env,
|  | struct query_info * | qinfo,
|  | hashvalue_type | hash,
|  | struct reply_info * | rep,
|  | time_t | leeway,
|  | int | pside,
|  | struct reply_info * | qrep,
|  | uint32_t | flags,
|  | struct regional * | region,
|  | time_t | qstarttime )

Store message in the cache.

Stores in message cache and rrset cache. Both qinfo and rep should be malloced and are put in the cache. They should not be used after this call, as they are then in shared cache. Does not return errors, they are logged and only lead to less cache.

Parameters

  env | module environment with the DNS cache.
  qinfo | query info
  hash | hash over qinfo.
  rep | reply info, together with qinfo makes up the message. Adjusts the reply info TTLs to absolute time.
  leeway | TTL value, if not 0, other rrsets are considered expired that many seconds before actual TTL expiry.
  pside | if true, information came from a server which was fetched from the parentside of the zonecut. This means that the type NS can be updated to full TTL even in prefetch situations.
  qrep | message that can be altered with better rrs from cache.
  flags | customization flags for the cache policy.
  qstarttime | time when the query was started, and thus when the delegations were looked up.
  region | to allocate into for qmsg.

References module_env::alloc, DNSCACHE_STORE_ZEROTTL, msgreply_entry::entry, rrset_ref::id, ub_packed_rrset_key::id, rrset_ref::key, log_err(), module_env::msg_cache, msg_cache_remove(), module_env::now, query_info::qclass, query_info::qname, query_info::qname_len, query_info::qtype, query_info_entrysetup(), reply_info::ref, reply_info_delete(), reply_info_set_ttls(), reply_info_sortref(), reply_info::rrset_count, reply_info::rrsets, slabhash_insert(), store_rrsets(), reply_info::ttl, VERB_ALGO, and verbose().

Referenced by dns_cache_store().

## ◆ dns_cache_find_delegation()

struct delegpt * dns_cache_find_delegation | ( | struct module_env * | env,
|  | uint8_t * | qname,
|  | size_t | qnamelen,
|  | uint16_t | qtype,
|  | uint16_t | qclass,
|  | struct regional * | region,
|  | struct dns_msg ** | msg,
|  | time_t | timenow,
|  | int | noexpiredabove,
|  | uint8_t * | expiretop,
|  | size_t | expiretoplen )

Find a delegation from the cache.

Parameters

  env | module environment with the DNS cache.
  qname | query name.
  qnamelen | length of qname.
  qtype | query type.
  qclass | query class.
  region | where to allocate result delegation.
  msg | if not NULL, delegation message is returned here, synthesized from the cache.
  timenow | the time now, for checking if TTL on cache entries is OK.
  noexpiredabove | if set, no expired NS rrsets above the one found are tolerated. It only returns delegations where the delegations above it are valid.
  expiretop | if not NULL, name where check for expiry ends for noexpiredabove.
  expiretoplen | length of expiretop dname.

Returns
  new delegation or NULL on error or if not found in cache.

References packed_rrset_data::count, lruhash_entry::data, delegpt_create(), delegpt_rrset_add_ns(), delegpt_set_name(), packed_rrset_key::dname, dns_msg_authadd(), dns_msg_create(), ub_packed_rrset_key::entry, find_add_addrs(), find_add_ds(), find_closest_of_type(), LDNS_RR_TYPE_NS, lruhash_entry::lock, log_err(), and ub_packed_rrset_key::rk.

Referenced by answer_norec_from_cache(), generate_parentside_target_query(), and processInitRequest().

## ◆ tomsg()

struct dns_msg * tomsg | ( | struct module_env * | env,
|  | struct query_info * | q,
|  | struct reply_info * | r,
|  | struct regional * | region,
|  | time_t | now,
|  | int | allow_expired,
|  | struct regional * | scratch )

generate dns_msg from cached message

Parameters

  env | module environment with the DNS cache. NULL if the LRU from cache does not need to be touched.
  q | query info, contains qname that will make up the dns message.
  r | reply info that, together with qname, will make up the dns message.
  region | where to allocate dns message.
  now | the time now, for check if TTL on cache entry is ok.
  allow_expired | if true and serve-expired is enabled, it will allow for expired dns_msg to be generated based on the configured serve-expired logic.
  scratch | where to allocate temporary data.

References reply_info::an_numrrsets, reply_info::ar_numrrsets, reply_info::authoritative, module_env::cfg, reply_info::flags, FLAGS_GET_RCODE, gen_dns_msg(), LDNS_RR_TYPE_CNAME, LDNS_RR_TYPE_DNAME, reply_info::ns_numrrsets, packed_rrset_copy_region(), reply_info::prefetch_ttl, PREFETCH_TTL_CALC, reply_info::qdcount, reply_info::reason_bogus, reply_info::reason_bogus_str, reply_info::ref, regional_strdup(), dns_msg::rep, reply_all_rrsets_secure(), reply_check_cname_chain(), ub_packed_rrset_key::rk, rrset_array_lock(), rrset_array_unlock(), rrset_array_unlock_touch(), module_env::rrset_cache, reply_info::rrset_count, reply_info::rrsets, sec_status_secure, reply_info::security, SERVE_EXPIRED_REPLY_TTL, config_file::serve_expired_reply_ttl, SERVE_EXPIRED_TTL, config_file::serve_expired_ttl, reply_info::serve_expired_ttl, reply_info::ttl, and packed_rrset_key::type.

Referenced by dns_cache_lookup(), and mesh_serve_expired_lookup().

## ◆ dns_msg_deepcopy_region()

struct dns_msg * dns_msg_deepcopy_region | ( | struct dns_msg * | origin,
|  | struct regional * | region )

Deep copy a dns_msg to a region.

Parameters

  origin | the dns_msg to copy.
  region | the region to copy all the data to.

Returns
  the new dns_msg or NULL on malloc error.

References gen_dns_msg(), packed_rrset_copy_region(), dns_msg::qinfo, reply_info::reason_bogus_str, regional_strdup(), dns_msg::rep, reply_info::rrset_count, and reply_info::rrsets.

Referenced by val_inform_super().

## ◆ dns_cache_lookup()

struct dns_msg * dns_cache_lookup | ( | struct module_env * | env,
|  | uint8_t * | qname,
|  | size_t | qnamelen,
|  | uint16_t | qtype,
|  | uint16_t | qclass,
|  | uint16_t | flags,
|  | struct regional * | region,
|  | struct regional * | scratch,
|  | int | no_partial,
|  | uint8_t * | dpname,
|  | size_t | dpnamelen )

Find cached message.

Parameters

  env | module environment with the DNS cache.
  qname | query name.
  qnamelen | length of qname.
  qtype | query type.
  qclass | query class.
  flags | flags with BIT_CD for AAAA queries in dns64 translation.
  region | where to allocate result.
  scratch | where to allocate temporary data.
  no_partial | if true, only complete messages and not a partial one (with only the start of the CNAME chain and not the rest).
  dpname | if not NULL, do not return NXDOMAIN above this name.
  dpnamelen | length of dpname.

Returns
  new response message (alloced in region, rrsets do not have IDs). or NULL on error or if not found in cache. TTLs are made relative to the current time.

References reply_info::an_numrrsets, module_env::cfg, lruhash_entry::data, dname_is_root(), dname_remove_label(), dname_subdomain_c(), ub_packed_rrset_key::entry, fill_any(), find_closest_of_type(), reply_info::flags, FLAGS_GET_RCODE, config_file::harden_below_nxdomain, iter_scrub_nxdomain(), lruhash_entry::key, msgreply_entry::key, LDNS_RR_TYPE_A, LDNS_RR_TYPE_ANY, LDNS_RR_TYPE_CNAME, LDNS_RR_TYPE_DNAME, LDNS_RR_TYPE_DS, query_info::local_alias, lruhash_entry::lock, module_env::msg_cache, module_env::now, query_info::qclass, dns_msg::qinfo, query_info::qname, query_info::qname_len, config_file::qname_minimisation, query_info::qtype, query_info_hash(), dns_msg::rep, ub_packed_rrset_key::rk, module_env::rrset_cache, rrset_cache_lookup(), rrset_msg(), rrset_trust_add_AA, rrset_trust_add_noAA, rrset_trust_auth_AA, rrset_trust_auth_noAA, reply_info::rrsets, sec_status_secure, sec_status_unchecked, reply_info::security, slabhash_lookup(), synth_dname_msg(), tomsg(), packed_rrset_data::trust, packed_rrset_key::type, and val_rrset_wildcard().

Referenced by processInitRequest(), and processQueryTargets().

## ◆ cache_fill_missing()

int cache_fill_missing | ( | struct module_env * | env,
|  | uint16_t | qclass,
|  | struct regional * | region,
|  | struct delegpt * | dp )

find and add A and AAAA records for missing nameservers in delegpt

Parameters

  env | module environment with rrset cache
  qclass | which class to look in.
  region | where to store new dp info.
  dp | delegation point to fill missing entries.

Returns
  false on alloc failure.

References BIT_CD, delegpt_ns::cache_lookup_count, delegpt_add_neg_msg(), delegpt_add_rrset_A(), delegpt_add_rrset_AAAA(), msgreply_entry::entry, ub_packed_rrset_key::entry, delegpt_ns::lame, LDNS_RR_TYPE_A, LDNS_RR_TYPE_AAAA, lruhash_entry::lock, log_nametypeclass(), msg_cache_lookup(), delegpt_ns::name, delegpt_ns::namelen, delegpt_ns::next, module_env::now, delegpt::nslist, module_env::rrset_cache, rrset_cache_lookup(), and VERB_ALGO.

Referenced by error_supers(), processInitRequest(), processLastResort(), and processQueryResponse().

## ◆ dns_msg_create()

struct dns_msg * dns_msg_create | ( | uint8_t * | qname,
|  | size_t | qnamelen,
|  | uint16_t | qtype,
|  | uint16_t | qclass,
|  | struct regional * | region,
|  | size_t | capacity )

Utility, create new, unpacked data structure for cache response.

QR bit set, no AA. Query set as indicated. Space for number of rrsets.

Parameters

  qname | query section name
  qnamelen | len of qname
  qtype | query section type
  qclass | query section class
  region | where to alloc.
  capacity | number of rrsets space to create in the array.

Returns
  new dns_msg struct or NULL on mem fail.

References BIT_QR, reply_info::flags, query_info::local_alias, query_info::qclass, reply_info::qdcount, dns_msg::qinfo, query_info::qname, query_info::qname_len, query_info::qtype, reply_info::reason_bogus, regional_alloc(), regional_alloc_init(), regional_alloc_zero(), dns_msg::rep, RR_COUNT_MAX, and reply_info::rrsets.

Referenced by dns_cache_find_delegation(), fill_any(), neg_nsec3_proof_ds(), val_find_DS(), and val_neg_getmsg().

## ◆ dns_msg_authadd()

int dns_msg_authadd | ( | struct dns_msg * | msg,
|  | struct regional * | region,
|  | struct ub_packed_rrset_key * | rrset,
|  | time_t | now )

Add rrset to authority section in unpacked dns_msg message.

Must have enough space left, does not grow the array.

Parameters

  msg | msg to put it in.
  region | region to alloc in
  rrset | to add in authority section
  now | now.

Returns
  true if worked, false on fail

References reply_info::ns_numrrsets, packed_rrset_copy_region(), dns_msg::rep, reply_info::rrset_count, and reply_info::rrsets.

Referenced by add_soa(), dns_cache_find_delegation(), neg_nsec3_proof_ds(), and val_neg_getmsg().

## ◆ dns_msg_ansadd()

int dns_msg_ansadd | ( | struct dns_msg * | msg,
|  | struct regional * | region,
|  | struct ub_packed_rrset_key * | rrset,
|  | time_t | now )

Add rrset to authority section in unpacked dns_msg message.

Must have enough space left, does not grow the array.

Parameters

  msg | msg to put it in.
  region | region to alloc in
  rrset | to add in authority section
  now | now.

Returns
  true if worked, false on fail

References reply_info::an_numrrsets, packed_rrset_copy_region(), dns_msg::rep, reply_info::rrset_count, and reply_info::rrsets.

Referenced by fill_any(), and val_neg_getmsg().

## ◆ dns_cache_prefetch_adjust()

int dns_cache_prefetch_adjust | ( | struct module_env * | env,
|  | struct query_info * | qinfo,
|  | time_t | adjust,
|  | uint16_t | flags )

Adjust the prefetch_ttl for a cached message.

This adds a value to the prefetch ttl - postponing the time when it will be prefetched for future incoming queries.

Parameters

  env | module environment with caches and time.
  qinfo | query info for the query that needs adjustment.
  adjust | time in seconds to add to the prefetch_leeway.
  flags | flags with BIT_CD for AAAA queries in dns64 translation.

Returns
  false if not in cache. true if added.

References lruhash_entry::data, msgreply_entry::entry, lruhash_entry::lock, msg_cache_lookup(), module_env::now, reply_info::prefetch_ttl, query_info::qclass, query_info::qname, query_info::qname_len, and query_info::qtype.

Referenced by error_response_cache().

## ◆ msg_cache_lookup()

struct msgreply_entry * msg_cache_lookup | ( | struct module_env * | env,
|  | uint8_t * | qname,
|  | size_t | qnamelen,
|  | uint16_t | qtype,
|  | uint16_t | qclass,
|  | uint16_t | flags,
|  | time_t | now,
|  | int | wr )

lookup message in message cache the returned nonNULL entry is locked and has to be unlocked by the caller

lookup message in message cache the returned nonNULL entry is locked and has to be unlocked by the caller

References lruhash_entry::data, lruhash_entry::key, query_info::local_alias, lruhash_entry::lock, module_env::msg_cache, query_info::qclass, query_info::qname, query_info::qname_len, query_info::qtype, query_info_hash(), and slabhash_lookup().

Referenced by cache_fill_missing(), dns_cache_prefetch_adjust(), error_response_cache(), and find_add_addrs().

## ◆ msg_cache_remove()

void msg_cache_remove | ( | struct module_env * | env,
|  | uint8_t * | qname,
|  | size_t | qnamelen,
|  | uint16_t | qtype,
|  | uint16_t | qclass,
|  | uint16_t | flags )

Remove entry from the message cache.

For unwanted entries.

Parameters

  env | with message cache.
  qname | query name, in wireformat
  qnamelen | length of qname, including terminating 0.
  qtype | query type, host order.
  qclass | query class, host order.
  flags | flags

Remove entry from the message cache.

References query_info::local_alias, module_env::msg_cache, query_info::qclass, query_info::qname, query_info::qname_len, query_info::qtype, query_info_hash(), and slabhash_remove().

Referenced by dns64_adjust_a(), and dns_cache_store_msg().