1 /* 2 * Copyright (c) 2008-2021 Apple Computer, 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 * @header kpi_socketfilter.h 30 * This header defines an API for intercepting communications at the 31 * socket layer. 32 * 33 * For the most part, socket filters want to do three things: Filter 34 * data in and out, watch for state changes, and intercept a few calls 35 * for security. The number of function pointers supplied by a socket 36 * filter has been significantly reduced. The filter no longer has any 37 * knowledge of socket buffers. The filter no longer intercepts nearly 38 * every internal socket call. There are two data filters, an in 39 * filter, and an out filter. The in filter occurs before data is 40 * placed in the receive socket buffer. This is done to avoid waking 41 * the process unnecessarily. The out filter occurs before the data is 42 * appended to the send socket buffer. This should cover inbound and 43 * outbound data. For monitoring state changes, we've added a notify 44 * function that will be called when various events that the filter can 45 * not intercept occur. In addition, we've added a few functions that a 46 * filter may use to intercept common operations. These functions are: 47 * connect (inbound), connect (outbound), bind, set socket option, 48 * get socket option, and listen. Bind, listen, connect in, and connect 49 * out could be used together to build a fairly comprehensive firewall 50 * without having to do much with individual packets. 51 */ 52 #ifndef __KPI_SOCKETFILTER__ 53 #define __KPI_SOCKETFILTER__ 54 55 #include <sys/kernel_types.h> 56 #include <sys/kpi_socket.h> 57 58 #ifndef PRIVATE 59 #include <Availability.h> 60 #define __NKE_API_DEPRECATED __API_DEPRECATED("Network Kernel Extension KPI is deprecated", macos(10.4, 10.15)) 61 #else 62 #define __NKE_API_DEPRECATED 63 #endif /* PRIVATE */ 64 65 struct sockaddr; 66 67 /*! 68 * @enum sflt_flags 69 * @abstract Constants defining mbuf flags. Only the flags listed below 70 * can be set or retrieved. 71 * @constant SFLT_GLOBAL Indicates this socket filter should be 72 * attached to all new sockets when they're created. 73 * @constant SFLT_PROG Indicates this socket filter should be attached 74 * only when request by the application using the SO_NKE socket 75 * option. 76 * @constant SFLT_EXTENDED Indicates that this socket filter utilizes 77 * the extended fields within the sflt_filter structure. 78 * @constant SFLT_EXTENDED_REGISTRY Indicates that this socket filter 79 * wants to attach to all the sockets already present on the 80 * system. It will also receive notifications for these sockets. 81 */ 82 enum { 83 SFLT_GLOBAL = 0x01, 84 SFLT_PROG = 0x02, 85 SFLT_EXTENDED = 0x04, 86 SFLT_EXTENDED_REGISTRY = 0x08 87 }; 88 typedef u_int32_t sflt_flags; 89 90 /*! 91 * @typedef sflt_handle 92 * @abstract A 4 byte identifier used with the SO_NKE socket option to 93 * identify the socket filter to be attached. 94 */ 95 typedef u_int32_t sflt_handle; 96 97 /*! 98 * @enum sflt_event_t 99 * @abstract Events notify a filter of state changes and other various 100 * events related to the socket. These events cannot be prevented 101 * or intercepted, only observed. 102 * @constant sock_evt_connected Indicates this socket has moved to the 103 * connected state. 104 * @constant sock_evt_disconnected Indicates this socket has moved to 105 * the disconnected state. 106 * @constant sock_evt_flush_read The read socket buffer has been 107 * flushed. 108 * @constant sock_evt_shutdown The read and or write side(s) of the 109 * connection have been shutdown. The param will point to an 110 * integer that indicates the direction that has been shutdown. See 111 * 'man 2 shutdown' for more information. 112 * @constant sock_evt_cantrecvmore Indicates the socket cannot receive 113 * more data. 114 * @constant sock_evt_cantsendmore Indicates the socket cannot send 115 * more data. 116 * @constant sock_evt_closing Indicates the socket is closing. 117 * @constant sock_evt_bound Indicates this socket has moved to the 118 * bound state (only for PF_INET/PF_INET6 domain). 119 */ 120 enum { 121 sock_evt_connecting = 1, 122 sock_evt_connected = 2, 123 sock_evt_disconnecting = 3, 124 sock_evt_disconnected = 4, 125 sock_evt_flush_read = 5, 126 sock_evt_shutdown = 6, /* param points to an integer specifying how (read, write, or both) see man 2 shutdown */ 127 sock_evt_cantrecvmore = 7, 128 sock_evt_cantsendmore = 8, 129 sock_evt_closing = 9, 130 sock_evt_bound = 10 131 }; 132 typedef u_int32_t sflt_event_t; 133 134 /*! 135 * @enum sflt_data_flag_t 136 * @abstract Inbound and outbound data filters may handle many 137 * different types of incoming and outgoing data. These flags help 138 * distinguish between normal data, out-of-band data, and records. 139 * @constant sock_data_filt_flag_oob Indicates this data is out-of-band 140 * data. 141 * @constant sock_data_filt_flag_record Indicates this data is a 142 * record. This flag is only ever seen on inbound data. 143 */ 144 enum { 145 sock_data_filt_flag_oob = 1, 146 sock_data_filt_flag_record = 2 147 }; 148 typedef u_int32_t sflt_data_flag_t; 149 150 __BEGIN_DECLS 151 152 /*! 153 * @typedef sf_unregistered_func 154 * 155 * @discussion sf_unregistered_func is called to notify the filter it 156 * has been unregistered. This is the last function the stack will 157 * call and this function will only be called once all other 158 * function calls in to your filter have completed. Once this 159 * function has been called, your kext may safely unload. 160 * @param handle The socket filter handle used to identify this filter. 161 */ 162 typedef void (*sf_unregistered_func)(sflt_handle handle); 163 164 /*! 165 * @typedef sf_attach_func 166 * 167 * @discussion sf_attach_func is called to notify the filter it has 168 * been attached to a socket. The filter may allocate memory for 169 * this attachment and use the cookie to track it. This filter is 170 * called in one of two cases: 171 * 1) You've installed a global filter and a new socket was created. 172 * 2) Your non-global socket filter is being attached using the SO_NKE 173 * socket option. 174 * @param cookie Used to allow the socket filter to set the cookie for 175 * this attachment. 176 * @param so The socket the filter is being attached to. 177 * @result If you return a non-zero value, your filter will not be 178 * attached to this socket. 179 */ 180 typedef errno_t (*sf_attach_func)(void **cookie, socket_t so); 181 182 /*! 183 * @typedef sf_detach_func 184 * 185 * @discussion sf_detach_func is called to notify the filter it has 186 * been detached from a socket. If the filter allocated any memory 187 * for this attachment, it should be freed. This function will 188 * be called when the socket is disposed of. 189 * @param cookie Cookie value specified when the filter attach was 190 * called. 191 * @param so The socket the filter is attached to. 192 * @discussion If you return a non-zero value, your filter will not be 193 * attached to this socket. 194 */ 195 typedef void (*sf_detach_func)(void *cookie, socket_t so); 196 197 /*! 198 * @typedef sf_notify_func 199 * 200 * @discussion sf_notify_func is called to notify the filter of various 201 * state changes and other events occuring on the socket. 202 * @param cookie Cookie value specified when the filter attach was 203 * called. 204 * @param so The socket the filter is attached to. 205 * @param event The type of event that has occurred. 206 * @param param Additional information about the event. 207 */ 208 typedef void (*sf_notify_func)(void *cookie, socket_t so, sflt_event_t event, 209 void *param); 210 211 /*! 212 * @typedef sf_getpeername_func 213 * 214 * @discussion sf_getpeername_func is called to allow a filter to 215 * to intercept the getpeername function. When called, sa will 216 * point to a pointer to a socket address that was malloced 217 * in zone M_SONAME. If you want to replace this address, either 218 * modify the currenty copy or allocate a new one and free the 219 * old one. 220 * @param cookie Cookie value specified when the filter attach was 221 * called. 222 * @param so The socket the filter is attached to. 223 * @param sa A pointer to a socket address pointer. 224 * @result If you return a non-zero value, processing will stop. If 225 * you return EJUSTRETURN, no further filters will be called 226 * but a result of zero will be returned to the caller of 227 * getpeername. 228 */ 229 typedef int (*sf_getpeername_func)(void *cookie, socket_t so, 230 struct sockaddr **sa); 231 232 /*! 233 * @typedef sf_getsockname_func 234 * 235 * @discussion sf_getsockname_func is called to allow a filter to 236 * to intercept the getsockname function. When called, sa will 237 * point to a pointer to a socket address that was malloced 238 * in zone M_SONAME. If you want to replace this address, either 239 * modify the currenty copy or allocate a new one and free the 240 * old one. 241 * @param cookie Cookie value specified when the filter attach was 242 * called. 243 * @param so The socket the filter is attached to. 244 * @param sa A pointer to a socket address pointer. 245 * @result If you return a non-zero value, processing will stop. If 246 * you return EJUSTRETURN, no further filters will be called 247 * but a result of zero will be returned to the caller of 248 * getsockname. 249 */ 250 typedef int (*sf_getsockname_func)(void *cookie, socket_t so, 251 struct sockaddr **sa); 252 253 /*! 254 * @typedef sf_data_in_func 255 * 256 * @discussion sf_data_in_func is called to filter incoming data. If your 257 * filter intercepts data for later reinjection, it must queue 258 * all incoming data to preserve the order of the data. Use 259 * sock_inject_data_in to later reinject this data if you return 260 * EJUSTRETURN. Warning: This filter is on the data path. Do not 261 * spend excesive time. Do not wait for data on another socket. 262 * @param cookie Cookie value specified when the filter attach was 263 * called. 264 * @param so The socket the filter is attached to. 265 * @param from The addres the data is from, may be NULL if the socket 266 * is connected. 267 * @param data The data being received. Control data may appear in the 268 * mbuf chain, be sure to check the mbuf types to find control 269 * data. 270 * @param control Control data being passed separately from the data. 271 * @param flags Flags to indicate if this is out of band data or a 272 * record. 273 * @result Return: 274 * 0 - The caller will continue with normal processing of the data. 275 * EJUSTRETURN - The caller will stop processing the data, the 276 * data will not be freed. 277 * Anything Else - The caller will free the data and stop 278 * processing. 279 */ 280 typedef errno_t (*sf_data_in_func)(void *cookie, socket_t so, 281 const struct sockaddr *from, mbuf_t *data, mbuf_t *control, 282 sflt_data_flag_t flags); 283 284 /*! 285 * @typedef sf_data_out_func 286 * 287 * @discussion sf_data_out_func is called to filter outbound data. If 288 * your filter intercepts data for later reinjection, it must queue 289 * all outbound data to preserve the order of the data when 290 * reinjecting. Use sock_inject_data_out to later reinject this 291 * data. 292 * @param cookie Cookie value specified when the filter attach was 293 * called. 294 * @param so The socket the filter is attached to. 295 * @param to The address the data is to, may be NULL if the socket 296 * is connected. 297 * @param data The data being received. Control data may appear in the 298 * mbuf chain, be sure to check the mbuf types to find control 299 * data. 300 * @param control Control data being passed separately from the data. 301 * @param flags Flags to indicate if this is out of band data or a 302 * record. 303 * @result Return: 304 * 0 - The caller will continue with normal processing of the data. 305 * EJUSTRETURN - The caller will stop processing the data, 306 * the data will not be freed. 307 * Anything Else - The caller will free the data and stop 308 * processing. 309 */ 310 typedef errno_t (*sf_data_out_func)(void *cookie, socket_t so, 311 const struct sockaddr *to, mbuf_t *data, mbuf_t *control, 312 sflt_data_flag_t flags); 313 314 /*! 315 * @typedef sf_connect_in_func 316 * 317 * @discussion sf_connect_in_func is called to filter inbound connections. 318 * A protocol will call this before accepting an incoming 319 * connection and placing it on the queue of completed connections. 320 * Warning: This filter is on the data path. Do not spend excesive 321 * time. Do not wait for data on another socket. 322 * @param cookie Cookie value specified when the filter attach was 323 * called. 324 * @param so The socket the filter is attached to. 325 * @param from The address the incoming connection is from. 326 * @result Return: 327 * 0 - The caller will continue with normal processing of the 328 * connection. 329 * Anything Else - The caller will rejecting the incoming 330 * connection. 331 */ 332 typedef errno_t (*sf_connect_in_func)(void *cookie, socket_t so, 333 const struct sockaddr *from); 334 335 /*! 336 * @typedef sf_connect_out_func 337 * 338 * @discussion sf_connect_out_func is called to filter outbound 339 * connections. A protocol will call this before initiating an 340 * outbound connection. 341 * @param cookie Cookie value specified when the filter attach was 342 * called. 343 * @param so The socket the filter is attached to. 344 * @param to The remote address of the outbound connection. 345 * @result Return: 346 * 0 - The caller will continue with normal processing of the 347 * connection. 348 * EJUSTRETURN - The caller will return with a value of 0 (no error) 349 * from that point without further processing the connect command. The 350 * protocol layer will not see the call. 351 * Anything Else - The caller will rejecting the outbound 352 * connection. 353 */ 354 typedef errno_t (*sf_connect_out_func)(void *cookie, socket_t so, 355 const struct sockaddr *to); 356 357 /*! 358 * @typedef sf_bind_func 359 * 360 * @discussion sf_bind_func is called before performing a bind 361 * operation on a socket. 362 * @param cookie Cookie value specified when the filter attach was 363 * called. 364 * @param so The socket the filter is attached to. 365 * @param to The local address of the socket will be bound to. 366 * @result Return: 367 * 0 - The caller will continue with normal processing of the bind. 368 * EJUSTRETURN - The caller will return with a value of 0 (no error) 369 * from that point without further processing the bind command. The 370 * protocol layer will not see the call. 371 * Anything Else - The caller will rejecting the bind. 372 */ 373 typedef errno_t (*sf_bind_func)(void *cookie, socket_t so, 374 const struct sockaddr *to); 375 376 /*! 377 * @typedef sf_setoption_func 378 * 379 * @discussion sf_setoption_func is called before performing setsockopt 380 * on a socket. 381 * @param cookie Cookie value specified when the filter attach was 382 * called. 383 * @param so The socket the filter is attached to. 384 * @param opt The socket option to set. 385 * @result Return: 386 * 0 - The caller will continue with normal processing of the 387 * setsockopt. 388 * EJUSTRETURN - The caller will return with a value of 0 (no error) 389 * from that point without further propagating the set option 390 * command. The socket and protocol layers will not see the call. 391 * Anything Else - The caller will stop processing and return 392 * this error. 393 */ 394 typedef errno_t (*sf_setoption_func)(void *cookie, socket_t so, sockopt_t opt); 395 396 /*! 397 * @typedef sf_getoption_func 398 * 399 * @discussion sf_getoption_func is called before performing getsockopt 400 * on a socket. 401 * @param cookie Cookie value specified when the filter attach was 402 * called. 403 * @param so The socket the filter is attached to. 404 * @param opt The socket option to get. 405 * @result Return: 406 * 0 - The caller will continue with normal processing of the 407 * getsockopt. 408 * EJUSTRETURN - The caller will return with a value of 0 (no error) 409 * from that point without further propagating the get option 410 * command. The socket and protocol layers will not see the call. 411 * Anything Else - The caller will stop processing and return 412 * this error. 413 */ 414 typedef errno_t (*sf_getoption_func)(void *cookie, socket_t so, sockopt_t opt); 415 416 /*! 417 * @typedef sf_listen_func 418 * 419 * @discussion sf_listen_func is called before performing listen 420 * on a socket. 421 * @param cookie Cookie value specified when the filter attach was 422 * called. 423 * @param so The socket the filter is attached to. 424 * @result Return: 425 * 0 - The caller will continue with normal processing of listen. 426 * EJUSTRETURN - The caller will return with a value of 0 (no error) 427 * from that point without further processing the listen command. The 428 * protocol will not see the call. 429 * Anything Else - The caller will stop processing and return 430 * this error. 431 */ 432 typedef errno_t (*sf_listen_func)(void *cookie, socket_t so); 433 434 /*! 435 * @typedef sf_ioctl_func 436 * 437 * @discussion sf_ioctl_func is called before performing an ioctl 438 * on a socket. 439 * 440 * All undefined ioctls are reserved for future use by Apple. If 441 * you need to communicate with your kext using an ioctl, please 442 * use SIOCSIFKPI and SIOCGIFKPI. 443 * @param cookie Cookie value specified when the filter attach was 444 * called. 445 * @param so The socket the filter is attached to. 446 * @param request The ioctl name. 447 * @param argp A pointer to the ioctl parameter. 448 * @result Return: 449 * 0 - The caller will continue with normal processing of 450 * this ioctl. 451 * EJUSTRETURN - The caller will return with a value of 0 (no error) 452 * from that point without further processing or propogating 453 * the ioctl. 454 * Anything Else - The caller will stop processing and return 455 * this error. 456 */ 457 typedef errno_t (*sf_ioctl_func)(void *cookie, socket_t so, 458 unsigned long request, const char* argp); 459 460 /*! 461 * @typedef sf_accept_func 462 * 463 * @discussion sf_accept_func is called after a socket is dequeued 464 * off the completed (incoming) connection list and before 465 * the file descriptor is associated with it. A filter can 466 * utilize this callback to intercept the accepted socket 467 * in order to examine it, prior to returning the socket to 468 * the caller of accept. Such a filter may also choose to 469 * discard the accepted socket if it wishes to do so. 470 * @param cookie Cookie value specified when the filter attach was called. 471 * @param so_listen The listening socket. 472 * @param so The socket that is about to be accepted. 473 * @param local The local address of the about to be accepted socket. 474 * @param remote The remote address of the about to be accepted socket. 475 * @result Return: 476 * 0 - The caller will continue with normal processing of accept. 477 * EJUSTRETURN - The to be accepted socket will be disconnected 478 * prior to being returned to the caller of accept. No further 479 * control or data operations on the socket will be allowed. 480 * This is the recommended return value as it has the least 481 * amount of impact, especially to applications which don't 482 * check the error value returned by accept. 483 * Anything Else - The to be accepted socket will be closed and 484 * the error will be returned to the caller of accept. 485 * Note that socket filter developers are advised to exercise 486 * caution when returning non-zero values to the caller, 487 * since some applications don't check the error value 488 * returned by accept and therefore risk breakage. 489 */ 490 typedef errno_t (*sf_accept_func)(void *cookie, socket_t so_listen, socket_t so, 491 const struct sockaddr *local, const struct sockaddr *remote); 492 493 /*! 494 * @struct sflt_filter 495 * @discussion This structure is used to define a socket filter. 496 * @field sf_handle A value used to find socket filters by 497 * applications. An application can use this value to specify that 498 * this filter should be attached when using the SO_NKE socket 499 * option. 500 * @field sf_flags Indicate whether this filter should be attached to 501 * all new sockets or just those that request the filter be 502 * attached using the SO_NKE socket option. If this filter 503 * utilizes the socket filter extension fields, it must also 504 * set SFLT_EXTENDED. 505 * @field sf_name A name used for debug purposes. 506 * @field sf_unregistered Your function for being notified when your 507 * filter has been unregistered. 508 * @field sf_attach Your function for handling attaches to sockets. 509 * @field sf_detach Your function for handling detaches from sockets. 510 * @field sf_notify Your function for handling events. May be null. 511 * @field sf_data_in Your function for handling incoming data. May be 512 * null. 513 * @field sf_data_out Your function for handling outgoing data. May be 514 * null. 515 * @field sf_connect_in Your function for handling inbound 516 * connections. May be null. 517 * @field sf_connect_out Your function for handling outbound 518 * connections. May be null. 519 * @field sf_bind Your function for handling binds. May be null. 520 * @field sf_setoption Your function for handling setsockopt. May be null. 521 * @field sf_getoption Your function for handling getsockopt. May be null. 522 * @field sf_listen Your function for handling listen. May be null. 523 * @field sf_ioctl Your function for handling ioctls. May be null. 524 * @field sf_len Length of socket filter extension structure; developers 525 * must initialize this to sizeof sflt_filter_ext structure. 526 * This field and all fields following it will only be valid 527 * if SFLT_EXTENDED flag is set in sf_flags field. 528 * @field sf_ext_accept Your function for handling inbound connections 529 * at accept time. May be null. 530 * @field sf_ext_rsvd Reserved for future use; you must initialize 531 * the reserved fields with zeroes. 532 */ 533 struct sflt_filter { 534 sflt_handle sf_handle; 535 int sf_flags; 536 char *sf_name; 537 538 sf_unregistered_func sf_unregistered; 539 sf_attach_func sf_attach; 540 sf_detach_func sf_detach; 541 542 sf_notify_func sf_notify; 543 sf_getpeername_func sf_getpeername; 544 sf_getsockname_func sf_getsockname; 545 sf_data_in_func sf_data_in; 546 sf_data_out_func sf_data_out; 547 sf_connect_in_func sf_connect_in; 548 sf_connect_out_func sf_connect_out; 549 sf_bind_func sf_bind; 550 sf_setoption_func sf_setoption; 551 sf_getoption_func sf_getoption; 552 sf_listen_func sf_listen; 553 sf_ioctl_func sf_ioctl; 554 /* 555 * The following are valid only if SFLT_EXTENDED flag is set. 556 * Initialize sf_ext_len to sizeof sflt_filter_ext structure. 557 * Filters must also initialize reserved fields with zeroes. 558 */ 559 struct sflt_filter_ext { 560 unsigned int sf_ext_len; 561 sf_accept_func sf_ext_accept; 562 void *sf_ext_rsvd[5]; /* Reserved */ 563 } sf_ext; 564 #define sf_len sf_ext.sf_ext_len 565 #define sf_accept sf_ext.sf_ext_accept 566 }; 567 568 /*! 569 * @function sflt_register 570 * @discussion Registers a socket filter. See 'man 2 socket' for a 571 * desciption of domain, type, and protocol. 572 * @param filter A structure describing the filter. 573 * @param domain The protocol domain these filters will be attached to. 574 * Only PF_INET & PF_INET6 domains are supported. 575 * @param type The socket type these filters will be attached to. 576 * @param protocol The protocol these filters will be attached to. 577 * @result 0 on success otherwise the errno error. 578 */ 579 #ifdef KERNEL_PRIVATE 580 extern errno_t sflt_register_internal(const struct sflt_filter *filter, 581 int domain, int type, int protocol); 582 583 #define sflt_register(filter, domain, type, protocol) \ 584 sflt_register_internal((filter), (domain), (type), (protocol)) 585 #else 586 extern errno_t sflt_register(const struct sflt_filter *filter, int domain, 587 int type, int protocol) 588 __NKE_API_DEPRECATED; 589 #endif /* KERNEL_PRIVATE */ 590 591 /*! 592 * @function sflt_unregister 593 * @discussion Unregisters a socket filter. This will not detach the 594 * socket filter from all sockets it may be attached to at the 595 * time, it will just prevent the socket filter from being attached 596 * to any new sockets. 597 * @param handle The sf_handle of the socket filter to unregister. 598 * @result 0 on success otherwise the errno error. 599 */ 600 extern errno_t sflt_unregister(sflt_handle handle) 601 __NKE_API_DEPRECATED; 602 603 /*! 604 * @function sflt_attach 605 * @discussion Attaches a socket filter to the specified socket. A 606 * filter must be registered before it can be attached. 607 * @param socket The socket the filter should be attached to. 608 * @param handle The handle of the registered filter to be attached. 609 * @result 0 on success otherwise the errno error. 610 */ 611 extern errno_t sflt_attach(socket_t socket, sflt_handle handle) 612 __NKE_API_DEPRECATED; 613 614 /*! 615 * @function sflt_detach 616 * @discussion Detaches a socket filter from a specified socket. 617 * @param socket The socket the filter should be detached from. 618 * @param handle The handle of the registered filter to be detached. 619 * @result 0 on success otherwise the errno error. 620 */ 621 extern errno_t sflt_detach(socket_t socket, sflt_handle handle) 622 __NKE_API_DEPRECATED; 623 624 /* Functions for manipulating sockets */ 625 /* 626 * Inject data in to the receive buffer of the socket as if it 627 * had come from the network. 628 * 629 * flags should match sflt_data_flag_t 630 */ 631 632 /*! 633 * @function sock_inject_data_in 634 * @discussion Inject data in to the receive buffer of the socket as if 635 * it had come from the network. 636 * @param so The socket to inject the data on. 637 * @param from The address the data is from, only necessary on 638 * un-connected sockets. A copy of the address will be made, caller 639 * is responsible for freeing the address after calling this 640 * function. 641 * @param data The data and possibly control mbufs. 642 * @param control The separate control mbufs. 643 * @param flags Flags indicating the type of data. 644 * @result 0 on success otherwise the errno error. If the function 645 * returns an error, the caller is responsible for freeing the 646 * mbuf. 647 */ 648 extern errno_t sock_inject_data_in(socket_t so, const struct sockaddr *from, 649 mbuf_t data, mbuf_t control, sflt_data_flag_t flags) 650 __NKE_API_DEPRECATED; 651 652 /*! 653 * @function sock_inject_data_out 654 * @discussion Inject data in to the send buffer of the socket as if it 655 * had come from the client. 656 * @param so The socket to inject the data on. 657 * @param to The address the data should be sent to, only necessary on 658 * un-connected sockets. The caller is responsible for freeing the 659 * to address after sock_inject_data_out returns. 660 * @param data The data and possibly control mbufs. 661 * @param control The separate control mbufs. 662 * @param flags Flags indicating the type of data. 663 * @result 0 on success otherwise the errno error. The data and control 664 * values are always freed regardless of return value. 665 */ 666 extern errno_t sock_inject_data_out(socket_t so, const struct sockaddr *to, 667 mbuf_t data, mbuf_t control, sflt_data_flag_t flags) 668 __NKE_API_DEPRECATED; 669 670 671 /* 672 * sockopt_t accessors 673 */ 674 675 enum { 676 sockopt_get = 1, 677 sockopt_set = 2 678 }; 679 typedef u_int8_t sockopt_dir; 680 681 /*! 682 * @function sockopt_direction 683 * @discussion Retrieves the direction of the socket option (Get or 684 * Set). 685 * @param sopt The socket option. 686 * @result sock_opt_get or sock_opt_set. 687 */ 688 extern sockopt_dir sockopt_direction(sockopt_t sopt) 689 __NKE_API_DEPRECATED; 690 691 /*! 692 * @function sockopt_level 693 * @discussion Retrieves the socket option level. (SOL_SOCKET, etc). 694 * @param sopt The socket option. 695 * @result The socket option level. See man 2 setsockopt 696 */ 697 extern int sockopt_level(sockopt_t sopt) 698 __NKE_API_DEPRECATED; 699 700 /*! 701 * @function sockopt_name 702 * @discussion Retrieves the socket option name. (SO_SNDBUF, etc). 703 * @param sopt The socket option. 704 * @result The socket option name. See man 2 setsockopt 705 */ 706 extern int sockopt_name(sockopt_t sopt) 707 __NKE_API_DEPRECATED; 708 709 /*! 710 * @function sockopt_valsize 711 * @discussion Retrieves the size of the socket option data. 712 * @param sopt The socket option. 713 * @result The length, in bytes, of the data. 714 */ 715 extern size_t sockopt_valsize(sockopt_t sopt) 716 __NKE_API_DEPRECATED; 717 718 /*! 719 * @function sockopt_copyin 720 * @discussion Copies the data from the socket option to a buffer. 721 * @param sopt The socket option. 722 * @param data A pointer to the buffer to copy the data in to. 723 * @param length The number of bytes to copy. 724 * @result An errno error or zero upon success. 725 */ 726 extern errno_t sockopt_copyin(sockopt_t sopt, void *data, size_t length) 727 __NKE_API_DEPRECATED; 728 729 /*! 730 * @function sockopt_copyout 731 * @discussion Copies the data from a buffer to a socket option. 732 * @param sopt The socket option. 733 * @param data A pointer to the buffer to copy the data out of. 734 * @param length The number of bytes to copy. 735 * @result An errno error or zero upon success. 736 */ 737 extern errno_t sockopt_copyout(sockopt_t sopt, void *data, size_t length) 738 __NKE_API_DEPRECATED; 739 740 #undef __NKE_API_DEPRECATED 741 __END_DECLS 742 #endif /* __KPI_SOCKETFILTER__ */ 743