FWKNOP(8)

NAME
fwknop - Firewall Knock Operator

SYNOPSIS
fwknop -A <ports> -k <host> [options]

DESCRIPTION
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 an iptables policy and/or specific commands to execute on the target system. 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. The authorization server passively monitors authorization packets via libpcap and hence there is no "server" to which to connect in the traditional sense. Any service protected by fwknop is inaccessible (by using iptables 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 iptables ulogd pcap writer (or a separate sniffer process that is writing to a file).

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:

    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

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.

A note about the interaction between fwknop and iptables; fwknop maintains a strict separation between dynamically generated rules and any existing iptables 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 /etc/fwknop/fwknop.conf.

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 iptables firewall in the Linux kernel. 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.

The server component of fwknop is the 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 /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 /etc/fwknop/access.conf. When run in client mode, fwknop generates either an encrypted knock sequence (see the EXAMPLES section below), or a shared knock sequence. Shared knock sequences are defined in the file ~/.fwknoprc (this file is not used for encrypted sequences). See the 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: http://www.cipherdyne.org/fwknop/docs/SPA.html

OPTIONS

-A, --Access <port list>
    Provide a list of ports and protocols to access via a remote fwknop server. The format of this list is "<proto>/<port>...<proto>/<port>", e.g. "tcp/22,udp/53".

-k, --knock-dst <IP>
    (Legacy port knocking mode). Run 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 --encrypt is passed on the command line) or read out of the file ~/.fwknoprc.

-R, --Resolve-external-IP
    This is an important option, and instructs fwknop to query http://www.whatismyip.com to determing the IP address that should be allowed through the iptables policy at the remote fwknop server side. This is useful if fwknop is being used on a system that is behind an unknown NAT address.

-l, --last-cmd
    Instruct fwknop to run with the same command line arguments that were used in a previous execution. This option is useful because the fwknop command line can be complex and difficult to recall.

-L, --Last-host <host>
    Instruct fwknop to use the same command line arguments that were used to authenticate to host.

--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 is prompted for the associated GPG password which is required to create the signature. This adds a cryptographically strong mechanism to allow the fwknopd server to establish exactly who created the SPA message.

--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 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.

--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 fwknop client.

--gpg-default-key
    Use the key that GnuPG defines as the default, i.e. the key that is specified by the default-key variable in ~/.gnupg/options. If the default-key variable is not defined within ~/.gnupg/options, then GnuPG tries to use the first suitable key on its key ring. If the user does not know the password for this key, then the standard password error will be thrown by GnuPG and reported back to the user.

--gpg-agent
    Instruct fwknop to acquire GnuPG key password from a running gpg-agent instance.

--gpg-agent-info <connection info>
    Specify the value of the GPG_AGENT_INFO environment variable as returned by the gpg-agent --daemon command. If the fwknop --gpg-agent command line argument is used instead of --gpg-agent-info, then fwknop assumes that the GPG_AGENT_INFO environment variable has already been set in the current shell.

--gpg-verbose
    Instruct fwknop to allow all output from the 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.

--Server-port <port>
    Specify the port number where fwknop accepts packets via libpcap or ulogd pcap writer. By default fwknop looks for authorization packets over UDP port 62201.

--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 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).

-q, --quiet
    This option instructs the fwknop to be as quiet as possible and only print absolutely necessary information to the terminal.

--Spoof-cmd <cmd>
    Specify the path to the command knopspoof which is used by fwknop in --Spoof-src mode. This command is install by default at /usr/sbin/knopspoof.

-a, --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 fwknop is being run in --encrypt encrypted knock mode.

-s, --source-ip
    Instruct fwknop to form an SPA packet that contains the special-case IP address "0.0.0.0" which will inform the destination SPA server to use the source IP address from which the SPA packet 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.

--Spoof-src <IP>
    Spoof the source address from which fwknop sends SPA 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.

--Spoof-cmd <cmd>
    Specify the path to the command knopspoof which is used by fwknop in --Spoof-src mode. This command is install by default at /usr/sbin/knopspoof.

--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 fwknop server (--Spoof-src mode requires that fwknop is executed as root).

--Spoof-file <file>
    Specify the path to the cache file that 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.

-T, --TCP-sock
    Have fwknop send an SPA packet over an established TCP connection. This is not normally done, but is useful for compatibility with the Tor for strong anonymity; see http://tor.eff.org/.

-u, --user-rc <rc-file>
    (Legacy port knocking mode). The default connection rc file fwknop uses to know what shared port knocking sequence to send to a destination machine is defined in the file ~/.fwknoprc. The path to this file can be changed with the --user-rc command line option.

--offset <port>
    (Legacy port knocking mode). Specify a port offset to use when running fwknop in encrypted knock mode. The default is 61000.

-r, --rotate-proto
    (Legacy port knocking mode). Rotate the protocol across tcp and udp for encrypted sequences. This just adds one more additional layer of obfuscation to an encrypted sequence.

-t, --time-delay <seconds>
    (Legacy port knocking mode). Specify a time delay to introduce between successive connection attempts. This option is only used when 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).

--Server-mode <mode>
    (Legacy port knocking 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 fwknop defaults to the Single Packet Authorization method which provides much better security characteristics than port knocking (encrypted or not).

-v, --verbose
    Run fwknop in verbose mode.

-h, --help
    Display usage information and exit.

-V, --Version
    Display version information and exit.

FILES
~/.fwknop.run
    Contains the last command line arguments that fwknop was invoked with.
~/.fwknop.hosts
    Contains the last command line arguments for individual hosts that fwknop has been used to gain access to. By using the --Last-host switch, these arguments can be recalled and used.

EXAMPLES
The following examples illustrate the command line arguments that could be supplied to fwknop in a few situations:

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:

$ fwknop -A 'tcp/22,udp/53' -a 192.168.10.4 -k 10.0.0.123

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):

$ fwknop -A 'tcp/22,udp/53' -s -k 10.0.0.123

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 source IP is put within the encrypted packet instead of having the fwknopd daemon grant the requested access from whatever IP address the SPA packet originates:

$ fwknop -A 'tcp/22,udp/53' -w -k 10.0.0.123

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:

$ fwknop -A 'tcp/22,udp/53' --gpg-sign ABCD1234 --gpg--recipient 1234ABCD -w -k 10.0.0.123

Instruct the fwknop server running at 10.0.0.123 to send a single ICMP echo request to www.yahoo.com:

$ fwknop --Server-cmd 'ping -c 1 www.yahoo.com' -k 10.0.0.123

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:

# fwknop --Spoof-src 'www.yahoo.com' -A tcp/22 -a 172.16.5.4 -k 10.0.0.123

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:

$ fwknop --Server-mode 'knock' -A tcp/22 -a 192.168.10.4 -k 10.0.0.123

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):

$ fwknop --Server-mode 'knock' -A tcp/22 -s -k 10.0.0.123

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):

$ fwknop --Server-mode 'knock' -A tcp/22 -s -r -k 10.0.0.123

LEGACY: Same as above, but change the base port for the encrypted sequence to 55000 (the default is 61000):

$ fwknop --Server-mode 'knock' -A tcp/22 -s -r --offset 55000 -k 10.0.0.123

LEGACY: Send a shared knock sequence to the IP 10.11.11.123. The fwknop client will read the sequence out of the file ~/.fwknoprc and the server will read the sequence out of /etc/fwknop/access.conf:

$ fwknop --Server-mode 'knock' -k 10.11.11.123

DEPENDENCIES
fwknop requires perl. To take advantage of all of the features in fwknop when run in server mode a functioning iptables firewall is required on the underlying operating system. If fwknop is being run in the legacy port knocking mode, then iptables 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 p0f to passively fingerprint operating systems.

DIAGNOSTICS
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.

SEE ALSO
fwknopd(8), iptables(8), gpg(1), gpg-agent(1), knopmd(8), knopwatchd(8) p0f(1),

AUTHOR
Michael Rash <mbr@cipherdyne.org>

CREDITS
The phrase "Single Packet Authorization" was coined by MadHat, see: http://www.nmrc.org/ The term "port knocking" was coined by Martin Krzywinski, see: http://www.portknocking.org/
 The original p0f passive OS fingerprinter was written by Michal Zalewski, and is available here: http://lcamtuf.coredump.cx/p0f.shtml

BUGS
Send bug reports to mbr@cipherdyne.org. Suggestions and/or comments are always welcome as well.

DISTRIBUTION
fwknop is distributed under the GNU General Public License (GPL), and the latest version may be downloaded from http://www.cipherdyne.org/