.\" $NetBSD: ipsecif.4,v 1.5 2018/01/25 09:29:18 maxv Exp $
.\"
.\" Copyright (C) 2017 Internet Initiative Japan Inc.
.\" 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.
.\" 3. Neither the name of the project nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT 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 PROJECT 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.
.\"
.Dd January 25, 2018
.Dt IPSECIF 4
.Os
.Sh NAME
.Nm ipsecif
.Nd IPsec interface
.Sh SYNOPSIS
.Cd "pseudo-device ipsecif"
.Sh DESCRIPTION
The
.Nm
interface is targeted for route-based VPNs.
It can tunnel IPv4 and IPv6 traffic over either IPv4 or IPv6 and
secure it with ESP.
.Pp
.Nm
interfaces are dynamically created and destroyed with the
.Xr ifconfig 8
.Cm create
and
.Cm destroy
subcommands.
The administrator must configure
.Nm
tunnel endpoint addresses.
These addresses will be used for the outer IP header of ESP packets.
The administrator also configures the protocol
and addresses for the inner IP header with the
.Xr ifconfig 8
.Cm inet
or
.Cm inet6
subcommands, and modify the routing table to route the packets through
the
.Nm
interface.
.Pp
The packet processing is similar to
.Xr gif 4
over
.Xr ipsec 4
transport mode, however the security policy management is different.
.Xr gif 4
over
.Xr ipsec 4
transport mode expects userland programs to manage their
security policies.
In contrast,
.Nm
manages its security policies by itself: when the administrator
sets up an
.Nm
tunnel source and destination address pair, the related security policies
are created automatically in the kernel.
They are automatically deleted when the tunnel is destroyed.
.Pp
It also means that
.Nm
ensures that both the in and out security policy pairs exist, that is,
.Nm
avoids the trouble caused when only one of the in and out security
policy pair exists.
.Pp
There are four security policies generated by
.Nm :
one in and out pair for IPv4 and IPv6 each.
These security policies are equivalent to the following
.Xr ipsec.conf 5
configuration where src and dst are IP addresses specified to the tunnel:
.Bd -literal -offset indent
spdadd "src" "dst" ipv4 -P out ipsec esp/transport//unique;
spdadd "dst" "src" ipv4 -P in ipsec esp/transport//unique;
spdadd "src" "dst" ipv6 -P out ipsec esp/transport//unique;
spdadd "dst" "src" ipv6 -P in ipsec esp/transport//unique;
.Ed
.Pp
The
.Nm
configuration will fail if such security policies already exist, and
vice versa.
.Pp
The related security associates can be established by an IKE daemon such as
.Xr racoon 8 .
They can also be manipulated manually by
.Xr setkey 8
with the
.Fl u
option which sets a security policy's unique id.
.Pp
Some
.Xr ifconfig 8
parameters change the behaviour of
.Nm .
link0 can enable NAT-Traversal,
link1 can enable ECN friendly mode like
.Xr gif 4 ,
and link2 can enable forwarding inner IPv6 packets.
Only link2 is set by default.
If you use only IPv4 packets as inner packets, you would want to
do
.Bd -literal -offset indent
ifconfig ipsec0 -link2
.Ed
.Pp
to reduce security associates for IPv6 packets.
.Sh EXAMPLES
Configuration example:
.Bd -literal
Out IP addr = 172.16.100.1 Out IP addr = 172.16.200.1
wm0 = 192.168.0.1/24 wm0 = 192.168.0.2/24
wm1 = 10.100.0.1/24 wm1 = 10.200.0.1/24
+------------+ +------------+
| NetBSD_A | | NetBSD_B |
|------------| |------------|
| [ipsec0] - - - - - - - - (tunnel) - - - - - - - - [ipsec0] |
| [wm0]------------- ... --------------[wm0] |
| | | |
+---[wm1]----+ +----[wm1]---+
| |
| |
+------------+ +------------+
| Host_X | | Host_Y |
+------------+ +------------+
.Ed
.Pp
Host_X and Host_Y will be able to communicate via an IPv4 IPsec
tunnel.
.Pp
On NetBSD_A:
.Bd -literal
# ifconfig wm0 inet 192.168.0.1/24
# ifconfig ipsec0 create
# ifconfig ipsec0 tunnel 192.168.0.1 192.168.0.2
# ifconfig ipsec0 inet 172.16.100.1/32 172.16.200.1
start IKE daemon or set security associates manually.
# ifconfig wm1 inet 10.100.0.1/24
# route add 10.200.0.1 172.16.100.1
.Ed
.Pp
On NetBSD_B:
.Bd -literal
# ifconfig wm0 inet 192.168.0.2/24
# ifconfig ipsec0 create
# ifconfig ipsec0 tunnel 192.168.0.2 192.168.0.1
# ifconfig ipsec0 inet 172.16.200.1/32 172.16.100.1
start IKE daemon or set security associates manually.
# ifconfig wm1 inet 10.200.0.1/24
# route add 10.100.0.1 172.16.200.1
.Ed
.Sh SEE ALSO
.Xr gif 4 ,
.Xr inet 4 ,
.Xr inet6 4 ,
.Xr ipsec 4 ,
.Xr ifconfig 8 ,
.Xr racoon 8 ,
.Xr setkey 8
.Sh HISTORY
The
.Nm
device first appeared in
.Nx 8.0 .
.Sh LIMITATIONS
Currently, the
.Nm
interface supports the ESP protocol only.
.Nm
supports default port number (4500) only for NAT-Traversal.