bsd/net/network_agent.h

   1 /*
   2  * Copyright (c) 2014-2017 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. The rights granted to you under the License
  10  * may not be used to create, or enable the creation or redistribution of,
  11  * unlawful or unlicensed copies of an Apple operating system, or to
  12  * circumvent, violate, or enable the circumvention or violation of, any
  13  * terms of an Apple operating system software license agreement.
  14  *
  15  * Please obtain a copy of the License at
  16  * http://www.opensource.apple.com/apsl/ and read it before using this file.
  17  *
  18  * The Original Code and all software distributed under the License are
  19  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  20  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  21  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  22  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  23  * Please see the License for the specific language governing rights and
  24  * limitations under the License.
  25  *
  26  * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  27  */
  28
  29 #ifndef _NETAGENT_H_
  30 #define _NETAGENT_H_
  31 #include <net/net_kev.h>
  32
  33 #ifdef PRIVATE
  34
  35 #include <netinet/in.h>
  36 #include <sys/socket.h>
  37
  38 #ifdef BSD_KERNEL_PRIVATE
  39 #include <stdbool.h>
  40
  41 errno_t netagent_init(void);
  42 #endif
  43 /*
  44  * Name registered by the Network Agent kernel control
  45  */
  46 #define NETAGENT_CONTROL_NAME "com.apple.net.netagent"
  47
  48 struct netagent_message_header {
  49         u_int8_t                message_type;
  50         u_int8_t                message_flags;
  51         u_int32_t               message_id;
  52         u_int32_t               message_error;
  53         u_int32_t               message_payload_length;
  54 };
  55
  56 struct netagent_trigger_message {
  57         u_int32_t               trigger_flags;
  58         pid_t                   trigger_pid;
  59         uuid_t                  trigger_proc_uuid;
  60 };
  61
  62 struct netagent_client_message {
  63         uuid_t                  client_id;
  64 };
  65
  66 struct netagent_assign_nexus_message {
  67         uuid_t                  assign_client_id;
  68         u_int8_t                assign_necp_results[0];
  69 };
  70
  71 #define NETAGENT_MESSAGE_TYPE_REGISTER                  1       // Pass netagent to set, no return value
  72 #define NETAGENT_MESSAGE_TYPE_UNREGISTER                2       // No value, no return value
  73 #define NETAGENT_MESSAGE_TYPE_UPDATE                    3       // Pass netagent to update, no return value
  74 #define NETAGENT_MESSAGE_TYPE_GET                               4       // No value, return netagent
  75 #define NETAGENT_MESSAGE_TYPE_TRIGGER                   5       // Kernel initiated, no reply expected
  76 #define NETAGENT_MESSAGE_TYPE_ASSERT                    6       // Deprecated
  77 #define NETAGENT_MESSAGE_TYPE_UNASSERT                  7       // Deprecated
  78 #define NETAGENT_MESSAGE_TYPE_TRIGGER_ASSERT    8       // Kernel initiated, no reply expected
  79 #define NETAGENT_MESSAGE_TYPE_TRIGGER_UNASSERT  9       // Kernel initiated, no reply expected
  80 #define NETAGENT_MESSAGE_TYPE_REQUEST_NEXUS             10      // Kernel initiated, struct netagent_client_message
  81 #define NETAGENT_MESSAGE_TYPE_ASSIGN_NEXUS              11      // Pass struct netagent_assign_nexus_message
  82 #define NETAGENT_MESSAGE_TYPE_CLOSE_NEXUS               12      // Kernel initiated, struct netagent_client_message
  83 #define NETAGENT_MESSAGE_TYPE_CLIENT_TRIGGER    13      // Kernel initiated, struct netagent_client_message
  84 #define NETAGENT_MESSAGE_TYPE_CLIENT_ASSERT             14      // Kernel initiated, struct netagent_client_message
  85 #define NETAGENT_MESSAGE_TYPE_CLIENT_UNASSERT   15      // Kernel initiated, struct netagent_client_message
  86
  87 #define NETAGENT_OPTION_TYPE_REGISTER                   NETAGENT_MESSAGE_TYPE_REGISTER          // Pass netagent to set, no return value
  88 #define NETAGENT_OPTION_TYPE_UNREGISTER                 NETAGENT_MESSAGE_TYPE_UNREGISTER        // No value, no return value
  89 #define NETAGENT_OPTION_TYPE_UPDATE                             NETAGENT_MESSAGE_TYPE_UPDATE            // Pass netagent to update, no return value
  90 #define NETAGENT_OPTION_TYPE_ASSIGN_NEXUS               NETAGENT_MESSAGE_TYPE_ASSIGN_NEXUS      // Pass struct netagent_assign_nexus_message
  91 #define NETAGENT_OPTION_TYPE_USE_COUNT                  16                                                                      // Pass use count to set, get current use count
  92 #define NETAGENT_MESSAGE_TYPE_ABORT_NEXUS               17      // Kernel private
  93
  94 #define NETAGENT_MESSAGE_FLAGS_RESPONSE                 0x01    // Used for acks, errors, and query responses
  95
  96 #define NETAGENT_MESSAGE_ERROR_NONE                     0
  97 #define NETAGENT_MESSAGE_ERROR_INTERNAL                 1
  98 #define NETAGENT_MESSAGE_ERROR_UNKNOWN_TYPE             2
  99 #define NETAGENT_MESSAGE_ERROR_INVALID_DATA             3
 100 #define NETAGENT_MESSAGE_ERROR_NOT_REGISTERED           4
 101 #define NETAGENT_MESSAGE_ERROR_ALREADY_REGISTERED       5
 102 #define NETAGENT_MESSAGE_ERROR_CANNOT_UPDATE            6
 103 #define NETAGENT_MESSAGE_ERROR_CANNOT_ASSIGN            7
 104
 105 #define NETAGENT_DOMAINSIZE             32
 106 #define NETAGENT_TYPESIZE               32
 107 #define NETAGENT_DESCSIZE               128
 108
 109 #define NETAGENT_MAX_DATA_SIZE  4096
 110
 111 #define NETAGENT_FLAG_REGISTERED                0x0001 // Agent is registered
 112 #define NETAGENT_FLAG_ACTIVE                    0x0002 // Agent is active
 113 #define NETAGENT_FLAG_KERNEL_ACTIVATED          0x0004 // Agent can be activated by kernel activity
 114 #define NETAGENT_FLAG_USER_ACTIVATED            0x0008 // Agent can be activated by system call (netagent_trigger)
 115 #define NETAGENT_FLAG_VOLUNTARY                 0x0010 // Use of agent is optional
 116 #define NETAGENT_FLAG_SPECIFIC_USE_ONLY         0x0020 // Agent should only be used and activated when specifically required
 117 #define NETAGENT_FLAG_NETWORK_PROVIDER          0x0040 // Agent provides network access
 118 #define NETAGENT_FLAG_NEXUS_PROVIDER            0x0080 // Agent provides a skywalk nexus
 119 #define NETAGENT_FLAG_SUPPORTS_BROWSE           0x0100 // Assertions will cause agent to fill in browse endpoints
 120 #define NETAGENT_FLAG_REQUIRES_ASSERT           0x0200 // Assertions are expected to be taken against this agent
 121 #define NETAGENT_FLAG_NEXUS_LISTENER            0x0400 // Nexus supports listeners
 122 #define NETAGENT_FLAG_UPDATE_IMMEDIATELY        0x0800 // Updates the clients without waiting for a leeway
 123 #define NETAGENT_FLAG_CUSTOM_ETHER_NEXUS        0x2000 // Agent provides a custom ethertype nexus
 124 #define NETAGENT_FLAG_CUSTOM_IP_NEXUS           0x4000 // Agent provides a custom IP nexus
 125 #define NETAGENT_FLAG_INTERPOSE_NEXUS           0x8000 // Agent provides an interpose nexus
 126 #define NETAGENT_FLAG_SUPPORTS_RESOLVE          0x10000 // Assertions will cause agent to fill in resolved endpoints
 127
 128 #define NETAGENT_NEXUS_MAX_REQUEST_TYPES                        16
 129 #define NETAGENT_NEXUS_MAX_RESOLUTION_TYPE_PAIRS        16
 130
 131 #define NETAGENT_NEXUS_FRAME_TYPE_UNKNOWN               0
 132 #define NETAGENT_NEXUS_FRAME_TYPE_LINK                  1
 133 #define NETAGENT_NEXUS_FRAME_TYPE_INTERNET              2
 134 #define NETAGENT_NEXUS_FRAME_TYPE_TRANSPORT             3
 135 #define NETAGENT_NEXUS_FRAME_TYPE_APPLICATION   4
 136
 137 #define NETAGENT_NEXUS_ENDPOINT_TYPE_ADDRESS    1
 138 #define NETAGENT_NEXUS_ENDPOINT_TYPE_HOST               2
 139 #define NETAGENT_NEXUS_ENDPOINT_TYPE_BONJOUR    3
 140 #define NETAGENT_NEXUS_ENDPOINT_TYPE_SRV        5
 141
 142 #define NETAGENT_NEXUS_FLAG_SUPPORTS_USER_PACKET_POOL   0x1
 143 #define NETAGENT_NEXUS_FLAG_ASSERT_UNSUPPORTED                  0x2 // No calls to assert the agent are required
 144 #define NETAGENT_NEXUS_FLAG_SHOULD_USE_EVENT_RING       0x4 // indicates that nexus agent should use event rings
 145
 146 struct netagent_nexus {
 147         u_int32_t       frame_type;
 148         u_int32_t       endpoint_assignment_type;
 149         u_int32_t       endpoint_request_types[NETAGENT_NEXUS_MAX_REQUEST_TYPES];
 150         u_int32_t       endpoint_resolution_type_pairs[NETAGENT_NEXUS_MAX_RESOLUTION_TYPE_PAIRS * 2];
 151         u_int32_t       nexus_flags;
 152 };
 153
 154 #define NETAGENT_TRIGGER_FLAG_USER              0x0001  // Userspace triggered agent
 155 #define NETAGENT_TRIGGER_FLAG_KERNEL            0x0002  // Kernel triggered agent
 156
 157 struct kev_netagent_data {
 158         uuid_t          netagent_uuid;
 159 };
 160
 161 // To be used with kernel control socket
 162 struct netagent {
 163         uuid_t          netagent_uuid;
 164         char            netagent_domain[NETAGENT_DOMAINSIZE];
 165         char            netagent_type[NETAGENT_TYPESIZE];
 166         char            netagent_desc[NETAGENT_DESCSIZE];
 167         u_int32_t       netagent_flags;
 168         u_int32_t       netagent_data_size;
 169         u_int8_t        netagent_data[0];
 170 };
 171
 172 // To be used with SIOCGAGENTDATA
 173 struct netagent_req {
 174         uuid_t          netagent_uuid;
 175         char            netagent_domain[NETAGENT_DOMAINSIZE];
 176         char            netagent_type[NETAGENT_TYPESIZE];
 177         char            netagent_desc[NETAGENT_DESCSIZE];
 178         u_int32_t       netagent_flags;
 179         u_int32_t       netagent_data_size;
 180         u_int8_t        *netagent_data;
 181 };
 182
 183 // To be used with SIOCGAGENTLIST
 184 struct netagentlist_req {
 185         u_int32_t       data_size;
 186         u_int8_t        *data;
 187 };
 188 #ifdef BSD_KERNEL_PRIVATE
 189 int netagent_ioctl(u_long cmd, caddr_t data);
 190
 191 struct netagent_req32 {
 192         uuid_t          netagent_uuid;
 193         char            netagent_domain[NETAGENT_DOMAINSIZE];
 194         char            netagent_type[NETAGENT_TYPESIZE];
 195         char            netagent_desc[NETAGENT_DESCSIZE];
 196         u_int32_t       netagent_flags;
 197         u_int32_t       netagent_data_size;
 198         user32_addr_t   netagent_data;
 199 };
 200 struct netagent_req64 {
 201         uuid_t          netagent_uuid;
 202         char            netagent_domain[NETAGENT_DOMAINSIZE];
 203         char            netagent_type[NETAGENT_TYPESIZE];
 204         char            netagent_desc[NETAGENT_DESCSIZE];
 205         u_int32_t       netagent_flags;
 206         u_int32_t       netagent_data_size;
 207         user64_addr_t   netagent_data __attribute__((aligned(8)));
 208 };
 209 struct netagentlist_req32 {
 210         u_int32_t       data_size;
 211         user32_addr_t   data;
 212 };
 213 struct netagentlist_req64 {
 214         u_int32_t       data_size;
 215         user64_addr_t   data __attribute__((aligned(8)));
 216 };
 217
 218 struct necp_client_agent_parameters;
 219
 220 // Kernel accessors
 221 extern void netagent_post_updated_interfaces(uuid_t uuid); // To be called from interface ioctls
 222
 223 extern u_int32_t netagent_get_flags(uuid_t uuid);
 224
 225 extern errno_t netagent_set_flags(uuid_t uuid, u_int32_t flags);
 226
 227 extern u_int32_t netagent_get_generation(uuid_t uuid);
 228
 229 extern bool netagent_get_agent_domain_and_type(uuid_t uuid, char *domain, char *type);
 230
 231 extern int netagent_kernel_trigger(uuid_t uuid);
 232
 233 extern int netagent_client_message(uuid_t agent_uuid, uuid_t necp_client_uuid, pid_t pid, void *handle, u_int8_t message_type);
 234
 235 extern int netagent_client_message_with_params(uuid_t agent_uuid,
 236     uuid_t necp_client_uuid,
 237     pid_t pid,
 238     void *handle,
 239     u_int8_t message_type,
 240     struct necp_client_agent_parameters *parameters,
 241     void **assigned_results,
 242     size_t *assigned_results_length);
 243
 244 extern int netagent_copyout(uuid_t uuid, user_addr_t user_addr, u_int32_t user_size);
 245
 246
 247 // Kernel agent management
 248
 249 typedef void * netagent_session_t;
 250
 251 struct netagent_nexus_agent {
 252         struct netagent                         agent;
 253         struct netagent_nexus           nexus_data;
 254 };
 255
 256 #define NETAGENT_EVENT_TRIGGER                                  NETAGENT_MESSAGE_TYPE_CLIENT_TRIGGER
 257 #define NETAGENT_EVENT_ASSERT                                   NETAGENT_MESSAGE_TYPE_CLIENT_ASSERT
 258 #define NETAGENT_EVENT_UNASSERT                                 NETAGENT_MESSAGE_TYPE_CLIENT_UNASSERT
 259 #define NETAGENT_EVENT_NEXUS_FLOW_INSERT                        NETAGENT_MESSAGE_TYPE_REQUEST_NEXUS
 260 #define NETAGENT_EVENT_NEXUS_FLOW_REMOVE                        NETAGENT_MESSAGE_TYPE_CLOSE_NEXUS
 261 #define NETAGENT_EVENT_NEXUS_FLOW_ABORT                         NETAGENT_MESSAGE_TYPE_ABORT_NEXUS
 262
 263 typedef errno_t (*netagent_event_f)(u_int8_t event, uuid_t necp_client_uuid, pid_t pid, void *necp_handle, void *context, struct necp_client_agent_parameters *parameters, void **assigned_results, size_t *assigned_results_length);
 264
 265 extern netagent_session_t netagent_create(netagent_event_f event_handler, void *handle);
 266
 267 extern void netagent_destroy(netagent_session_t session);
 268
 269 extern errno_t netagent_register(netagent_session_t session, struct netagent *agent);
 270
 271 extern errno_t netagent_update(netagent_session_t session, struct netagent *agent);
 272
 273 extern errno_t netagent_unregister(netagent_session_t session);
 274
 275 extern errno_t netagent_assign_nexus(netagent_session_t _session,
 276     uuid_t necp_client_uuid,
 277     void *assign_message,
 278     size_t assigned_results_length);                                                                      // Length of assigned_results_length
 279
 280 extern errno_t netagent_update_flow_protoctl_event(netagent_session_t _session,
 281     uuid_t client_id,
 282     uint32_t protoctl_event_code,
 283     uint32_t protoctl_event_val,
 284     uint32_t protoctl_event_tcp_seq_number);
 285
 286 extern int netagent_use(uuid_t agent_uuid, uint64_t *out_use_count);
 287
 288 #endif /* BSD_KERNEL_PRIVATE */
 289
 290 #ifndef KERNEL
 291 extern int netagent_trigger(uuid_t agent_uuid, size_t agent_uuidlen);
 292 #endif /* !KERNEL */
 293
 294 #endif /* PRIVATE */
 295
 296 #endif /* _NETAGENT_H_ */