Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Added backwards compatibility section to the client man page

Added backwards compatibility section and new material on a 'quick start'
subsection for the EXAMPLES section.
  • Loading branch information...
commit 1b41e606a7cd69c7a66da37c3aa78806a8f9efe5 1 parent 1c8d247
@mrash authored
Showing with 234 additions and 57 deletions.
  1. +102 −26 client/fwknop.8.in
  2. +132 −31 doc/fwknop.man.asciidoc
View
128 client/fwknop.8.in
@@ -2,12 +2,12 @@
.\" Title: fwknop
.\" Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
-.\" Date: 05/31/2013
+.\" Date: 06/02/2013
.\" Manual: Fwknop Client
.\" Source: Fwknop Client
.\" Language: English
.\"
-.TH "FWKNOP" "8" "05/31/2013" "Fwknop Client" "Fwknop Client"
+.TH "FWKNOP" "8" "06/02/2013" "Fwknop Client" "Fwknop Client"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
@@ -42,7 +42,7 @@ This is the manual page for the \fBfwknop\fR client which is responsible for con
.sp
SPA packets generated by \fBfwknop\fR leverage HMAC for authenticated encryption in the encrypt\-then\-authenticate model\&. Although the usage of an HMAC is currently optional (enabled via the \fB\-\-use\-hmac\fR command line switch), it is highly recommended for three reasons: \fI1)\fR without an HMAC, cryptographically strong authentication is not possible with \fBfwknop\fR unless GnuPG is used, but even then an HMAC should still be applied, \fI2)\fR an HMAC applied after encryption protects against cryptanalytic CBC\-mode padding oracle attacks such as the Vaudenay attack and related trickery (like the more recent "Lucky 13" attack against SSL), and \fI3)\fR the code required by the \fBfwknopd\fR daemon to verify an HMAC is much more simplistic than the code required to decrypt an SPA packet, so an SPA packet without a proper HMAC isn\(cqt even sent through the decryption routines\&. Reason \fI3)\fR is why an HMAC should still be used even when SPA packets are encrypted with GnuPG due to the fact that SPA data is not sent through \fBlibgpgme\fR functions unless the HMAC checks out first\&. GnuPG and libgpgme are relatively complex bodies of code, and therefore limiting the ability of a potential attacker to interact with this code through an HMAC operation helps to maintain a stronger security stance\&. Generating an HMAC for SPA communications requires a dedicated key in addition to the normal encryption key, and both can be generated with the \fB\-\-key\-gen\fR option\&.
.sp
-\fBfwknop\fR encrypts SPA packets either with the \fIRijndael\fR block cipher or via \fIGnuPG\fR and associated asymmetric cipher\&. If the symmetric encryption method is chosen, then as usual the encryption key is shared between the client and server (see the \fBfwknopd\fR \fI\*(Aq@sysconfdir@/fwknop/access\&.conf\fR file for details)\&. The actual encryption key used for Rijndael encryption is generated via the standard PBKDF1 key derivation algorithm, and CBC mode is set\&. If the GnuPG method is chosen, then the encryption keys are derived from GnuPG key rings\&. SPA packets generated by fwknop running as a client adhere to the following format (before encryption and the HMAC is applied):
+\fBfwknop\fR encrypts SPA packets either with the \fIRijndael\fR block cipher or via \fIGnuPG\fR and associated asymmetric cipher\&. If the symmetric encryption method is chosen, then as usual the encryption key is shared between the client and server (see the \fBfwknopd\fR \fI@sysconfdir@/fwknop/access\&.conf\fR file for details)\&. The actual encryption key used for Rijndael encryption is generated via the standard PBKDF1 key derivation algorithm, and CBC mode is set\&. If the GnuPG method is chosen, then the encryption keys are derived from GnuPG key rings\&. SPA packets generated by fwknop running as a client adhere to the following format (before encryption and the HMAC is applied):
.sp
.if n \{\
.RS 4
@@ -68,7 +68,7 @@ By default, the \fBfwknop\fR client sends authorization packets over UDP port 62
The \fBfwknop\fR client is quite portable, and is known to run on various Linux distributions (all major distros and embedded ones such as OpenWRT as well), FreeBSD, OpenBSD, and Cygwin on Windows\&. There is also a library \fBlibfko\fR that both \fBfwknop\fR and \fBfwknopd\fR use for SPA packet encryption/decryption and HMAC authentication operations\&. This library can be used to allow third party applications to use SPA subject to the terms of the GNU Public License (GPL)\&.
.SH "REQUIRED ARGUMENTS"
.sp
-These required arguments can be specified via command\-line or from within the \fI\&.fwknoprc\fR file (see \fI\-n, \-\-named\-config\fR option and the FWKNOPRC FILE section below)\&.
+These required arguments can be specified via command\-line or from within the \fI~/\&.fwknoprc\fR file (see \fI\-n, \-\-named\-config\fR option and the FWKNOPRC FILE section below)\&.
.PP
\fB\-A, \-\-access\fR=\fI<port list>\fR
.RS 4
@@ -109,7 +109,11 @@ options instead of
\fB\-s\fR
in order to harden SPA communications against possible
\fIMan\-In\-The\-Middle\fR
-(MITM) attacks\&.
+(MITM) attacks, and on the server side set
+\fIREQUIRE_SOURCE_ADDRESS\fR
+variable in the
+\fI@sysconfdir@/fwknop/access\&.conf\fR
+file\&.
.RE
.SH "GENERAL OPTIONS"
.PP
@@ -537,7 +541,7 @@ Specify the message digest algorithm to use in the SPA data\&. Choices are:
\fB\-M, \-\-encryption\-mode\fR=\fI<mode>\fR
.RS 4
Specify the encryption mode when AES is used for encrypting SPA packets\&. The default is CBC mode, but others can be chosen such as CFB or OFB as long as this is also specified in the
-\fI\*(Aq@sysconfdir@/fwknop/access\&.conf\fR
+\fI@sysconfdir@/fwknop/access\&.conf\fR
file on the server side via the ENCRYPTION_MODE variable\&. In general, it is recommended to not include this argument and let the default (CBC) apply\&. Note that the string \(lqlegacy\(rq can be specified in order to generate SPA packets with the old initialization vector strategy used by versions of
\fBfwknop\fR
prior to 2\&.5\&. With the 2\&.5 release,
@@ -594,9 +598,9 @@ In
\fB\-P icmp\fR
mode, specify the ICMP code value that will be set in the SPA packet ICMP header\&. The default is zero\&.
.RE
-.SH "GPG-RELATED OPTIONS"
+.SH "GPG OPTIONS"
.sp
-Note that the usage of GPG for SPA encryption/decryption can and should involve GPG keys that are signed by each side (client and server)\&. The basic procedure for this involves the following steps after the client key has been transferred the server and vice\-versa:
+Note that the usage of GPG for SPA encryption/decryption can and should involve GPG keys that are signed by each side (client and server)\&. The basic procedure for this involves the following steps after the client key has been transferred to the server and vice\-versa:
.sp
.if n \{\
.RS 4
@@ -858,23 +862,92 @@ Have the fwknop client assign a random port for NAT access (\fI\-\-nat\-rand\-po
\fBSPOOF_USER\fR, \fBGPG_AGENT_INFO\fR (only used in \fB\-\-gpg\-agent\fR mode)\&.
.SH "SPA PACKET SPOOFING"
.sp
-Because \fBfwknop\fR places the IP to be allowed through the firewall within the encrypted SPA payload (unless \fB\-s\fR is used which is not recommended and can be prohibited in the \fBfwknopd\fR server configuration), SPA packets can easily be spoofed, and this is a good thing in this context\&. That is, the source IP of an SPA packet is ignored by the \fBfwknopd\fR daemon and only the IP that is contained within an authenticated and properly decrypted SPA packet is granted access through the firewall\&. This makes it possible to make it appear as though, say, www\&.yahoo\&.com is trying to authenticate to a target system but in reality the actual connection will come from a seemingly unrelated IP\&.
+Because \fBfwknop\fR places the IP to be allowed through the firewall within the encrypted SPA payload (unless \fB\-s\fR is used which is not recommended and can be prohibited in the \fBfwknopd\fR server configuration), SPA packets can easily be spoofed, and this is a good thing in this context\&. That is, the source IP of an SPA packet is ignored by the \fBfwknopd\fR daemon (when the \fIREQUIRE_SOURCE_ADDRESS\fR variable is set in the \fI@sysconfdir@/fwknop/access\&.conf\fR file) and only the IP that is contained within an authenticated and properly decrypted SPA packet is granted access through the firewall\&. This makes it possible to make it appear as though, say, www\&.yahoo\&.com is trying to authenticate to a target system but in reality the actual connection will come from a seemingly unrelated IP\&.
.SH "EXAMPLES"
.sp
The following examples illustrate the command line arguments that could be supplied to the fwknop client in a few situations:
+.SS "Quick start"
+.sp
+The most effective and easiest way to use \fBfwknop\fR is to have the client generate both an encryption key and an HMAC key, and then save them to the \(lq$HOME/\&.fwknoprc\(rq file along with access request specifics\&. The keys will also need to be transferred to the system where \fBfwknopd\fR is running\&. The also client supports a separate set of encryption and HMAC keys for each SPA destination if multiple fwknopd servers are running on different systems\&.
+.sp
+So, assuming that the IP \fI2\&.2\&.2\&.2\fR is the system where \fBfwknopd\fR is deployed and SSH is protected by the firewall on that system in a default\-drop stance, run the client like so to generate encryption and HMAC keys:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+ $ fwknop \-A tcp/22 \-\-use\-hmac \-R \-D 2\&.2\&.2\&.2 \-\-key\-gen \-\-save\-rc\-stanza \-\-verbose
+ [+] Wrote Rijndael and HMAC keys to rc file: /home/user/\&.fwknoprc
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+With the access request arguments and encryption and HMAC keys generated and saved in \(lq$HOME/\&.fwknoprc\(rq, the keys themselves need to be transferred to the \fI2\&.2\&.2\&.2\fR system where fwknopd is running\&. As always, this should be done via some secure means such as SSH before SPA is enabled and SSHD is blocked by the firewall\&. Here is what the new \fI2\&.2\&.2\&.2\fR stanza looks like in the \&.fwknoprc file:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+ $ tail \-n 8 /home/user/\&.fwknoprc
+ [2\&.2\&.2\&.2]
+ ACCESS tcp/22
+ SPA_SERVER 2\&.2\&.2\&.2
+ KEY_BASE64 HvUtIOramehLGKimD4ECXOzinaH4h3U8H1WXum7b54Q=
+ HMAC_KEY_BASE64 DLeLf93a3yBT2vhEpM+dWlirGta5GU+jdyG5uXp4461HgOtbqMem4gX0Bp2PJGzYZlbbcavcOM00UPm+0GqkXA==
+ USE_HMAC Y
+ VERBOSE 1
+ RESOLVE_IP_HTTP Y
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+The keys are base64 encoded blobs of random data, and both the \fBKEY_BASE64\fR and \fBHMAC_KEY_BASE64\fR lines should be copied verbatim and placed within the \fI@sysconfdir@/fwknop/access\&.conf\fR file on \fI2\&.2\&.2\&.2\fR\&. Once this is done, \fBfwknopd\fR can be started on that system, a default\-drop policy against SSH connections can be put in place, and then access to SSH is managed via fwknop\&. To access SSH, just use the \fB\-n\fR argument to reference the \fI2\&.2\&.2\&.2\fR stanza out of the \&.fwknoprc file (some \fB\-\-verbose\fR output is included for illustration):
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+ $ fwknop \-n 2\&.2\&.2\&.2
+
+ FKO Field Values:
+ =================
+
+ Random Value: 8950423288486978
+ Username: mbr
+ Timestamp: 1370194770
+ FKO Version: 2\&.5\&.0
+ Message Type: 1 (Access msg)
+ Message String: 1\&.1\&.1\&.1,tcp/22
+ Nat Access: <NULL>
+ Server Auth: <NULL>
+ Client Timeout: 0 (seconds)
+ Digest Type: 3 (SHA256)
+ HMAC Type: 3 (SHA256)
+ Encryption Type: 1 (Rijndael)
+ Encryption Mode: 2 (CBC)
+ \&.\&.\&.
+
+ $ ssh \-l user 2\&.2\&.2\&.2
+ user@2\&.2\&.2\&.2\*(Aqs password:
+.fi
+.if n \{\
+.RE
+.\}
.SS "Access mode examples"
.sp
-The most common usage of \fBfwknop\fR is to gain access to \fISSH\fR running on a remote system that has the \fBfwknopd\fR daemon deployed along with a default\-drop firewall policy\&. The following command illustrates this where IP \fI1\&.1\&.1\&.1\fR is the IP to be allowed through the firewall running on \fI2\&.2\&.2\&.2\fR (note that the \fI\*(Aq@sysconfdir@/fwknop/access\&.conf\fR file consumed by \fBfwknopd\fR will need to have matching encryption and HMAC keys, and configuration specifics can be found in the \fIfwknopd(8)\fR manual page):
+The most common usage of \fBfwknop\fR is to gain access to SSH running on a remote system that has the \fBfwknopd\fR daemon deployed along with a default\-drop firewall policy\&. The following command illustrates this where IP \fI1\&.1\&.1\&.1\fR is the IP to be allowed through the firewall running on \fI3\&.3\&.3\&.3\fR (note that the \fI@sysconfdir@/fwknop/access\&.conf\fR file consumed by \fBfwknopd\fR will need to have matching encryption and HMAC keys, and configuration specifics can be found in the \fIfwknopd(8)\fR manual page)\&. Also, note the examples below prompt the user to supply the encryption and HMAC keys via stdin instead of writing them to disk as in the case of using the \(lq$HOME/\&.fwknoprc\(rq file in the example above\&. However, all of the following examples can be converted to using the \&.fwknoprc file just by adding the \fB\-\-save\-rc\-stanza\fR argument:
.sp
.if n \{\
.RS 4
.\}
.nf
- $ fwknop \-A tcp/22 \-\-use\-hmac \-a 1\&.1\&.1\&.1 \-D 2\&.2\&.2\&.2
+ $ fwknop \-A tcp/22 \-\-use\-hmac \-a 1\&.1\&.1\&.1 \-D 3\&.3\&.3\&.3
Enter encryption key:
Enter HMAC key:
- $ ssh \-l user 2\&.2\&.2\&.2
- user@2\&.2\&.2\&.2\*(Aqs password:
+ $ ssh \-l user 3\&.3\&.3\&.3
+ user@3\&.3\&.3\&.3\*(Aqs password:
.fi
.if n \{\
.RE
@@ -886,7 +959,7 @@ If the \fB\-\-verbose\fR flag is added to the command line, then some SPA packet
.RS 4
.\}
.nf
- $ fwknop \-A tcp/22 \-\-use\-hmac \-a 1\&.1\&.1\&.1 \-D 2\&.2\&.2\&.2 \-\-verbose
+ $ fwknop \-A tcp/22 \-\-use\-hmac \-a 1\&.1\&.1\&.1 \-D 3\&.3\&.3\&.3 \-\-verbose
Enter encryption key:
Enter HMAC key:
@@ -908,13 +981,13 @@ If the \fB\-\-verbose\fR flag is added to the command line, then some SPA packet
.RE
.\}
.sp
-Simultaneous access to multiple services is also supported, and here is an example of requesting access to both \fISSH\fR and \fIOpenVPN\fR on \fI2\&.2\&.2\&.2\fR:
+Simultaneous access to multiple services is also supported, and here is an example of requesting access to both \fISSH\fR and \fIOpenVPN\fR on \fI3\&.3\&.3\&.3\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
- $ fwknop \-A "tcp/22,tcp/1194" \-\-use\-hmac \-a 1\&.1\&.1\&.1 \-D 2\&.2\&.2\&.2
+ $ fwknop \-A "tcp/22,tcp/1194" \-\-use\-hmac \-a 1\&.1\&.1\&.1 \-D 3\&.3\&.3\&.3
.fi
.if n \{\
.RE
@@ -926,7 +999,7 @@ There are many cases where an \fBfwknop\fR client is deployed on a network behin
.RS 4
.\}
.nf
- $ fwknop \-A tcp/22 \-\-use\-hmac \-R \-D 2\&.2\&.2\&.2
+ $ fwknop \-A tcp/22 \-\-use\-hmac \-R \-D 3\&.3\&.3\&.3
.fi
.if n \{\
.RE
@@ -938,45 +1011,48 @@ Use the Single Packet Authorization mode to gain access to \fISSH\fR and this ti
.RS 4
.\}
.nf
- $ fwknop \-A tcp/22 \-\-use\-hmac \-\-gpg\-sign ABCD1234 \-\-gpg\-\-recipient 1234ABCD \-R \-D 2\&.2\&.2\&.2
+ $ fwknop \-A tcp/22 \-\-use\-hmac \-\-gpg\-sign ABCD1234 \-\-gpg\-\-recipient 1234ABCD \-R \-D 3\&.3\&.3\&.3
.fi
.if n \{\
.RE
.\}
.sp
-Instruct the fwknop server running at 2\&.2\&.2\&.2 to allow 1\&.1\&.1\&.1 to connect to \fISSH\fR, but spoof the authorization packet from an IP associated with \fIwww\&.yahoo\&.com\fR (requires root on the \fBfwknop\fR client OS):
+Instruct the fwknop server running at 3\&.3\&.3\&.3 to allow 1\&.1\&.1\&.1 to connect to \fISSH\fR, but spoof the authorization packet from an IP associated with \fIwww\&.yahoo\&.com\fR (requires root on the \fBfwknop\fR client OS):
.sp
.if n \{\
.RS 4
.\}
.nf
- # fwknop \-\-spoof\-src "www\&.yahoo\&.com" \-A tcp/22 \-\-use\-hmac \-a 1\&.1\&.1\&.1 \-D 2\&.2\&.2\&.2
+ # fwknop \-\-spoof\-src "www\&.yahoo\&.com" \-A tcp/22 \-\-use\-hmac \-a 1\&.1\&.1\&.1 \-D 3\&.3\&.3\&.3
.fi
.if n \{\
.RE
.\}
.sp
-When \fBfwknopd\fR is running on an iptables firewall with systems deployed behind it, it is possible to take advantage of the \fINAT\fR capabilities offered by iptables in order to transparently reach systems behind the firewall via SPA\&. Here is an example where the \fBfwknop\fR client is used to gain access to \fISSH\fR running on the non\-routable IP \fI192\&.168\&.10\&.23\fR that is deployed on the network behind \fI2\&.2\&.2\&.2\fR\&. In this case, the \fISSH\fR connection made to \fI2\&.2\&.2\&.2\fR is translated into the \fI192\&.168\&.10\&.2\fR system automatically:
+When \fBfwknopd\fR is running on an iptables firewall with systems deployed behind it, it is possible to take advantage of the NAT capabilities offered by iptables in order to transparently reach systems behind the firewall via SPA\&. Here is an example where the \fBfwknop\fR client is used to gain access to SSH running on the non\-routable IP \fI192\&.168\&.10\&.23\fR that is deployed on the network behind \fI3\&.3\&.3\&.3\fR\&. In this case, the SSH connection made to \fI3\&.3\&.3\&.3\fR is translated via NAT to the \fI192\&.168\&.10\&.2\fR system automatically:
.sp
.if n \{\
.RS 4
.\}
.nf
- $ fwknop \-A tcp/22 \-N 192\&.168\&.10\&.2:22 \-R \-D 2\&.2\&.2\&.2
+ $ fwknop \-A tcp/22 \-N 192\&.168\&.10\&.2:22 \-R \-D 3\&.3\&.3\&.3
.fi
.if n \{\
.RE
.\}
+.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 possible for SPA packets that don\(cqt use an HMAC\&. It is recommended to upgrade all fwknop clients and servers to 2\&.5 and use the new HMAC mode for properly authenticated SPA communications\&.
.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, libpcap is a required dependency\&.
+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\&.
.sp
-For GPG functionality, GnuPG must also be correctly installed and configured along with the libgpgme library\&.
+For GPG functionality, GnuPG must also be correctly installed and configured along with the \fIlibgpgme\fR library\&.
.sp
-To take advantage of all of the authentication and access management features of the \fBfwknopd\fR daemon/service a functioning iptables, ipfw, or pf firewall is required on the underlying operating system\&.
+To take advantage of all of the authentication and access management features of the \fBfwknopd\fR daemon/service a functioning \fIiptables\fR, \fIipfw\fR, or \fIpf\fR firewall is required on the underlying operating system\&.
.SH "DIAGNOSTICS"
.sp
-The most comprehensive way to gain diagnostic information on \fBfwknop\fR is to run the test suite \fItest\-fwknop\&.pl\fR script located in the \fItest/\fR directory in the fwknop sources\&. The test suite runs sends fwknop through a large number of run time tests, has \fIvalgrind\fR support, validates both SPA encryption and HMAC results against OpenSSL, and even has its own built in fuzzer for SPA communications\&. For more basic diagnostic information, \fBfwknop\fR can be executed with the \fB\-T\fR (or \fB\-\-test\fR) command line option\&. This will have \fBfwknop\fR simply create and print the SPA packet information, then run it through a decrypt/decode cycle and print it again\&. In addition, the \fB\-\-verbose\fR command line switch is useful to see various SPA packet specifics printed to stdout\&.
+The most comprehensive way to gain diagnostic information on \fBfwknop\fR is to run the test suite \fItest\-fwknop\&.pl\fR script located in the \fItest/\fR directory in the fwknop sources\&. The test suite sends fwknop through a large number of run time tests, has \fIvalgrind\fR support, validates both SPA encryption and HMAC results against OpenSSL, and even has its own built in fuzzer for SPA communications\&. For more basic diagnostic information, \fBfwknop\fR can be executed with the \fB\-T\fR (or \fB\-\-test\fR) command line option\&. This will have \fBfwknop\fR simply create and print the SPA packet information, then run it through a decrypt/decode cycle and print it again\&. In addition, the \fB\-\-verbose\fR command line switch is useful to see various SPA packet specifics printed to stdout\&.
.SH "SEE ALSO"
.sp
fwknopd(8), iptables(8), pf(4), pfctl(8), ipfw(8), gpg(1), libfko documentation\&.
View
163 doc/fwknop.man.asciidoc
@@ -68,7 +68,7 @@ encryption key, and both can be generated with the *--key-gen* option.
*fwknop* encrypts SPA packets either with the 'Rijndael' block cipher or via
'GnuPG' and associated asymmetric cipher. If the symmetric encryption method
is chosen, then as usual the encryption key is shared between the client and
-server (see the *fwknopd* ''@sysconfdir@/fwknop/access.conf' file for details). The actual
+server (see the *fwknopd* '@sysconfdir@/fwknop/access.conf' file for details). The actual
encryption key used for Rijndael encryption is generated via the standard
PBKDF1 key derivation algorithm, and CBC mode is set. If the GnuPG method
is chosen, then the encryption keys are derived from GnuPG key rings. SPA
@@ -116,7 +116,7 @@ Public License (GPL).
REQUIRED ARGUMENTS
------------------
These required arguments can be specified via command-line or from within
-the '.fwknoprc' file (see '-n, --named-config' option and the FWKNOPRC FILE
+the '~/.fwknoprc' file (see '-n, --named-config' option and the FWKNOPRC FILE
section below).
*-A, --access*='<port list>'::
@@ -138,7 +138,8 @@ section below).
*fwknopd* daemon what IP should be allowed through the local firewall. It
is recommend to use the *-R* or *-a* options instead of *-s* in order
to harden SPA communications against possible 'Man-In-The-Middle' (MITM)
- attacks.
+ attacks, and on the server side set 'REQUIRE_SOURCE_ADDRESS' variable in
+ the '@sysconfdir@/fwknop/access.conf' file.
GENERAL OPTIONS
@@ -439,7 +440,7 @@ SPA OPTIONS
*-M, --encryption-mode*='<mode>'::
Specify the encryption mode when AES is used for encrypting SPA packets.
The default is CBC mode, but others can be chosen such as CFB or OFB
- as long as this is also specified in the ''@sysconfdir@/fwknop/access.conf' file on the
+ as long as this is also specified in the '@sysconfdir@/fwknop/access.conf' file on the
server side via the ENCRYPTION_MODE variable. In general, it is
recommended to not include this argument and let the default (CBC) apply.
Note that the string ``legacy'' can be specified in order to generate SPA
@@ -485,12 +486,12 @@ SPA OPTIONS
SPA packet ICMP header. The default is zero.
-GPG-RELATED OPTIONS
--------------------
+GPG OPTIONS
+-----------
Note that the usage of GPG for SPA encryption/decryption can and should involve
GPG keys that are signed by each side (client and server). The basic procedure
for this involves the following steps after the client key has been transferred
-the server and vice-versa:
+to the server and vice-versa:
..........................
[spaserver]# gpg --import client.asc
@@ -697,7 +698,8 @@ Because *fwknop* places the IP to be allowed through the firewall within the
encrypted SPA payload (unless *-s* is used which is not recommended and can be
prohibited in the *fwknopd* server configuration), SPA packets can easily be
spoofed, and this is a good thing in this context. That is, the source IP of
-an SPA packet is ignored by the *fwknopd* daemon and only the IP that is
+an SPA packet is ignored by the *fwknopd* daemon (when the 'REQUIRE_SOURCE_ADDRESS'
+variable is set in the '@sysconfdir@/fwknop/access.conf' file) and only the IP that is
contained within an authenticated and properly decrypted SPA packet is granted
access through the firewall. This makes it possible to make it appear as
though, say, www.yahoo.com is trying to authenticate to a target system but in
@@ -709,29 +711,102 @@ EXAMPLES
The following examples illustrate the command line arguments that could
be supplied to the fwknop client in a few situations:
+Quick start
+~~~~~~~~~~~
+The most effective and easiest way to use *fwknop* is to have the client
+generate both an encryption key and an HMAC key, and then save them to the
+``$HOME/.fwknoprc'' file along with access request specifics. The keys will
+also need to be transferred to the system where *fwknopd* is running. The
+also client supports a separate set of encryption and HMAC keys for each SPA
+destination if multiple fwknopd servers are running on different systems.
+
+So, assuming that the IP '2.2.2.2' is the system where *fwknopd* is deployed
+and SSH is protected by the firewall on that system in a default-drop stance,
+run the client like so to generate encryption and HMAC keys:
+
+..........................
+ $ fwknop -A tcp/22 --use-hmac -R -D 2.2.2.2 --key-gen --save-rc-stanza --verbose
+ [+] Wrote Rijndael and HMAC keys to rc file: /home/user/.fwknoprc
+..........................
+
+With the access request arguments and encryption and HMAC keys generated and saved
+in ``$HOME/.fwknoprc'', the keys themselves need to be transferred to the '2.2.2.2'
+system where fwknopd is running. As always, this should be done via some secure
+means such as SSH before SPA is enabled and SSHD is blocked by the firewall. Here
+is what the new '2.2.2.2' stanza looks like in the .fwknoprc file:
+
+..........................
+ $ tail -n 8 /home/user/.fwknoprc
+ [2.2.2.2]
+ ACCESS tcp/22
+ SPA_SERVER 2.2.2.2
+ KEY_BASE64 HvUtIOramehLGKimD4ECXOzinaH4h3U8H1WXum7b54Q=
+ HMAC_KEY_BASE64 DLeLf93a3yBT2vhEpM+dWlirGta5GU+jdyG5uXp4461HgOtbqMem4gX0Bp2PJGzYZlbbcavcOM00UPm+0GqkXA==
+ USE_HMAC Y
+ VERBOSE 1
+ RESOLVE_IP_HTTP Y
+..........................
+
+The keys are base64 encoded blobs of random data, and both the *KEY_BASE64* and
+*HMAC_KEY_BASE64* lines should be copied verbatim and placed within the
+'@sysconfdir@/fwknop/access.conf' file on '2.2.2.2'. Once this is done, *fwknopd*
+can be started on that system, a default-drop policy against SSH connections can
+be put in place, and then access to SSH is managed via fwknop. To access SSH,
+just use the *-n* argument to reference the '2.2.2.2' stanza out of the .fwknoprc
+file (some *--verbose* output is included for illustration):
+
+..........................
+ $ fwknop -n 2.2.2.2
+
+ FKO Field Values:
+ =================
+
+ Random Value: 8950423288486978
+ Username: mbr
+ Timestamp: 1370194770
+ FKO Version: 2.5.0
+ Message Type: 1 (Access msg)
+ Message String: 1.1.1.1,tcp/22
+ Nat Access: <NULL>
+ Server Auth: <NULL>
+ Client Timeout: 0 (seconds)
+ Digest Type: 3 (SHA256)
+ HMAC Type: 3 (SHA256)
+ Encryption Type: 1 (Rijndael)
+ Encryption Mode: 2 (CBC)
+ ...
+
+ $ ssh -l user 2.2.2.2
+ user@2.2.2.2's password:
+..........................
+
Access mode examples
~~~~~~~~~~~~~~~~~~~~
-The most common usage of *fwknop* is to gain access to 'SSH' running on a
+The most common usage of *fwknop* is to gain access to SSH running on a
remote system that has the *fwknopd* daemon deployed along with a default-drop
firewall policy. The following command illustrates this where IP '1.1.1.1' is
-the IP to be allowed through the firewall running on '2.2.2.2' (note that the
-''@sysconfdir@/fwknop/access.conf' file consumed by *fwknopd* will need to have matching encryption
+the IP to be allowed through the firewall running on '3.3.3.3' (note that the
+'@sysconfdir@/fwknop/access.conf' file consumed by *fwknopd* will need to have matching encryption
and HMAC keys, and configuration specifics can be found in the 'fwknopd(8)'
-manual page):
+manual page). Also, note the examples below prompt the user to supply the
+encryption and HMAC keys via stdin instead of writing them to disk as in the
+case of using the ``$HOME/.fwknoprc'' file in the example above. However, all
+of the following examples can be converted to using the .fwknoprc file just by
+adding the *--save-rc-stanza* argument:
..........................
- $ fwknop -A tcp/22 --use-hmac -a 1.1.1.1 -D 2.2.2.2
+ $ fwknop -A tcp/22 --use-hmac -a 1.1.1.1 -D 3.3.3.3
Enter encryption key:
Enter HMAC key:
- $ ssh -l user 2.2.2.2
- user@2.2.2.2's password:
+ $ ssh -l user 3.3.3.3
+ user@3.3.3.3's password:
..........................
If the *--verbose* flag is added to the command line, then some SPA packet
specifics are printed to stdout (not all output is shown for brevity):
..........................
- $ fwknop -A tcp/22 --use-hmac -a 1.1.1.1 -D 2.2.2.2 --verbose
+ $ fwknop -A tcp/22 --use-hmac -a 1.1.1.1 -D 3.3.3.3 --verbose
Enter encryption key:
Enter HMAC key:
@@ -751,10 +826,10 @@ specifics are printed to stdout (not all output is shown for brevity):
..........................
Simultaneous access to multiple services is also supported, and here is an
-example of requesting access to both 'SSH' and 'OpenVPN' on '2.2.2.2':
+example of requesting access to both 'SSH' and 'OpenVPN' on '3.3.3.3':
..........................
- $ fwknop -A "tcp/22,tcp/1194" --use-hmac -a 1.1.1.1 -D 2.2.2.2
+ $ fwknop -A "tcp/22,tcp/1194" --use-hmac -a 1.1.1.1 -D 3.3.3.3
..........................
There are many cases where an *fwknop* client is deployed on a network behind
@@ -769,48 +844,74 @@ IP address the SPA packet originates (i.e. using *-s* opens the possibility of
a MITM attack):
..........................
- $ fwknop -A tcp/22 --use-hmac -R -D 2.2.2.2
+ $ fwknop -A tcp/22 --use-hmac -R -D 3.3.3.3
..........................
Use the Single Packet Authorization mode to gain access to 'SSH' and this time
use GnuPG keys to encrypt and decrypt:
..........................
- $ fwknop -A tcp/22 --use-hmac --gpg-sign ABCD1234 --gpg--recipient 1234ABCD -R -D 2.2.2.2
+ $ fwknop -A tcp/22 --use-hmac --gpg-sign ABCD1234 --gpg--recipient 1234ABCD -R -D 3.3.3.3
..........................
-Instruct the fwknop server running at 2.2.2.2 to allow 1.1.1.1 to connect to
+Instruct the fwknop server running at 3.3.3.3 to allow 1.1.1.1 to connect to
'SSH', but spoof the authorization packet from an IP associated with
'www.yahoo.com' (requires root on the *fwknop* client OS):
..........................
- # fwknop --spoof-src "www.yahoo.com" -A tcp/22 --use-hmac -a 1.1.1.1 -D 2.2.2.2
+ # fwknop --spoof-src "www.yahoo.com" -A tcp/22 --use-hmac -a 1.1.1.1 -D 3.3.3.3
..........................
When *fwknopd* is running on an iptables firewall with systems deployed behind
-it, it is possible to take advantage of the 'NAT' capabilities offered by
+it, it is possible to take advantage of the NAT capabilities offered by
iptables in order to transparently reach systems behind the firewall via SPA.
-Here is an example where the *fwknop* client is used to gain access to 'SSH'
+Here is an example where the *fwknop* client is used to gain access to SSH
running on the non-routable IP '192.168.10.23' that is deployed on the network
-behind '2.2.2.2'. In this case, the 'SSH' connection made to '2.2.2.2' is
-translated into the '192.168.10.2' system automatically:
+behind '3.3.3.3'. In this case, the SSH connection made to '3.3.3.3' is
+translated via NAT to the '192.168.10.2' system automatically:
..........................
- $ fwknop -A tcp/22 -N 192.168.10.2:22 -R -D 2.2.2.2
+ $ fwknop -A tcp/22 -N 192.168.10.2:22 -R -D 3.3.3.3
..........................
+BACKWARDS COMPATIBILITY
+-----------------------
+With the '2.5' release, *fwknop* 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 '2.5' release
+are incompatible with previous versions of fwknop. However, backwards
+compatibility is supported through setting the 'legacy' encryption mode with
+*-M* on the fwknop client command line and/or the 'ENCRYPTION_MODE' variable in
+the '@sysconfdir@/fwknop/access.conf' file. This way, a pre-2.5 server can
+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 possible for SPA packets that don't use an HMAC. It is recommended to
+upgrade all fwknop clients and servers to 2.5 and use the new HMAC mode for
+properly authenticated SPA communications.
+
+
DEPENDENCIES
------------
The *fwknop* client requires 'libfko' which is normally included with both source
and binary distributions, and is a dedicated library developed by the fwknop
-project. Whenever the *fwknopd* server is used, libpcap is a required dependency.
+project. Whenever the *fwknopd* server is used, 'libpcap' is a required dependency.
+However, the upcoming '2.6' 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's 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.
For GPG functionality, GnuPG must also be correctly installed and configured
-along with the libgpgme library.
+along with the 'libgpgme' library.
To take advantage of all of the authentication and access management
-features of the *fwknopd* daemon/service a functioning iptables, ipfw, or pf
+features of the *fwknopd* daemon/service a functioning 'iptables', 'ipfw', or 'pf'
firewall is required on the underlying operating system.
@@ -818,7 +919,7 @@ DIAGNOSTICS
-----------
The most comprehensive way to gain diagnostic information on *fwknop* is to run
the test suite 'test-fwknop.pl' script located in the 'test/' directory in the fwknop
-sources. The test suite runs sends fwknop through a large number of run time
+sources. The test suite sends fwknop through a large number of run time
tests, has 'valgrind' support, validates both SPA encryption and HMAC results
against OpenSSL, and even has its own built in fuzzer for SPA communications.
For more basic diagnostic information, *fwknop* can be executed with the *-T*

0 comments on commit 1b41e60

Please sign in to comment.
Something went wrong with that request. Please try again.