root/fwknop/tags/fwknop-0.9.7-pre3/fwknop.8

.\" Process this file with
.\" groff -man -Tascii foo.1
.\"
.TH FWKNOP 8 "May, 2005" Linux
.SH NAME
.B fwknop
\- Firewall Knock Operator
.SH SYNOPSIS
.B fwknop [-u
.I user-rc file
.B ] [-k
.I knock-dst
.B ] [-a
.I allow-IP
.B ] [--gpg-signing-key
.I keyID
.B ] [--gpg-recipient
.I keyID
.B ] [--gpg-verbose] [--gpg-home-dir
.I GnuPG dir
.B ] [--Server-port
.I port
.B ] [--Server-mode
.I mode
.B ] [--Server-cmd
.I command
.B ] [--Spoof-src
.I IP
.B ] [--Spoof-cmd
.I command
.B ] [--Spoof-file
.I file
.B ] [--Spoof-user
.I user
.B ] [--no-save-args] [-d] [-e] [-s] [-r] [-w] [-K] [-R] [-A] [-t
.I time-delay
.B ] [-g
.I key-file
.B ] [--offset
.I port-offset
.B ] [-H
.I homedir
.B ] [--Status] [-l] [-v] [-V] [-h]
.SH DESCRIPTION

.B fwknop
implements an authorization scheme known as Single Packet Authorization (SPA)
that requires only a single encrypted
packet to communicate various pieces of information including desired access
through a Netfilter policy and/or specific commands to execute on the target
system.  The main application of this program is to protect services such as
.B SSH
with an additional layer of security in order to make the exploitation of
vulnerabilities (both 0-day and unpatched code) much more difficult.  The
authorization server passively monitors authorization packets via
.B libpcap
and hence there is no "server" to which to connect in the traditional sense.
Any service protected by fwknop
is inaccessible (by using Netfilter to intercept packets within the Linux
kernel) before authenticating; anyone scanning for the service will not be
able to detect that it is even listening.  This authorization scheme offers
many advantages over port knocking, include being non-replayable, much more
data can be communicated, and the scheme cannot be broken by simply
connecting to extraneous ports on the server in an effort to break
knock sequences.  The authorization packets can easily be spoofed as
well, and this makes it possible to make it appear as though, say, www.yahoo.com
is trying to authenticate to a target system but in reality the actual
connection will come from a seemingly unrelated IP. Although the default data
collection method in Single Packet Authorization mode is to use libpcap to sniff
packets off the wire, fwknop can also read packets out of a file that is written
by the Netfilter
. B ulogd
pcap writer (or a separate sniffer process that is writing to a file).
.PP
Authorization packets are either encrypted with the Rijndael block cipher
or via GnuPG and associated asymmetric ciphers.  If the symmetric encryption
method is chosen, then the encryption key is shared between between the
client and server (see the file /etc/fwknop/access.conf).  If the GnuPG
method is chosen, then the encryption keys are derived from GnuPG key
rings.  Authorization packets generated by fwknop running as a client adhere
to the following format before being encrypted:
.PP
    random number (16 bytes)
    username
    timestamp
    software version
    mode (command mode (0) or access mode (1))
    if command mode => command to execute
    else access mode  => IP,proto,port
    MD5 sum
.PP
Each of the above fields are separated by a ":" character due to the
variable length of several of the fields, and those that might contain
":" characters are base64 encoded.  The MD5 message sum allows the
server to check message integrity after decryption, and the 16 bytes
of random data ensures (with high probability) that no two messages are
identical.  For each packet coming from an fwknop client, the server
caches the MD5 sum calculated over the entire packet and compares against
previous MD5 sums in order to detect attempted replay attacks.  Both
syslog and email alerts are (optionally) generated if a replay is
attempted.  By default, fwknop sends authorization packets over UDP
port 62201, but this can be altered with the --Server-port argument.
The fwknop server is not limited to acquiring authorization packets
over any particular port or protocol, but the PCAP_FILTER and
ULOG_PCAP_FILTER keywords in /etc/fwknop/fwknop.conf limit the server
to inspecting traffic over the default UDP port 62201.  See the EXAMPLES
section for example invocations of fwknop in client mode, and see the
FWKNOP CONFIG section for an explanation of server configuration
keywords.
.PP
A note about the interaction between
.B fwknop
and Netfilter; fwknop maintains a strict separation between dynamically
generated rules and any existing Netfilter policy by adding all rules
to a custom chain "FWKNOP_INPUT".  Packets are jumped to this chain from
the INPUT chain.  Interaction with the FORWARD chain can be accomplished
by altering the IPT_AUTO_CHAIN{n} keywords in
.B /etc/fwknop/fwknop.conf.
.PP
In addition to the Single Packet Authorization method, fwknop maintains
the ability to generate encrypted port knocking sequences and combine
them with passive OS fingerprinting, but this mode is not enabled by
default.  This scheme is based around log
messages generated by the Netfilter firewall in the Linux kernel.
.B fwknop
supports both shared and encrypted port knock sequences, passive OS fingerprinting,
multi-protocol knock sequences (tcp, udp, and icmp), firewall access across
multiple ports and protocols, firewall access timeouts, relative timeouts between
knock packets, and more.
.PP
The server component of fwknop is the
.B fwknopd
daemon which normally sniffs the wire directly or monitors a pcap file for SPA
packets generated by fwknop clients.  If run in legacy port knocking mode, fwknopd
 watches iptables log messages as they are written via syslog to a named pipe
.B /var/lib/fwknop/fwknopfifo.
If a valid knock sequence is seen, then fwknop will modify the iptables ruleset to
grant the appropriate access to the originating IP address.  Knock sequence parameters
are defined in the file
.B /etc/fwknop/access.conf.
When run in client mode, fwknop generates either an encrypted knock sequence (see
the
.B EXAMPLES
section below), or a shared knock sequence.  Shared knock sequences are defined in
the file
.B ~/.fwknoprc
(this file is not used for encrypted sequences).

See the
.B fwknopd (8)
man page for more information.  Also, more information on the
differences between port knocking and Single Packet Authorization can be found
in the paper "Single Packet Authorization with fwknop" available here:
.B http://www.cipherdyne.org/fwknop/docs/SPA.html

.SH OPTIONS
.TP
.BR \-A "\fR,\fP " \-\^\-Access\ \<port\ list>
Provide a list of ports and protocols to access via a remote
.B fwknop
server. The format of this list is "<proto>/<port>...<proto>/<port>",
e.g. "tcp/22,udp/53".
.TP
.BR \-\^\-gpg-signing-key\ \<key ID>
Specify the GnuPG key ID, e.g. "ABCD1234" (see the output of "gpg --list-keys")
to use to sign a Single Packet Authorization message.  The user prompted for the
associated GPG password which is required for creating the signature.  This
.TP
.BR \-\^\-gpg-recipient\ \<key ID>
Specify the GnuPG key ID, e.g. "1234ABCD" (see the output of "gpg --list-keys")
of the recipient of the Single Packet Authorization message.  This key is imported
by the
.B fwknopd
server and the associated private key is used to decrypt the SPA packet.  The
recipient's key must be imported into the client GnuPG key ring.
.TP
.BR \-\^\-gpg-home-dir\ \<dir>
Specify the path to the GnuPG directory; normally this path is derived from the
home directory of the user that is running the
.B fwknop
client.
.TP
.BR \-\^\-gpg-verbose
Instruct
.B fwknop
to allow all output from the
.B gpg
process that is used by fwknop in GPG mode.  This is primarily used for debugging
purposes if it appears that the GPG encrypt/decrypt is not performing correctly.
.TP
.BR \-\^\-Server-port\ \<port>
Specify the port number where
.B fwknop
accepts packets via libpcap or ulogd pcap writer.  By default fwknop looks for
authorization packets over UDP port 62201.
.TP
.BR \-\^\-Server-cmd\ \<cmd>
The --Server-cmd argument allows a complete command (e.g. "ping -c 1 www.yahoo.com",
or "iptables -t nat -A PREROUTING -p tcp -s 65.x.x.x --dport 443 -i eth0 -j DNAT --to 192.168.10.20:443")
to be send to an
.B fwknop
server, which will execute the command as root.  Command execution is enabled only
if the ENABLE_CMD_EXEC keyword is given in /etc/fwknop/access.conf (note that
commands can easily be restricted with the CMD_REGEX keyword as well).
.TP
.BR \-u "\fR,\fP " \-\^\-user-rc\ \<rc-file>
The default connection rc file
.B fwknop
uses to know what shared port knocking sequence to send to a destination machine
is defined in the file
.B ~/.fwknoprc.
The path to this file can be changed with the
.B --user-rc
command line option.
.TP
.BR \-k "\fR,\fP " \-\^\-knock-dst\ \<IP>
Run
.B fwknop
in port knocking mode against the destination IP address.  The specific port
knock sequence that is sent to the destination will either be encrypted (if
.B --encrypt
is passed on the command line) or read out of the file
.B ~/.fwknoprc.
.TP
.BR \-a "\fR,\fP " \-\^\-allow-ip\ \<allow-IP>
Specify a third-party IP address (can be the local machine) to allow
through the destination knock server firewall.  This option is only used
when
.B fwknop
is being run in
.B --encrypt
encrypted knock mode.
.TP
.BR \-s "\fR,\fP " \-\^\-source-ip
Instruct
.B fwknop
to form an encrypted knock sequence that will contain the special-case IP
address "0.0.0.0" which will inform the destination knock server to use
the source IP address from which an encrypted knock sequence originates as
the IP that will be allowed through upon modification of the firewall ruleset.
This option is useful if the fwknop client is deployed on a machine that is
behind a NAT device.  This option is only used in
.B --encrypt
encrypted knock mode.
.TP
.BR \-\^\-Spoof-src\ \<IP>
Spoof the source address from which
.B fwknop
sends authorization packets.  This requires root access since a raw socket
is required to accomplish this.  Note that the --Spoof-user argument can be
given in this mode in order to pass any REQUIRE_USERNAME keyword that might
be specified in /etc/fwknop/access.conf.
.TP
.BR \-\^\-Spoof-cmd\ \<cmd>
Specify the path to the command
.B knopspoof
which is used by
.B fwknop
in --Spoof-src mode.  This command is install by default at /usr/sbin/knopspoof.
.TP
.BR \-\^\-Spoof-user\ \<user>
Specify the username that is included within authorization messages.  This allows
the client to satisfy any non-root REQUIRE_USERNAME keyword on the
.B fwknop
server (--Spoof-src mode requires that fwknop is executed as root).
.TP
.BR \-\^\-Spoof-file\ \<file>
Specify the path to the cache file that
.B knopspoof
reads in order to correctly generate the authorization packet.  This
file defaults to /tmp/spoof.cache, and contains source and destination
IP addresses, protocol and port numbers, and the encrypted authorization
message.
.TP
.BR \-\^\-offset\ \<port>
Specify a port offset to use when running
.B fwknop
in encrypted knock mode.  The default is 61000.
.TP
.BR \-r "\fR,\fP " \-\^\-rotate-proto
Rotate the protocol across tcp and udp for encrypted sequences.  This just
adds one more additional layer of obfuscation to an encrypted sequence.
.TP
.BR \-t "\fR,\fP " \-\^\-time-delay\ \<seconds>
Specify a time delay to introduce between successive connection attempts.
This option is only used when
.B fwknop
is run in client mode.  On the server side, the variables MIN_TIME_DIFF
and MAX_TIME_DIFF will control whether the time delay actually means
something (i.e. if the MIN_TIME_DIFF is 2 seconds for a SOURCE block,
then the argument to the --time-delay option must be at least 2 at the
client side).
.TP
.BR \-\^\-Server-mode\ \<mode>
This command line switch provides an interface to the old port knocking method if
the mode argument is "knock".  If the --Server-mode argument is not given then
.B fwknop
defaults to the Single Packet Authorization method which provides much better
security characteristics than port knocking (encrypted or not).
.TP
.BR \-g "\fR,\fP " \-\^\-get-key\ \<file>
Get encryption key from
.B <file>
instead of from STDIN.  This option can only be specified when running
.B fwknop
in encrypted knock mode against a system running a fwknop server.
.TP
.BR \-l "\fR,\fP " \-\^\-last-cmd
Run
.B fwknop
with the command line arguments given for the previous execution.  This
makes it easy to run the same fwknop command over and over without having
to remember complicated command line args.
.TP
.BR \-\^\-no-save-args
Instruct
.B fwknop
to not save the command line arguments it was invoked with.  This is useful to
test fwknop with new command line args that should not be saved to disk, and
this leaves existing saved arguments from a previous fwknop execution intact.
.TP
.BR \-H "\fR,\fP " \-\^\-Home-dir\ \<directory>
Manually specify the home directory associated with the current user (useful
if fwknop is unable to automatically determine the home directory).
.TP
.BR \-v "\fR,\fP " \-\^\-verbose
Run fwknop in verbose mode.
.TP
.BR \-h "\fR,\fP " \-\^\-help
Display usage information and exit.
.TP
.BR \-V "\fR,\fP " \-\^\-Version
Display version information and exit.
.SH EXAMPLES
The following examples illustrate the command line arguments that could
be supplied to fwknop in a few situations:
.PP
Use the Single Packet Authorization mode to gain access to tcp/22 (ssh)
and udp/53 running on the system 10.0.0.123 from the IP 192.168.10.4:
.PP
.B $ fwknop -A "tcp/22,udp/53" -a 192.168.10.4 -k 10.0.0.123
.PP
Same as above example, but gain access from whatever source IP is seen
by the fwknop server (useful if the fwknop client is behind a NAT device):
.PP
.B $ fwknop -A "tcp/22,udp/53" -s -k 10.0.0.123
.PP
Same as above example, but use the IP identification website http://www.whatismyip.com
to derive the client IP address.  This is a safer method of acquiring the client IP
address than using the "-s" option because the IP is put within the encrypted packet
(a man-in-the-middle attack becomes infeasible against this).
.PP
.B $ fwknop -A "tcp/22,udp/53" -w -k 10.0.0.123
.PP
Use the Single Packet Authorization mode to gain access to tcp/22 (ssh)
and udp/53 running on the system 10.0.0.123, and use GnuPG keys to encrypt
and decrypt:
.PP
.B $ fwknop -A "tcp/22,udp/53" --gpg-sign ABCD1234 --gpg--recipient 1234ABCD -w -k 10.0.0.123
.PP
Instruct the fwknop server running at 10.0.0.123 to send a single ICMP
echo request to www.yahoo.com:
.PP
.B $ fwknop --Server-cmd "ping -c 1 www.yahoo.com" -k 10.0.0.123
.PP
Instruct the fwknop server running at 10.0.0.123 to allow 172.16.5.4 to
connect to TCP/22, but spoof the authorization packet from an IP associated
with www.yahoo.com:
.PP
.B # fwknop --Spoof-src "www.yahoo.com" -A tcp/22 -a 172.16.5.4 -k 10.0.0.123
.PP
LEGACY: Send an encrypted knock sequence to the IP "10.0.0.123" instructing the
fwknop daemon running there to open tcp port 22 to source address
192.168.10.4:
.PP
.B $ fwknop --Server-mode "knock" -A tcp/22 -a 192.168.10.4 -k 10.0.0.123
.PP
LEGACY: Same as above, but this time instruct the remote fwknop daemon to open
tcp port 22 to whatever source address the encrypted sequence originates
from (useful if the fwknop client is behind a NAT device):
.PP
.B $ fwknop --Server-mode "knock" -A tcp/22 -s -k 10.0.0.123
.PP
LEGACY: Same as above, but rotate the knock sequence through the tcp and udp
protocols (remember that iptables must be configured to log both tcp and
udp packets to the default port range of 61000-61255):
.PP
.B $ fwknop --Server-mode "knock" -A tcp/22 -s -r -k 10.0.0.123
.PP
LEGACY: Same as above, but change the base port for the encrypted sequence to
55000 (the default is 61000):
.PP
.B $ fwknop --Server-mode "knock" -A tcp/22 -s -r --offset 55000 -k 10.0.0.123
.PP
LEGACY: Send a shared knock sequence to the IP 10.11.11.123.  The fwknop client
will read the sequence out of the file
.B ~/.fwknoprc
and the server will read the sequence out of
.B /etc/fwknop/access.conf:
.PP
.B $ fwknop --Server-mode "knock" -k 10.11.11.123
.SH DEPENDENCIES
.B fwknop
requires perl.  To take advantage of all of the features in fwknop when run
in server mode a functioning Netfilter firewall is required on the underlying
operating system.  If fwknop is being run in the legacy port knocking mode,
then Netfilter must log packets via syslog, and ideally the --log-tcp-options
argument will be specified in the iptables logging rule so that fwknop will
be able to use a strategy similar to
.B p0f
to passively fingerprint operating systems.
.SH DIAGNOSTICS
.B fwknop
can be run in debug mode with the --debug command line option.  This will
disable daemon mode execution, and print verbose information to the screen
on STDERR as packets are received.
.SH "SEE ALSO"
.BR fwknopd (8),
.BR iptables (8),
.BR p0f (1),
.BR knopmd (8),
.BR knopwatchd (8)
.SH AUTHOR
Michael Rash <mbr@cipherdyne.org>
.SH CREDITS
The phrase "Single Packet Authorization" was coined by MadHat, see:
.B http://www.nmrc.org/
The term "port knocking" was coined by Martin Krzywinski, see:
.B http://www.portknocking.org/
 The original p0f passive OS fingerprinter was written by Michal Zalewski, and is
available here:
.B http://lcamtuf.coredump.cx/p0f.shtml
.SH BUGS
Send bug reports to mbr@cipherdyne.org.  Suggestions and/or comments are
always welcome as well.
.SH DISTRIBUTION
.B fwknop
is distributed under the GNU General Public License (GPL), and the latest
version may be downloaded from
.B http://www.cipherdyne.org/