218 lines
8.6 KiB
Groff
218 lines
8.6 KiB
Groff
|
.\"-
|
||
|
|
.\" 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.
|
||
|
|
.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.
|