merge/remove EXAMPLES:

previously we were documenting in 2 places how to set up ipsecadm stuff,
and in one place isakmpd. this led to inconsistencies and repitition.

sanity checks + ok hshoexer@

1 files changed, 165 insertions, 222 deletions

diff --git a/share/man/man8/vpn.8 b/share/man/man8/vpn.8
index 133123a7f8b..e6d39c7f77b 100644
--- a/share/man/man8/vpn.8
+++ b/share/man/man8/vpn.8
@@ -1,4 +1,4 @@
-.\" $OpenBSD: vpn.8,v 1.94 2005/04/16 00:01:17 jmc Exp $
+.\" $OpenBSD: vpn.8,v 1.95 2005/04/17 12:34:23 jmc Exp $
 .\"
 .\" Copyright 1998 Niels Provos <provos@physnet.uni-hamburg.de>
 .\" All rights reserved.
@@ -37,8 +37,8 @@
 .Nm vpn
 .Nd configuring the system for virtual private networks
 .Sh DESCRIPTION
-A virtual private network is used to securely connect two or more subnets
-over the internet.
+A Virtual Private Network (VPN)
+is used to securely connect two or more subnets over the internet.
 For each subnet there is a security gateway which is
 linked via a cryptographically secured tunnel to the security gateway of
 the other subnet.
@@ -50,33 +50,56 @@ Briefly, creating a VPN consists of the following steps:
 .Pp
 .Bl -enum -compact
 .It
-Choose a key exchange method: manual or automated.
-.It
 Enable packet forwarding.
 .It
+Choose a key exchange method: manual or automated.
+.It
 For manual keying, generate the keys.
 .It
-For manual keying, create the Security Associations (SA), one for
-each endpoint.
+For manual keying, create the Security Associations (SA).
 .It
 For manual keying, create the appropriate IPsec flows.
 .It
-For automated keying, create a configuration file for the keying
-daemon.
+For automated keying, configure the keying daemon.
 .It
-Configure your firewall rules appropriately.
-.El
-.Ss Choosing a key exchange method
-There are currently two key exchange methods available:
-.Pp
-.Bl -bullet -compact
+Configure firewall rules appropriately.
 .It
-manual keying:
-.Xr ipsecadm 8
+Enable the packet filter.
 .It
-automated keying:
-.Xr isakmpd 8
+For automated keying, start the keying daemon.
 .El
+.Ss About this page
+It is recommended that a test setup be created before attempting to
+deploy a VPN on the internet.
+The examples in this page can be done using two machines
+directly connected to each other,
+and a little imagination.
+The IP address of each machine represents a gateway address;
+the alias (see below) is simply a hook into a fictitious network.
+.Pp
+The following steps are only necessary
+if the VPN is being set up as a test VPN,
+on an internal LAN.
+.Pp
+The VPN can be represented using two machines (A and B).
+An alias should be added to each machine,
+to give it the appearance of being in another network.
+.Pp
+On machine A:
+.Bd -literal -offset indent
+# ifconfig ne0 192.168.1.13 description "Machine A"
+# ifconfig ne0 alias 10.0.50.1
+.Ed
+.Pp
+On machine B:
+.Bd -literal -offset indent
+# ifconfig bge0 192.168.1.15 description "Machine B"
+# ifconfig bge0 alias 10.0.99.1
+.Ed
+.Pp
+For all other (non-test) cases,
+.Xr ifconfig 8
+should be used to configure machines as normal.
 .Ss Enabling Packet Forwarding
 For security gateways, proper operation often requires packet
 forwarding to be enabled using
@@ -92,6 +115,17 @@ Packet forwarding defaults to
 For more permanent operation,
 the appropriate option(s) should be enabled in your
 .Xr sysctl.conf 5 .
+.Ss Choosing a Key Exchange Method
+There are currently two key exchange methods available:
+.Pp
+.Bl -bullet -compact
+.It
+manual keying:
+.Xr ipsecadm 8
+.It
+automated keying:
+.Xr isakmpd 8
+.El
 .Ss Generating Manual Keys [manual keying]
 The shared secret symmetric keys used to create a VPN can
 be any hexadecimal value, so long as both sides of the connection use
@@ -132,16 +166,27 @@ Note that DES requires 8 bytes to form a 56-bit key and 3DES requires 24 bytes
 to form its 168-bit key.
 This is because the most significant bit of each byte is ignored by both
 algorithms.
+.Pp
+The following would create suitable keys for a 3DES encryption key
+and SHA-1 authentication key:
+.Bd -literal -offset indent
+# openssl rand 24 | hexdump -e '24/1 "%02x"' \*(Gt enc_key
+# openssl rand 20 | hexdump -e '20/1 "%02x"' \*(Gt auth_key
+.Ed
+.Pp
+The 3DES encryption key needs 192 bits (3x64), or 24 bytes.
+The SHA-1 authentication key needs 160 bits, or 20 bytes.
 .Ss Creating Security Associations [manual keying]
 Before the IPsec flows can be defined, two Security Associations (SAs)
 must be defined on each end of the VPN e.g.:
 .Bd -literal -offset indent
-# ipsecadm new esp -spi $SPI_AB -src $GATEWAY_A \e
-    -dst $GATEWAY_B -forcetunnel -enc 3des -auth sha1 \e
+# ipsecadm new esp -src $GATEWAY_A -dst $GATEWAY_B \e
+    -spi $SPI_AB -forcetunnel -enc 3des -auth sha1 \e
     -keyfile $ENCRYPTION_KEY_FILE \e
     -authkeyfile $AUTHENTICATION_KEY_FILE
-# ipsecadm new esp -spi $SPI_BA -src $GATEWAY_B \e
-    -dst $GATEWAY_A -forcetunnel -enc 3des -auth sha1 \e
+
+# ipsecadm new esp -src $GATEWAY_B -dst $GATEWAY_A \e
+    -spi $SPI_BA -forcetunnel -enc 3des -auth sha1 \e
     -keyfile $ENCRYPTION_KEY_FILE \e
     -authkeyfile $AUTHENTICATION_KEY_FILE
 .Ed
@@ -159,9 +204,12 @@ command at the appropriate time (or use a program for doing so).
 .Ss Creating IPsec Flows [manual keying]
 Both IPsec gateways need to configure
 .Xr ipsec 4
-routes with the
+routes (flows) with the
 .Xr ipsecadm 8
-tool:
+tool.
+Two flows are created on each machine:
+the first is for outbound flows,
+the second is the ingress filter for the incoming security association.
 .Pp
 On the security gateway of subnet A:
 .Bd -literal -offset indent
@@ -182,200 +230,16 @@ On the security gateway of subnet B:
     -src $GATEWAY_B -dst $GATEWAY_A \e
     -addr $NETWORK_A $NETWORK_B
 .Ed
-.Ss Configure and run the keying daemon [automated keying]
+.Ss Configuring the Keying Daemon [automated keying]
 Unless manual keying is used, both security gateways need to start
 the
 .Xr isakmpd 8
 key management daemon.
-To make sure the daemon is properly configured
-to provide the required security services (typically, encryption and
-authentication), start the daemon with debugging or verbose output.
-Sample configuration files are provided below.
-.Pp
 .Xr isakmpd 8
 implements security policy using the
 .Em KeyNote
 trust management system.
-.Ss Configuring Firewall Rules
-.Xr pf 4
-needs to be configured such that all packets from the outside are blocked
-by default.
-Only successfully IPsec-processed packets (from the
-.Xr enc 4
-interface), or key management packets (for
-.Xr isakmpd 8 ,
-.Tn UDP
-packets with source and destination ports of 500) should be allowed to pass.
-Additional filter rules may be present for other traffic,
-though care should be taken that other rules do not leak IPsec traffic.
-.Pp
-.Sy Note :
-The examples in this page describe a test setup on an internal LAN,
-using private (non-routable) IP addresses.
-In a typical setup,
-at least GATEWAY_A and GATEWAY_B would be configured using
-public (routable) IP addresses.
-NETWORK_A and NETWORK_B may or may not use public IP addresses,
-depending on the network.
-.Pp
-The
-.Xr pf.conf 5
-rules for a tunnel which uses encryption (the ESP IPsec protocol) and
-.Xr isakmpd 8
-on security gateway A might look like this:
-.Bd -literal -offset indent
-GATEWAY_A = "192.168.1.13"
-GATEWAY_B = "192.168.1.15"
-NETWORK_A = "10.0.50.0/24"
-NETWORK_B = "10.0.99.0/24"
-
-ext_if="ne0"
-
-# default deny
-# $ext_if is the only interface going to the outside.
-block log on { enc0, $ext_if } all
-
-# Passing in encrypted traffic from security gateways
-pass in proto esp from $GATEWAY_B to $GATEWAY_A
-pass out proto esp from $GATEWAY_A to $GATEWAY_B
-
-# Need to allow ipencap traffic on enc0.
-pass in on enc0 proto ipencap all
-
-# Passing in traffic from the designated subnets.
-pass in on enc0 from $NETWORK_B to $NETWORK_A
-pass out on enc0 from $NETWORK_A to $NETWORK_B
-
-# Passing in isakmpd(8) traffic from the security gateways
-pass in on $ext_if proto udp from $GATEWAY_B port = 500 \e
-	to $GATEWAY_A port = 500
-pass out on $ext_if proto udp from $GATEWAY_A port = 500 \e
-	to $GATEWAY_B port = 500
-.Ed
-.Pp
-If there are no other
-.Xr pf.conf 5
-rules, the "quick" clause can be added to the last four rules.
-NAT rules can also be used on the
-.Xr enc 4
-interface.
-.Pp
-.Sy Note :
-it is strongly encouraged that instead of detailed PF rules,
-the SPD (IPsec flow database) be utilized to specify security policy,
-if only to avoid filtering conflicts.
-.Sh EXAMPLES
-It is recommended that a test setup be created before attempting to
-deploy a VPN on the internet.
-The examples in this page can be done using two machines
-directly connected to each other,
-and a little imagination.
-The IP address of each machine represents a gateway address;
-the alias (see below) is simply a hook into a fictitious network.
-.Ss Manual and automated keying
-This step is only necessary if the VPN is being set up as a test VPN,
-on an internal LAN.
-.Pp
-The VPN can be represented using two machines (A and B).
-An alias should be added to each machine,
-to give it the appearance of being in another network.
-.Pp
-On machine A:
-.Bd -literal -offset indent
-# ifconfig ne0 192.168.1.13 description "Machine A"
-# ifconfig ne0 alias 10.0.50.1
-.Ed
-.Pp
-On machine B:
-.Bd -literal -offset indent
-# ifconfig bge0 192.168.1.15 description "Machine B"
-# ifconfig bge0 alias 10.0.99.1
-.Ed
 .Pp
-For all other (non-test) cases,
-.Xr ifconfig 8
-should be used to configure machines appropriately.
-.Ss Manual keying
-To create a manual keyed VPN between two class C networks using
-3DES encryption and the following IP addresses:
-.Bd -literal -offset indent
-GATEWAY_A = 192.168.1.13
-GATEWAY_B = 192.168.1.15
-NETWORK_A = 10.0.50.0/24
-NETWORK_B = 10.0.99.0/24
-.Ed
-.Bl -enum
-.It
-Choose the shared secrets using a suitably random method.
-The 3DES encryption key needs 192 bits (3x64), or 24 bytes.
-The SHA-1 authentication key needs 160 bits, or 20 bytes.
-.Bd -literal -offset indent
-# openssl rand 24 | hexdump -e '24/1 "%02x"' > enc_key
-# openssl rand 20 | hexdump -e '20/1 "%02x"' > auth_key
-.Ed
-.It
-Create the Security Associations (on both endpoints):
-.Bd -literal -offset indent
-# /sbin/ipsecadm new esp -src 192.168.1.15 -dst 192.168.1.13 \e
-	-forcetunnel -spi 1000 -enc 3des -auth sha1 \e
-	-keyfile enc_key -authkeyfile auth_key
-
-# /sbin/ipsecadm new esp -src 192.168.1.13 -dst 192.168.1.15 \e
-	-forcetunnel -spi 1001 -enc 3des -auth sha1 \e
-	-keyfile enc_key -authkeyfile auth_key
-.Ed
-.It
-Create the IPsec flows on machine A (the first is for
-outbound flows, the latter is the ingress filter for the
-incoming security association):
-.Bd -literal -offset indent
-# ipsecadm flow -out -require -proto esp \e
-	-src 192.168.1.13 -dst 192.168.1.15 \e
-	-addr 10.0.50.0/24 10.0.99.0/24
-# ipsecadm flow -in -require -proto esp \e
-	-src 192.168.1.13 -dst 192.168.1.15 \e
-	-addr 10.0.99.0/24 10.0.50.0/24
-.Ed
-.It
-Create the matching IPsec flows on machine B:
-.Bd -literal -offset indent
-# ipsecadm flow -out -require -proto esp \e
-	-src 192.168.1.13 -dst 192.168.1.15 \e
-	-addr 10.0.50.0/24 10.0.99.0/24
-# ipsecadm flow -in -require -proto esp \e
-	-src 192.168.1.13 -dst 192.168.1.15 \e
-	-addr 10.0.99.0/24 10.0.50.0/24
-.Ed
-.It
-Configure the firewall rules on machine A
-using the previously defined ruleset:
-.Bd -literal -offset indent
-GATEWAY_A = "192.168.1.13"
-GATEWAY_B = "192.168.1.15"
-NETWORK_A = "10.0.50.0/24"
-NETWORK_B = "10.0.99.0/24"
-
-(rest of ruleset per Configuring Firewall Rules, above)
-.Ed
-.It
-Configure the firewall rules on machine B, modifying the
-definitions as appropriate:
-.Bd -literal -offset indent
-GATEWAY_A = "192.168.1.13"
-GATEWAY_B = "192.168.1.15"
-NETWORK_A = "10.0.50.0/24"
-NETWORK_B = "10.0.99.0/24"
-
-(rest of ruleset, modified as appropriate)
-.Ed
-.It
-Enable the packet filter and load the ruleset:
-.Bd -literal -offset indent
-# pfctl -e
-# pfctl -f /etc/pf.conf
-.Ed
-.El
-.Ss Automated keying
 To create a VPN between the same two C class networks as the example
 above, using
 .Xr isakmpd 8 :
@@ -531,42 +395,122 @@ Keynote-version: 2
 Authorizer: "POLICY"
 Conditions: app_domain == "IPsec policy" &&
             esp_present == "yes" &&
-            esp_enc_alg != "null" -> "true";
+            esp_enc_alg != "null" -\*(Gt "true";
 .Ed
 .Pp
 Due to the sensitive information contained in the policy file,
 it must be installed without any permissions for "group" or "other".
 .Pp
 .Dl # chmod og-rwx /etc/isakmpd/isakmpd.policy
-.It
-Configure the firewall rules on machine A
-using the previously defined ruleset:
+.El
+.Ss Configuring Firewall Rules
+.Xr pf 4
+needs to be configured such that all packets from the outside are blocked
+by default.
+Only successfully IPsec-processed packets (from the
+.Xr enc 4
+interface), or key management packets (for
+.Xr isakmpd 8 ,
+.Tn UDP
+packets with source and destination ports of 500) should be allowed to pass.
+Additional filter rules may be present for other traffic,
+though care should be taken that other rules do not leak IPsec traffic.
+.Pp
+.Sy Note :
+The examples in this page describe a test setup on an internal LAN,
+using private (non-routable) IP addresses.
+In a typical setup,
+at least GATEWAY_A and GATEWAY_B would be configured using
+public (routable) IP addresses.
+NETWORK_A and NETWORK_B may or may not use public IP addresses,
+depending on the network.
+.Pp
+The
+.Xr pf.conf 5
+rules for a tunnel which uses encryption (the ESP IPsec protocol) and
+.Xr isakmpd 8
+on security gateway A might look like this:
 .Bd -literal -offset indent
 GATEWAY_A = "192.168.1.13"
 GATEWAY_B = "192.168.1.15"
 NETWORK_A = "10.0.50.0/24"
 NETWORK_B = "10.0.99.0/24"
 
-(rest of ruleset per Configuring Firewall Rules, above)
+ext_if="ne0"
+
+# default deny
+# $ext_if is the only interface going to the outside.
+block log on { enc0, $ext_if } all
+
+# Passing in encrypted traffic from security gateways
+pass in proto esp from $GATEWAY_B to $GATEWAY_A
+pass out proto esp from $GATEWAY_A to $GATEWAY_B
+
+# Need to allow ipencap traffic on enc0.
+pass in on enc0 proto ipencap all
+
+# Passing in traffic from the designated subnets.
+pass in on enc0 from $NETWORK_B to $NETWORK_A
+pass out on enc0 from $NETWORK_A to $NETWORK_B
+
+# Passing in isakmpd(8) traffic from the security gateways
+pass in on $ext_if proto udp from $GATEWAY_B port = 500 \e
+	to $GATEWAY_A port = 500
+pass out on $ext_if proto udp from $GATEWAY_A port = 500 \e
+	to $GATEWAY_B port = 500
 .Ed
-.It
-Configure the firewall rules on machine B, modifying the
-definitions as appropriate:
+.Pp
+The
+.Xr pf.conf 5
+rules on security gateway B might look like this:
 .Bd -literal -offset indent
 GATEWAY_A = "192.168.1.13"
 GATEWAY_B = "192.168.1.15"
 NETWORK_A = "10.0.50.0/24"
 NETWORK_B = "10.0.99.0/24"
 
-(rest of ruleset, modified as appropriate)
+ext_if="bge0"
+
+# default deny
+# $ext_if is the only interface going to the outside.
+block log on { enc0, $ext_if } all
+
+# Passing in encrypted traffic from security gateways
+pass in proto esp from $GATEWAY_A to $GATEWAY_B
+pass out proto esp from $GATEWAY_B to $GATEWAY_A
+
+# Need to allow ipencap traffic on enc0.
+pass in on enc0 proto ipencap all
+
+# Passing in traffic from the designated subnets.
+pass in on enc0 from $NETWORK_A to $NETWORK_B
+pass out on enc0 from $NETWORK_B to $NETWORK_A
+
+# Passing in isakmpd(8) traffic from the security gateways
+pass in on $ext_if proto udp from $GATEWAY_A port = 500 \e
+	to $GATEWAY_B port = 500
+pass out on $ext_if proto udp from $GATEWAY_B port = 500 \e
+	to $GATEWAY_A port = 500
 .Ed
-.It
+.Pp
+If there are no other
+.Xr pf.conf 5
+rules, the "quick" clause can be added to the last four rules.
+NAT rules can also be used on the
+.Xr enc 4
+interface.
+.Pp
+.Sy Note :
+it is strongly encouraged that instead of detailed PF rules,
+the SPD (IPsec flow database) be utilized to specify security policy,
+if only to avoid filtering conflicts.
+.Ss Enabling the Packet Filter
 Enable the packet filter and load the ruleset:
 .Bd -literal -offset indent
 # pfctl -e
 # pfctl -f /etc/pf.conf
 .Ed
-.It
+.Ss Starting the Keying Daemon [automated keying]
 Start
 .Xr isakmpd 8
 .Pp
@@ -577,7 +521,6 @@ On both machines, run:
 To run with verbose debugging enabled, instead start with:
 .Pp
 .Dl # /sbin/isakmpd -d -DA=99
-.El
 .Sh FILES
 .Bl -tag -width "/etc/isakmpd/isakmpd.policyXX" -compact
 .It Pa /etc/isakmpd/isakmpd.conf