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