path: root/static/netbsd/man4/ipsec.4 3.html

<table class="head">
  <tr>
    <td class="head-ltitle">IPSEC(4)</td>
    <td class="head-vol">Device Drivers Manual</td>
    <td class="head-rtitle">IPSEC(4)</td>
  </tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">ipsec</code> &#x2014; <span class="Nd">IP
    security protocol</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="Cd">options IPSEC</code>
  <br/>
  <code class="Cd">options IPSEC_DEBUG</code></p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">This manual page describes the IPsec protocol. For the network
    device driver please see <a class="Xr">ipsecif(4)</a>.</p>
<p class="Pp"><code class="Nm">ipsec</code> is a security protocol in the
    Internet Protocol (IP) layer. <code class="Nm">ipsec</code> is defined for
    both IPv4 and IPv6 (<a class="Xr">inet(4)</a> and
    <a class="Xr">inet6(4)</a>). <code class="Nm">ipsec</code> consists of three
    sub-protocols:</p>
<dl class="Bl-hang">
  <dt id="Encapsulated"><a class="permalink" href="#Encapsulated"><i class="Em">Encapsulated
    Security Payload</i></a> (ESP)</dt>
  <dd>protects IP payloads from wire-tapping (interception) by encrypting them
      with secret key cryptography algorithms.</dd>
  <dt id="Authentication"><a class="permalink" href="#Authentication"><i class="Em">Authentication
    Header</i></a> (AH)</dt>
  <dd>guarantees the integrity of IP packets and protects them from intermediate
      alteration or impersonation, by attaching cryptographic checksums computed
      by one-way hash functions.</dd>
  <dt id="IP"><a class="permalink" href="#IP"><i class="Em">IP Payload
    Compression Protocol</i></a> (IPComp)</dt>
  <dd>increases the communication performance by compressing the datagrams.</dd>
</dl>
<p class="Pp"><code class="Nm">ipsec</code> has two operation modes:</p>
<dl class="Bl-hang">
  <dt id="Transport"><a class="permalink" href="#Transport"><i class="Em">Transport
    mode</i></a></dt>
  <dd>is for protecting peer-to-peer communication between end nodes.</dd>
  <dt id="Tunnel"><a class="permalink" href="#Tunnel"><i class="Em">Tunnel
    mode</i></a></dt>
  <dd>includes IP-in-IP encapsulation operation and is designed for security
      gateways, as in Virtual Private Network (VPN) configurations.</dd>
</dl>
<section class="Ss">
<h2 class="Ss" id="Kernel_interface"><a class="permalink" href="#Kernel_interface">Kernel
  interface</a></h2>
<p class="Pp"><code class="Nm">ipsec</code> is controlled by two engines in the
    kernel: one for key management and one for policy.</p>
<p class="Pp">The key management engine can be accessed from userland by using
    <code class="Dv">PF_KEY</code> sockets. The <code class="Dv">PF_KEY</code>
    socket API is defined in RFC2367.</p>
<p class="Pp">The policy engine can be controlled through the
    <code class="Dv">PF_KEY</code> API, <a class="Xr">setsockopt(2)</a>
    operations, and the <a class="Xr">sysctl(3)</a> interface. The kernel
    implements an extended version of the <code class="Dv">PF_KEY</code>
    interface and allows you to define IPsec policy like per-packet filters.
    <a class="Xr">setsockopt(2)</a> is used to define per-socket behavior, and
    <a class="Xr">sysctl(3)</a> is used to define host-wide default
  behavior.</p>
<p class="Pp">The kernel does not implement dynamic encryption key exchange
    protocols like IKE (Internet Key Exchange). That should be done in userland
    (usually as a daemon), using the APIs described above.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Policy_management"><a class="permalink" href="#Policy_management">Policy
  management</a></h2>
<p class="Pp">The kernel implements experimental policy management code. You can
    manage the IPsec policy in two ways. One is to configure per-socket policy
    using <a class="Xr">setsockopt(2)</a>. The other is to configure kernel
    packet filter-based policy using the <code class="Dv">PF_KEY</code>
    interface, via <a class="Xr">setkey(8)</a>. In both cases, IPsec policy must
    be specified with syntax described in
  <a class="Xr">ipsec_set_policy(3)</a>.</p>
<p class="Pp">With <a class="Xr">setsockopt(2)</a>, you can define IPsec policy
    on a per-socket basis. You can enforce particular IPsec policy on packets
    that go through a particular socket.</p>
<p class="Pp">With <a class="Xr">setkey(8)</a> you can define IPsec policy for
    packets using a form of packet filtering rules. See
    <a class="Xr">setkey(8)</a> for details.</p>
<p class="Pp">In the latter case,
    &#x201C;<code class="Li">default</code>&#x201D; policy is allowed for use
    with <a class="Xr">setkey(8)</a>. By configuring policy to
    <code class="Li">default</code>, you can refer to system-wide
    <a class="Xr">sysctl(8)</a> variables for default settings. The following
    variables are available. <code class="Li">1</code> means
    &#x201C;<code class="Li">use</code>&#x201D;, and <code class="Li">2</code>
    means &#x201C;<code class="Li">require</code>&#x201D; in the syntax.</p>
<table class="Bl-column">
  <tr id="Name">
    <td><a class="permalink" href="#Name"><b class="Sy">Name</b></a></td>
    <td><a class="permalink" href="#Type"><b class="Sy" id="Type">Type</b></a></td>
    <td><a class="permalink" href="#Changeable"><b class="Sy" id="Changeable">Changeable</b></a></td>
  </tr>
  <tr>
    <td>net.inet.ipsec.esp_trans_deflev</td>
    <td>integer</td>
    <td>yes</td>
  </tr>
  <tr>
    <td>net.inet.ipsec.esp_net_deflev</td>
    <td>integer</td>
    <td>yes</td>
  </tr>
  <tr>
    <td>net.inet.ipsec.ah_trans_deflev</td>
    <td>integer</td>
    <td>yes</td>
  </tr>
  <tr>
    <td>net.inet.ipsec.ah_net_deflev</td>
    <td>integer</td>
    <td>yes</td>
  </tr>
  <tr>
    <td>net.inet6.ipsec6.esp_trans_deflev</td>
    <td>integer</td>
    <td>yes</td>
  </tr>
  <tr>
    <td>net.inet6.ipsec6.esp_net_deflev</td>
    <td>integer</td>
    <td>yes</td>
  </tr>
  <tr>
    <td>net.inet6.ipsec6.ah_trans_deflev</td>
    <td>integer</td>
    <td>yes</td>
  </tr>
  <tr>
    <td>net.inet6.ipsec6.ah_net_deflev</td>
    <td>integer</td>
    <td>yes</td>
  </tr>
</table>
<p class="Pp">If the kernel finds no matching policy, the system-wide default
    value is applied. System-wide defaults are specified by the following
    <a class="Xr">sysctl(8)</a> variables. <code class="Li">0</code> means
    &#x201C;<code class="Li">discard</code>&#x201D; which asks the kernel to
    drop the packet. <code class="Li">1</code> means
    &#x201C;<code class="Li">none</code>&#x201D;.</p>
<table class="Bl-column">
  <tr id="Name~2">
    <td><a class="permalink" href="#Name~2"><b class="Sy">Name</b></a></td>
    <td><a class="permalink" href="#Type~2"><b class="Sy" id="Type~2">Type</b></a></td>
    <td><a class="permalink" href="#Changeable~2"><b class="Sy" id="Changeable~2">Changeable</b></a></td>
  </tr>
  <tr>
    <td>net.inet.ipsec.def_policy</td>
    <td>integer</td>
    <td>yes</td>
  </tr>
  <tr>
    <td>net.inet6.ipsec6.def_policy</td>
    <td>integer</td>
    <td>yes</td>
  </tr>
</table>
</section>
<section class="Ss">
<h2 class="Ss" id="Miscellaneous_sysctl_variables"><a class="permalink" href="#Miscellaneous_sysctl_variables">Miscellaneous
  sysctl variables</a></h2>
<p class="Pp">The following variables are accessible via
    <a class="Xr">sysctl(8)</a>, for tweaking kernel IPsec behavior:</p>
<table class="Bl-column">
  <tr id="Name~3">
    <td><a class="permalink" href="#Name~3"><b class="Sy">Name</b></a></td>
    <td><a class="permalink" href="#Type~3"><b class="Sy" id="Type~3">Type</b></a></td>
    <td><a class="permalink" href="#Changeable~3"><b class="Sy" id="Changeable~3">Changeable</b></a></td>
  </tr>
  <tr>
    <td>net.inet.ipsec.ah_cleartos</td>
    <td>integer</td>
    <td>yes</td>
  </tr>
  <tr>
    <td>net.inet.ipsec.ah_offsetmask</td>
    <td>integer</td>
    <td>yes</td>
  </tr>
  <tr>
    <td>net.inet.ipsec.crypto_support</td>
    <td>integer</td>
    <td>yes</td>
  </tr>
  <tr>
    <td>net.inet.ipsec.dfbit</td>
    <td>integer</td>
    <td>yes</td>
  </tr>
  <tr>
    <td>net.inet.ipsec.ecn</td>
    <td>integer</td>
    <td>yes</td>
  </tr>
  <tr>
    <td>net.inet.ipsec.debug</td>
    <td>integer</td>
    <td>yes</td>
  </tr>
  <tr>
    <td>net.inet6.ipsec6.ecn</td>
    <td>integer</td>
    <td>yes</td>
  </tr>
  <tr>
    <td>net.inet6.ipsec6.debug</td>
    <td>integer</td>
    <td>yes</td>
  </tr>
</table>
<p class="Pp">The variables are interpreted as follows:</p>
<dl class="Bl-tag">
  <dt id="ipsec.ah_cleartos"><a class="permalink" href="#ipsec.ah_cleartos"><code class="Li">ipsec.ah_cleartos</code></a></dt>
  <dd>If set to non-zero, the kernel clears the type-of-service field in the
      IPv4 header during AH authentication data computation. The variable is for
      tweaking AH behavior to interoperate with devices that implement RFC1826
      AH. It should be set to non-zero (clear the type-of-service field) for
      RFC2402 conformance.</dd>
  <dt id="ipsec.ah_offsetmask"><a class="permalink" href="#ipsec.ah_offsetmask"><code class="Li">ipsec.ah_offsetmask</code></a></dt>
  <dd>During AH authentication data computation, the kernel will include a 16
      bit fragment offset field (including flag bits) in the IPv4 header, after
      computing logical AND with the variable. The variable is for tweaking AH
      behavior to interoperate with devices that implement RFC1826 AH. It should
      be set to zero (clear the fragment offset field during computation) for
      RFC2402 conformance.</dd>
  <dt id="ipsec.crypto_support"><a class="permalink" href="#ipsec.crypto_support"><code class="Li">ipsec.crypto_support</code></a></dt>
  <dd>This variable configures the kernel behavior for selecting encryption
      drivers. If set to &gt; 0, the kernel will select a hardware encryption
      driver first. If set to &lt; 0, the kernel will select a software
      encryption driver first. If set to 0, the kernel will select either a
      hardware or software driver.</dd>
  <dt id="ipsec.dfbit"><a class="permalink" href="#ipsec.dfbit"><code class="Li">ipsec.dfbit</code></a></dt>
  <dd>This variable configures the kernel behavior on IPv4 IPsec tunnel
      encapsulation. If set to 0, the DF bit on the outer IPv4 header will be
      cleared. 1 means that the outer DF bit is set from the inner DF bit. 2
      means that the DF bit is copied from the inner header to the outer. The
      variable is supplied to conform to RFC2401 chapter 6.1.</dd>
  <dt id="ipsec.ecn"><a class="permalink" href="#ipsec.ecn"><code class="Li">ipsec.ecn</code></a></dt>
  <dd>If set to non-zero, IPv4 IPsec tunnel encapsulation/decapsulation behavior
      will be friendly to ECN (explicit congestion notification), as documented
      in <code class="Li">draft-ietf-ipsec-ecn-02.txt</code>.
      <a class="Xr">gif(4)</a> talks more about the behavior.</dd>
  <dt id="ipsec.debug"><a class="permalink" href="#ipsec.debug"><code class="Li">ipsec.debug</code></a></dt>
  <dd>If set to non-zero, debug messages will be generated via
      <a class="Xr">syslog(3)</a>.</dd>
</dl>
<p class="Pp">Variables under the <code class="Li">net.inet6.ipsec6</code> tree
    have similar meanings to their <code class="Li">net.inet.ipsec</code>
    counterparts.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Cryptographic_operations"><a class="permalink" href="#Cryptographic_operations">Cryptographic
  operations</a></h2>
<p class="Pp">The current IPsec implementation, formerly called Fast IPsec, uses
    the <a class="Xr">opencrypto(9)</a> subsystem to carry out cryptographic
    operations. This means, in particular, that cryptographic hardware devices
    are employed whenever possible to optimize the performance of
  sub-protocols.</p>
<p class="Pp">System configuration requires the <a class="Xr">opencrypto(9)</a>
    subsystem. When the Fast IPsec protocols are configured for use, all
    protocols are included in the system. To selectively enable/disable
    protocols, use <a class="Xr">sysctl(8)</a>.</p>
</section>
</section>
<section class="Sh">
<h1 class="Sh" id="PROTOCOLS"><a class="permalink" href="#PROTOCOLS">PROTOCOLS</a></h1>
<p class="Pp">The <code class="Nm">ipsec</code> protocol works like a plug-in to
    <a class="Xr">inet(4)</a> and <a class="Xr">inet6(4)</a> protocols.
    Therefore, <code class="Nm">ipsec</code> supports most of the protocols
    defined upon those IP-layer protocols. Some of the protocols, like
    <a class="Xr">icmp(4)</a> or <a class="Xr">icmp6(4)</a>, may behave
    differently with <code class="Nm">ipsec</code>. This is because
    <code class="Nm">ipsec</code> can prevent <a class="Xr">icmp(4)</a> or
    <a class="Xr">icmp6(4)</a> routines from looking into IP payload.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
  ALSO</a></h1>
<p class="Pp"><a class="Xr">ioctl(2)</a>, <a class="Xr">socket(2)</a>,
    <a class="Xr">ipsec_set_policy(3)</a>, <a class="Xr">icmp6(4)</a>,
    <a class="Xr">intro(4)</a>, <a class="Xr">ip6(4)</a>,
    <a class="Xr">ipsecif(4)</a>, <a class="Xr">racoon(8)</a>,
    <a class="Xr">setkey(8)</a>, <a class="Xr">sysctl(8)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="STANDARDS"><a class="permalink" href="#STANDARDS">STANDARDS</a></h1>
<p class="Pp"><cite class="Rs"><span class="RsA">Daniel L. McDonald</span>,
    <span class="RsA">Craig Metz</span>, and <span class="RsA">Bao G.
    Phan</span>, <span class="RsT">PF_KEY Key Management API, Version 2</span>,
    <span class="RsR">RFC</span>, <span class="RsN">2367</span>.</cite></p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">The protocols draw heavily on the <span class="Ux">OpenBSD</span>
    implementation of the IPsec protocols. The policy management code is derived
    from the KAME implementation found in their IPsec protocols. The Fast IPsec
    protocols are based on code which appeared in <span class="Ux">FreeBSD
    4.7</span>. The <span class="Ux">NetBSD</span> version is a close copy of
    the <span class="Ux">FreeBSD</span> original, and first appeared in
    <span class="Ux">NetBSD 2.0</span>.</p>
<p class="Pp">Support for IPv6 and IPcomp protocols has been added in
    <span class="Ux">NetBSD 4.0</span>.</p>
<p class="Pp">Support for Network Address Translator Traversal as described in
    RFCs 3947 and 3948 has been added in <span class="Ux">NetBSD 5.0</span>.</p>
<p class="Pp">Since <span class="Ux">NetBSD 6.0</span>, the IPsec implementation
    formerly known as Fast IPsec is used.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1>
<p class="Pp">IPsec support is subject to change as the IPsec protocols
  develop.</p>
<p class="Pp">There is no single standard for policy engine API, so the policy
    engine API described herein is just for the version introduced by KAME.</p>
<p class="Pp">AH and tunnel mode encapsulation may not work as you might expect.
    If you configure inbound &#x201C;require&#x201D; policy against AH tunnel or
    any IPsec encapsulating policy with AH (like
    &#x201C;<code class="Li">esp/tunnel/A-B/use
    ah/transport/A-B/require</code>&#x201D;), tunneled packets will be rejected.
    This is because we enforce policy check on inner packet on reception, and AH
    authenticates encapsulating (outer) packet, not the encapsulated (inner)
    packet (so for the receiving kernel there's no sign of authenticity). The
    issue will be solved when we revamp our policy engine to keep all the packet
    decapsulation history.</p>
<p class="Pp">Under certain conditions, truncated results may be raised from the
    kernel against <code class="Dv">SADB_DUMP</code> and
    <code class="Dv">SADB_SPDDUMP</code> operations on
    <code class="Dv">PF_KEY</code> sockets. This occurs if there are too many
    database entries in the kernel and socket buffer for the
    <code class="Dv">PF_KEY</code> socket is insufficient. If you manipulate
    many IPsec key/policy database entries, increase the size of socket buffer
    or use <a class="Xr">sysctl(8)</a> interface.</p>
<p class="Pp">Certain legacy authentication algorithms are not supported because
    of issues with the <a class="Xr">opencrypto(9)</a> subsystem.</p>
</section>
</div>
<table class="foot">
  <tr>
    <td class="foot-date">June 13, 2018</td>
    <td class="foot-os">NetBSD 10.1</td>
  </tr>
</table>