1.\"- 2.\" Copyright (c) 2010 Ana Kukec 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd September 19, 2010 29.Dt SEND 4 30.Os 31.Sh NAME 32.Nm send 33.Nd "Kernel side support for Secure Neighbor Discovery (SeND)" 34.Sh SYNOPSIS 35.In sys/socket.h 36.In netinet/in.h 37.In netinet6/send.h 38.Ft int 39.Fn socket PF_INET6 SOCK_RAW IPPROTO_SEND 40.Pp 41To load the driver as a module at boot time, place the following line in 42.Xr loader.conf 5 : 43.Bd -literal -offset indent 44send_load="YES" 45.Ed 46.Sh DESCRIPTION 47IPv6 nodes use the Neighbor Discovery Protocol (NDP) to discover other nodes 48on the link, to determine their link-layer addresses to find routers, and 49to maintain reachability information about the paths to active members. 50NDP is vulnerable to various attacks [RFC3756]. 51Secure Neighbor Discovery is a set of extensions to NDP that counter threats 52to NDP [RFC3971]. 53.Pp 54Kernel side support for SeND consists of a kernel module with hooks that 55divert relevant packets (Neighbor Solicitations, Neighbor Advertisements, 56Router Solicitations, Router Advertisements and Redirects) from the NDP stack, 57send them to user space on a dedicated socket and reinject them back for 58further processing. 59Hooks are triggered only if the 60.Nm 61module is loaded. 62.Pp 63The native SeND socket is similar to a raw IP socket, but with its own, 64internal pseudo-protocol (IPPROTO_SEND). 65Struct sockaddr_send is defined in 66.In netinet6/send.h . 67It defines the total length of the structure, the address family, packet's 68incoming or outgoing direction from the interface's point of view, and the 69interface index. 70.Bd -literal 71struct sockaddr_send { 72 unsigned char send_len; /* total length */ 73 sa_family_t send_family; /* address family */ 74 int send_direction; 75 int send_ifidx; 76 char send_zero[8]; 77}; 78.Ed 79.Pp 80The address family is always 81.Va AF_INET6 . 82The 83.Va send_direction 84variable denotes the direction of the packet from the interface's 85point of view and has either the value 86.Dv SND_IN 87or 88.Dv SND_OUT . 89The 90.Va send_ifidx 91variable is the interface index of the receiving or sending interface. 92The 93.Va send_zero 94variable is padding and must always be zero. 95.Pp 96In case that no user space application is connected to the send socket, 97processing continues normally as if the module was not loaded. 98.Sh INPUT HOOK 99The input hook is named after the input path of the incoming or outgoing 100NDP packets, on the way from the wire, through the nd6 stack, to user 101space. 102Relevant packets are identified by adding an mbuf_tag 103(see 104.Xr mbuf_tags 9 ) 105to the 106.Xr mbuf 9 , 107if the 108.Nm 109module is loaded. 110It is then passed on to the kernel-userland interface 111for either cryptographic protection or validation by the SeND application. 112The hook takes an argument that describes the direction of the packet, both 113in case of incoming and outgoing packets. 114.Dv SND_IN 115is the direction of the incoming packets that are usually protected 116by the SeND options and then sent to user space for cryptographic validation. 117.Dv SND_OUT 118is the outgoing direction. 119It describes both reply and locally 120originated outgoing packets that are sent to user space for the addition 121of SeND options. 122.Sh INCOMING PACKETS 123The incoming ND packet from the wire: 124.Bd -literal 125 kernelspace ( userspace 126 ) 127 incoming SeND/ND packet ( 128 | ) 129 v ( SND_IN ) ( 130 icmp6_input() -> send_input_hook ---> send socket ----+ 131 : ) | 132 : # # ( | 133 normal : # # ) v 134 processing : # send.ko # ( SeND application 135 path : # # ) | 136 : # # ( | 137 v ) | 138 icmp6/nd6_??_input() <- protocol switch <--- send socket <---+ 139 | structure (IPPPROTO_SEND) ) 140 | ( SND_IN ) ( 141 v ) 142 continue normal ND processing ( 143.Ed 144.Sh OUTGOING PACKETS 145Outgoing ND packet (reply or locally triggered): 146.Bd -literal 147 kernelspace ( userspace 148 ) 149 nd6_na_input() ( 150 +PACKET_TAG_ND_OUTGOING ) 151 | ) 152 | outgoing packet ( 153 | | ) 154 | v ( 155 | icmp6_redirect_output() ) 156 | nd6_ns_output() ( 157 | nd6_na_output() ) 158 | +PACKET_TAG_ND_OUTGOING ( 159 | | ) 160 | +-----------<- rip6_output() <----------)----- rtsol/rtadvd/.. 161 | | +PACKET_TAG_ND_OUTGOING ( 162 | v ) 163 | ip6_output() ( 164 | | ) 165 +-------->-+ ( 166 | ) 167 v ( SND_OUT ) ( 168 nd6_output_lle() -> send_input_hook ---> send socket ----+ 169 -PACKET_TAG_ND_OUTGOING ) | 170 : # # ( | 171 normal : # # ) v 172 processing : # send.ko # ( SeND application 173 path : # # ) | 174 : # # ( | 175 v ) | 176 (*ifp->if_output)() <- protocol switch <--- send socket <---+ 177 | structure (IPPPROTO_SEND) ) 178 | ( SND_OUT ) ( 179 v ) 180 continue with normal packet output ( 181.Ed 182.Sh ERRORS 183A socket operation may fail with one of the following errors returned: 184.Bl -tag -width Er 185.It Bq Er EEXIST 186Another user space SeND application is bound to the socket. 187.It Bq Er ENOBUFS 188Shortage of space to receive the incoming (SeND-protected) or outgoing 189(SeND-validated) packet from the SeND application. 190.It Bq Er ENOSYS 191A packet received from user space and passed to the NDP stack for further 192processing is neither Neighbor Solicitation, Neighbor Advertisement, 193Router Solicitation, Router Advertisement nor Redirect. 194.It Bq Er ENOENT 195Occurs if interface output routines fail to send the packet out of the 196interface. 197.El 198.Sh SEE ALSO 199.Xr recvfrom 2 , 200.Xr sendto 2 , 201.Xr socket 2 , 202.Xr loader.conf 5 203.Sh HISTORY 204The 205.Nm 206module first appeared in 207.Fx 9.0 . 208.Sh AUTHORS 209.An Ana Kukec Aq Mt anchie@FreeBSD.org , 210University of Zagreb 211.Sh BUGS 212Due to the lack of NDP locking, it is currently not possible to unload the 213.Nm 214module. 215