various tweaks;

1 files changed, 97 insertions, 191 deletions

diff --git a/share/man/man4/ipsec.4 b/share/man/man4/ipsec.4
index f7981344ef7..6bc7ab69af9 100644
--- a/share/man/man4/ipsec.4
+++ b/share/man/man4/ipsec.4
@@ -1,4 +1,4 @@
-.\" $OpenBSD: ipsec.4,v 1.57 2004/03/27 16:52:43 deraadt Exp $
+.\" $OpenBSD: ipsec.4,v 1.58 2005/04/02 00:14:44 jmc Exp $
 .\"
 .\" Copyright 1997 Niels Provos <provos@physnet.uni-hamburg.de>
 .\" All rights reserved.
@@ -43,77 +43,62 @@ may be enabled or disabled using the following
 variables in
 .Pa /etc/sysctl.conf .
 By default, both protocols are enabled:
-.Bl -tag -width xxxxxxxxxxxxxxxxxxxxx
+.Pp
+.Bl -tag -width "net.inet.esp.enableXX" -offset indent -compact
 .It net.inet.esp.enable
 Enable the ESP IPsec protocol
 .It net.inet.ah.enable
 Enable the AH IPsec protocol
 .El
 .Sh DESCRIPTION
-.Tn IPsec
-is a pair of protocols,
-.Tn ESP
-(for Encapsulating Security
-Payload) and
-.Tn AH
-(for Authentication Header), which provide
-security services for
-.Tn IP
-datagrams.
+IPsec is a pair of protocols,
+Encapsulating Security Payload (ESP)
+and Authentication Header (AH),
+which provide security services for IP datagrams.
 .Pp
-The original Internet Protocol -
-.Tn IPv4 -
+The original Internet Protocol, IPv4,
 does not inherently provide any
 protection to transferred data.
 Furthermore, it does not even guarantee that the sender is who he
 claims to be.
-.Tn IPsec
-tries to remedy this by providing the required security services for
-.Tn IP
-datagrams.
-There are four main security properties provided by
-.Tn IPsec :
+IPsec tries to remedy this by providing the required security services for
+IP datagrams.
+There are four main security properties provided by IPsec:
 .Bl -inset -offset indent
 .It Confidentiality
-- Ensure it is hard for anyone but the
+\- Ensure it is hard for anyone but the
 receiver to understand what data has been communicated.
 For example, ensuring the secrecy of passwords when logging
 into a remote machine over the Internet.
 .It Integrity
-- Guarantee that the data does not get changed
+\- Guarantee that the data does not get changed
 in transit.
 If you are on a line carrying invoicing data you
 probably want to know that the amounts and account numbers
 are correct and have not been modified by a third party.
 .It Authenticity
-- Sign your data so that others can see that it
+\- Sign your data so that others can see that it
 is really you that sent it.
 It is clearly nice to know that documents are not forged.
 .It Replay protection
-- We need ways to ensure a datagram is processed only once, regardless
+\- We need ways to ensure a datagram is processed only once, regardless
 of how many times it is received.
-I.e. it should not be possible for an attacker
+That is, it should not be possible for an attacker
 to record a transaction (such as a bank account withdrawal), and then
 by replaying it verbatim cause the peer to think a new message
 (withdrawal request) had been received.
-WARNING: as per the standards specification, replay protection is not
+WARNING: as per the standard's specification, replay protection is not
 performed when using manual-keyed IPsec (e.g., when using
 .Xr ipsecadm 8 ) .
 .El
 .Ss IPsec Protocols
-.Tn IPsec
-provides these services using two new protocols:
-.Tn AH ,
-Authentication Header, and
-.Tn ESP ,
-Encapsulating Security Payload.
+IPsec provides these services using two new protocols:
+Authentication Header (AH), and
+Encapsulating Security Payload (ESP).
 .Pp
-.Tn ESP
-can provide the properties authentication, integrity, replay protection, and
-confidentiality of the data (it secures everything in the packet that
-follows the
-.Tn IP
-header).
+ESP can provide the properties authentication, integrity, replay protection,
+and confidentiality of the data
+(it secures everything in the packet that follows the IP header).
 Replay protection requires authentication and
 integrity (these two always go together).
 Confidentiality (encryption) can be used with or without
@@ -121,57 +106,35 @@ authentication/integrity.
 Similarly, one could use authentication/integrity with or without
 confidentiality.
 .Pp
-.Tn AH
-provides authentication, integrity, and replay protection (but not
-confidentiality).
+AH provides authentication, integrity, and replay protection
+(but not confidentiality).
 The main difference between the authentication features of
-.Tn AH
-and
-.Tn ESP
-is that
-.Tn AH
-also authenticates portions of the
-.Tn IP
-header of the packet (such as the source/destination
-addresses).
-.Tn ESP
-authenticates only the packet payload.
+AH and ESP is that AH also authenticates portions of the IP
+header of the packet
+(such as the source/destination addresses).
+ESP authenticates only the packet payload.
 .Ss Security Associations (SAs)
 These protocols require certain parameters for each connection, describing
 exactly how the desired protection will be achieved.
 These parameters are collected in an entity called a security association,
-or
-.Tn SA
-for short.
-Typical
-.Tn SA
-parameters include encryption algorithm, hash algorithm,
+or SA for short.
+Typical SA parameters include encryption algorithm, hash algorithm,
 encryption key, and authentication key, to name a few.
-When two peers have established matching
-.Tn SAs
+When two peers have established matching SAs
 (one at each end),
-packets protected with one end's
-.Tn SA
-may be verified and/or decrypted
-using the information in the other end's
-.Tn SA .
-The only issue remaining is to ensure that both ends have matching
-.Tn SAs .
+packets protected with one end's SA may be verified and/or decrypted
+using the information in the other end's SA.
+The only issue remaining is to ensure that both ends have matching SAs.
 This may be done manually, or automatically using a key management daemon.
 .Pp
-Further information on manual
-.Tn SA
-establishment is described in
+Further information on manual SA establishment is described in
 .Xr ipsecadm 8 .
 Information on automated key management may be found in
 .Xr isakmpd 8 .
 .Ss Authentication Header (AH)
-.Tn AH
-works by computing a value that depends on all of the payload
-data, some of the
-.Tn IP
-header data, and a certain secret value (the
-authentication key).
+AH works by computing a value that depends on all of the payload
+data, some of the IP header data, and a certain secret value
+(the authentication key).
 This value is then sent with the rest of each packet.
 The receiver performs the same computation, and if the value matches,
 he knows no one tampered with the data (integrity), the address information
@@ -182,12 +145,8 @@ altering the packet.
 The algorithms used to compute these values are called hash algorithms and are
 parameters in the SA, just like the authentication key.
 .Ss Encapsulating Security Payload (ESP)
-.Tn ESP
-optionally does almost everything that
-.Tn AH
-does except that it does not
-protect the outer
-.Tn IP
+ESP optionally does almost everything that AH does
+except that it does not protect the outer IP
 header but furthermore it encrypts the payload data with an encryption
 algorithm using a secret encryption key.
 Only the ones knowing this key can decrypt the data, thus providing
@@ -202,92 +161,57 @@ unidirectional construct.
 For a bidirectional communication channel, two SAs are required, one
 outgoing and one incoming, where the destination address is our local
 IP address.
-The SPI is just a number that helps us make the name unique, it can be
-arbitrarily chosen in the range 0x100 - 0xffffffff.
-The security protocol number should be 50 for
-.Tn ESP
-and 51 for
-.Tn AH ,
+The SPI is just a number that helps us make the name unique;
+it can be arbitrarily chosen in the range 0x100 \- 0xffffffff.
+The security protocol number should be 50 for ESP and 51 for AH,
 as these are the protocol numbers assigned by IANA.
 .Ss Modes of Operation
-.Tn IPsec
-can operate in two modes, either tunnel or transport mode.
-In transport mode the ordinary
-.Tn IP
-header is used to deliver the packets to their endpoint,
-in tunnel mode the ordinary
-.Tn IP
-header just tells us the address of a
-security gateway, knowing how to verify/decrypt the payload and forward the
-packet to a destination given by another
-.Tn IP
+IPsec can operate in two modes, either tunnel or transport mode.
+In transport mode the ordinary IP
+header is used to deliver the packets to their endpoint;
+in tunnel mode the ordinary IP
+header just tells us the address of a security gateway
+which knows how to verify/decrypt the payload and forward the
+packet to a destination given by another IP
 header contained in the protected payload.
-Tunnel mode can be used for establishing VPNs, virtual
-private networks, where parts of the networks can be spread out over an
+Tunnel mode can be used for establishing virtual private networks (VPNs),
+where parts of the networks can be spread out over an
 unsafe public network, but security gateways at each subnet are responsible
 for encrypting and decrypting the data passing over the public net.
-An SA will hold information telling if it is a tunnel or transport mode SA,
-and for tunnels, it will contain values to fill in into the outer
-.Tn IP
-header.
+An SA will contain information specifying
+whether it is a tunnel or transport mode SA,
+and for tunnels it will contain values to fill in into the outer IP header.
 .Ss Lifetimes
 The SA also holds a couple of other parameters, especially useful for
 automatic keying, called lifetimes, which puts a limit on how much we can
 use an SA for protecting our data.
 These limits can be in wall-clock time or in volume of our data.
 .Ss IPsec Examples
-To better illustrate how
-.Tn IPsec
-works, consider a typical
-.Tn TCP
-packet:
-.Bd -literal -offset indent
-[IP header] [TCP header] [data...]
-.Ed
+To better illustrate how IPsec works, consider a typical TCP packet:
 .Pp
-If we apply
-.Tn ESP
-in transport mode to the above packet, we will get:
-.Bd -literal -offset indent
-[IP header] [ESP header] [TCP header] [data...]
-.Ed
+.Dl [IP header] [TCP header] [data...]
 .Pp
-where everything after the
-.Tn ESP
-header is protected by whatever services of
-.Tn ESP
-we are using (authentication/integrity, replay protection,
-confidentiality).
-This means the
-.Tn IP
-header itself is not protected.
+If we apply ESP in transport mode to the above packet, we will get:
 .Pp
-If we apply
-.Tn ESP
-in tunnel mode to the original packet, we would get:
-.Bd -literal -offset indent
-[IP header] [ESP header] [IP header] [TCP header] [data...]
-.Ed
+.Dl [IP header] [ESP header] [TCP header] [data...]
 .Pp
-where, again, everything after the
-.Tn ESP
-header is cryptographically
-protected.
-Notice the insertion of an
-.Tn IP
-header between the
-.Tn ESP
-and
-.Tn TCP
-header.
+Everything after the ESP
+header is protected by whatever services of ESP we are using
+(authentication/integrity, replay protection, confidentiality).
+This means the IP header itself is not protected.
+.Pp
+If we apply ESP in tunnel mode to the original packet, we would get:
+.Pp
+.Dl [IP header] [ESP header] [IP header] [TCP header] [data...]
+.Pp
+Again, everything after the ESP header is cryptographically protected.
+Notice the insertion of an IP header between the ESP and TCP header.
 This mode of operation allows us to hide who the true
-source and destination addresses of a packet are (since the protected
-and the unprotected
-.Tn IP
+source and destination addresses of a packet are
+(since the protected and the unprotected IP
 headers don't have to be exactly the same).
 A typical application of this is in Virtual Private Networks (or VPNs),
-where two firewalls use
-.Tn IPsec
+where two firewalls use IPsec
 to secure the traffic of all the hosts behind them.
 For example:
 .Bd -literal -offset indent
@@ -295,15 +219,12 @@ Net A <----> Firewall 1 <--- Internet ---> Firewall 2 <----> Net B
 .Ed
 .Pp
 Firewall 1 and Firewall 2 can protect all communications between Net A
-and Net B by using
-.Tn IPsec
-in tunnel mode, as illustrated above.
+and Net B by using IPsec in tunnel mode, as illustrated above.
 .Pp
-This implementation makes use of a virtual interface
+This implementation makes use of a virtual interface,
 .Nm enc0 ,
 which can be used in packet filters to specify those packets that have
-been or will be processed by
-.Tn IPsec .
+been or will be processed by IPsec.
 .Pp
 NAT can also be applied to
 .Nm enc#
@@ -315,14 +236,9 @@ UL/R -> [X] -> PF/NAT(enc0) -> IPsec -> PF/NAT(IF) -> IF
 UL/R <-------- PF/NAT(enc0) <- IPsec -> PF/NAT(IF) <- IF
 .Ed
 .Pp
-With
-.Tn IF
-being the real interface and
-.Tn UL/R
-the Upper Layer or Routing code.
-The
-.Tn [X]
-Stage on the output path represents the point where the packet
+With IF being the real interface and UL/R the Upper Layer or Routing code.
+The [X]
+stage on the output path represents the point where the packet
 is matched against the IPsec flow database (SPD) to determine if and how
 the packet has to be IPsec-processed.
 If, at this point, it is determined that the packet should be IPsec-processed,
@@ -336,15 +252,14 @@ utility or automatically with the
 .Xr isakmpd 8
 key management daemon.
 .Ss API Details
-The following
-.Tn IP-level
+The following IP-level
 .Xr setsockopt 2
 and
 .Xr getsockopt 2
 options are specific to
 .Nm ipsec .
 A socket can specify security levels for three different categories:
-.Bl -tag -width IP_ESP_NETWORK_LEVEL
+.Bl -tag -width IP_ESP_NETWORK_LEVEL -offset 2n
 .It IP_AUTH_LEVEL
 Specifies the use of authentication for packets sent or received by the
 socket.
@@ -357,7 +272,7 @@ Specifies the use of encryption in tunnel mode.
 .Pp
 For each of the categories there are five possible levels which
 specify the security policy to use in that category:
-.Bl -tag -width IPSEC_LEVEL_REQUIRE
+.Bl -tag -width IPSEC_LEVEL_REQUIRE -offset 2n
 .It IPSEC_LEVEL_BYPASS
 Bypass the default system security policy.
 This option can only be used by privileged processes.
@@ -401,14 +316,14 @@ listens to messages from the kernel.
 .Pp
 A list of all security associations in the kernel tables can be
 obtained via the kernfs file
-.Aq Pa ipsec
-(typically in
-.Aq Pa /kern/ipsec ) .
+.Aq Pa ipsec ,
+typically in
+.Aq Pa /kern/ipsec .
 .Sh DIAGNOSTICS
 A socket operation may fail with one of the following errors returned:
 .Bl -tag -width [EINVAL]
 .It Bq Er EACCES
-when an attempt is made to lower the security level below the system default
+An attempt was made to lower the security level below the system default
 by a non-privileged process.
 .It Bq Er EINVAL
 The length of option field did not match or an unknown security level
@@ -416,20 +331,14 @@ was given.
 .El
 .Pp
 .Xr netstat 1
-can be used to obtain some statistics about
-.Tn AH
-and
-.Tn ESP
-usage, using the
+can be used to obtain some statistics about AH and ESP usage, using the
 .Fl p
 flag.
 Using the
 .Fl r
 flag,
 .Xr netstat 1
-displays information about
-.Tn IPsec
-flows.
+displays information about IPsec flows.
 .Pp
 .Xr vmstat 8
 displays information about memory use by IPsec with the
@@ -447,10 +356,8 @@ flag (look for ``tdb'' and ``xform'' allocations).
 .Xr isakmpd 8 ,
 .Xr vpn 8
 .Sh HISTORY
-The
-.Tn IPsec
-protocol design process was started in 1992 by John Ioannidis, Phil Karn
-and William Allen Simpson.
+The IPsec protocol design process was started in 1992 by
+John Ioannidis, Phil Karn, and William Allen Simpson.
 In 1995, the former wrote an implementation for
 .Bsx .
 Angelos D. Keromytis ported it to
@@ -460,9 +367,8 @@ and
 The latest transforms and new features were
 implemented by Angelos D. Keromytis and Niels Provos.
 .Sh ACKNOWLEDGMENTS
-The authors of the
-.Tn IPsec
-code proper are John Ioannidis, Angelos D. Keromytis, and Niels Provos.
+The authors of the IPsec code proper are
+John Ioannidis, Angelos D. Keromytis, and Niels Provos.
 .Pp
 Niklas Hallqvist and Niels Provos are the authors of
 .Xr isakmpd 8 .
@@ -473,11 +379,11 @@ DES algorithm.
 Steve Reid's SHA-1 code was also used.
 .Pp
 The
-.Xr setsockopt 2 / Ns Xr getsockopt 2
+.Xr setsockopt 2 Ns / Ns Xr getsockopt 2
 interface follows somewhat loosely the
-draft-mcdonald-simple-ipsec-api (since expired, but
-still available from
-.Pa ftp://ftp.kame.net/pub/internet-drafts/ )
+draft-mcdonald-simple-ipsec-api
+(since expired, but still available from
+.Pa ftp://ftp.kame.net/pub/internet-drafts/ ) .
 .Sh BUGS
 There's a lot more to be said on this subject.
 This is just a beginning.