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
  41 To enable
  42 .Ns Nm
  43 support, load the kernel side SeND as a module.
  44 To load it at boot time, add the following line to
  45 .Xr loader.conf 5 :
  46 .Bd -literal -offset indent
  47 send_load="YES"
  48 .Ed
  49 .Sh DESCRIPTION
  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
  55 to NDP [RFC3971].
  56 .Pp
  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
  61 further processing.
  62 Hooks are triggered only if the
  63 .Nm
  64 module is loaded.
  65 .Pp
  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
  69 .In netinet6/send.h .
  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
  72 interface index.
  73 .Bd -literal
  74 struct 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
  83 The address family is always
  84 .Va AF_INET6 .
  85 The
  86 .Va send_direction
  87 variable denotes the direction of the packet from the interface's
  88 point of view and has either the value
  89 .Dv SND_IN
  90 or
  91 .Dv SND_OUT .
  92 The
  93 .Va send_ifidx
  94 variable is the interface index of the receiving or sending interface.
  95 The
  96 .Va send_zero
  97 variable is padding and must always be zero.
  98 .Pp
  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.
 101 .Sh INPUT HOOK
 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
 104 space.
 105 Relevant packets are identified by adding an mbuf_tag
 106 (see
 107 .Xr mbuf_tags 9 )
 108 to the
 109 .Xr mbuf 9 ,
 110 if the
 111 .Nm
 112 module is loaded.
 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.
 117 .Dv SND_IN
 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.
 120 .Dv SND_OUT
 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
 124 of SeND options.
 125 .Sh INCOMING PACKETS
 126 The 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
 148 Outgoing 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
 186 A socket operation may fail with one of the following errors returned:
 187 .Bl -tag -width Er
 188 .It Bq Er EEXIST
 189 Another user space SeND application is bound to the socket.
 190 .It Bq Er ENOBUFS
 191 Shortage of space to receive the incoming (SeND-protected) or outgoing
 192 (SeND-validated) packet from the SeND application.
 193 .It Bq Er ENOSYS
 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.
 197 .It Bq Er ENOENT
 198 Occurs if interface output routines fail to send the packet out of the
 199 interface.
 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
 207 The
 208 .Nm
 209 module first appeared in
 210 .Fx 9.0 .
 211 .Sh AUTHORS
 212 .An Ana Kukec Aq anchie@FreeBSD.org ,
 213 University of Zagreb
 214 .Sh BUGS
 215 Due to the lack of NDP locking, it is currently not possible to unload the
 216 .Nm
 217 module.