2 .\" Copyright (c) 2010 Ana Kukec
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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
28 .Dd September 19, 2010
33 .Nd "Kernel side support for Secure Neighbor Discovery (SeND)"
39 .Fn socket PF_INET6 SOCK_RAW IPPROTO_SEND
43 support, load the kernel side SeND as a module.
44 To load it at boot time, add the following line to
46 .Bd -literal -offset indent
50 IPv6 nodes use the Neighbor Discovery Protocol (NDP) to discover other nodes
51 on the link, to determine their link-layer addresses to find routers, and
52 to maintain reachability information about the paths to active members.
53 NDP is vulnerable to various attacks [RFC3756].
54 Secure Neighbor Discovery is a set of extensions to NDP that counter threats
57 Kernel side support for SeND consists of a kernel module with hooks that
58 divert relevant packets (Neighbor Solicitations, Neighbor Advertisements,
59 Router Solicitations, Router Advertisements and Redirects) from the NDP stack,
60 send them to user space on a dedicated socket and reinject them back for
62 Hooks are triggered only if the
66 The native SeND socket is similar to a raw IP socket, but with its own,
67 internal pseudo-protocol (IPPROTO_SEND).
68 Struct sockaddr_send is defined in
70 It defines the total length of the structure, the address family, packet's
71 incoming or outgoing direction from the interface's point of view, and the
74 struct sockaddr_send {
75 unsigned char send_len; /* total length */
76 sa_family_t send_family; /* address family */
83 The address family is always
87 variable denotes the direction of the packet from the interface's
88 point of view and has either the value
94 variable is the interface index of the receiving or sending interface.
97 variable is padding and must always be zero.
99 In case that no user space application is connected to the send socket,
100 processing continues normally as if the module was not loaded.
102 The input hook is named after the input path of the incoming or outgoing
103 NDP packets, on the way from the wire, through the nd6 stack, to user
105 Relevant packets are identified by adding an mbuf_tag
113 It is then passed on to the kernel-userland interface
114 for either cryptographic protection or validation by the SeND application.
115 The hook takes an argument that describes the direction of the packet, both
116 in case of incoming and outgoing packets.
118 is the direction of the incoming packets that are usually protected
119 by the SeND options and then sent to user space for cryptographic validation.
121 is the outgoing direction.
122 It describes both reply and locally
123 originated outgoing packets that are sent to user space for the addition
126 The incoming ND packet from the wire:
128 kernelspace ( userspace
130 incoming SeND/ND packet (
133 icmp6_input() -> send_input_hook ---> send socket ----+
137 processing : # send.ko # ( SeND application
141 icmp6/nd6_??_input() <- protocol switch <--- send socket <---+
142 | structure (IPPPROTO_SEND) )
145 continue normal ND processing (
148 Outgoing ND packet (reply or locally triggered):
150 kernelspace ( userspace
153 +PACKET_TAG_ND_OUTGOING )
158 | icmp6_redirect_output() )
161 | +PACKET_TAG_ND_OUTGOING (
163 | +-----------<- rip6_output() <----------)----- rtsol/rtadvd/..
164 | | +PACKET_TAG_ND_OUTGOING (
171 nd6_output_lle() -> send_input_hook ---> send socket ----+
172 -PACKET_TAG_ND_OUTGOING ) |
175 processing : # send.ko # ( SeND application
179 (*ifp->if_output)() <- protocol switch <--- send socket <---+
180 | structure (IPPPROTO_SEND) )
183 continue with normal packet output (
186 A socket operation may fail with one of the following errors returned:
189 Another user space SeND application is bound to the socket.
191 Shortage of space to receive the incoming (SeND-protected) or outgoing
192 (SeND-validated) packet from the SeND application.
194 A packet received from user space and passed to the NDP stack for further
195 processing is neither Neighbor Solicitation, Neighbor Advertisement,
196 Router Solicitation, Router Advertisement nor Redirect.
198 Occurs if interface output routines fail to send the packet out of the
209 module first appeared in
212 .An Ana Kukec Aq anchie@FreeBSD.org ,
215 Due to the lack of NDP locking, it is currently not possible to unload the