DeforaNetworks/fwknop
DeforaNetworks/fwknop
3
0
Fork 0
Code Releases Activity

minor documentation updates

Browse Source
This commit is contained in:
Michael Rash 2013-05-30 22:26:09 -04:00
parent 0504627c2e
commit 1e77535068
2 changed files with 37 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
doc/fwknop.man.asciidoc
View File

@ -16,32 +16,34 @@ SYNOPSIS
DESCRIPTION DESCRIPTION
----------- -----------
*fwknop* implements an authorization scheme known as Single Packet *fwknop* implements an authorization scheme known as Single Packet
Authorization (SPA) for passive service protection. SPA requires only a single Authorization (SPA) for strong service protection. SPA requires only a single
non-replayed encrypted packet together with an HMAC in order to communicate packet which is encrypted, non-replayable, and authenticated via an HMAC in order
various pieces of information including desired access to a service that is to communicate desired access to a service that is hidden behind a firewall in a
otherwise blocked by a firewall. The main application of SPA is to use a default-drop filtering stance. The main application of SPA is to use a
firewall in a default-drop stance to protect services such as 'SSH' with an firewall to drop all attempts to connect to services such as 'SSH' in order
additional layer of security in order to make the exploitation of to make the exploitation of vulnerabilities (both 0-day and unpatched code)
vulnerabilities (both 0-day and unpatched code) more difficult. In more difficult. Any service that is protected by SPA naturally cannot be
addition, services that are protected in this fashion naturally cannot be scanned for with 'Nmap'. The fwknop project supports three different
scanned for with 'Nmap'. 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 SPA is essentially next generation Port Knocking (PK), but solves many of the
limitations exhibited by PK while retaining its core benefits. PK limitations limitations exhibited by PK while retaining its core benefits. PK limitations
include a general difficulty in protecting against replay attacks, asymmetric include a general difficulty in protecting against replay attacks, asymmetric
ciphers and HMAC schemes are not usually supported, and it is trivially easy ciphers and HMAC schemes are not usually possible to reliably support, and it
to mount a DoS attack against a PK server just by spoofing an additional is trivially easy to mount a DoS attack against a PK server just by spoofing an
packet into a PK sequence as it traverses the network (thereby convincing the 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 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 limitation are solved by SPA. At the same time, SPA hides services behind a
default-drop firewall policy, acquires SPA data passively (usually via default-drop firewall policy, acquires SPA data passively (usually via
libpcap or other means), and implements lightweight cryptographic operations libpcap or other means), and implements standard cryptographic operations
for SPA packet authentication and encryption/decryption. for SPA packet authentication and encryption/decryption.
This is the manual page for the *fwknop* client which is responsible for This is the manual page for the *fwknop* client which is responsible for
constructing SPA packets and sending them over the network. The server side is constructing SPA packets and sending them over the network. The server side is
implemented by the *fwknopd* daemon which sniffs the network for SPA packets, implemented by the *fwknopd* daemon which sniffs the network for SPA packets
and it is recommended to read the 'fwknopd(8)' manual page as well. and interacts with the local firewall to allow SPA authenticated connections.
It is recommended to read the 'fwknopd(8)' manual page as well.
SPA packets generated by *fwknop* leverage HMAC for authenticated encryption SPA packets generated by *fwknop* leverage HMAC for authenticated encryption
in the encrypt-then-authenticate model. Although the usage of an HMAC is in the encrypt-then-authenticate model. Although the usage of an HMAC is
@ -56,7 +58,10 @@ 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 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 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 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 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 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. encryption key, and both can be generated with the *--key-gen* option.
@ -104,7 +109,8 @@ distributions (all major distros and embedded ones such as OpenWRT as well),
FreeBSD, OpenBSD, and Cygwin on Windows. There is also a library *libfko* FreeBSD, OpenBSD, and Cygwin on Windows. There is also a library *libfko*
that both *fwknop* and *fwknopd* use for SPA packet encryption/decryption that both *fwknop* and *fwknopd* use for SPA packet encryption/decryption
and HMAC authentication operations. This library can be used to allow and HMAC authentication operations. This library can be used to allow
third party applications to use SPA. third party applications to use SPA subject to the terms of the GNU
Public License (GPL).
REQUIRED ARGUMENTS REQUIRED ARGUMENTS

21
doc/libfko.texi
View File

@ -135,12 +135,17 @@ abstract the details of encoding, encryption, decoding, parsing, and verifying
@acronym{SPA} messages such as those used by Michael Rash's @dfn{Firewall @acronym{SPA} messages such as those used by Michael Rash's @dfn{Firewall
Knock Operator} (fwknop). Knock Operator} (fwknop).
@dfn{fwknop} implements @acronym{SPA}; an authorization scheme that requires @dfn{fwknop} implements an authorization scheme known as Single Packet
only a single encrypted packet to communicate various pieces of information Authorization (@acronym{SPA}) for strong service protection. SPA requires only a single
including desired access through an iptables policy and/or specific commands packet which is encrypted, non-replayable, and authenticated via an HMAC in order
to execute on the target system. The main application for a program of this to communicate desired access to a service that is hidden behind a firewall in a
type is to protect services such as SSH with an additional layer of security default-drop filtering stance. The main application of SPA is to use a
in order to make the exploitation of vulnerabilities much more difficult. 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. Any service that is protected 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.
libfko is not an implementation of an fwknop client or server. It simply libfko is not an implementation of an fwknop client or server. It simply
provides the functions for managing the @acronym{SPA} data used by those provides the functions for managing the @acronym{SPA} data used by those
@ -174,8 +179,8 @@ interface of the library.
@section Features @section Features
The primary advantage of using libfko is it provides a single API for either The primary advantage of using libfko is it provides a single API for either
creating, or parsing of existing @acronym{SPA} data that is fully compatible creating, or parsing of existing @acronym{SPA} data. Additional advantages
with the existing Perl-based fwknop implemetation. Other advantages include: include:
@table @asis @table @asis
@item It's free software @item It's free software