From 1e775350682b906d4c96e1a1a31f41dd5d578779 Mon Sep 17 00:00:00 2001 From: Michael Rash Date: Thu, 30 May 2013 22:26:09 -0400 Subject: [PATCH] minor documentation updates --- doc/fwknop.man.asciidoc | 40 +++++++++++++++++++++++----------------- doc/libfko.texi | 23 ++++++++++++++--------- 2 files changed, 37 insertions(+), 26 deletions(-) diff --git a/doc/fwknop.man.asciidoc b/doc/fwknop.man.asciidoc index 358e4795..1d9e9f14 100644 --- a/doc/fwknop.man.asciidoc +++ b/doc/fwknop.man.asciidoc @@ -16,32 +16,34 @@ SYNOPSIS DESCRIPTION ----------- *fwknop* implements an authorization scheme known as Single Packet -Authorization (SPA) for passive service protection. SPA requires only a single -non-replayed encrypted packet together with an HMAC in order to communicate -various pieces of information including desired access to a service that is -otherwise blocked by a firewall. The main application of SPA is to use a -firewall in a default-drop stance 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) more difficult. In -addition, services that are protected in this fashion naturally cannot be -scanned for with 'Nmap'. +Authorization (SPA) for strong service protection. 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. 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. 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 supported, 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 +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 lightweight cryptographic operations +libpcap or other means), and implements standard cryptographic operations for SPA packet authentication and encryption/decryption. 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 -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. +implemented by the *fwknopd* daemon which sniffs the network for SPA packets +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 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 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 +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. @@ -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* that both *fwknop* and *fwknopd* use for SPA packet encryption/decryption 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 diff --git a/doc/libfko.texi b/doc/libfko.texi index 8f2b8ccf..57b4a45d 100644 --- a/doc/libfko.texi +++ b/doc/libfko.texi @@ -135,16 +135,21 @@ abstract the details of encoding, encryption, decoding, parsing, and verifying @acronym{SPA} messages such as those used by Michael Rash's @dfn{Firewall Knock Operator} (fwknop). -@dfn{fwknop} implements @acronym{SPA}; an authorization scheme that requires -only a single encrypted packet to communicate various pieces of information -including desired access through an iptables policy and/or specific commands -to execute on the target system. The main application for a program of this -type is to protect services such as SSH with an additional layer of security -in order to make the exploitation of vulnerabilities much more difficult. +@dfn{fwknop} implements an authorization scheme known as Single Packet +Authorization (@acronym{SPA}) for strong service protection. 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. 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 provides the functions for managing the @acronym{SPA} data used by those -programs. +programs. @sp 1 @noindent @@ -174,8 +179,8 @@ interface of the library. @section Features 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 -with the existing Perl-based fwknop implemetation. Other advantages include: +creating, or parsing of existing @acronym{SPA} data. Additional advantages +include: @table @asis @item It's free software