updated README to include the introduction from the fwknop man page
authorMichael Rash <mbr@cipherdyne.org>
Sun, 30 Jun 2013 19:52:47 +0000 (15:52 -0400)
committerMichael Rash <mbr@cipherdyne.org>
Sun, 30 Jun 2013 19:52:47 +0000 (15:52 -0400)
README

diff --git a/README b/README
index f2e582f..01e09ac 100644 (file)
--- a/README
+++ b/README
@@ -1,29 +1,78 @@
-This is the top-level directory for the C version of fwknop.
-
-Additional information and details can be found on the fwknop-c site at
-http://devmetrix.org/trac/fwknop-c.
-
+This is the top-level directory for the fwknop project.
 
 INTRODUCTION
 ============
-This distribution will be a C-based implementation of Michael Rash's
-Perl-based "fwknop" programs.  For more information on fwknop and what
-it is all about, go to http://www.cipherdyne.org/fwknop.
+fwknop implements an authorization scheme known as Single Packet Authorization
+(SPA) for strong service concealment. SPA requires only a single packet which
+is encrypted, non-replayable, and authenticated via an HMAC in order to
+communicate desired access to a service that is hidden behind a firewall in a
+default-drop filtering stance. The main application of SPA is to use a firewall
+to drop all attempts to connect to services such as SSH in order to make the
+exploitation of vulnerabilities (both 0-day and unpatched code) more difficult.
+Any service that is concealed by SPA naturally cannot be scanned for with Nmap.
+The fwknop project supports three different firewalls: iptables on Linux
+systems, pf on OpenBSD, and ipfw on FreeBSD and Mac OS X.
+
+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 possible to reliably support, 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 standard cryptographic operations for
+SPA packet authentication and encryption/decryption.
+
+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 (enabled via the --use-hmac command line switch), it is highly
+recommended for three reasons: 1) without an HMAC, cryptographically strong
+authentication is not possible with fwknop unless GnuPG is used, but even then
+an HMAC should still be applied, 2) 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 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 even sent through the decryption routines.
+Reason 3) 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 libgpgme
+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 --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 /etc/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.
 
 
 CURRENT STATE
 =============
-At present, we have an implementation of the Firewall Knock Operator
-library; `libfko', as well as the fwknop client and server applications.
-The library provides the API and back-end functionality for managing the
-Single Packet Authorization (SPA) data that the other fwknop components
-employ.  It also can be used by other programs that need SPA functonality
-(see the `perl' directory for the FKO perl module as an example).
+This README file describes the present state of the fwknop project as of the
+2.5 release made in July, 2013.  At present, we have an implementation of the
+Firewall Knock Operator library; `libfko', as well as the fwknop client and
+server applications.  The library provides the API and back-end functionality
+for managing the Single Packet Authorization (SPA) data that the other fwknop
+components employ.  It also can be used by other programs that need SPA
+functonality (see the `perl' directory for the FKO perl module as an example,
+and there are python bindings as well in the 'python' directory).
+
 
-This first version of the C implementation is planned to be compatible
-with legacy Perl-based fwknop version 1.9.x. However, it was decided to
-start the version number at 2.0 to differentiate it from the current
-Perl implementation.
+UPGRADING
+=========
+If you are upgrading from an older version of fwknop (and this includes the
+original perl implementation as well), then you will want to read the
+following link to ensure a smooth transition to fwknop-2.5:
+
+http://www.cipherdyne.org/fwknop/docs/fwknop-tutorial.html#backwards-compatibility
 
 
 BUILDING fwknop
@@ -49,13 +98,16 @@ There are some "configure" options that are specific to fwknop.  They are
   --with-ipfw=/path/to/ipfw
                           Specify path to the ipfw executable [default=check
                           path]
-  --with-sh=/path/to/sh   Specify path to the sh executable [default=check
+  --with-pf=/path/to/pfctl
+                          Specify path to the pf executable [default=check
+                          path]
+  --with-ipf=/path/to/ipf Specify path to the ipf executable [default=check
                           path]
 
 
 NOTE to those who may be migrating from the Perl version of fwknop
 ==================================================================
-For those of you who are currently using the Perl version and plan to 
+For those of you who are currently using the Perl version and plan to
 migrate to this version, there are some things to be aware of:
 
     - Not all of the features and functionality of the Perl-based
@@ -84,4 +136,3 @@ The fwknop and fwknopd man page nroff sources are included in their
 respective directorys (client and server).  These nroff files are derived
 from the asciidoc sources in the 'docs' directory.  See the README in docs
 for details.
-