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