mDNSMacOSX/Private/dns_services.h

   1 /* -*- Mode: C; tab-width: 4 -*-
   2  *
   3  * Copyright (c) 2012-2020 Apple Inc. All rights reserved.
   4  *
   5  *
   6  * @header      Interface to DNSX SPI
   7  *
   8  * @discussion  Describes the functions and data structures
   9  *              that make up the DNSX SPI
  10  */
  11
  12 #ifndef _DNS_SERVICES_H
  13 #define _DNS_SERVICES_H
  14
  15 #include <dispatch/dispatch.h>
  16
  17 #if (defined(__GNUC__) && (__GNUC__ >= 4))
  18 #define DNS_SERVICES_EXPORT __attribute__((visibility("default")))
  19 #else
  20 #define DNS_SERVICES_EXPORT
  21 #endif
  22
  23 // DNSXConnRef: Opaque internal data type
  24 typedef struct _DNSXConnRef_t *DNSXConnRef;
  25
  26 typedef enum
  27 {
  28     kDNSX_NoError                   =  0,
  29     kDNSX_UnknownErr                = -65537,   /* 0xFFFE FFFF */
  30     kDNSX_NoMem                     = -65539,   /* No Memory   */
  31     kDNSX_BadParam                  = -65540,   /* Client passed invalid arg */
  32     kDNSX_Busy                      = -65551,   /* DNS Proxy already in use: incorrect use of SPI by client */
  33     kDNSX_DaemonNotRunning          = -65563    /* Daemon not running */
  34 } DNSXErrorType;
  35
  36 // A max of 5 input interfaces can be processed
  37 #define MaxInputIf 5
  38 #define IfIndex uint64_t
  39 #define kDNSIfindexAny 0
  40
  41 // Enable DNS Proxy with an appropriate parameter defined below
  42 typedef enum
  43 {
  44     kDNSProxyEnable = 1
  45     // Other values reserved for future use
  46 } DNSProxyParameters;
  47
  48 /*********************************************************************************************
  49  *
  50  *  Enable DNS Proxy Functionality
  51  *
  52  *********************************************************************************************/
  53
  54 /* DNSXEnableProxy : Turns ON the DNS Proxy (Details below)
  55  *
  56  * DNSXEnableProxyReply() parameters:
  57  *
  58  * connRef:                  The DNSXConnRef initialized by DNSXEnableProxy().
  59  *
  60  * errCode:                  Will be kDNSX_NoError on success, otherwise will indicate the
  61  *                           failure that occurred.
  62  *
  63  */
  64
  65 typedef void (*DNSXEnableProxyReply)
  66 (
  67     DNSXConnRef           connRef,
  68     DNSXErrorType         errCode
  69 );
  70
  71 /* DNSXEnableProxy
  72  *
  73  * Enables the DNS Proxy functionality which will remain ON until the client explicitly turns it OFF
  74  * by passing the returned DNSXConnRef to DNSXRefDeAlloc(), or the client exits or crashes.
  75  *
  76  * DNSXEnableProxy() Parameters:
  77  *
  78  * connRef:                   A pointer to DNSXConnRef that is initialized to NULL.
  79  *                            If the call succeeds it will be initialized to a non-NULL value.
  80  *                            Client terminates the DNS Proxy by passing this DNSXConnRef to DNSXRefDeAlloc().
  81  *
  82  * proxyparam:                Enable DNS Proxy functionality with parameters that are described in
  83  *                            DNSProxyParameters above.
  84  *
  85  * inIfindexArr[MaxInputIf]:  List of input interfaces from which the DNS queries will be accepted and
  86  *                            forwarded to the output interface specified below. The daemon processes
  87  *                            MaxInputIf entries in the list. For eg. if one has less than MaxInputIfs
  88  *                            values, just initialize the other values to be 0. Note: This field needs to
  89  *                            be initialized by the client.
  90  *
  91  * outIfindex:                Output interface on which the query will be forwarded.
  92  *                            Passing kDNSIfindexAny causes DNS Queries to be sent on the primary interface.
  93  *
  94  *                            Note: It is the responsibility of the client to ensure the input/output interface
  95  *                            indexes are valid.
  96  *
  97  * clientq:                   Queue the client wants to schedule the callBack on (Note: Must not be NULL)
  98  *
  99  * callBack:                  CallBack function for the client that indicates success or failure.
 100  *                            Note: callback may be invoked more than once, For e.g. if enabling DNS Proxy
 101  *                            first succeeds and the daemon possibly crashes sometime later.
 102  *
 103  * return value:              Returns kDNSX_NoError when no error otherwise returns an error code indicating
 104  *                            the error that occurred. Note: A return value of kDNSX_NoError does not mean
 105  *                            that DNS Proxy was successfully enabled. The callBack may asynchronously
 106  *                            return an error (such as kDNSX_DaemonNotRunning)
 107  *
 108  */
 109
 110 DNS_SERVICES_EXPORT
 111 DNSXErrorType DNSXEnableProxy
 112 (
 113     DNSXConnRef              *connRef,
 114     DNSProxyParameters       proxyparam,
 115     IfIndex                  inIfindexArr[MaxInputIf],
 116     IfIndex                  outIfindex,
 117     dispatch_queue_t         clientq,
 118     DNSXEnableProxyReply     callBack
 119  );
 120
 121 typedef uint32_t DNSXProxyFlags;
 122
 123 #define kDNSXProxyFlagNull               0         // No flags.
 124 #define kDNSXProxyFlagForceAAAASynthesis (1U << 1) // Force AAAA synthesis during DNS64.
 125
 126 /* DNSXEnableProxy64
 127  *
 128  * Enables the DNS Proxy functionality which will remain ON until the client explicitly turns it OFF
 129  * by passing the returned DNSXConnRef to DNSXRefDeAlloc(), or the client exits or crashes.
 130  *
 131  * DNSXEnableProxy64() Parameters:
 132  *
 133  * connRef:                   A pointer to DNSXConnRef that is initialized to NULL.
 134  *                            If the call succeeds it will be initialized to a non-NULL value.
 135  *                            Client terminates the DNS Proxy by passing this DNSXConnRef to DNSXRefDeAlloc().
 136  *
 137  * proxyparam:                Enable DNS Proxy functionality with parameters that are described in
 138  *                            DNSProxyParameters above.
 139  *
 140  * inIfindexArr[MaxInputIf]:  List of input interfaces from which the DNS queries will be accepted and
 141  *                            forwarded to the output interface specified below. The daemon processes
 142  *                            MaxInputIf entries in the list. For eg. if one has less than MaxInputIfs
 143  *                            values, just initialize the other values to be 0. Note: This field needs to
 144  *                            be initialized by the client.
 145  *
 146  * outIfindex:                Output interface on which the query will be forwarded.
 147  *                            Passing kDNSIfindexAny causes DNS Queries to be sent on the primary interface.
 148  *
 149  *                            Note: It is the responsibility of the client to ensure the input/output interface
 150  *                            indexes are valid.
 151  *
 152  * ipv6Prefix:                IPv6 prefix to use for DNS64.
 153  *
 154  * ipv6PrefixBitLength:       Bit length of IPv6 prefix to use for DNS64.
 155  *
 156  * flags:                     Flags to specify additional behavioral aspects of the proxy.
 157  *
 158  * clientq:                   Queue the client wants to schedule the callBack on (Note: Must not be NULL)
 159  *
 160  * callBack:                  CallBack function for the client that indicates success or failure.
 161  *                            Note: callback may be invoked more than once, For e.g. if enabling DNS Proxy
 162  *                            first succeeds and the daemon possibly crashes sometime later.
 163  *
 164  * return value:              Returns kDNSX_NoError when no error otherwise returns an error code indicating
 165  *                            the error that occurred. Note: A return value of kDNSX_NoError does not mean
 166  *                            that DNS Proxy was successfully enabled. The callBack may asynchronously
 167  *                            return an error (such as kDNSX_DaemonNotRunning)
 168  *
 169  */
 170
 171 SPI_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0))
 172 DNSXErrorType DNSXEnableProxy64
 173 (
 174     DNSXConnRef              *connRef,
 175     DNSProxyParameters       proxyparam,
 176     IfIndex                  inIfindexArr[MaxInputIf],
 177     IfIndex                  outIfindex,
 178     uint8_t                  ipv6Prefix[16],
 179     int                      ipv6PrefixBitLength,
 180     DNSXProxyFlags           flags,
 181     dispatch_queue_t         clientq,
 182     DNSXEnableProxyReply     callBack
 183 );
 184
 185 /* DNSXRefDeAlloc()
 186  *
 187  * Terminate a connection with the daemon and free memory associated with the DNSXConnRef.
 188  * Used to Disable DNS Proxy on that connection.
 189  *
 190  * connRef:        A DNSXConnRef initialized by any of the DNSX*() calls.
 191  *
 192  */
 193 DNS_SERVICES_EXPORT
 194 void DNSXRefDeAlloc(DNSXConnRef connRef);
 195
 196 #endif