[client] finished documenting client command line options via the man page
authorMichael Rash <mbr@cipherdyne.org>
Sun, 19 May 2013 19:50:16 +0000 (15:50 -0400)
committerMichael Rash <mbr@cipherdyne.org>
Sun, 19 May 2013 19:50:16 +0000 (15:50 -0400)
doc/fwknop.man.asciidoc

index 7090d20..d708fc5 100644 (file)
@@ -45,21 +45,26 @@ 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 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 even
-sent through the decryption routines.  Generating an HMAC for SPA
-communications requires a dedicated key in addition to the normal encryption
-key.
+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 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 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.  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
 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
+server (see the *fwknopd* '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
 packets generated by fwknop running as a client adhere to the following
 format (before encryption and the HMAC is applied):
@@ -94,7 +99,7 @@ Also, *fwknop* can send the SPA packet over a random port via the
 *EXAMPLES* section for example invocations of the *fwknop* client.
 
 The *fwknop* client is quite portable, and is known to run on various Linux
-distributions (all major distros and embedded ones as well such as OpenWRT),
+distributions (all major distros and embedded ones such as OpenWRT as well),
 FreeBSD, OpenBSD, and Cygwin on Windows.  There is also a library *libfko*
 that both *fwknop* and *fwknopd* use for SPA packet encryption/decryption
 and HMAC authentication operations.  This library can be used to allow
@@ -163,7 +168,17 @@ GENERAL OPTIONS
     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*).
+    the ``$HOME/.fwknoprc'' file (or the file referenced by *--get-key*).  Such
+    keys are generally more secure than passphrases that are typed in from the
+    command line.
+
+*--key-len*='<length>'::
+    Specify the number of bytes for a generated Rijndael key.  The maximum size
+    is currently 128 bytes.
+
+*--hmac-key-len*='<length>'::
+    Specify the number of bytes for a generated HMAC key.  The maximum size is
+    currently 128 bytes.
 
 *-l, --last-cmd*::
     Execute *fwknop* with the command-line arguments from the previous
@@ -211,10 +226,10 @@ GENERAL OPTIONS
 
 *--save-rc-stanza*='<stanza name>'::
     Save command line arguments to the $HOME/.fwknoprc stanza specified with
-    the -n option.
+    the *-n* option.
 
 *--force-stanza*::
-    Used with --save-rc-stanza to overwrite all of the variables for the
+    Used with *--save-rc-stanza* to overwrite all of the variables for the
     specified stanza
 
 *--show-last*::
@@ -222,7 +237,7 @@ GENERAL OPTIONS
 
 *-E, --save-args-file*='<file>'::
     Save command line arguments to a specified file path.  Without this
-    option, and when '--no-save-args' is not also specified, then the default
+    option, and when *--no-save-args* is not also specified, then the default
     save args path is '~/.fwknop.run'.
 
 *--no-save-args*::
@@ -239,7 +254,7 @@ GENERAL OPTIONS
     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
+    Append the generated packet data to the file specified with the *-B*
     option.
 
 *-v, --verbose*::
@@ -247,7 +262,7 @@ GENERAL OPTIONS
     some extra information about the current command and the resulting SPA
     data.
 
-*-V, --Version*::
+*-V, --version*::
     Display version information and exit.
 
 
@@ -308,6 +323,15 @@ SPA OPTIONS
     that any external attacker would only see a connection over port 55,000
     instead of the expected port 22 after the SPA packet is sent.
 
+*--nat-port*::
+    Usually *fwknop* is used to request access to a specific port such as
+    tcp/22 on a system running *fwknopd*.  However, by using the *--nat-port*
+    argument, it is possible to request access to a (again, such as tcp/22),
+    but have this access granted via the specified port (so, the *-p* argument
+    would then be used on the 'SSH' client command line).  See the
+    *--nat-local* and *--nat-access* command line arguments to *fwknop* for
+    additional details on gaining access to services via a NAT operation.
+
 *--nat-rand-port*::
     Usually *fwknop* is used to request access to a specific port such as
     tcp/22 on a system running *fwknopd*.  However, by using the
@@ -316,7 +340,7 @@ SPA OPTIONS
     granted  via a random translated port.  That is, once the *fwknop*
     client has been executed in this mode and the random port selected
     by *fwknop* is displayed, the destination port used by the follow-on
-    client must be changed to match this random port.  For SSH, this is
+    client must be changed to match this random port.  For 'SSH', this is
     accomplished via the *-p* argument.  See the *--nat-local* and
     *--nat-access* command line arguments to *fwknop* for additional
     details on gaining access to services via a NAT operation.
@@ -380,6 +404,13 @@ SPA OPTIONS
 *-S, --source-port*='<port>'::
     Set the source port for outgoing SPA packet.
 
+*-f, --fw-timeout*='<seconds>'::
+    Specify the length of time (seconds) that the remote firewall rule that
+    grants access to a service is to remain active.  The default maintained by
+    *fwknopd* is 30 seconds, but any established connection can be kept open
+    after the initial accept rule is deleted through the use of a connection
+    tracking mechanism that may be offered by the firewall.
+
 *-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