| 1 |
/* SPDX-License-Identifier: LGPL-2.1-or-later */ |
| 2 |
|
| 3 |
#include "varlink-io.systemd.Resolve.Hook.h" |
| 4 |
|
| 5 |
/* We want to reuse the ResourceKey structure from the io.systemd.Resolve interface, hence import it here */ |
| 6 |
#include "varlink-io.systemd.Resolve.h" |
| 7 |
|
| 8 |
static SD_VARLINK_DEFINE_STRUCT_TYPE( |
| 9 |
Answer, |
| 10 |
SD_VARLINK_FIELD_COMMENT("A resource record that shall be looked up. Note that this field is (currently) mostly " |
| 11 |
"decoration, useful for debugging, and may be omitted. The data actually used is encoded in the " |
| 12 |
"'raw' field."), |
| 13 |
SD_VARLINK_DEFINE_FIELD_BY_TYPE(rr, ResourceRecord, SD_VARLINK_NULLABLE), |
| 14 |
SD_VARLINK_FIELD_COMMENT("A resource record encoded in DNS wire format, in turn encoded in Base64. This is the actual data " |
| 15 |
"returned to the application, and should carry the same information as the 'rr' field, just in a " |
| 16 |
"different encoding."), |
| 17 |
SD_VARLINK_DEFINE_FIELD(raw, SD_VARLINK_STRING, 0)); |
| 18 |
|
| 19 |
static SD_VARLINK_DEFINE_STRUCT_TYPE( |
| 20 |
Question, |
| 21 |
SD_VARLINK_FIELD_COMMENT("A resource record key that shall be looked up."), |
| 22 |
SD_VARLINK_DEFINE_FIELD_BY_TYPE(key, ResourceKey, 0)); |
| 23 |
|
| 24 |
static SD_VARLINK_DEFINE_METHOD_FULL( |
| 25 |
QueryFilter, |
| 26 |
SD_VARLINK_SUPPORTS_MORE, |
| 27 |
SD_VARLINK_FIELD_COMMENT("A list of domains this hook is interested in. Lookups for domains not listed here will not be " |
| 28 |
"passed to the Hook via ResolveRecord(). If this field is not set, requests for all domains " |
| 29 |
"will be passed to the hook. Note that this applies recursively, i.e. a domain of a lookup is " |
| 30 |
"considered matching the listed domains both if it exactly matches it, and in case only a suffix " |
| 31 |
"of it matches it. If this is set to an empty array the hook is disabled."), |
| 32 |
SD_VARLINK_DEFINE_OUTPUT(filterDomains, SD_VARLINK_STRING, SD_VARLINK_NULLABLE|SD_VARLINK_ARRAY), |
| 33 |
SD_VARLINK_FIELD_COMMENT("Require the specified number of labels or more in a domain for the hook to be considered."), |
| 34 |
SD_VARLINK_DEFINE_OUTPUT(filterLabelsMin, SD_VARLINK_INT, SD_VARLINK_NULLABLE), |
| 35 |
SD_VARLINK_FIELD_COMMENT("Require the specified number of labels or less in a domain for the hook to be considered."), |
| 36 |
SD_VARLINK_DEFINE_OUTPUT(filterLabelsMax, SD_VARLINK_INT, SD_VARLINK_NULLABLE)); |
| 37 |
|
| 38 |
static SD_VARLINK_DEFINE_METHOD( |
| 39 |
ResolveRecord, |
| 40 |
SD_VARLINK_FIELD_COMMENT("The question being looked up, i.e. a combination of resource record keys. Note that unlike DNS " |
| 41 |
"queries on the wire these lookups can carry multiple key requests, albeit closely related ones. " |
| 42 |
"Specifically, lookups for A+AAAA for the the same hostname are submitted as one question, as " |
| 43 |
"are lookups for TXT+SRV when doing DNS-SD resolution. Moreover, when looking up resources with " |
| 44 |
"non-ASCII characters, they are placed together in a single question, once with labels encoded in " |
| 45 |
"UTF-8, and once in IDNA. Hook implementations must be able to deal with these and other similar " |
| 46 |
"combinations of resource key requests, and reply with all matching answers at once, or fail them " |
| 47 |
"as one. Partial success/failure combinations are not supported."), |
| 48 |
SD_VARLINK_DEFINE_INPUT_BY_TYPE(question, Question, SD_VARLINK_ARRAY), |
| 49 |
SD_VARLINK_FIELD_COMMENT("A DNS response code. If a hook sets this return parameter further processing of the lookup via " |
| 50 |
"regular protocols such as DNS, LLMNR, mDNS is skipped, and the return code returned immediately. " |
| 51 |
"In other words, if a hook intends to let the request pass to normal resolution, it should not " |
| 52 |
"set this return parameter."), |
| 53 |
SD_VARLINK_DEFINE_OUTPUT(rcode, SD_VARLINK_INT, SD_VARLINK_NULLABLE), |
| 54 |
SD_VARLINK_FIELD_COMMENT("An answer for a lookup, i.e. a combination of resource records, matching the request. This " |
| 55 |
"should only be set when the 'rcode' parameter is returned as 0 (SUCCESS)."), |
| 56 |
SD_VARLINK_DEFINE_OUTPUT_BY_TYPE(answer, Answer, SD_VARLINK_ARRAY|SD_VARLINK_NULLABLE)); |
| 57 |
|
| 58 |
SD_VARLINK_DEFINE_INTERFACE( |
| 59 |
io_systemd_Resolve_Hook, |
| 60 |
"io.systemd.Resolve.Hook", |
| 61 |
SD_VARLINK_INTERFACE_COMMENT("Generic interface for implementing a domain name resolution hook."), |
| 62 |
SD_VARLINK_SYMBOL_COMMENT("Encapsulates a positive lookup answer"), |
| 63 |
&vl_type_Answer, |
| 64 |
SD_VARLINK_SYMBOL_COMMENT("Encapsulates a lookup question"), |
| 65 |
&vl_type_Question, |
| 66 |
SD_VARLINK_SYMBOL_COMMENT("Encapsulates the class/type/name part of a DNS resource record."), |
| 67 |
&vl_type_ResourceKey, |
| 68 |
SD_VARLINK_SYMBOL_COMMENT("Encapsulates a DNS resource record."), |
| 69 |
&vl_type_ResourceRecord, |
| 70 |
SD_VARLINK_SYMBOL_COMMENT("Returns filter parameters for this hook. A hook service can implement this to reduce lookup " |
| 71 |
"requests, by enabling itself only for certain domains or certain numbers of labels in the name. " |
| 72 |
"It's recommended to implement this to reduce the number of redundant calls to each hook. Note " |
| 73 |
"that this is advisory only, and implementing services must be able to gracefully handle lookup " |
| 74 |
"requests that do not match this filter. This call is usually made with the 'more' flag set, in " |
| 75 |
"which case the connection is left open after the first reply, and the implementing hook " |
| 76 |
"services can send updates to the filter at any time. Whenever a further reply is sent the " |
| 77 |
"filter configured therein fully replaces any previously communicated filter."), |
| 78 |
&vl_method_QueryFilter, |
| 79 |
SD_VARLINK_SYMBOL_COMMENT("Sent whenever a resolution request is made. This typically takes the filter parameters returned " |
| 80 |
"by QueryFilter() into account, but this is not guaranteed."), |
| 81 |
&vl_method_ResolveRecord); |