diff --git a/doc/fwknop.man.asciidoc b/doc/fwknop.man.asciidoc index 7090d204..d708fc53 100644 --- a/doc/fwknop.man.asciidoc +++ b/doc/fwknop.man.asciidoc @@ -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*='':: + Specify the number of bytes for a generated Rijndael key. The maximum size + is currently 128 bytes. + +*--hmac-key-len*='':: + 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*='':: 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*='':: 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*='':: Set the source port for outgoing SPA packet. +*-f, --fw-timeout*='':: + 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*='':: Instead of requesting access to a service with an SPA packet, the *--server-cmd* argument specifies a command that will be executed by