151 lines
7.7 KiB
Plaintext
151 lines
7.7 KiB
Plaintext
This is the top-level directory for the fwknop project.
|
|
|
|
INTRODUCTION
|
|
============
|
|
fwknop implements an authorization scheme known as Single Packet Authorization
|
|
(SPA) for strong service concealment. SPA requires only a single packet which
|
|
is encrypted, non-replayable, and authenticated via an HMAC in order to
|
|
communicate desired access to a service that is hidden behind a firewall in a
|
|
default-drop filtering stance. The main application of SPA is to use a firewall
|
|
to drop all attempts to connect to services such as SSH in order to make the
|
|
exploitation of vulnerabilities (both 0-day and unpatched code) more difficult.
|
|
Because there are no open ports, any service that is concealed by SPA naturally
|
|
cannot be scanned for with Nmap. The fwknop project supports three different
|
|
firewalls: iptables on Linux systems, pf on OpenBSD, and ipfw on FreeBSD and
|
|
Mac OS X.
|
|
|
|
SPA is essentially next generation Port Knocking (PK), but solves many of the
|
|
limitations exhibited by PK while retaining its core benefits. PK limitations
|
|
include a general difficulty in protecting against replay attacks, asymmetric
|
|
ciphers and HMAC schemes are not usually possible to reliably support, and it
|
|
is trivially easy to mount a DoS attack against a PK server just by spoofing an
|
|
additional packet into a PK sequence as it traverses the network (thereby
|
|
convincing the PK server that the client doesn't know the proper sequence). All
|
|
of these limitation are solved by SPA. At the same time, SPA hides services
|
|
behind a default-drop firewall policy, acquires SPA data passively (usually via
|
|
libpcap or other means), and implements standard cryptographic operations for
|
|
SPA packet authentication and encryption/decryption.
|
|
|
|
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 (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 cryptanalytic CBC-mode padding oracle attacks such as the Vaudenay
|
|
attack and related trickery (like 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. GnuPG and libgpgme are relatively
|
|
complex bodies of code, and therefore limiting the ability of a potential
|
|
attacker to interact with this code through an HMAC operation helps to maintain
|
|
a stronger security stance. Generating an HMAC for SPA communications requires
|
|
a dedicated key in addition to the normal encryption key, and both can be
|
|
generated with the --key-gen option.
|
|
|
|
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 /etc/fwknop/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.
|
|
|
|
A comprehensive tutorial on fwknop can be found here:
|
|
|
|
http://www.cipherdyne.org/fwknop/docs/fwknop-tutorial.html
|
|
|
|
|
|
LICENSE
|
|
=======
|
|
The fwknop project is released as open source software under the terms of the
|
|
GNU General Public License (GPL v2). The latest release can be found at
|
|
http://www.cipherdyne.org/fwknop/
|
|
|
|
|
|
CURRENT STATE
|
|
=============
|
|
This README file describes the present state of the fwknop project as of the
|
|
2.5 release made in July, 2013. At present, we have an implementation of the
|
|
Firewall Knock Operator library; `libfko', as well as the fwknop client and
|
|
server applications. The library provides the API and back-end functionality
|
|
for managing the Single Packet Authorization (SPA) data that the other fwknop
|
|
components employ. It also can be used by other programs that need SPA
|
|
functionality (see the `perl' directory for the FKO perl module as an example,
|
|
and there are python bindings as well in the 'python' directory).
|
|
|
|
|
|
UPGRADING
|
|
=========
|
|
If you are upgrading from an older version of fwknop (and this includes the
|
|
original perl implementation as well), then you will want to read the
|
|
following link to ensure a smooth transition to fwknop-2.5:
|
|
|
|
http://www.cipherdyne.org/fwknop/docs/fwknop-tutorial.html#backwards-compatibility
|
|
|
|
|
|
BUILDING fwknop
|
|
===============
|
|
This distribution uses GNU autoconf for setting up the build. Please see
|
|
the `INSTALL' file for the general basics on using autoconf.
|
|
|
|
There are some "configure" options that are specific to fwknop. They are
|
|
(extracted from ./configure --help):
|
|
|
|
--disable-client Do not build the fwknop client component. The
|
|
default is to build the client.
|
|
--disable-server Do not build the fwknop server component. The
|
|
default is to build the server.
|
|
--with-gpgme support for gpg encryption using libgpgme
|
|
[default=check]
|
|
--with-gpgme-prefix=PFX prefix where GPGME is installed (optional)
|
|
--with-gpg=/path/to/gpg Specify path to the gpg executable that gpgme will
|
|
use [default=check path]
|
|
--with-iptables=/path/to/iptables
|
|
Specify path to the iptables executable
|
|
[default=check path]
|
|
--with-ipfw=/path/to/ipfw
|
|
Specify path to the ipfw executable [default=check
|
|
path]
|
|
--with-pf=/path/to/pfctl
|
|
Specify path to the pf executable [default=check
|
|
path]
|
|
--with-ipf=/path/to/ipf Specify path to the ipf executable [default=check
|
|
path]
|
|
|
|
|
|
NOTE to those who may be migrating from the Perl version of fwknop
|
|
==================================================================
|
|
For those of you who are currently using the Perl version and plan to
|
|
migrate to this version, there are some things to be aware of:
|
|
|
|
- Not all of the features and functionality of the Perl-based
|
|
fwknop were ported to this implementation. We felt it important
|
|
to keep the C version as lean and lightweight as possible. Most
|
|
of the omitted feature/functions (like email alerts) can be
|
|
accomplished through other means (i.e. use an external script
|
|
to monitor log files and alert based on appropriate log messages).
|
|
|
|
- There are some differences in the fwknop configuration and access
|
|
file directives and values. Some of these are fairly subtle. You
|
|
should pay careful attention to the documentation and comments in
|
|
those files.
|
|
|
|
|
|
NOTE FOR DEVELOPERS
|
|
===================
|
|
If you are pulling this distribution from git, you should run the
|
|
"autogen.sh" script to generate the autoconf files. If you get errors about
|
|
missing directories or files, try running "autogen.sh" again. After that
|
|
you can run the "autoreconf -i" when you want to regenerate the configuration.
|
|
If, for some reason, autoreconf does not work for you, the "autogen.sh"
|
|
script should suffice.
|
|
|
|
The fwknop and fwknopd man page nroff sources are included in their
|
|
respective directories (client and server). These nroff files are derived
|
|
from the asciidoc sources in the 'docs' directory. See the README in docs
|
|
for details.
|