FWKNOP(8)

NAME
fwknop - Firewall Knock Operator

SYNOPSIS
fwknop [-c config-file ] [-u user-rc file ] [-k knock-dst ] [-a allow-ip ] [--Server-port port ] [--Server-mode mode ] [--Server-cmd command ] [--Spoof-src IP ] [--Spoof-cmd command ] [--Spoof-file file ] [--Spoof-user user ] [-d] [-e] [-s] [-r] [-K] [-R] [-A] [-p port ] [-P protocol ] [-t time-delay ] [-g key-file ] [--offset port-offset ] [--os] [-i iptables-log ] [-H homedir ] [--Status] [-l] [-v] [-V] [-h]

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 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 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 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 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 ulogd pcap writer. Authorization packets are encrypted with the Rijndael block cipher using a shared encryption key agreed upon by both the fwknop client and server (see the file /etc/fwknop/access.conf). 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 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 /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. For completeness this mode is described below: Fwknop implements a flexible port knocking scheme based around log messages generated by the Netfilter 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. There are two primary modes of execution; server mode, and client mode. When run in server mode, fwknop becomes a daemon and 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).

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".
--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).
-u, --user-rc <rc-file>
    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.
-k, --knock-dst <IP>
    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.
-e, --encrypt
    Instruct fwknop to form an encrypted knock sequence that the destination knock server will decrypt to determine which port, protocol, and IP address should be allowed through the local firewall. Options that should also be specified with --encrypt are --allow-ip or --source-ip, --port, and --Proto. The port knock sequence will be encrypted with the Rijndael AES block cipher. The encryption key is specified in /etc/fwknop/access.conf on the server side, and is read from STDIN on the client side (or read from a key file if --get-key is passed on the command line).
-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 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 --encrypt encrypted knock mode.
-p, --port <port>
    Port to open on the remote knock server. If --Proto is not also given, fwknop will default to a tcp port.
-P, --Proto <protocol>
    Protocol associated with the port to open on the remote knock server. Either tcp or udp may be specified, but fwknop will default to tcp if this command line argument is not given.
--Spoof-src <IP>
    Spoof the source address from which 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.
--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.
--offset <port>
    Specify a port offset to use when running fwknop in encrypted knock mode. The default is 61000.
-c, --config <config-file>
    When run in server mode fwknop references the file /etc/fwknop/fwknop.conf for various run-time configuration variables. The path to this file can be changed through the use of the --config command line option.
-r, --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.
-t, --time-delay <seconds>
    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>
    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).
--os
    Run fwknop in OS fingerprinting mode against an existing iptables logfile. This will generate a listing of IP addresses along with a guess at the associated operating system type. The default iptables logfile path is /var/log/fwknop/fwdata but this path can be altered through the use of the --iptables-log option below.
-i, --iptables-log <iptableslogfile>
    Specify path to an existing iptables logfile when running fwknop in --os mode.
-g, --get-key <file>
    Get encryption key from <file> instead of from STDIN. This option can only be specified when running fwknop in encrypted knock mode against a system running a fwknop server.
-l, --last-cmd
    Run 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.
-K, --Kill
    Kill the current fwknop process along with knopwatchd and knopmd. This provides a quick and easy way to stop all fwknop processes without having to look in the process table or appeal to the fwknop init script.
-R, --Restart
    Restart the currently running fwknop processes. This option will preserve the command line options that were supplied to the original fwknop process.
--Status
    Display the status of any fwknop processes that may or not be running.
-H, --Home-dir <directory>
    Manually specify the home directory associated with the current user (useful if fwknop is unable to automatically determine the home directory).
-v, --verbose
    Run fwknop in verbose mode.
-h, --help
    Display usage information and exit.
-V, --Version
    Display version information and exit.

FILES
/etc/fwknop/fwknop.conf
    The main configuration file for fwknop.
/etc/fwknop/access.conf
    Defines all knock sequences and access control directives.
/etc/fwknop/pf.os
    Defines p0f signatures used by fwknop.

FWKNOP CONFIG AND ACCESS VARIABLES
fwknop references the file /etc/fwknop/fwknop.conf for configuration variables such as the path to the firewall logfile, the sleep interval fwknop uses to check for new log messages, and paths to system binaries, etc. The fwknop config file does not define any access control directives; they are located in the file /etc/fwknop/access.conf. Access control directives define encryption keys and level of access that is granted to an fwknop client that has generated the appropriate encrypted message. This file is referenced for this information when run in either the single packet authorization mode, or the legacy port knocking mode.

SOURCE: <IP,..,IP/NET,..,NET/ANY>
    This defines the source address from which an authorization packet (or legacy knock sequence) will be accepted. The string "ANY" is also accepted if a valid authorization packet should be honored from any source IP. Every authorization stanza in /etc/fwknop/access.conf definition must start with the SOURCE keyword. Networks can be specified in either CIDR (e.g. "192.168.10.0/24") or regular (e.g. "192.168.10.0/255.255.255.0") notation, and individual IP addresses can be specified as well. Also, multiple IP's and/or networks can be defined as a comma separated list (e.g. "192.168.10.0/24, 10.1.1.123")

DATA_COLLECT_MODE: PCAP|FILE_PCAP|ULOG_PCAP|ENCRYPT_SEQUENCE
    If DATA_COLLECT_MODE is set to "PCAP", fwknop sniffs the wire directly via libpcap to capture authorization packets. If set to "FILE_PCAP", fwknop reads a pcap-formatted file (defined by the PCAP_PKT_FILE keyword in the fwknop.conf file) that is written to by a separate sniffer process. If set to "ULOG_PCAP", fwknop collects packets via the Netfilter ulogd pcap writer. This requires that packets are logged via the ULOG target in the Netfilter policy. If set to ENCRYPT_SEQUENCE, fwknop falls back to the legacy port knocking method of network authorization.

ENABLE_CMD_EXEC
    This instructs fwknop to accept complete commands that are contained within an authorization packet. Any such command will be executed as root by the fwknop server.

CMD_REGEX: <regex>
    If ENABLE_CMD_EXEC is specified, the CMD_REGEX keyword instructs fwknop to restrict command execution to only those command that match the given regular expression.

KEY: <8-16 chars>
    Define the encryption key for an ENCRYPT_SEQUENCE block. This variable is required for all encrypted sequences (each encrypted sequence may have its own unique key), and must be provided at execution to an fwknop client attempting to gain access. When run in client mode, fwknop will prompt the user for the encryption key, or a path to the key may be provided on the command line with --get-key <file>.

OPEN_PORTS: <proto/port>, ..., <proto/port>
    Define a set of ports and protocols (tcp or udp) that will be opened if a valid knock sequence is seen. This variable is required for shared knock sequences since the port information is not sent within the sequence, and optional for encrypted knock sequences which can include the port and protocol within the sequence.

FW_ACCESS_TIMEOUT: <seconds>
    Define the length of time access will be granted by fwknop through the firewall after a valid knock sequence from a source IP address. If FW_ACCESS_TIMEOUT is not set then the default timeout of 300 seconds (5 minutes) will automatically be set.

REQUIRE_OS: <operating system>
    Require a specific operating system fingerprint match (e.g. "Linux:2.4::Linux 2.4/2.6" or "OpenBSD:3.0-3.5::OpenBSD 3.0-3.5" before a knock sequence will be accepted. The fingerprints are listed in /etc/fwknop/pf.os. Note that the corresponding knock sequence must utilize the tcp protocol (this is only be an issue for shared sequences since encrypted sequences use tcp by default) since OS fingerprinting requires tcp syn packets. This variable is optional.

REQUIRE_OS_REGEX: <regex>
    Require an operating system fingerprint that matches <regex>, e.g. "linux" or "*bsd". Note that the regex will be matched case in- sensitively. This variable is optional.

REQUIRE_USERNAME: <username>
    Require a specific username from the client system. This username is sent across the network in an encrypted knock sequence to the fwknop server. If there are multiple users on the client system, only a knock sequence that is initiated by the required username will be honored. This variable is optional and is only valid with an encrypted sequence definition.

ENCRYPT_SEQUENCE
    Expect that all port knock sequences originating from the SOURCE will be encrypted. Fwknop will try to decrypt all such sequences. ENCRYPT_SEQUENCE does not accept any arguments. Either this variable or the "SHARED_SEQUENCE" variable is required for each SOURCE block.

SHARED_SEQUENCE: <proto/port>, ..., <proto/port>
    Define the sequence of ports (together with their associated protocol; tcp or udp) that will be sent to the destination knock server. This sequence is not encrypted, and source IP will be allowed to connect through the destination firewall ruleset to a set of tcp or udp ports (defined by the OPEN_PORTS variable). Using an encrypted sequence is much more secure. Either this variable or the "ENCRYPT_SEQUENCE" variable above is required for each SOURCE block.

KNOCK_INTERVAL: <seconds>
    Define the interval of time in which a port knock sequence will be honored. I.e. the number of seconds after the first connection attempt the last connection attempt in the sequence must be received for the knock sequence to be accepted by the destination fwknop daemon. If a KNOCK_INTERVAL is not specified then the default interval of 60 seconds will automatically be set.

KNOCK_LIMIT: <number>
    Define the maximum number of times a knock sequence will be honored. Note that repetitive access to the fwknop server will eventually be restricted if this option is used.

PORT_OFFSET: <offset>
    Encrypted knock sequences take place over a range of 256 ports starting at a default port of 61000. This value can be changed through the use of the PORT_OFFSET variable. The PORT_OFFSET is optional and will be set to 61000 by fwknop if it is not specified in /etc/fwknop/access.conf.

MIN_TIME_DIFF: <seconds>
    Set the minimum number of seconds that must pass between successive connection attempts in a shared knock sequence. This variable is optional.

MAX_TIME_DIFF: <seconds>
    Set the maximum number of seconds that must pass between successive connection attempts in a shared knock sequence. This variable is optional.

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 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 172.16.5.4 -P tcp -p 22 -k 10.0.0.123 Start fwknop in server mode: # fwknop Same as above, but this time we use the init script to start fwknop: # /etc/init.d/fwknop start 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 -e -P tcp -p 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 -e -s -P tcp -p 22 -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 -e -s -P tcp -p 22 -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 -e -s -P tcp -p 22 -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 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 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
iptables(8), p0f(1), knopmd(8), knopwatchd(8)

AUTHOR
Michael Rash <mbr@cipherdyne.org>

CREDITS
The phrase "Single Packet Authorization" was coined by Simple Nomad, 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/