continued man page updates in preparation for the 2.5 release
authorMichael Rash <mbr@cipherdyne.org>
Sat, 18 May 2013 03:05:58 +0000 (23:05 -0400)
committerMichael Rash <mbr@cipherdyne.org>
Sat, 18 May 2013 03:05:58 +0000 (23:05 -0400)
doc/fwknop.man.asciidoc
doc/fwknopd.man.asciidoc

index dcc76b9..138e3d3 100644 (file)
@@ -46,14 +46,15 @@ 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*
+an HMAC, cryptographically strong authentication is not possible with *fwknop*
+unless GnuPG is used, '2)' an HMAC applied after encryption protects against
+CBC-mode padding oracle attacks such as 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.
+decrypt an SPA packet, so an SPA packet without a proper HMAC isn't even
+sent through the decryption routines.  Generating an HMAC for SPA
+communications 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
@@ -106,12 +107,6 @@ These required arguments can be specified via command-line or from within
 the '.fwknoprc' file (see '-n, --named-config' option and the FWKNOPRC FILE
 section below.
 
-*-D, --destination*='<IP-address>'::
-    Direct the *fwknop* client to authenticate with the *fwknopd*
-    daemon/service at the specified destination hostname or IP address. The
-    connection mode is discovered by the *fwknopd* daemon/service when it
-    decrypts and parses the authentication packet.
-
 *-A, --access*='<port list>'::
     Provide a list of ports and protocols to access on a remote computer
     running *fwknopd*.  The format of this list is
@@ -120,9 +115,15 @@ section below.
     sending full commands with the *--server-cmd* argument via an SPA
     packet to be executed by *fwknopd* does not require this argument.
 
+*-D, --destination*='<IP-address>'::
+    Direct the *fwknop* client to authenticate with the *fwknopd*
+    daemon/service at the specified destination hostname or IP address. The
+    connection mode is discovered by the *fwknopd* daemon/service when it
+    decrypts and parses the authentication packet.
+
 *-R|-a|-s*::
     One of these options (see below) is required to tell the remote
-    *fwknopd* daemon what IP should be let through the local firewall.  It
+    *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.
@@ -133,14 +134,6 @@ GENERAL OPTIONS
 *-h, --help*::
     Print a usage summary message and exit.
 
-*-B, --save-packet*='<file>'::
-    Instruct the *fwknop* client to write a newly created SPA packet out
-    to the specified file so that it can be examined off-line.
-
-*-b, --save-packet-append*::
-    Append the generated packet data to the file specified with the -B
-    option.
-
 *-G, --get-key*='<file>'::
     Load an encryption key/password from the specified file.  The key file
     contains a line for each destination hostname or IP address, a colon
@@ -166,29 +159,11 @@ GENERAL OPTIONS
     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
-    such as 'ps' under Unix, this form should only be used where security is
-    not critical.  Having the *fwknop* client prompt you for the key is
-    generally more secure.
-
-*--key-base64-rijndael*='<key>'::
-    Specify the base64 encoded Rijndael key. Since the key may be visible
-    to utilities such as 'ps' under Unix, this form should only be used where
-    security is not critical.  Having the *fwknop* client prompt you for the
-    key is generally more secure.
-
-*--key-base64-hmac*='<key>'::
-    Specify the base64 encoded HMAC key. Since the key may be visible
-    to utilities such as 'ps' under Unix, this form should only be used where
-    security is not critical.  Having the *fwknop* client prompt you for the
-    key is generally more secure.
-
-*--key-hmac*='<key>'::
-    Specify the raw HMAC key (not base64 encoded). Since the key may be visible
-    to utilities such as 'ps' under Unix, this form should only be used where
-    security is not critical.  Having the *fwknop* client prompt you for the
-    key is generally more secure.
+*--key-gen*::
+    Have *fwknop* generate both Rijndael and HMAC keys that can be used for SPA
+    packet encryption.  These keys are derived from /dev/random and then base64
+    encoded before being printed to stdout, and are meant to be included within
+    the ``$HOME/.fwknoprc'' file (or the file referenced by *--get-key*).
 
 *-l, --last-cmd*::
     Execute *fwknop* with the command-line arguments from the previous
@@ -203,6 +178,34 @@ GENERAL OPTIONS
     FWKNOPRC FILE below for a list of the valid configuration directives in
     the '.fwknoprc' file.
 
+*--key-rijndael*='<key>'::
+    Specify the Rijndael key on the command line. Since the key may be visible
+    to utilities such as 'ps' under Unix, this form should only be used where
+    security is not critical.  Having the *fwknop* client either prompt you for
+    the key or acquire via the ``$HOME/.fwknoprc'' file is generally more
+    secure.
+
+*--key-base64-rijndael*='<key>'::
+    Specify the base64 encoded Rijndael key. Since the key may be visible
+    to utilities such as 'ps' under Unix, this form should only be used where
+    security is not critical.  Having the *fwknop* client either prompt you for
+    the key or acquire via the ``$HOME/.fwknoprc'' file is generally more
+    secure.
+
+*--key-base64-hmac*='<key>'::
+    Specify the base64 encoded HMAC key. Since the key may be visible
+    to utilities such as 'ps' under Unix, this form should only be used where
+    security is not critical.  Having the *fwknop* client either prompt you for
+    the key or acquire via the ``$HOME/.fwknoprc'' file is generally more
+    secure.
+
+*--key-hmac*='<key>'::
+    Specify the raw HMAC key (not base64 encoded). Since the key may be visible
+    to utilities such as 'ps' under Unix, this form should only be used where
+    security is not critical.  Having the *fwknop* client either prompt you for
+    the key or acquire via the ``$HOME/.fwknoprc'' file is generally more
+    secure.
+
 *--rc-file*='<file>'::
     Specify path to the fwknop rc file (default is $HOME/.fwknoprc).
 
@@ -231,6 +234,14 @@ GENERAL OPTIONS
     the decryption and decoding process and print the break-down again.
     This is primarily a debugging feature.
 
+*-B, --save-packet*='<file>'::
+    Instruct the *fwknop* client to write a newly created SPA packet out
+    to the specified file so that it can be examined off-line.
+
+*-b, --save-packet-append*::
+    Append the generated packet data to the file specified with the -B
+    option.
+
 *-v, --verbose*::
     Run the *fwknop* client in verbose mode.  This causes *fwknop* to print
     some extra information about the current command and the resulting SPA
@@ -242,6 +253,11 @@ GENERAL OPTIONS
 
 SPA OPTIONS
 -----------
+*--use-hmac*::
+    Set HMAC mode for authenticated encryption of SPA communications.  As of
+    *fwknop* 2.5, this is an optional feature, but this will become the
+    default in a future release.
+
 *-a, --allow-ip*='<IP-address>'::
     Specify IP address that should be permitted through the destination
     *fwknopd* server firewall (this IP is encrypted within the SPA packet
@@ -258,50 +274,16 @@ SPA OPTIONS
     system is connected to by querying a website that returns the actual
     IP address it sees from the calling system.
 
-*-C, --server-cmd*='<command to execute>'::
-    Instead of requesting access to a service with an SPA packet, the
-    *--server-cmd* argument specifies a command that will be executed by
-    the *fwknopd* server.  The command is encrypted within the SPA packet
-    and sniffed off the wire (as usual) by the *fwknopd* server.
-
 *-g, --gpg-encryption*::
     Use GPG encryption on the SPA packet (default if not specified is
     Rijndael). *Note:* Use of this option will require the specification of
     a GPG recipient (see *--gpg-recipient* along with other GPG-related
     options below).
 
-*-H, --http-proxy*='<proxy-host>[:port]'::
-    Specify an HTTP proxy that the *fwknop* client will use to send the SPA
-    packet through.  Using this option will automatically set the SPA packet
-    transmission mode (usually set via the *--server-proto* argument) to
-    "http".  You can also specify the proxy port by adding ":<port>" to
-    the proxy host name or ip.
-
-*-m, --digest-type*='<digest>'::
-    Specify the message digest algorithm to use in the SPA data.  Choices
-    are: *MD5*, *SHA1*, *SHA256* (the default), *SHA384*, and *SHA512*.
-
-*-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 '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 (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 for authenticated encryption of SPA packets.
     Choices are: *MD5*, *SHA1*, *SHA256* (the default), *SHA384*, and *SHA512*.
 
-*--use-hmac*::
-    Set HMAC mode for authenticated encryption of SPA communications.  As of
-    *fwknop* 2.5, this is an optional feature, but this will become the
-    default in a future release.
-
 *-N, --nat-access*='<internalIP:forwardPort>'::
     The *fwknopd* server offers the ability to provide SPA access through
     an iptables firewall to an internal service by interfacing with the
@@ -398,6 +380,35 @@ SPA OPTIONS
 *-S, --source-port*='<port>'::
     Set the source port for outgoing SPA packet.
 
+*-C, --server-cmd*='<command to execute>'::
+    Instead of requesting access to a service with an SPA packet, the
+    *--server-cmd* argument specifies a command that will be executed by
+    the *fwknopd* server.  The command is encrypted within the SPA packet
+    and sniffed off the wire (as usual) by the *fwknopd* server.
+
+*-H, --http-proxy*='<proxy-host>[:port]'::
+    Specify an HTTP proxy that the *fwknop* client will use to send the SPA
+    packet through.  Using this option will automatically set the SPA packet
+    transmission mode (usually set via the *--server-proto* argument) to
+    "http".  You can also specify the proxy port by adding ":<port>" to
+    the proxy host name or ip.
+
+*-m, --digest-type*='<digest>'::
+    Specify the message digest algorithm to use in the SPA data.  Choices
+    are: *MD5*, *SHA1*, *SHA256* (the default), *SHA384*, and *SHA512*.
+
+*-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 '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 (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.
+
 *--time-offset-plus*='<time>'::
     By default, the *fwknopd* daemon on the server side enforces time
     synchronization between the clocks running on client and server
@@ -743,9 +754,9 @@ translated into the '192.168.10.2' system automatically:
 
 DEPENDENCIES
 ------------
-*fwknop* requires 'libfko' (which is normally included with both source and
-binary distributions).  Whenever the *fwknopd* server is used, libpcap is a
-required dependency.
+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.
 
 For GPG functionality, GnuPG must also be correctly installed and configured
 along with the libgpgme library.
index 76b9905..873615e 100644 (file)
@@ -19,12 +19,15 @@ DESCRIPTION
 *fwknopd* is the server component for the FireWall Knock Operator, and
 is responsible for monitoring and processing Single Packet Authorization
 (SPA) packets that are generated by *fwknop* clients, modifying a firewall
-or ACL policy to allow the desired access after decrypting a valid SPA packet,
-and removing access after a configurable timeout.
+or ACL policy to allow the desired access after authenticating and
+decrypting a valid SPA packet (in that order), and removing access after a
+configurable timeout.
 
 The main application of this program is 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.
+vulnerabilities (both 0-day and unpatched code) much more difficult.  In
+addition, services that are protected in this fashion naturally cannot be
+scanned for with 'Nmap'.
 
 The main configuration for *fwknopd* is maintained within two files:
 'fwknopd.conf' and 'access.conf'.  The default location for these files
@@ -461,9 +464,19 @@ Defines all knock sequences and access control directives.
 
 DEPENDENCIES
 ------------
-The *fwknopd* daemon requires a functioning firewall on the underlying
-operating system.  Supported firewalls as of the fwknop-2.0 release are
-iptables, ipfw, and pf.
+*fwknopd* requires 'libfko' which is normally included with both source and
+binary distributions, and is a dedicated library developed by the fwknop
+project.
+
+For packet sniffing, *fwknopd* currently requires libpcap, but future versions
+still remove this as a dependency.
+
+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, ipfw, or pf
+firewall is required on the underlying operating system.
 
 
 DIAGNOSTICS
@@ -473,28 +486,52 @@ the *-v, --verbose* command line options.  This will disable daemon mode
 execution, and print verbose information to the screen on stderr as packets
 are received.
 
+The most comprehensive way to gain diagnostic information on *fwknopd* 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
+tests, has 'valgrind' support, validates both SPA encryption and HMAC results
+against OpenSSL, and even has its own built in fuzzer for SPA communications.
+
 
 SEE ALSO
 --------
-fwknop(8), iptables(8), libfko documentation.
+fwknopd(8), iptables(8), pf(4), pfctl(8), ipfw(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'.  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.
 
+*fwknop* uses the 'git' versioning system as its source code repository
+along with 'Github' for tracking of issues and milestones:
 
-AUTHOR
-------
+..........................
+    $ git clone https://github.com/mrash/fwknop.git fwknop.git
+..........................
+
+
+AUTHORS
+-------
 Damien Stuart <dstuart@dstuart.org>,
 Michael Rash <mbr@cipherdyne.org>
 
 
-CREDITS
--------
-This ``C'' version of *fwknopd* was derived from the original Perl-based
-version on which many people who are active in the open source community
-have contributed.  See the 'CREDITS' file in the fwknop sources, or visit
+CONTRIBUTORS
+------------
+This ``C'' version of fwknop was derived from the original Perl-based version
+on which many people who are active in the open source community have
+contributed.  See the CREDITS file in the fwknop sources, or visit
 'http://www.cipherdyne.org/fwknop/docs/contributors.html' to view the online
-list of contributors.
+list of contributors.  A few contributors deserve to be singled out including:
+Franck Joncourt, Max Kastanas, Vlad Glagolev, Sean Greven, Hank Leininger,
+Fernando Arnaboldi, and Erik Gomez.
 
 The phrase ``Single Packet Authorization'' was coined by MadHat and Simple
-Nomad at the BlackHat Briefings of 2005 (see: 'http://www.nmrc.org').
+Nomad at the BlackHat Briefings of 2005.
 
 
 BUGS