From ebe1aec54250f5ae8fbacd84254f0b71a0d370c6 Mon Sep 17 00:00:00 2001 From: Michael Rash Date: Fri, 17 May 2013 23:05:58 -0400 Subject: [PATCH] continued man page updates in preparation for the 2.5 release --- doc/fwknop.man.asciidoc | 175 +++++++++++++++++++++------------------ doc/fwknopd.man.asciidoc | 69 +++++++++++---- 2 files changed, 146 insertions(+), 98 deletions(-) diff --git a/doc/fwknop.man.asciidoc b/doc/fwknop.man.asciidoc index dcc76b96..138e3d3d 100644 --- a/doc/fwknop.man.asciidoc +++ b/doc/fwknop.man.asciidoc @@ -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*='':: - 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*='':: 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*='':: + 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*='':: - 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*='':: 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*='':: - 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*='':: - 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*='':: - 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*='':: - 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*='':: + 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*='':: + 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*='':: + 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*='':: + 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*='':: 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*='':: + 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*='':: 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*='':: - 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*='[: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 ":" to - the proxy host name or ip. - -*-m, --digest-type*='':: - Specify the message digest algorithm to use in the SPA data. Choices - are: *MD5*, *SHA1*, *SHA256* (the default), *SHA384*, and *SHA512*. - -*-M, --encryption-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*='':: 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*='':: 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*='':: Set the source port for outgoing SPA packet. +*-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 + 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*='[: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 ":" to + the proxy host name or ip. + +*-m, --digest-type*='':: + Specify the message digest algorithm to use in the SPA data. Choices + are: *MD5*, *SHA1*, *SHA256* (the default), *SHA384*, and *SHA512*. + +*-M, --encryption-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*='