feat: Added NetBSD man pages

1 files changed, 397 insertions, 0 deletions

diff --git a/static/netbsd/man4/ipsec.4 b/static/netbsd/man4/ipsec.4
new file mode 100644
index 00000000..bc1072a0
--- /dev/null
+++ b/static/netbsd/man4/ipsec.4
@@ -0,0 +1,397 @@
+.\"	$NetBSD: ipsec.4,v 1.46 2024/03/18 22:47:19 gutteridge Exp $
+.\"	$KAME: ipsec.4,v 1.17 2001/06/27 15:25:10 itojun Exp $
+.\"
+.\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project.
+.\" 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 June 13, 2018
+.Dt IPSEC 4
+.Os
+.Sh NAME
+.Nm ipsec
+.Nd IP security protocol
+.Sh SYNOPSIS
+.Cd "options IPSEC"
+.Cd "options IPSEC_DEBUG"
+.Sh DESCRIPTION
+This manual page describes the IPsec protocol.
+For the network device driver please see
+.Xr ipsecif 4 .
+.Pp
+.Nm
+is a security protocol in the Internet Protocol (IP) layer.
+.Nm
+is defined for both IPv4 and IPv6
+.Po
+.Xr inet 4
+and
+.Xr inet6 4
+.Pc .
+.Nm
+consists of three sub-protocols:
+.Bl -hang
+.It Em Encapsulated Security Payload Pq ESP
+protects IP payloads from wire-tapping (interception) by encrypting them with
+secret key cryptography algorithms.
+.It Em Authentication Header Pq AH
+guarantees the integrity of IP packets
+and protects them from intermediate alteration or impersonation,
+by attaching cryptographic checksums computed by one-way hash functions.
+.It Em IP Payload Compression Protocol Pq IPComp
+increases the communication performance by compressing the datagrams.
+.El
+.Pp
+.Nm
+has two operation modes:
+.Bl -hang
+.It Em Transport mode
+is for protecting peer-to-peer communication between end nodes.
+.It Em Tunnel mode
+includes IP-in-IP encapsulation operation
+and is designed for security gateways, as in Virtual Private Network (VPN)
+configurations.
+.El
+.Ss Kernel interface
+.Nm
+is controlled by two engines in the kernel: one for key management
+and one for policy.
+.Pp
+The key management engine can be accessed from userland by using
+.Dv PF_KEY
+sockets.
+The
+.Dv PF_KEY
+socket API is defined in RFC2367.
+.Pp
+The policy engine can be controlled through the
+.Dv PF_KEY
+API,
+.Xr setsockopt 2
+operations, and
+the
+.Xr sysctl 3
+interface.
+The kernel implements an
+extended version of the
+.Dv PF_KEY
+interface and allows you to define IPsec policy like per-packet filters.
+.Xr setsockopt 2
+is used to define per-socket behavior, and
+.Xr sysctl 3
+is used to define host-wide default behavior.
+.Pp
+The kernel does not implement dynamic encryption key exchange protocols
+like IKE
+.Pq Internet Key Exchange .
+That should be done in userland
+.Pq usually as a daemon ,
+using the APIs described above.
+.\"
+.Ss Policy management
+The kernel implements experimental policy management code.
+You can manage the IPsec policy in two ways.
+One is to configure per-socket policy using
+.Xr setsockopt 2 .
+The other is to configure kernel packet filter-based policy using the
+.Dv PF_KEY
+interface, via
+.Xr setkey 8 .
+In both cases, IPsec policy must be specified with syntax described in
+.Xr ipsec_set_policy 3 .
+.Pp
+With
+.Xr setsockopt 2 ,
+you can define IPsec policy on a per-socket basis.
+You can enforce particular IPsec policy on packets that go through a
+particular socket.
+.Pp
+With
+.Xr setkey 8
+you can define IPsec policy for packets using a form of packet
+filtering rules.
+See
+.Xr setkey 8
+for details.
+.Pp
+In the latter case,
+.Dq Li default
+policy is allowed for use with
+.Xr setkey 8 .
+By configuring policy to
+.Li default ,
+you can refer to system-wide
+.Xr sysctl 8
+variables for default settings.
+The following variables are available.
+.Li 1
+means
+.Dq Li use ,
+and
+.Li 2
+means
+.Dq Li require
+in the syntax.
+.Bl -column net.inet6.ipsec6.esp_trans_deflev integerxxx
+.It Sy Name Ta Sy Type Ta Sy Changeable
+.It net.inet.ipsec.esp_trans_deflev Ta integer Ta yes
+.It net.inet.ipsec.esp_net_deflev Ta integer Ta yes
+.It net.inet.ipsec.ah_trans_deflev Ta integer Ta yes
+.It net.inet.ipsec.ah_net_deflev Ta integer Ta yes
+.It net.inet6.ipsec6.esp_trans_deflev Ta integer Ta yes
+.It net.inet6.ipsec6.esp_net_deflev Ta integer Ta yes
+.It net.inet6.ipsec6.ah_trans_deflev Ta integer Ta yes
+.It net.inet6.ipsec6.ah_net_deflev Ta integer Ta yes
+.El
+.Pp
+If the kernel finds no matching policy, the system-wide default
+value is applied.
+System-wide defaults are specified by the following
+.Xr sysctl 8
+variables.
+.Li 0
+means
+.Dq Li discard
+which asks the kernel to drop the packet.
+.Li 1
+means
+.Dq Li none .
+.Bl -column net.inet6.ipsec6.esp_trans_deflev integerxxx
+.It Sy Name Ta Sy Type Ta Sy Changeable
+.It net.inet.ipsec.def_policy Ta integer Ta yes
+.It net.inet6.ipsec6.def_policy Ta integer Ta yes
+.El
+.\"
+.Ss Miscellaneous sysctl variables
+The following variables are accessible via
+.Xr sysctl 8 ,
+for tweaking kernel IPsec behavior:
+.Bl -column net.inet6.ipsec6.esp_trans_deflev integerxxx
+.It Sy Name Ta Sy Type Ta Sy Changeable
+.It net.inet.ipsec.ah_cleartos Ta integer Ta yes
+.It net.inet.ipsec.ah_offsetmask Ta integer Ta yes
+.It net.inet.ipsec.crypto_support Ta integer Ta yes
+.It net.inet.ipsec.dfbit Ta integer Ta yes
+.It net.inet.ipsec.ecn Ta integer Ta yes
+.It net.inet.ipsec.debug Ta integer Ta yes
+.It net.inet6.ipsec6.ecn Ta integer Ta yes
+.It net.inet6.ipsec6.debug Ta integer Ta yes
+.El
+.Pp
+The variables are interpreted as follows:
+.Bl -tag -width "123456"
+.It Li ipsec.ah_cleartos
+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
+.Pq clear the type-of-service field
+for RFC2402 conformance.
+.It Li ipsec.ah_offsetmask
+During AH authentication data computation, the kernel will include a
+16 bit fragment offset field
+.Pq 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
+.Pq clear the fragment offset field during computation
+for RFC2402 conformance.
+.It Li ipsec.crypto_support
+This variable configures the kernel behavior for selecting encryption drivers.
+If set to > 0, the kernel will select a hardware encryption driver first.
+If set to < 0, the kernel will select a software encryption driver first.
+If set to 0, the kernel will select either a hardware or software driver.
+.It Li ipsec.dfbit
+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.
+.It Li ipsec.ecn
+If set to non-zero, IPv4 IPsec tunnel encapsulation/decapsulation behavior will
+be friendly to ECN
+.Pq explicit congestion notification ,
+as documented in
+.Li draft-ietf-ipsec-ecn-02.txt .
+.Xr gif 4
+talks more about the behavior.
+.It Li ipsec.debug
+If set to non-zero, debug messages will be generated via
+.Xr syslog 3 .
+.El
+.Pp
+Variables under the
+.Li net.inet6.ipsec6
+tree have similar meanings to their
+.Li net.inet.ipsec
+counterparts.
+.Ss Cryptographic operations
+The current IPsec implementation, formerly called Fast IPsec,
+uses the
+.Xr opencrypto 9
+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.
+.Pp
+System configuration requires the
+.Xr opencrypto 9
+subsystem.
+When the
+Fast IPsec
+protocols are configured for use, all protocols are included in the system.
+To selectively enable/disable protocols, use
+.Xr sysctl 8 .
+.\"
+.Sh PROTOCOLS
+The
+.Nm
+protocol works like a plug-in to
+.Xr inet 4
+and
+.Xr inet6 4
+protocols.
+Therefore,
+.Nm
+supports most of the protocols defined upon those IP-layer protocols.
+Some of the protocols, like
+.Xr icmp 4
+or
+.Xr icmp6 4 ,
+may behave differently with
+.Nm ipsec .
+This is because
+.Nm
+can prevent
+.Xr icmp 4
+or
+.Xr icmp6 4
+routines from looking into IP payload.
+.\"
+.Sh SEE ALSO
+.Xr ioctl 2 ,
+.Xr socket 2 ,
+.Xr ipsec_set_policy 3 ,
+.Xr icmp6 4 ,
+.Xr intro 4 ,
+.Xr ip6 4 ,
+.Xr ipsecif 4 ,
+.Xr racoon 8 ,
+.Xr setkey 8 ,
+.Xr sysctl 8
+.Sh STANDARDS
+.Rs
+.%A Daniel L. McDonald
+.%A Craig Metz
+.%A Bao G. Phan
+.%T "PF_KEY Key Management API, Version 2"
+.%R RFC
+.%N 2367
+.Re
+.Sh HISTORY
+The protocols draw heavily on the
+.Ox
+implementation of the
+.Tn IPsec
+protocols.
+The policy management code is derived from the
+.Tn KAME
+implementation found in their
+.Tn IPsec
+protocols.
+The
+Fast IPsec
+protocols are based on code which appeared in
+.Fx 4.7 .
+The
+.Nx
+version is a close copy of the
+.Fx
+original, and first appeared in
+.Nx 2.0 .
+.Pp
+Support for IPv6 and
+.Tn IPcomp
+protocols has been added in
+.Nx 4.0 .
+.Pp
+Support for Network Address Translator Traversal as
+described in RFCs 3947 and 3948 has been added in
+.Nx 5.0 .
+.Pp
+Since
+.Nx 6.0 ,
+the IPsec implementation formerly known as Fast IPsec is used.
+.Sh BUGS
+IPsec support is subject to change as the IPsec protocols develop.
+.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.
+.Pp
+AH and tunnel mode encapsulation may not work as you might expect.
+If you configure inbound
+.Dq require
+policy against AH tunnel or any IPsec encapsulating policy with AH
+.Po
+like
+.Dq Li esp/tunnel/A-B/use ah/transport/A-B/require
+.Pc ,
+tunneled packets will be rejected.
+This is because we enforce policy check on inner packet on reception,
+and AH authenticates encapsulating
+.Pq outer
+packet, not the encapsulated
+.Pq inner
+packet
+.Po
+so for the receiving kernel there's no sign of authenticity
+.Pc .
+The issue will be solved when we revamp our policy engine to keep all the
+packet decapsulation history.
+.Pp
+Under certain conditions, truncated results may be raised from the kernel
+against
+.Dv SADB_DUMP
+and
+.Dv SADB_SPDDUMP
+operations on
+.Dv PF_KEY
+sockets.
+This occurs if there are too many database entries in the kernel
+and socket buffer for the
+.Dv PF_KEY
+socket is insufficient.
+If you manipulate many IPsec key/policy database entries,
+increase the size of socket buffer or use
+.Xr sysctl 8
+interface.
+.Pp
+Certain legacy authentication algorithms are not supported because of
+issues with the
+.Xr opencrypto 9
+subsystem.