document recent changes, with jmc@

1 files changed, 126 insertions, 1 deletions

diff --git a/sbin/ipsecctl/ipsec.conf.5 b/sbin/ipsecctl/ipsec.conf.5
index 230aa6ffe84..d1a17f5afec 100644
--- a/sbin/ipsecctl/ipsec.conf.5
+++ b/sbin/ipsecctl/ipsec.conf.5
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: ipsec.conf.5,v 1.15 2005/08/10 08:49:33 jmc Exp $
+.\"	$OpenBSD: ipsec.conf.5,v 1.16 2005/08/11 09:26:27 hshoexer Exp $
 .\"
 .\" Copyright (c) 2004 Mathieu Sauve-Frankel  All rights reserved.
 .\"
@@ -104,6 +104,126 @@ the
 .Ar peer
 specification can be left out.
 .El
+.Sh IPSEC SAs
+The security parameters for a
+.Ar flow
+are stored in the Security Association Database
+(SADB).
+The following rules enter SAs in the SADB:
+.Pp
+.Bl -tag -width Ds -offset indent -compact
+.It Ic esp
+Enter an ESP SA.
+.It Ic ah
+Enter an AH SA.
+.El
+.Pp
+Parameters specify the peers, Security Parameter Index (SPI),
+cryptographic transforms, and key material to be used.
+.Bl -tag -width xxxx
+.It Xo
+.Ar from
+.Aq Ar src
+.Ar to
+.Aq Ar dst
+.Xc
+This SA is for a
+.Ar flow
+between the peers
+.Aq Ar src
+and
+.Aq Ar dst .
+.It Xo
+.Ar spi
+.Aq Ar number
+.Xc
+The SPI identifies a specific SA.
+.Ar number
+is a 32-bit value and needs to be unique.
+.It Xo
+.Ar auth
+.Aq Ar algorithm
+.Xc
+For both
+.Ar esp
+and
+.Ar ah
+an authentication algorithm can be specified.
+Possible algorithms are
+.Ar hmac-md5 ,
+.Ar hmac-ripemd160 ,
+.Ar hmac-sha1 ,
+.Ar hmac-sha2-256 ,
+.Ar hmac-sha2-384 ,
+.Ar hmc-sha2-512 ,
+.Ar md5 ,
+and
+.Ar sha1 .
+.Pp
+If no algorithm is specified,
+.Xr ipsecctl 8
+will choose
+.Ar hmac-sha2-256
+by default.
+.It Xo
+.Ar enc
+.Aq Ar algorithm
+.Xc
+For
+.Ar esp
+an encryption algorithm needs to be specified.
+Possible algorithms are
+.Ar 3des-cbc ,
+.Ar des-cbc ,
+.Ar aes ,
+.Ar aesctr ,
+.Ar blowfish ,
+.Ar cast128 ,
+.Ar null ,
+and
+.Ar skipjack .
+.Pp
+If no alogrithm is specified,
+.Xr ipsecctl 8
+will choose
+.Ar aesctr
+by default.
+.It Xo
+.Ar authkey
+.Aq Ar keyspec
+.Xc
+.Ar keyspec
+defines the authentication key to be used.
+It is either a hexadecimal string or a file specified as follows:
+.Bd -literal -offset -indent
+authkey file "filename"
+.Ed
+.It Xo
+.Ar enckey
+.Aq Ar keyspec
+.Xc
+The encryption key is defined similar to
+.Ar authkey .
+.El
+.Pp
+It is very important that keys are not guessable.
+One practical way of generating 160-bit (20-byte) keys is a follows:
+.Bd -literal -offset indent
+$ openssl rand 20 | hexdump -e '20/1 "%02x"'
+.Ed
+.Pp
+For
+.Ar spi ,
+.Ar authkey ,
+and
+.Ar enckey ,
+it is possible to specify two colon separated values.
+.Xr ipsecctl 8
+will then generate the matching incoming SA using the second values for
+.Ar spi ,
+.Ar authkey ,
+and
+.Ar enckey .
 .Sh TCP MD5 SIGNATURES
 RFC 2385 describes a mechanism to protect
 .Xr tcp 4
@@ -173,6 +293,11 @@ flow esp from 192.168.7.0/24 to 192.168.8.0/24 peer 192.168.3.12
 flow esp out from 192.168.7.0/24 to 192.168.8.0/24 peer 192.168.3.12
 flow esp in  from 192.168.8.0/24 to 192.168.7.0/24 peer 192.168.3.12
 
+# Set up IPsec SAs for a flows between 192.168.3.14 and 192.168.3.12
+esp from 192.168.3.14 to 192.168.3.12 spi 0xdeadbeef:0xbeefdead \e
+	auth hmac-sha2-256 enc aesctr authkey file "auth14:auth12" \e
+	enckey file "enc14:enc12"
+
 # Set up keys for TCP MD5 signatures
 tcpmd5 from 192.168.3.14 to 192.168.3.27 spi 0x1000:0x1001 \e
 	authkey 0xdeadbeef:0xbeefdead