From 80ba2a07f7b50b6ec7cb61e52af24d29c7d5759b Mon Sep 17 00:00:00 2001 From: anchie Date: Sun, 19 Sep 2010 12:54:18 +0000 Subject: Manual page for the kernel side Secure Neighbor Discovery support. Reviewed by: brueffer Approved by: bz (mentor) --- share/man/man4/Makefile | 1 + share/man/man4/send.4 | 218 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 219 insertions(+) create mode 100644 share/man/man4/send.4 (limited to 'share/man') diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile index 0310f0d9..7e5cdf1 100644 --- a/share/man/man4/Makefile +++ b/share/man/man4/Makefile @@ -357,6 +357,7 @@ MAN= aac.4 \ sctp.4 \ sdhci.4 \ sem.4 \ + send.4 \ ses.4 \ sf.4 \ sge.4 \ diff --git a/share/man/man4/send.4 b/share/man/man4/send.4 new file mode 100644 index 0000000..35ed77f --- /dev/null +++ b/share/man/man4/send.4 @@ -0,0 +1,218 @@ +.\"- +.\" Copyright (c) 2010 Ana Kukec +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 19, 2010 +.Dt SEND 4 +.Os +.Sh NAME +.Nm send +.Nd "Kernel side support for Secure Neighbor Discovery (SeND)" +.Sh SYNOPSIS +.In sys/socket.h +.In netinet/in.h +.In netinet6/send.h +.Ft int +.Fn socket PF_INET6 SOCK_RAW IPPROTO_SEND +.Pp +To enable +.Ns Nm +support, load the kernel side SeND as a module. +To load it at boot time, add the following line to +.Xr loader.conf 5 : +.Bd -literal -offset indent +send_load="YES" +.Ed +.Sh DESCRIPTION +IPv6 nodes use the Neighbor Discovery Protocol (NDP) to discover other nodes +on the link, to determine their link-layer addresses to find routers, and +to maintain reachability information about the paths to active members. +NDP is vulnerable to various attacks [RFC3756]. +Secure Neighbor Discovery is a set of extensions to NDP that counter threats +to NDP [RFC3971]. +.Pp +Kernel side support for SeND consists of a kernel module with hooks that +divert relevant packets (Neighbor Solicitations, Neighbor Advertisements, +Router Solicitations, Router Advertisements and Redirects) from the NDP stack, +send them to user space on a dedicated socket and reinject them back for +further processing. +Hooks are triggered only if the +.Nm +module is loaded. +.Pp +The native SeND socket is similar to a raw IP socket, but with its own, +internal pseudo-protocol (IPPROTO_SEND). +Struct sockaddr_send is defined in +.In netinet6/send.h . +It defines the total length of the structure, the address family, packet's +incoming or outgoing direction from the interface's point of view, and the +interface index. +.Pp +.Bd -literal +struct sockaddr_send { + unsigned char send_len; /* total length */ + sa_family_t send_family; /* address family */ + int send_direction; + int send_ifidx; + char send_zero[8]; +}; +.Ed +.Pp +The address family is always +.Va AF_INET6 . +The +.Va send_direction +variable denotes the direction of the packet from the interface's +point of view and has either the value +.Dv SND_IN +or +.Dv SND_OUT . +The +.Va send_ifidx +variable is the interface index of the receiving or sending interface. +The +.Va send_zero +variable is padding and must always be zero. +.Pp +In case that no user space application is connected to the send socket, +processing continues normally as if the module was not loaded. +.Sh INPUT HOOK +The input hook is named after the input path of the incoming or outgoing +NDP packets, on the way from the wire, through the nd6 stack, to user +space. +Relevant packets are identified by adding an mbuf_tag +(see +.Xr mbuf_tags 9 ) +to the +.Xr mbuf 9 , +if the +.Nm +module is loaded. +It is then passed on to the kernel-userland interface +for either cryptographic protection or validation by the SeND application. +The hook takes an argument that describes the direction of the packet, both +in case of incoming and outgoing packets. +.Dv SND_IN +is the direction of the incoming packets that are usually protected +by the SeND options and then sent to user space for cryptographic validation. +.Dv SND_OUT +is the outgoing direction. +It describes both reply and locally +originated outgoing packets that are sent to user space for the addition +of SeND options. +.Sh INCOMING PACKETS +The incoming ND packet from the wire: +.Bd -literal + kernelspace ( userspace + ) + incoming SeND/ND packet ( + | ) + v ( SND_IN ) ( + icmp6_input() -> send_input_hook ---> send socket ----+ + : ) | + : # # ( | + normal : # # ) v + processing : # send.ko # ( SeND application + path : # # ) | + : # # ( | + v ) | + icmp6/nd6_??_input() <- protocol switch <--- send socket <---+ + | structure (IPPPROTO_SEND) ) + | ( SND_IN ) ( + v ) + continue normal ND processing ( +.Ed +.Sh OUTGOING PACKETS +Outgoing ND packet (reply or locally triggered): +.Bd -literal + kernelspace ( userspace + ) + nd6_na_input() ( + +PACKET_TAG_ND_OUTGOING ) + | ) + | outgoing packet ( + | | ) + | v ( + | icmp6_redirect_output() ) + | nd6_ns_output() ( + | nd6_na_output() ) + | +PACKET_TAG_ND_OUTGOING ( + | | ) + | +-----------<- rip6_output() <----------)----- rtsol/rtadvd/.. + | | +PACKET_TAG_ND_OUTGOING ( + | v ) + | ip6_output() ( + | | ) + +-------->-+ ( + | ) + v ( SND_OUT ) ( + nd6_output_lle() -> send_input_hook ---> send socket ----+ + -PACKET_TAG_ND_OUTGOING ) | + : # # ( | + normal : # # ) v + processing : # send.ko # ( SeND application + path : # # ) | + : # # ( | + v ) | + (*ifp->if_output)() <- protocol switch <--- send socket <---+ + | structure (IPPPROTO_SEND) ) + | ( SND_OUT ) ( + v ) + continue with normal packet output ( +.Ed +.Sh ERRORS +A socket operation may fail with one of the following errors returned: +.Bl -tag -width Er +.It Bq Er EEXIST +Another user space SeND application is bound to the socket. +.It Bq Er ENOBUFS +Shortage of space to receive the incoming (SeND-protected) or outgoing +(SeND-validated) packet from the SeND application. +.It Bq Er ENOSYS +A packet received from user space and passed to the NDP stack for further +processing is neither Neighbor Solicitation, Neighbor Advertisement, +Router Solicitation, Router Advertisement nor Redirect. +.It Bq Er ENOENT +Occurs if interface output routines fail to send the packet out of the +interface. +.El +.Sh SEE ALSO +.Xr recvfrom 2 +.Xr sendto 2 +.Xr socket 2 +.Xr loader.conf 5 +.Sh HISTORY +The +.Nm +module first appeared in +.Fx 9.0 . +.Sh AUTHORS +.An Ana Kukec Aq anchie@FreeBSD.org , +University of Zagreb +.Sh BUGS +Due to the lack of NDP locking, it is currently not possible to unload the +.Nm +module. -- cgit v1.1