/share/man/man4/send.4

  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 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.