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