[docs] fwknop client man page update for HMAC material
authorMichael Rash <mbr@cipherdyne.org>
Wed, 15 May 2013 03:22:03 +0000 (23:22 -0400)
committerMichael Rash <mbr@cipherdyne.org>
Wed, 15 May 2013 03:22:03 +0000 (23:22 -0400)
doc/fwknop.man.asciidoc

index b6cb6e2..de7925f 100644 (file)
@@ -16,40 +16,55 @@ SYNOPSIS
 DESCRIPTION
 -----------
 *fwknop* implements an authorization scheme known as Single Packet
-Authorization (SPA) for Linux systems running iptables.  This mechanism
-requires only a single encrypted and non-replayed packet to communicate
-various pieces of information including desired access through an iptables
-or ipfw policy.  The main application of this program is to use iptables
-in a default-drop stance to protect services such as 'SSH' with an
+Authorization (SPA) for passive service protection.  SPA requires only a single
+non-replayed encrypted packet together with an HMAC in order to communicate
+various pieces of information including desired access to a service that is
+otherwise blocked by a firewall.  The main application of SPA is to use a
+firewall in a default-drop stance to protect services such as 'SSH' with an
 additional layer of security in order to make the exploitation of
-vulnerabilities (both 0-day and unpatched code) much more difficult.
-
-An authorization server *fwknopd* passively monitors authorization packets
-via 'libpcap' and hence there is no ``server'' to which to connect in the
-traditional sense.  Any service protected by *fwknop* is inaccessible (by
-using 'iptables' or 'ipfw' to intercept packets within the kernel) before
-authenticating; anyone scanning for the service will not be able to detect
-that it is even listening.  Single Packet Authorization offers many
-advantages over port knocking, including non-replayability of SPA packets,
-ability to use asymmetric ciphers (such as Elgamal), and SPA cannot be
-broken by simply spoofing packets to duplicate ports within the knock
-sequence on the server to break port knocking authentication.
-
-SPA packets can easily be spoofed as well (this is a good thing in this
-context), and 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.
-
-Authorization packets are either encrypted with the 'Rijndael' block cipher
-or via 'GnuPG' and associated asymmetric ciphers.  If the symmetric encryption
-method is chosen, then the encryption key is shared between the client and
-server (see the fwknopd 'access.conf' file for details).  If the GnuPG method
+vulnerabilities (both 0-day and unpatched code) more difficult.  In
+addition, services that are protected in this fashion naturally cannot be
+scanned for with 'Nmap'.
+
+SPA is essentially next generation Port Knocking (PK), but solves many of the
+limitations exhibited by PK while retaining its core benefits.  PK limitations
+include a general difficulty in protecting against replay attacks, asymmetric
+ciphers and HMAC schemes are not usually supported, and it is trivially easy
+to mount a DoS attack against a PK server just by spoofing an additional
+packet into a PK sequence as it traverses the network (thereby convincing the
+PK server that the client doesn't know the proper sequence).  All of these
+limitation are solved by SPA.  At the same time, SPA hides services behind a
+default-drop firewall policy, acquires SPA data passively (usually via
+libpcap or other means), and implements lightweight cryptographic operations
+for SPA packet authentication and encryption/decryption.
+
+This is the manual page for the *fwknop* client which is responsible for
+constructing SPA packets and sending them over the network.  The server side is
+implemented by the *fwknopd* daemon which sniffs the network for SPA packets,
+and it is recommended to read the 'fwknopd(8)' manual page as well.
+
+SPA packets generated by *fwknop* leverage HMAC for authenticated encryption
+in the encrypt-then-authenticate model.  Although the usage of an HMAC is
+currently optional, it is highly recommended for three reasons: '1)' without
+an HMAC, cryptographically strong authentication is not possible unless GnuPG
+is used, '2)' an HMAC applied after encryption protects against CBC-mode
+padding oracle attacks (see the Vaudenay attack and the more recent
+"Lucky 13" attack against SSL), and '3)' the code required by the *fwknopd*
+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't event
+sent through the decryption routines.  Generating an HMAC requires a dedicated
+key in addition to the normal encryption key.
+
+*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* 'access.conf' file for details).  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 they are encrypted):
+format (before encryption and the HMAC is applied):
 
 ..........................
-    random number (16 bytes)
+    random data (16 bytes)
     username
     timestamp
     software version
@@ -59,27 +74,24 @@ format (before they are encrypted):
     message digest (SHA512 / SHA384 / SHA256 / SHA1 / MD5)
 ..........................
 
-Each of the above fields are separated by a ":" character due to the
-variable length of several of the fields, and those that might contain
-":" characters are base64 encoded.  The message digest (*SHA256* by
-default in all versions of *fwknop* greater than 1.9.1) allows the server
-to check message integrity after decryption, and the 16 bytes of random data
-ensures (with high probability) that no two messages are identical.  This
-ensures that replay attacks are not possible against *fwknop*.
-
-For each packet coming from an *fwknop* client, the *fwknopd* server can
-cache the digest calculated over the entire packet and compares against
-previous packet digests in order to detect attempted replay attacks.  Syslog
+Each of the above fields are separated by a ":" character due to the variable
+length of several of the fields, and those that might contain ":" characters
+are base64 encoded.  The message digest (*SHA256* by default) is part of the
+data to be encrypted and is independent of the HMAC which is appended to the
+SPA packet data after encryption.  The 16 bytes of random data ensures that no
+two SPA packets are identical, and this is in addition to and independent of
+using PBKDF1 for key derivation for Rijndael in CBC mode.  Because *fwknopd*
+tracks the SHA256 digest of all incoming valid SPA packets and throws out
+duplicates, replay attacks are not possible against *fwknop*.  Syslog
 alerts are generated if a replay is detected.
 
 By default, the *fwknop* client sends authorization packets over UDP port
-62201, but this can be altered with the *--server-port* argument. The server
-must first be configured to acquire the SPA data on the changed protocol-port.
+62201, but this can be altered with the *--server-port* argument (this requires
+*fwknopd* to be configured to acquire SPA data over the selected port).
 Also, *fwknop* can send the SPA packet over a random port via the
 *--rand-port* argument. See 'fwknopd(8)' for further details. See the
 *EXAMPLES* section for example invocations of the *fwknop* client.
 
-
 REQUIRED ARGUMENTS
 ------------------
 These required arguments can be specified via command-line or from within
@@ -130,8 +142,8 @@ GENERAL OPTIONS
     with cleartext passwords is not a good idea and is not recommended.
     Having the *fwknop* client prompt you for the key is generally more
     secure.  Note also that if a key is stored on disk, the *fwknop* rc
-    file is a more powerful mechanism for specifying the key but other
-    options as well.
+    file is a more powerful mechanism for specifying not only the key but
+    other options as well.
 
 *--get-hmac-key*='<file>'::
     Load an HMAC key/password from the specified file.  Similarly to the
@@ -143,7 +155,8 @@ GENERAL OPTIONS
     not a good idea and is not recommended.  Having the *fwknop* client
     prompt you for the HMAC key is generally more secure.  Note also that
     if a key is stored on disk, the *fwknop* rc file is a more powerful
-    mechanism for specifying the key but other options as well.
+    mechanism for specifying not only the HMAC key but other options as
+    well.
 
 *--key-rijndael*='<key>'::
     Specify the Rijndael key. Since the key may be visible to utilities
@@ -266,11 +279,12 @@ SPA OPTIONS
     The default is CBC mode, but others can be chosen such as CFB or OFB
     as long as this is also specified in the 'access.conf' file on the
     server side via the ENCRYPTION_MODE variable.  In general, it is
-    recommended to not use this argument and just use the default.  Note that
-    the string ``legacy'' can be specified in order to generate SPA packets
-    with the old initialization vector strategy used by versions of *fwknop*
-    before 2.5.  With the 2.5 release, *fwknop* generates initialization
-    vectors in a manner that is compatible with OpenSSL.
+    recommended to not use this argument and just use the default (CBC).
+    Note that the string ``legacy'' can be specified in order to generate SPA
+    packets with the old initialization vector strategy used by versions of
+    *fwknop* prior to 2.5.  With the 2.5 release, *fwknop* generates
+    initialization vectors in a manner that is compatible with OpenSSL via the
+    PBKDF1 algorithm.
 
 *--hmac-digest-type*='<digest>'::
     Set the HMAC digest algorithm (default is sha256). Options are md5, sha1,
@@ -368,7 +382,9 @@ SPA OPTIONS
     *fwknopd* SPA server to use the source IP address from which the
     SPA packet originates as the IP that will be allowed through upon
     modification of the firewall ruleset.  This option is useful if the
-    *fwknop* client is deployed on a machine that is behind a NAT device. 
+    *fwknop* client is deployed on a machine that is behind a NAT device and
+    the external IP is not known.  However, usage of this option is not
+    recommended, and either the *-a* or *-R* options should be used instead.
     The permit-address options *-s*, *-R* and *-a* are mutually
     exclusive.
 
@@ -558,6 +574,18 @@ ENVIRONMENT
 -----------
 *SPOOF_USER*, *GPG_AGENT_INFO* (only used in *--gpg-agent* mode).
 
+SPA PACKET SPOOFING
+-------------------
+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
+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.
+
 EXAMPLES
 --------
 The following examples illustrate the command line arguments that could
@@ -565,17 +593,23 @@ be supplied to the fwknop client in a few situations:
 
 Access mode examples
 ~~~~~~~~~~~~~~~~~~~~
-Packet contents printed to stdout at the fwknop client when creating
-an ``access mode'' SPA packet:
+Packet contents printed to stdout by the fwknop client in *--verbose* mode when
+creating a normal ``access mode'' SPA packet with a SHA256 HMAC applied:
 
 ..........................
-    Random data:    6565240948266426
-    Username:       mbr
-    Timestamp:      1203863233
-    Version:        1.9.2
-    Type:           1 (access mode)
-    Access:         127.0.0.2,tcp/22
-    SHA256 sum:     gngquSL8AuM7r27XsR4qPmJhuBo9pG2PYwII06AaJHw
+       Random Value: 1916307060193417
+           Username: mbr
+          Timestamp: 1368498909
+        FKO Version: 2.5.0
+       Message Type: 1 (Access msg)
+     Message String: 127.0.0.2,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)
 ..........................
 
 Use the Single Packet Authorization mode to gain access to
@@ -583,7 +617,9 @@ tcp/22 (ssh) and udp/53 running on the system 10.0.0.123 from
 the IP 192.168.10.4:
 
 ..........................
-    $ fwknop -A "tcp/22,udp/53" -a 192.168.10.4 -D 10.0.0.123
+    $ fwknop -A "tcp/22,udp/53" --use-hmac -a 192.168.10.4 -D 10.0.0.123
+    Enter encryption key:
+    Enter HMAC key:
 ..........................
 
 Same as above example, but gain access from whatever source IP
@@ -591,17 +627,22 @@ is seen by the fwknop server (useful if the fwknop client is
 behind a NAT device):
 
 ..........................
-    $ fwknop -A "tcp/22,udp/53" -s -D 10.0.0.123
+    $ fwknop -A "tcp/22,udp/53" --use-hmac -s -D 10.0.0.123
+    Enter encryption key:
+    Enter HMAC key:
 ..........................
 
-Same as above example, but use an IP identification website to derive
-the client IP address.  This is a safer method of acquiring the client
+Same as above example, but use the IP resolution service available at
+'http://www.cipherdyne.org/cgi-bin/myip' to derive the external client IP
+address.  This is a safer method of acquiring the client
 IP address than using the *-s* option because the source IP is put within
 the encrypted packet instead of having the *fwknopd* daemon grant the
 requested access from whatever IP address the SPA packet originates:
 
 ..........................
-    $ fwknop -A "tcp/22,udp/53" -R -D 10.0.0.123
+    $ fwknop -A "tcp/22,udp/53" --use-hmac -R -D 10.0.0.123
+    Enter encryption key:
+    Enter HMAC key:
 ..........................
 
 Use the Single Packet Authorization mode to gain access to tcp/22
@@ -609,8 +650,9 @@ Use the Single Packet Authorization mode to gain access to tcp/22
 to encrypt and decrypt:
 
 ..........................
-    $ fwknop -A "tcp/22,udp/53" --gpg-sign ABCD1234 --gpg--recipient
-    1234ABCD -R -D 10.0.0.123
+    $ fwknop -A "tcp/22,udp/53" --use-hmac --gpg-sign ABCD1234 --gpg--recipient 1234ABCD -R -D 10.0.0.123
+    Enter encryption key:
+    Enter HMAC key:
 ..........................
 
 Instruct the fwknop server running at 10.0.0.123 to allow 172.16.5.4
@@ -618,21 +660,24 @@ to connect to TCP/22, but spoof the authorization packet from an IP
 associated with www.yahoo.com:
 
 ..........................
-    # fwknop --Spoof-src ’www.yahoo.com’ -A tcp/22 -a 172.16.5.4 -D
-    10.0.0.123
+    # fwknop --Spoof-src ’www.yahoo.com’ -A tcp/22 --use-hmac -a 172.16.5.4 -D 10.0.0.123
+    Enter encryption key:
+    Enter HMAC key:
 ..........................
 
 
 DEPENDENCIES
 ------------
 *fwknop* requires 'libfko' (which is normally included with both source and
-binary distributions).
+binary distributions).  Whenever the *fwknopd* server is used, libpcap is a
+required dependency.
 
-For GPG functionality, GnuPG must also be correctly installed and configured.
+For GPG functionality, GnuPG must also be correctly installed and configured
+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 firewall
-is required on the underlying operating system.
+To take advantage of all of the authentication and access management
+features of the *fwknopd* daemon/service a functioning iptables, ipfw, or pf
+firewall is required on the underlying operating system.
 
 
 DIAGNOSTICS
@@ -647,7 +692,12 @@ fwknopd(8), iptables(8), gpg(1), libfko documentation.
 
 More information on Single Packet Authorization can be found in the paper
 ``Single Packet Authorization with fwknop'' available at
-'http://www.cipherdyne.org/fwknop/docs/SPA.html'.
+'http://www.cipherdyne.org/fwknop/docs/SPA.html'.  A comprehensive tutorial
+on *fwknop* operations and theory can be found at
+'http://www.cipherdyne.org/fwknop/docs/fwknop-tutorial.html'.  This tutorial
+also includes information about the design of *fwknop* that may be worth
+reading for those interested in why fwknop is different from other SPA
+implementations.
 
 AUTHORS
 -------
@@ -667,12 +717,10 @@ Nomad at the BlackHat Briefings of 2005 (see: 'http://www.nmrc.org').
 
 BUGS
 ----
-Send  bug  reports  to dstuart@dstuart.org or mbr@cipherdyne.org.  Suggestions
+Send bug reports to dstuart@dstuart.org or mbr@cipherdyne.org.  Suggestions
 and/or comments are always welcome as well.
 
 DISTRIBUTION
 ------------
-*fwknop* is distributed under the GNU General Public License (GPL), and
-the latest version may be downloaded from 'http://www.cipherdyne.org'.
-
-
+*fwknop* is distributed under the GNU General Public License (GPL) version 2,
+and the latest version may be downloaded from 'http://www.cipherdyne.org'.