[client] minor man page backwards compatibility update to include better examples
authorMichael Rash <mbr@cipherdyne.org>
Sun, 16 Jun 2013 12:27:29 +0000 (08:27 -0400)
committerMichael Rash <mbr@cipherdyne.org>
Sun, 16 Jun 2013 12:27:29 +0000 (08:27 -0400)
client/fwknop.8.in
doc/fwknop.man.asciidoc

index 85c0c0d..07a503d 100644 (file)
@@ -2,12 +2,12 @@
 .\"     Title: fwknop
 .\"    Author: [see the "AUTHORS" section]
 .\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
-.\"      Date: 06/10/2013
+.\"      Date: 06/16/2013
 .\"    Manual: Fwknop Client
 .\"    Source: Fwknop Client
 .\"  Language: English
 .\"
-.TH "FWKNOP" "8" "06/10/2013" "Fwknop Client" "Fwknop Client"
+.TH "FWKNOP" "8" "06/16/2013" "Fwknop Client" "Fwknop Client"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -1052,7 +1052,33 @@ When \fBfwknopd\fR is running on an iptables firewall with systems deployed behi
 .\}
 .SH "BACKWARDS COMPATIBILITY"
 .sp
-With the \fI2\&.5\fR release, \fBfwknop\fR underwent significant changes in its usage of cryptography including the addition of support for HMAC authenticated encryption, ensuring the proper usage of PBKDF1 for key derivation when SPA packets are encrypted with Rijndael, and several bugs were fixed from previous versions of fwknop\&. In general, this implies that SPA packets produced by the \fI2\&.5\fR release are incompatible with previous versions of fwknop\&. However, backwards compatibility is supported through setting the \fIlegacy\fR encryption mode with \fB\-M\fR on the fwknop client command line and/or the \fIENCRYPTION_MODE\fR variable in the \fI@sysconfdir@/fwknop/access\&.conf\fR file\&. This way, a pre\-2\&.5 server can decrypt SPA packets produced by a 2\&.5 and later client (set \fI\-M legacy\fR), and a 2\&.5 and later server can decrypt SPA packets produced by pre\-2\&.5 clients (set \fIENCRYPTION_MODE legacy\fR in the access\&.conf file)\&. Note that HMAC is only supported as of 2\&.5 and is an optional feature, so backwards compatibility is only configurations that don\(cqt use an HMAC on either side\&. It is strongly recommended to upgrade all fwknop clients and servers to 2\&.5 and use the new HMAC mode for properly authenticated SPA communications\&.
+With the \fI2\&.5\fR release, \fBfwknop\fR underwent significant changes in its usage of cryptography including the addition of support for HMAC authenticated encryption, ensuring the proper usage of PBKDF1 for key derivation when SPA packets are encrypted with Rijndael, and several bugs were fixed from previous versions of fwknop\&. In general, this implies that SPA packets produced by the \fI2\&.5\fR release are incompatible with previous versions of fwknop\&. However, backwards compatibility is supported through setting the \fIlegacy\fR encryption mode with \fB\-M\fR on the fwknop client command line and/or the \fIENCRYPTION_MODE\fR variable in the \fI@sysconfdir@/fwknop/access\&.conf\fR file\&. This way, a pre\-2\&.5 server can decrypt SPA packets produced by a 2\&.5 and later client (set \fI\-M legacy\fR), and a 2\&.5 and later server can decrypt SPA packets produced by pre\-2\&.5 clients (set \fIENCRYPTION_MODE legacy\fR in the access\&.conf file)\&. Note that HMAC is only supported as of 2\&.5 and is an optional feature, so backwards compatibility is only for configurations that don\(cqt use an HMAC on either side\&. It is strongly recommended to upgrade all fwknop clients and servers to 2\&.5 and use the new HMAC mode for properly authenticated SPA communications\&. The backwards compatibility support is used to make it easier to upgrade clients and servers with a phased approach\&.
+.sp
+For emphasis, if the \fBfwknopd\fR server is upgraded to 2\&.5 (or later), but older clients cannot be upgraded at the same time, then for each \fISOURCE\fR stanza in the \fI@sysconfdir@/fwknop/access\&.conf\fR file, add the following line:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+    ENCRYPTION_MODE         legacy
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+In addition, if the \fIKEY\fR variable has an encryption key longer than 16 bytes, it will need to be truncated to 16 characters in the \fIaccess\&.conf\fR file in order for pre\-2\&.5 clients to work properly\&. This limitation is fixed in 2\&.5, and provides additional motiviation for upgrading all clients and servers to 2\&.5 or later\&.
+.sp
+Now, flipping the scenario around, if the \fBfwknop\fR clients are upgraded but the \fBfwknopd\fR server is still at a pre\-2\&.5 version, then add the \fI\-M legacy\fR argument to the fwknop command line:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+    $ fwknop \-A tcp/22 \-M legacy \-R \-D 2\&.2\&.2\&.2
+.fi
+.if n \{\
+.RE
+.\}
 .SH "DEPENDENCIES"
 .sp
 The \fBfwknop\fR client requires \fIlibfko\fR which is normally included with both source and binary distributions, and is a dedicated library developed by the fwknop project\&. Whenever the \fBfwknopd\fR server is used, \fIlibpcap\fR is a required dependency\&. However, the upcoming \fI2\&.6\fR release will offer a UDP listener mode along with privilege separation support and will not require libpcap in this mode\&. In UDP listener mode, even though fwknopd binds to a UDP port, SPA packets are never acknowledged so from an attacker\(cqs perspective there is no difference between fwknopd sniffing the wire passively vs\&. listening on a UDP socket in terms of what can be scanned for\&.
index 1eb7bde..c28c2fb 100644 (file)
@@ -900,9 +900,33 @@ decrypt SPA packets produced by a 2.5 and later client (set '-M legacy'), and
 a 2.5 and later server can decrypt SPA packets produced by pre-2.5 clients (set
 'ENCRYPTION_MODE legacy' in the access.conf file).  Note that HMAC is only
 supported as of 2.5 and is an optional feature, so backwards compatibility is
-only configurations that don't use an HMAC on either side.  It is strongly
+only for configurations that don't use an HMAC on either side.  It is strongly
 recommended to upgrade all fwknop clients and servers to 2.5 and use the new
-HMAC mode for properly authenticated SPA communications.
+HMAC mode for properly authenticated SPA communications.  The backwards
+compatibility support is used to make it easier to upgrade clients and servers
+with a phased approach.
+
+For emphasis, if the *fwknopd* server is upgraded to 2.5 (or later), but older
+clients cannot be upgraded at the same time, then for each 'SOURCE' stanza in
+the '@sysconfdir@/fwknop/access.conf' file, add the following line:
+
+..........................
+    ENCRYPTION_MODE         legacy
+..........................
+
+In addition, if the 'KEY' variable has an encryption key longer than 16 bytes,
+it will need to be truncated to 16 characters in the 'access.conf' file in
+order for pre-2.5 clients to work properly.  This limitation is fixed in 2.5,
+and provides additional motiviation for upgrading all clients and servers to
+2.5 or later.
+
+Now, flipping the scenario around, if the *fwknop* clients are upgraded but the
+*fwknopd* server is still at a pre-2.5 version, then add the '-M legacy'
+argument to the fwknop command line:
+
+..........................
+    $ fwknop -A tcp/22 -M legacy -R -D 2.2.2.2
+..........................
 
 
 DEPENDENCIES