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