diff options
Diffstat (limited to 'static/freebsd/man4/ipsec.4 3.html')
| -rw-r--r-- | static/freebsd/man4/ipsec.4 3.html | 423 |
1 files changed, 423 insertions, 0 deletions
diff --git a/static/freebsd/man4/ipsec.4 3.html b/static/freebsd/man4/ipsec.4 3.html new file mode 100644 index 00000000..c5768845 --- /dev/null +++ b/static/freebsd/man4/ipsec.4 3.html @@ -0,0 +1,423 @@ +<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> — <span class="Nd">Internet + Protocol 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_SUPPORT</code> + <br/> + <code class="Cd">device crypto</code></p> +<p class="Pp"> + <br/> + <code class="In">#include <<a class="In">sys/types.h</a>></code> + <br/> + <code class="In">#include <<a class="In">netinet/in.h</a>></code> + <br/> + <code class="In">#include <<a class="In">netipsec/ipsec.h</a>></code> + <br/> + <code class="In">#include + <<a class="In">netipsec/ipsec6.h</a>></code></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp"><code class="Nm">ipsec</code> is a security protocol implemented + within the Internet Protocol layer of the networking stack. + <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> is a set of protocols, ESP (for Encapsulating + Security Payload) AH (for Authentication Header), and IPComp (for IP Payload + Compression Protocol) that provide security services for IP datagrams. AH + both authenticates and guarantees the integrity of an IP packet by attaching + a cryptographic checksum computed using one-way hash functions. ESP, in + addition, prevents unauthorized parties from reading the payload of an IP + packet by also encrypting it. IPComp tries to increase communication + performance by compressing IP payload, thus reducing the amount of data + sent. This will help nodes on slow links but with enough computing power. + <code class="Nm">ipsec</code> operates in one of two modes: transport mode + or tunnel mode. Transport mode is used to protect peer-to-peer communication + between end nodes. Tunnel mode encapsulates IP packets within other IP + packets and is designed for security gateways such as VPN endpoints.</p> +<p class="Pp">System configuration requires the <a class="Xr">crypto(4)</a> + subsystem.</p> +<p class="Pp">The packets can be passed to a virtual <a class="Xr">enc(4)</a> + interface, to perform packet filtering before outbound encryption and after + decapsulation inbound.</p> +<p class="Pp">To properly filter on the inner packets of an + <code class="Nm">ipsec</code> tunnel with firewalls, you can change the + values of the following sysctls</p> +<table class="Bl-column"> + <tr id="Name"> + <td><a class="permalink" href="#Name"><b class="Sy">Name</b></a></td> + <td>Default</td> + <td>Enable</td> + </tr> + <tr> + <td>net.inet.ipsec.filtertunnel</td> + <td>0</td> + <td>1</td> + </tr> + <tr> + <td>net.inet6.ipsec6.filtertunnel</td> + <td>0</td> + <td>1</td> + </tr> +</table> +<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 a key management + and policy engine, that reside in the operating system kernel. Key + management is the process of associating keys with security associations, + also know as SAs. Policy management dictates when new security associations + created or destroyed.</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 is controlled by an extension to the + <code class="Dv">PF_KEY</code> API, <a class="Xr">setsockopt(2)</a> + operations, and <a class="Xr">sysctl(3)</a> interface. The kernel implements + an extended version of the <code class="Dv">PF_KEY</code> interface and + allows the programmer to define IPsec policies which are similar to the + per-packet filters. The <a class="Xr">setsockopt(2)</a> interface is used to + define per-socket behavior, and <a class="Xr">sysctl(3)</a> interface is + used to define host-wide default behavior.</p> +<p class="Pp">The kernel code does not implement a dynamic encryption key + exchange protocol such as IKE (Internet Key Exchange). Key exchange + protocols are beyond what is necessary in the kernel and should be + implemented as daemon processes which call the + <code class="Nm">APIs.</code></p> +</section> +<section class="Ss"> +<h2 class="Ss" id="Policy_management"><a class="permalink" href="#Policy_management">Policy + management</a></h2> +<p class="Pp">IPsec policies can be managed in one of two ways, either by + configuring per-socket policies using the <a class="Xr">setsockopt(2)</a> + system calls, or by configuring kernel level packet filter-based policies + using the <code class="Dv">PF_KEY</code> interface, via the + <a class="Xr">setkey(8)</a> you can define IPsec policies against packets + using rules similar to packet filtering rules. Refer to + <a class="Xr">setkey(8)</a> on how to use it.</p> +<p class="Pp">Depending on the socket's address family, IPPROTO_IP or + IPPROTO_IPV6 transport level and IP_IPSEC_POLICY or IPV6_IPSEC_POLICY socket + options may be used to configure per-socket security policies. A + properly-formed IPsec policy specification structure can be created using + <a class="Xr">ipsec_set_policy(3)</a> function and used as socket option + value for the <a class="Xr">setsockopt(2)</a> call.</p> +<p class="Pp">When setting policies using the <a class="Xr">setkey(8)</a> + command, the “<code class="Li">default</code>” option + instructs the system to use its default policy, as explained below, for + processing packets. The following sysctl variables are available for + configuring the system's IPsec behavior. The variables can have one of two + values. A <code class="Li">1</code> means + “<code class="Li">use</code>”, which means that if there is a + security association then use it but if there is not then the packets are + not processed by IPsec. The value <code class="Li">2</code> is synonymous + with “<code class="Li">require</code>”, which requires that a + security association must exist for the packets to move, and not be dropped. + These terms are defined in <a class="Xr">ipsec_set_policy(3)</a>.</p> +<table class="Bl-column"> + <tr id="Name~2"> + <td><a class="permalink" href="#Name~2"><b class="Sy">Name</b></a></td> + <td>Type</td> + <td>Changeable</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 does not find a matching, system wide, policy then + the default value is applied. The system wide default policy is specified by + the following <a class="Xr">sysctl(8)</a> variables. + <code class="Li">0</code> means + “<code class="Li">discard</code>” which asks the kernel to + drop the packet. <code class="Li">1</code> means + “<code class="Li">none</code>”.</p> +<table class="Bl-column"> + <tr id="Name~3"> + <td><a class="permalink" href="#Name~3"><b class="Sy">Name</b></a></td> + <td>Type</td> + <td>Changeable</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">When the <code class="Nm">ipsec</code> 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> +<table class="Bl-column"> + <tr id="Name~4"> + <td><a class="permalink" href="#Name~4"><b class="Sy">Name</b></a></td> + <td>Default</td> + </tr> + <tr> + <td>net.inet.esp.esp_enable</td> + <td>On</td> + </tr> + <tr> + <td>net.inet.ah.ah_enable</td> + <td>On</td> + </tr> + <tr> + <td>net.inet.ipcomp.ipcomp_enable</td> + <td>On</td> + </tr> +</table> +<p class="Pp">In addition the following variables are accessible via + <a class="Xr">sysctl(8)</a>, for tweaking the kernel's IPsec behavior:</p> +<table class="Bl-column"> + <tr id="Name~5"> + <td><a class="permalink" href="#Name~5"><b class="Sy">Name</b></a></td> + <td>Type</td> + <td>Changeable</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.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.inet.ipsec.natt_cksum_policy</td> + <td>integer</td> + <td>yes</td> + </tr> + <tr> + <td>net.inet.ipsec.check_policy_history</td> + <td>integer</td> + <td>yes</td> + </tr> + <tr> + <td>net.inet.ipsec.random_id</td> + <td></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. This variable is + used to get current systems to inter-operate 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 16bit + fragment offset field (including flag bits) in the IPv4 header, after + computing logical AND with the variable. The variable is used for + inter-operating 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.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 while 1 means that the outer DF bit is set regardless from the + inner DF bit and 2 indicates that the DF bit is copied from the inner + header to the outer one. 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> + <dt id="ipsec.natt_cksum_policy"><a class="permalink" href="#ipsec.natt_cksum_policy"><code class="Li">ipsec.natt_cksum_policy</code></a></dt> + <dd>Controls how the kernel handles TCP and UDP checksums when ESP in UDP + encapsulation is used for IPsec transport mode. If set to a non-zero + value, the kernel fully recomputes checksums for inbound TCP segments and + UDP datagrams after they are decapsulated and decrypted. If set to 0 and + original addresses were configured for corresponding SA by the IKE daemon, + the kernel incrementally recomputes checksums for inbound TCP segments and + UDP datagrams. If addresses were not configured, the checksums are + ignored.</dd> + <dt id="ipsec.check_policy_history"><a class="permalink" href="#ipsec.check_policy_history"><code class="Li">ipsec.check_policy_history</code></a></dt> + <dd>Enables strict policy checking for inbound packets. By default, inbound + security policies check that packets handled by IPsec have been decrypted + and authenticated. If this variable is set to a non-zero value, each + packet handled by IPsec is checked against the history of IPsec security + associations. The IPsec security protocol, mode, and SA addresses must + match.</dd> + <dt id="ipsec.random_id"><a class="permalink" href="#ipsec.random_id"><code class="Li">ipsec.random_id</code></a></dt> + <dd>Enables randomization of encapsulated IPv4 packets ID. By default, ID + randomization is not enabled.</dd> +</dl> +<p class="Pp">Variables under the <code class="Li">net.inet6.ipsec6</code> tree + have similar meanings to those described above.</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 acts as a plug-in to + the <a class="Xr">inet(4)</a> and <a class="Xr">inet6(4)</a> protocols and + therefore supports most of the protocols defined upon those IP-layer + protocols. The <a class="Xr">icmp(4)</a> and <a class="Xr">icmp6(4)</a> + protocols may behave differently with <code class="Nm">ipsec</code> 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 the 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">crypto(4)</a>, + <a class="Xr">enc(4)</a>, <a class="Xr">icmp6(4)</a>, + <a class="Xr">if_ipsec(4)</a>, <a class="Xr">intro(4)</a>, + <a class="Xr">ip6(4)</a>, <a class="Xr">setkey(8)</a>, + <a class="Xr">sysctl(8)</a></p> +<p class="Pp"><cite class="Rs"><span class="RsA">S. Kent</span> and + <span class="RsA">R. Atkinson</span>, <span class="RsT">IP Authentication + Header</span>, <span class="RsO">RFC 2404</span>.</cite></p> +<p class="Pp"><cite class="Rs"><span class="RsA">S. Kent</span> and + <span class="RsA">R. Atkinson</span>, <span class="RsT">IP Encapsulating + Security Payload (ESP)</span>, <span class="RsO">RFC 2406</span>.</cite></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> +<p class="Pp"><cite class="Rs"><span class="RsA">D. L. McDonald</span>, + <span class="RsT">A Simple IP Security API Extension to BSD Sockets</span>, + <span class="RsR">internet draft</span>, + <span class="RsN">draft-mcdonald-simple-ipsec-api-03.txt</span>, + <span class="RsO">work in progress material</span>.</cite></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The original <code class="Nm">ipsec</code> implementation appeared + in the WIDE/KAME IPv6/IPsec stack.</p> +<p class="Pp">For <span class="Ux">FreeBSD 5.0</span> a fully locked IPsec + implementation called fast_ipsec was brought in. The protocols drew heavily + on the <span class="Ux">OpenBSD</span> implementation of the IPsec + protocols. The policy management code was derived from the KAME + implementation found in their IPsec protocols. The fast_ipsec implementation + lacked <a class="Xr">ip6(4)</a> support but made use of the + <a class="Xr">crypto(4)</a> subsystem.</p> +<p class="Pp">For <span class="Ux">FreeBSD 7.0</span> <a class="Xr">ip6(4)</a> + support was added to fast_ipsec. After this the old KAME IPsec + implementation was dropped and fast_ipsec became what now is the only + <code class="Nm">ipsec</code> implementation in + <span class="Ux">FreeBSD</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1> +<p class="Pp">There is no single standard for the policy engine API, so the + policy engine API described herein is just for this implementation.</p> +<p class="Pp">AH and tunnel mode encapsulation may not work as you might expect. + If you configure inbound “require” policy with an AH tunnel or + any IPsec encapsulating policy with AH (like + “<code class="Li">esp/tunnel/A-B/use + ah/transport/A-B/require</code>”), tunnelled packets will be + rejected. This is because the policy check is enforced on the inner packet + on reception, and AH authenticates encapsulating (outer) packet, not the + encapsulated (inner) packet (so for the receiving kernel there is 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">When a large database of security associations or policies is + present in the kernel the <code class="Dv">SADB_DUMP</code> and + <code class="Dv">SADB_SPDDUMP</code> operations on + <code class="Dv">PF_KEY</code> sockets may fail due to lack of space. + Increasing the socket buffer size may alleviate this problem.</p> +<p class="Pp">The IPcomp protocol may occasionally error because of + <a class="Xr">zlib(3)</a> problems.</p> +<p class="Pp">This documentation needs more review.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">March 4, 2025</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |