1 /* 2 * Copyright (c) 2014-2017, 2023 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 #include <uuid/uuid.h> 38 39 #ifdef BSD_KERNEL_PRIVATE 40 #include <stdbool.h> 41 42 errno_t netagent_init(void); 43 #endif 44 /* 45 * Name registered by the Network Agent kernel control 46 */ 47 #define NETAGENT_CONTROL_NAME "com.apple.net.netagent" 48 49 struct netagent_message_header { 50 u_int8_t message_type; 51 u_int8_t message_flags; 52 u_int32_t message_id; 53 u_int32_t message_error; 54 u_int32_t message_payload_length; 55 }; 56 57 struct netagent_session_message_header { 58 u_int8_t message_type; 59 u_int8_t message_flags; 60 u_int32_t message_id; 61 u_int32_t message_error; 62 uuid_t message_agent_id; 63 u_int32_t message_payload_length; 64 }; 65 66 struct netagent_trigger_message { 67 u_int32_t trigger_flags; 68 pid_t trigger_pid; 69 uuid_t trigger_proc_uuid; 70 }; 71 72 struct netagent_client_message { 73 uuid_t client_id; 74 }; 75 76 struct netagent_client_error_message { 77 uuid_t client_id; 78 int32_t error_code; 79 }; 80 81 struct netagent_client_group_message { 82 uuid_t client_id; 83 u_int8_t group_members[0]; 84 }; 85 86 struct netagent_assign_nexus_message { 87 uuid_t assign_client_id; 88 u_int8_t assign_necp_results[0]; 89 }; 90 91 struct netagent_session_assign_nexus_message { 92 uuid_t agent_id; 93 uuid_t assign_client_id; 94 u_int8_t assign_necp_results[0]; 95 }; 96 97 #define NETAGENT_MESSAGE_TYPE_REGISTER 1 // Pass netagent to set, no return value 98 #define NETAGENT_MESSAGE_TYPE_UNREGISTER 2 // No value, no return value 99 #define NETAGENT_MESSAGE_TYPE_UPDATE 3 // Pass netagent to update, no return value 100 #define NETAGENT_MESSAGE_TYPE_GET 4 // No value, return netagent 101 #define NETAGENT_MESSAGE_TYPE_TRIGGER 5 // Kernel initiated, no reply expected 102 #define NETAGENT_MESSAGE_TYPE_ASSERT 6 // Deprecated 103 #define NETAGENT_MESSAGE_TYPE_UNASSERT 7 // Deprecated 104 #define NETAGENT_MESSAGE_TYPE_TRIGGER_ASSERT 8 // Kernel initiated, no reply expected 105 #define NETAGENT_MESSAGE_TYPE_TRIGGER_UNASSERT 9 // Kernel initiated, no reply expected 106 #define NETAGENT_MESSAGE_TYPE_REQUEST_NEXUS 10 // Kernel initiated, struct netagent_client_message 107 #define NETAGENT_MESSAGE_TYPE_ASSIGN_NEXUS 11 // Pass struct netagent_assign_nexus_message 108 #define NETAGENT_MESSAGE_TYPE_CLOSE_NEXUS 12 // Kernel initiated, struct netagent_client_message 109 #define NETAGENT_MESSAGE_TYPE_CLIENT_TRIGGER 13 // Kernel initiated, struct netagent_client_message 110 #define NETAGENT_MESSAGE_TYPE_CLIENT_ASSERT 14 // Kernel initiated, struct netagent_client_message 111 #define NETAGENT_MESSAGE_TYPE_CLIENT_UNASSERT 15 // Kernel initiated, struct netagent_client_message 112 113 #define NETAGENT_OPTION_TYPE_REGISTER NETAGENT_MESSAGE_TYPE_REGISTER // Pass netagent to set, no return value 114 #define NETAGENT_OPTION_TYPE_UNREGISTER NETAGENT_MESSAGE_TYPE_UNREGISTER // Pass agent uuid in session mode, no return value 115 #define NETAGENT_OPTION_TYPE_UPDATE NETAGENT_MESSAGE_TYPE_UPDATE // Pass netagent to update, no return value 116 #define NETAGENT_OPTION_TYPE_ASSIGN_NEXUS NETAGENT_MESSAGE_TYPE_ASSIGN_NEXUS // Pass struct netagent_assign_nexus_message 117 #define NETAGENT_OPTION_TYPE_USE_COUNT 16 // Pass use count to set, get current use count 118 #define NETAGENT_MESSAGE_TYPE_ABORT_NEXUS 17 // Kernel private 119 #define NETAGENT_MESSAGE_TYPE_ADD_GROUP_MEMBERS 18 // Kernel initiated, struct netagent_client_group_message 120 #define NETAGENT_MESSAGE_TYPE_REMOVE_GROUP_MEMBERS 19 // Kernel initiated, struct netagent_client_group_message 121 #define NETAGENT_MESSAGE_TYPE_ASSIGN_GROUP_MEMBERS 20 // Pass struct netagent_assign_nexus_message 122 #define NETAGENT_OPTION_TYPE_ADD_TOKEN 21 // Set new token bytes 123 #define NETAGENT_OPTION_TYPE_FLUSH_TOKENS 22 // Flush all tokens 124 #define NETAGENT_OPTION_TYPE_TOKEN_COUNT 23 // Get remaining token count (uint32_t) 125 #define NETAGENT_OPTION_TYPE_TOKEN_LOW_WATER 24 // Set/get token low water mark (uint32_t) 126 #define NETAGENT_MESSAGE_TYPE_TOKENS_NEEDED 25 // Kernel intiated, no content 127 #define NETAGENT_MESSAGE_TYPE_CLIENT_ERROR 26 // Kernel intiated, struct netagent_client_error_message 128 #define NETAGENT_OPTION_TYPE_RESET_CLIENT_ERROR 27 // Call to reset client error and counts 129 #define NETAGENT_OPTION_TYPE_ENABLE_SESSION_MODE 28 // Enables registering multiple agents on a single fd "session". Must be set before registering an agent. 130 #define NETAGENT_OPTION_TYPE_UNREGISTER_ALL 29 // Applicable for session mode, unregisters all associated agents. 131 132 #define NETAGENT_MESSAGE_FLAGS_RESPONSE 0x01 // Used for acks, errors, and query responses 133 134 #define NETAGENT_MESSAGE_ERROR_NONE 0 135 #define NETAGENT_MESSAGE_ERROR_INTERNAL 1 136 #define NETAGENT_MESSAGE_ERROR_UNKNOWN_TYPE 2 137 #define NETAGENT_MESSAGE_ERROR_INVALID_DATA 3 138 #define NETAGENT_MESSAGE_ERROR_NOT_REGISTERED 4 139 #define NETAGENT_MESSAGE_ERROR_ALREADY_REGISTERED 5 140 #define NETAGENT_MESSAGE_ERROR_CANNOT_UPDATE 6 141 #define NETAGENT_MESSAGE_ERROR_CANNOT_ASSIGN 7 142 143 #define NETAGENT_DOMAINSIZE 32 144 #define NETAGENT_TYPESIZE 32 145 #define NETAGENT_DESCSIZE 128 146 147 #define NETAGENT_MAX_DATA_SIZE 4096 148 149 #define NETAGENT_MAX_TOKEN_COUNT 256 150 151 152 #define NETAGENT_FLAG_REGISTERED 0x0001 // Agent is registered 153 #define NETAGENT_FLAG_ACTIVE 0x0002 // Agent is active 154 #define NETAGENT_FLAG_KERNEL_ACTIVATED 0x0004 // Agent can be activated by kernel activity 155 #define NETAGENT_FLAG_USER_ACTIVATED 0x0008 // Agent can be activated by system call (netagent_trigger) 156 #define NETAGENT_FLAG_VOLUNTARY 0x0010 // Use of agent is optional 157 #define NETAGENT_FLAG_SPECIFIC_USE_ONLY 0x0020 // Agent should only be used and activated when specifically required 158 #define NETAGENT_FLAG_NETWORK_PROVIDER 0x0040 // Agent provides network access 159 #define NETAGENT_FLAG_NEXUS_PROVIDER 0x0080 // Agent provides a skywalk nexus 160 #define NETAGENT_FLAG_SUPPORTS_BROWSE 0x0100 // Assertions will cause agent to fill in browse endpoints 161 #define NETAGENT_FLAG_REQUIRES_ASSERT 0x0200 // Assertions are expected to be taken against this agent 162 #define NETAGENT_FLAG_NEXUS_LISTENER 0x0400 // Nexus supports listeners 163 #define NETAGENT_FLAG_UPDATE_IMMEDIATELY 0x0800 // Updates the clients without waiting for a leeway 164 #define NETAGENT_FLAG_CUSTOM_ETHER_NEXUS 0x2000 // Agent provides a custom ethertype nexus 165 #define NETAGENT_FLAG_CUSTOM_IP_NEXUS 0x4000 // Agent provides a custom IP nexus 166 #define NETAGENT_FLAG_INTERPOSE_NEXUS 0x8000 // Agent provides an interpose nexus 167 #define NETAGENT_FLAG_SUPPORTS_RESOLVE 0x10000 // Assertions will cause agent to fill in resolved endpoints 168 #define NETAGENT_FLAG_SUPPORTS_GROUPS 0x20000 // Group actions can be performed 169 170 #define NETAGENT_NEXUS_MAX_REQUEST_TYPES 16 171 #define NETAGENT_NEXUS_MAX_RESOLUTION_TYPE_PAIRS 15 172 173 #define NETAGENT_NEXUS_FRAME_TYPE_UNKNOWN 0 174 #define NETAGENT_NEXUS_FRAME_TYPE_LINK 1 175 #define NETAGENT_NEXUS_FRAME_TYPE_INTERNET 2 176 #define NETAGENT_NEXUS_FRAME_TYPE_TRANSPORT 3 177 #define NETAGENT_NEXUS_FRAME_TYPE_APPLICATION 4 178 179 #define NETAGENT_NEXUS_ENDPOINT_TYPE_ADDRESS 1 180 #define NETAGENT_NEXUS_ENDPOINT_TYPE_HOST 2 181 #define NETAGENT_NEXUS_ENDPOINT_TYPE_BONJOUR 3 182 #define NETAGENT_NEXUS_ENDPOINT_TYPE_SRV 5 183 184 #define NETAGENT_NEXUS_FLAG_SUPPORTS_USER_PACKET_POOL 0x1 185 #define NETAGENT_NEXUS_FLAG_ASSERT_UNSUPPORTED 0x2 // No calls to assert the agent are required 186 #define NETAGENT_NEXUS_FLAG_SHOULD_USE_EVENT_RING 0x4 // indicates that nexus agent should use event rings 187 #define NETAGENT_NEXUS_FLAG_COMPLETE_RESOLVE_ON_CONNECT 0x8 // Indicates resolver should mark itself as complete once it has a connected child 188 #define NETAGENT_NEXUS_FLAG_CANCEL_REMOVED_ENDPOINTS 0x10 // Indicates resolver should cancel connection attempts to endpoints removed from resolved endpoints list 189 190 struct netagent_nexus { 191 u_int32_t frame_type; 192 u_int32_t endpoint_assignment_type; 193 u_int32_t endpoint_request_types[NETAGENT_NEXUS_MAX_REQUEST_TYPES]; 194 u_int32_t endpoint_resolution_type_pairs[NETAGENT_NEXUS_MAX_RESOLUTION_TYPE_PAIRS * 2]; 195 u_int32_t nexus_max_buf_size; 196 u_int32_t reserved; 197 u_int32_t nexus_flags; 198 }; 199 200 #define NETAGENT_NEXUS_HAS_MAX_BUF_SIZE 1 // struct netagent_nexus includes nexus_max_buf_size 201 202 #define NETAGENT_TRIGGER_FLAG_USER 0x0001 // Userspace triggered agent 203 #define NETAGENT_TRIGGER_FLAG_KERNEL 0x0002 // Kernel triggered agent 204 205 struct kev_netagent_data { 206 uuid_t netagent_uuid; 207 }; 208 209 // To be used with kernel control socket 210 struct netagent { 211 uuid_t netagent_uuid; 212 char netagent_domain[NETAGENT_DOMAINSIZE]; 213 char netagent_type[NETAGENT_TYPESIZE]; 214 char netagent_desc[NETAGENT_DESCSIZE]; 215 u_int32_t netagent_flags; 216 u_int32_t netagent_data_size; 217 u_int8_t netagent_data[0]; 218 }; 219 220 // To be used with SIOCGAGENTDATA 221 struct netagent_req { 222 uuid_t netagent_uuid; 223 char netagent_domain[NETAGENT_DOMAINSIZE]; 224 char netagent_type[NETAGENT_TYPESIZE]; 225 char netagent_desc[NETAGENT_DESCSIZE]; 226 u_int32_t netagent_flags; 227 u_int32_t netagent_data_size; 228 u_int8_t *netagent_data; 229 }; 230 231 // To be used with SIOCGAGENTLIST 232 struct netagentlist_req { 233 u_int32_t data_size; 234 u_int8_t *data; 235 }; 236 #ifdef BSD_KERNEL_PRIVATE 237 int netagent_ioctl(u_long cmd, caddr_t __sized_by(IOCPARM_LEN(cmd)) data); 238 239 struct netagent_req32 { 240 uuid_t netagent_uuid; 241 char netagent_domain[NETAGENT_DOMAINSIZE]; 242 char netagent_type[NETAGENT_TYPESIZE]; 243 char netagent_desc[NETAGENT_DESCSIZE]; 244 u_int32_t netagent_flags; 245 u_int32_t netagent_data_size; 246 user32_addr_t netagent_data; 247 }; 248 struct netagent_req64 { 249 uuid_t netagent_uuid; 250 char netagent_domain[NETAGENT_DOMAINSIZE]; 251 char netagent_type[NETAGENT_TYPESIZE]; 252 char netagent_desc[NETAGENT_DESCSIZE]; 253 u_int32_t netagent_flags; 254 u_int32_t netagent_data_size; 255 user64_addr_t netagent_data __attribute__((aligned(8))); 256 }; 257 struct netagentlist_req32 { 258 u_int32_t data_size; 259 user32_addr_t data; 260 }; 261 struct netagentlist_req64 { 262 u_int32_t data_size; 263 user64_addr_t data __attribute__((aligned(8))); 264 }; 265 266 struct necp_client_agent_parameters; 267 268 // Kernel accessors 269 extern void netagent_post_updated_interfaces(uuid_t uuid); // To be called from interface ioctls 270 271 extern u_int32_t netagent_get_flags(uuid_t uuid); 272 273 extern errno_t netagent_set_flags(uuid_t uuid, u_int32_t flags); 274 275 extern u_int32_t netagent_get_generation(uuid_t uuid); 276 277 extern bool netagent_get_agent_domain_and_type(uuid_t uuid, char *domain __sized_by(NETAGENT_DOMAINSIZE), char *type __sized_by(NETAGENT_TYPESIZE)); 278 279 extern int netagent_kernel_trigger(uuid_t uuid); 280 281 extern int netagent_client_message(uuid_t agent_uuid, uuid_t necp_client_uuid, pid_t pid, void *handle, u_int8_t message_type); 282 283 extern int netagent_client_message_with_params(uuid_t agent_uuid, 284 uuid_t necp_client_uuid, 285 pid_t pid, 286 void *handle, 287 u_int8_t message_type, 288 struct necp_client_agent_parameters *parameters, 289 void * __sized_by(*assigned_results_length) * assigned_results, 290 size_t *assigned_results_length); 291 292 extern int netagent_copyout(uuid_t uuid, user_addr_t user_addr, u_int32_t user_size); 293 294 extern int netagent_acquire_token(uuid_t uuid, user_addr_t user_addr, u_int32_t user_size, int *retval); 295 296 297 // Kernel agent management 298 299 typedef void * netagent_session_t; 300 301 struct netagent_nexus_agent { 302 struct netagent agent; 303 struct netagent_nexus nexus_data; 304 }; 305 306 #define NETAGENT_EVENT_TRIGGER NETAGENT_MESSAGE_TYPE_CLIENT_TRIGGER 307 #define NETAGENT_EVENT_ASSERT NETAGENT_MESSAGE_TYPE_CLIENT_ASSERT 308 #define NETAGENT_EVENT_UNASSERT NETAGENT_MESSAGE_TYPE_CLIENT_UNASSERT 309 #define NETAGENT_EVENT_NEXUS_FLOW_INSERT NETAGENT_MESSAGE_TYPE_REQUEST_NEXUS 310 #define NETAGENT_EVENT_NEXUS_FLOW_REMOVE NETAGENT_MESSAGE_TYPE_CLOSE_NEXUS 311 #define NETAGENT_EVENT_NEXUS_FLOW_ABORT NETAGENT_MESSAGE_TYPE_ABORT_NEXUS 312 313 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 * __sized_by (*assigned_results_length) *assigned_results, size_t *assigned_results_length); 314 315 extern netagent_session_t netagent_create(netagent_event_f event_handler, void *handle); 316 317 extern void netagent_destroy(netagent_session_t session); 318 319 extern errno_t netagent_register(netagent_session_t session, struct netagent *agent); 320 321 extern errno_t netagent_update(netagent_session_t session, struct netagent *agent); 322 323 extern errno_t netagent_unregister(netagent_session_t session); 324 325 extern errno_t netagent_assign_nexus(netagent_session_t _session, 326 uuid_t necp_client_uuid, 327 void *assign_message __sized_by(assigned_results_length), 328 size_t assigned_results_length); // Length of assigned_results_length 329 330 extern errno_t netagent_update_flow_protoctl_event(netagent_session_t _session, 331 uuid_t client_id, 332 uint32_t protoctl_event_code, 333 uint32_t protoctl_event_val, 334 uint32_t protoctl_event_tcp_seq_number); 335 336 extern int netagent_use(uuid_t agent_uuid, uint64_t *out_use_count); 337 338 #endif /* BSD_KERNEL_PRIVATE */ 339 340 #ifndef KERNEL 341 extern int netagent_trigger(uuid_t agent_uuid, size_t agent_uuidlen); 342 #endif /* !KERNEL */ 343 344 #endif /* PRIVATE */ 345 346 #endif /* _NETAGENT_H_ */ 347