X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_dns_service.h;h=8713a215482d6169d38da4a00a4d47cccfe8efc6;hb=cbd60b5e56aac2d6711e299086383f83357794f8;hp=a6471d6e9b0941964f75dc064978f202c3acb733;hpb=fc34264e662b3b24ff43c585324987a4712a187b;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_dns_service.h b/src/include/gnunet_dns_service.h index a6471d6e9..8713a2154 100644 --- a/src/include/gnunet_dns_service.h +++ b/src/include/gnunet_dns_service.h @@ -1,174 +1,191 @@ /* This file is part of GNUnet - (C) 2010, 2011, 2012 Christian Grothoff (and other contributing authors) + Copyright (C) 2012 GNUnet e.V. - GNUnet is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published - by the Free Software Foundation; either version 2, or (at your - option) any later version. + GNUnet is free software: you can redistribute it and/or modify it + under the terms of the GNU General Public License as published + by the Free Software Foundation, either version 3 of the License, + or (at your option) any later version. GNUnet is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. - - You should have received a copy of the GNU General Public License - along with GNUnet; see the file COPYING. If not, write to the - Free Software Foundation, Inc., 59 Temple Place - Suite 330, - Boston, MA 02111-1307, USA. + Affero General Public License for more details. */ /** - * @file include/gnunet_dns_service.h - * @brief API to access the DNS service. Not finished at all, - * currently only contains the structs for the IPC, which - * don't even belong here (legacy code in transition) - * @author Philipp Toelke - * - * TODO: - * - replace (most?) structs with nice function (prototypes) that take - * the appropriate arguments to pass the data - * - clean up API implementation itself (nicer reconnect, etc.) + * @author Christian Grothoff + * + * @file + * API to access the DNS service. + * + * @defgroup dns DNS service + * + * @see [Documentation](https://gnunet.org/gnunet-service-dns) + * + * @{ */ #ifndef GNUNET_DNS_SERVICE_H #define GNUNET_DNS_SERVICE_H -#include "gnunet_common.h" #include "gnunet_util_lib.h" -GNUNET_NETWORK_STRUCT_BEGIN -struct query_packet -{ - struct GNUNET_MessageHeader hdr; - - /** - * The IP-Address this query was originally sent to - */ - char orig_to[16]; - /** - * The IP-Address this query was originally sent from - */ - char orig_from[16]; - /** - * The UDP-Portthis query was originally sent from - */ - char addrlen; - uint16_t src_port GNUNET_PACKED; - - unsigned char data[1]; /* The DNS-Packet */ -}; +/** + * Opaque DNS handle + */ +struct GNUNET_DNS_Handle; -struct query_packet_list -{ - struct query_packet_list *next GNUNET_PACKED; - struct query_packet_list *prev GNUNET_PACKED; - struct query_packet pkt; -}; +/** + * Handle to identify an individual DNS request. + */ +struct GNUNET_DNS_RequestHandle; -enum GNUNET_DNS_ANSWER_Subtype +/** + * Flags that specify when to call the client's handler. + */ +enum GNUNET_DNS_Flags { - /** - * Answers of this type contain a dns-packet that just has to be transmitted - */ - GNUNET_DNS_ANSWER_TYPE_IP, - - /** - * Answers of this type contain an incomplete dns-packet. The IP-Address - * is all 0s. The addroffset points to it. - */ - GNUNET_DNS_ANSWER_TYPE_SERVICE, - - /** - * Answers of this type contain an incomplete dns-packet as answer to a - * PTR-Query. The resolved name is not allocated. The addroffset points to it. - */ - GNUNET_DNS_ANSWER_TYPE_REV, - - /** - * Answers of this type contains an IP6-Address but traffic to this IP should - * be routed through the GNUNet. - */ - GNUNET_DNS_ANSWER_TYPE_REMOTE_AAAA, - - /** - * Answers of this type contains an IP4-Address but traffic to this IP should - * be routed through the GNUNet. - */ - GNUNET_DNS_ANSWER_TYPE_REMOTE_A -}; -struct GNUNET_vpn_service_descriptor -{ - GNUNET_HashCode peer GNUNET_PACKED; - GNUNET_HashCode service_descriptor GNUNET_PACKED; - uint64_t ports GNUNET_PACKED; - uint32_t service_type GNUNET_PACKED; -}; + /** + * Useless option: never call the client. + */ + GNUNET_DNS_FLAG_NEVER = 0, + + /** + * Set this flag to see all requests first prior to resolution + * (for monitoring). Clients that set this flag must then + * call "GNUNET_DNS_request_forward" when they process a request + * for the first time. Caling "GNUNET_DNS_request_answer" is + * not allowed for MONITOR peers. + */ + GNUNET_DNS_FLAG_REQUEST_MONITOR = 1, + + /** + * This client should be called on requests that have not + * yet been resolved as this client provides a resolution + * service. Note that this does not guarantee that the + * client will see all requests as another client might be + * called first and that client might have already done the + * resolution, in which case other pre-resolution clients + * won't see the request anymore. + */ + GNUNET_DNS_FLAG_PRE_RESOLUTION = 2, + + /** + * This client wants to be called on the results of a DNS resolution + * (either resolved by PRE-RESOLUTION clients or the global DNS). + * The client then has a chance to modify the answer (or cause it to + * be dropped). There is no guarantee that other POST-RESOLUTION + * client's won't modify (or drop) the answer afterwards. + */ + GNUNET_DNS_FLAG_POST_RESOLUTION = 4, + + /** + * Set this flag to see all requests just before they are + * returned to the network. Clients that set this flag must then + * call "GNUNET_DNS_request_forward" when they process a request + * for the last time. Caling "GNUNET_DNS_request_answer" is + * not allowed for MONITOR peers. + */ + GNUNET_DNS_FLAG_RESPONSE_MONITOR = 8 -struct answer_packet -{ - /* General data */ - struct GNUNET_MessageHeader hdr; - enum GNUNET_DNS_ANSWER_Subtype subtype GNUNET_PACKED; - - char from[16]; - char to[16]; - char addrlen; - unsigned dst_port:16 GNUNET_PACKED; - /* -- */ - - /* Data for GNUNET_DNS_ANSWER_TYPE_SERVICE */ - struct GNUNET_vpn_service_descriptor service_descr; - /* -- */ - - /* Data for GNUNET_DNS_ANSWER_TYPE_REV */ - /* The offsett in octets from the beginning of the struct to the field - * in data where the IP-Address has to go. */ - uint16_t addroffset GNUNET_PACKED; - /* -- */ - - /* Data for GNUNET_DNS_ANSWER_TYPE_REMOTE */ - /* either 4 or 16 */ - char addrsize; - unsigned char addr[16]; - /* -- */ - - unsigned char data[1]; }; -struct answer_packet_list -{ - struct answer_packet_list *next GNUNET_PACKED; - struct answer_packet_list *prev GNUNET_PACKED; - struct GNUNET_SERVER_Client *client; - struct answer_packet pkt; -}; -GNUNET_NETWORK_STRUCT_END -struct GNUNET_DNS_Handle; /** - * Connect to the service-dns + * Signature of a function that is called whenever the DNS service + * encounters a DNS request and needs to do something with it. The + * function has then the chance to generate or modify the response by + * calling one of the three "GNUNET_DNS_request_*" continuations. + * + * When a request is intercepted, this function is called first to + * give the client a chance to do the complete address resolution; + * "rdata" will be NULL for this first call for a DNS request, unless + * some other client has already filled in a response. + * + * If multiple clients exist, all of them are called before the global + * DNS. The global DNS is only called if all of the clients' + * functions call GNUNET_DNS_request_forward. Functions that call + * GNUNET_DNS_request_forward will be called again before a final + * response is returned to the application. If any of the clients' + * functions call GNUNET_DNS_request_drop, the response is dropped. + * + * @param cls closure + * @param rh request handle to user for reply + * @param request_length number of bytes in request + * @param request udp payload of the DNS request */ -struct GNUNET_DNS_Handle * -GNUNET_DNS_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, - GNUNET_SCHEDULER_Task cb, - void *cb_cls); +typedef void +(*GNUNET_DNS_RequestHandler)(void *cls, + struct GNUNET_DNS_RequestHandle *rh, + size_t request_length, + const char *request); + +/** + * If a GNUNET_DNS_RequestHandler calls this function, the client + * has no desire to interfer with the request and it should + * continue to be processed normally. + * + * @param rh request that should now be forwarded + */ void -GNUNET_DNS_restart_hijack (struct GNUNET_DNS_Handle *h); +GNUNET_DNS_request_forward (struct GNUNET_DNS_RequestHandle *rh); /** - * FIXME: we should not expost our internal structures like this. - * Just a quick initial hack. + * If a GNUNET_DNS_RequestHandler calls this function, the request is + * to be dropped and no response should be generated. + * + * @param rh request that should now be dropped */ void -GNUNET_DNS_queue_request (struct GNUNET_DNS_Handle *h, - struct query_packet_list *q); +GNUNET_DNS_request_drop (struct GNUNET_DNS_RequestHandle *rh); + +/** + * If a GNUNET_DNS_RequestHandler calls this function, the request is + * supposed to be answered with the data provided to this call (with + * the modifications the function might have made). The reply given + * must always be a valid DNS reply and not a mutated DNS request. + * + * @param rh request that should now be answered + * @param reply_length size of @a reply (uint16_t to force sane size) + * @param reply reply data + */ void -GNUNET_DNS_disconnect (struct GNUNET_DNS_Handle *h); +GNUNET_DNS_request_answer (struct GNUNET_DNS_RequestHandle *rh, + uint16_t reply_length, + const char *reply); + + +/** + * Connect to the service-dns + * + * @param cfg configuration to use + * @param flags when to call @a rh + * @param rh function to call with DNS requests + * @param rh_cls closure to pass to @a rh + * @return DNS handle + */ +struct GNUNET_DNS_Handle * +GNUNET_DNS_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, + enum GNUNET_DNS_Flags flags, + GNUNET_DNS_RequestHandler rh, + void *rh_cls); + + +/** + * Disconnect from the DNS service. + * + * @param dh DNS handle + */ +void +GNUNET_DNS_disconnect (struct GNUNET_DNS_Handle *dh); + #endif + +/** @} */ /* end of group */