^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ===================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) DNS Resolver Module
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) ===================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) .. Contents:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) - Overview.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) - Compilation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) - Setting up.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) - Usage.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) - Mechanism.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) - Debugging.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) Overview
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) ========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) The DNS resolver module provides a way for kernel services to make DNS queries
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) by way of requesting a key of key type dns_resolver. These queries are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) upcalled to userspace through /sbin/request-key.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) These routines must be supported by userspace tools dns.upcall, cifs.upcall and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) request-key. It is under development and does not yet provide the full feature
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) set. The features it does support include:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) (*) Implements the dns_resolver key_type to contact userspace.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) It does not yet support the following AFS features:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) (*) Dns query support for AFSDB resource record.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) This code is extracted from the CIFS filesystem.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) Compilation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) ===========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) The module should be enabled by turning on the kernel configuration options::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) CONFIG_DNS_RESOLVER - tristate "DNS Resolver support"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) Setting up
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) ==========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) To set up this facility, the /etc/request-key.conf file must be altered so that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) /sbin/request-key can appropriately direct the upcalls. For example, to handle
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) basic dname to IPv4/IPv6 address resolution, the following line should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) added::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) #OP TYPE DESC CO-INFO PROGRAM ARG1 ARG2 ARG3 ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) #====== ============ ======= ======= ==========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) create dns_resolver * * /usr/sbin/cifs.upcall %k
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) To direct a query for query type 'foo', a line of the following should be added
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) before the more general line given above as the first match is the one taken::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) create dns_resolver foo:* * /usr/sbin/dns.foo %k
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) Usage
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) =====
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) To make use of this facility, one of the following functions that are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) implemented in the module can be called after doing::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) #include <linux/dns_resolver.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) int dns_query(const char *type, const char *name, size_t namelen,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) const char *options, char **_result, time_t *_expiry);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) This is the basic access function. It looks for a cached DNS query and if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) it doesn't find it, it upcalls to userspace to make a new DNS query, which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) may then be cached. The key description is constructed as a string of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) form::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) [<type>:]<name>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) where <type> optionally specifies the particular upcall program to invoke,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) and thus the type of query to do, and <name> specifies the string to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) looked up. The default query type is a straight hostname to IP address
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) set lookup.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) The name parameter is not required to be a NUL-terminated string, and its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) length should be given by the namelen argument.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) The options parameter may be NULL or it may be a set of options
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) appropriate to the query type.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) The return value is a string appropriate to the query type. For instance,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) for the default query type it is just a list of comma-separated IPv4 and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) IPv6 addresses. The caller must free the result.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) The length of the result string is returned on success, and a negative
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) error code is returned otherwise. -EKEYREJECTED will be returned if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) DNS lookup failed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) If _expiry is non-NULL, the expiry time (TTL) of the result will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) returned also.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) The kernel maintains an internal keyring in which it caches looked up keys.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) This can be cleared by any process that has the CAP_SYS_ADMIN capability by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) the use of KEYCTL_KEYRING_CLEAR on the keyring ID.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) Reading DNS Keys from Userspace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) ===============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) Keys of dns_resolver type can be read from userspace using keyctl_read() or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) "keyctl read/print/pipe".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) Mechanism
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) =========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) The dnsresolver module registers a key type called "dns_resolver". Keys of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) this type are used to transport and cache DNS lookup results from userspace.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) When dns_query() is invoked, it calls request_key() to search the local
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) keyrings for a cached DNS result. If that fails to find one, it upcalls to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) userspace to get a new result.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) Upcalls to userspace are made through the request_key() upcall vector, and are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) directed by means of configuration lines in /etc/request-key.conf that tell
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) /sbin/request-key what program to run to instantiate the key.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) The upcall handler program is responsible for querying the DNS, processing the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) result into a form suitable for passing to the keyctl_instantiate_key()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) routine. This then passes the data to dns_resolver_instantiate() which strips
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) off and processes any options included in the data, and then attaches the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) remainder of the string to the key as its payload.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) The upcall handler program should set the expiry time on the key to that of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) lowest TTL of all the records it has extracted a result from. This means that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) the key will be discarded and recreated when the data it holds has expired.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) dns_query() returns a copy of the value attached to the key, or an error if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) that is indicated instead.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) See <file:Documentation/security/keys/request-key.rst> for further
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) information about request-key function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) Debugging
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) =========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) Debugging messages can be turned on dynamically by writing a 1 into the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) following file::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) /sys/module/dnsresolver/parameters/debug
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags