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