continued man page updates in preparation for the 2.5 release
This commit is contained in:
Michael Rash
+93
-82
@@ -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.
|
||||
|
||||
+53
-16
@@ -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:
|
||||
|
||||
..........................
|
||||
$ git clone https://github.com/mrash/fwknop.git fwknop.git
|
||||
..........................
|
||||
|
||||
|
||||
AUTHOR
|
||||
------
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user