FWKNOPD(8)

NAME
fwknopd - Firewall Knock Operator (server component)

SYNOPSIS
fwknopd [options]

DESCRIPTION
fwknopd is the server component for the FireWall Knock Operator, and is responsible for monitoring Single Packet Authorization (SPA) packets that are generated by fwknop clients, modifying an iptables or ipfw policy to allow the desired access after decrypting a valid SPA packet, and removing access after a configurable timeout. 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 main configuration for fwknopd is maintained within two files: fwknop.conf and access.conf within the /etc/fwknop directory, and configuration variables within these files are desribed below.

OPTIONS

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

-i, --intf <interface>
    Manually specify interface on which to sniff, e.g. "-i eth0". This option is not usually needed because the PCAP_INTF keyword in /etc/fwknop/fwknop.conf file defines the sniffing interface.

--fw-list
    List all active rules in the FWKNOP Netfilter chain(s).

--fw-flush
    Flush all active rules in the FWKNOP Netfilter chain(s).

-O, --Override-config <file>
    Override config variable values that are normally read from the /etc/fwknop/fwknop.conf file with values from the specified file. Multiple override config files can be given as a comma separated list.

-D, --Dump-config
    Dump the configuration values that fwknopd derives from the /etc/fwknop/fwknop.conf (or other override files) on STDERR.

-o, --os
    Parse Netfilter logs and fingerprint operating systems from which tcp SYN packets have been logged.

--fw-log <file>
    Specify the path to the Netfilter log file that is parsed when running in --os mode.

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

-S, --Status
    Display the status of any fwknop processes that may or not be running.

-l,  --locale <locale>
    Provide a locale setting other than the default "C" locale.

--no-locale
    Do not set the locale at all so that the default system locale will apply.

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

GPG_DECRYPT_ID: <keyID>
    Define a GnuPG key ID to use for decrypting SPA messages that have been encrypted by an fwknop client. This keyword is required for authentication that is based on gpg keys. The gpg key ring on the client must have imported and signed the fwknopd server key, and vice versa. It is ok to use a sensitive personal gpg key on the client, but each fwknopd server should have its own gpg key that is generated specifically for fwknop communications. The reason for this is that the decryption password for the server key must be placed within the /etc/fwknop/access.conf file for fwknopd to function (it has to be able to decrypt SPA messages that have been encrypted with the server's public key). For more information on using fwknop with GnuPG keys, see the following link: http://www.cipherdyne.org/fwknop/docs/gpghowto.html

GPG DECRYPT_PW: <decrypt password>
    Specify the decryption password for the gpg key defined by the GPG_DECRYPT_ID above. This is a required field for gpg-based authentication.

GPG_REMOTE_ID: <keyID,...,keyID>
    Define a list of gpg key ID's that are required to have signed any incoming SPA message that has been encrypted with the fwknopd server key. This ensures that the verification of the remote user is accomplished via a strong cryptographic mechanism.

GPG_HOME_DIR: <path>
    Define the path to the GnuPG directory to be used by the fwknopd server. If this keyword is not specified within /etc/fwknop/access.conf then fwknopd will default to using the /root/.gnupg directory for the server key(s).

GPG_USE_OPTIONS
    By default, fwknopd instructs gpg to not reference any options file when decrypting incoming SPA packets that have been encrypted with GnuPG by the fwknop client. This argument re-enables options in gpg.

GPG_NO_REQUIRE_PREFIX
    This option controls whether the GnuPG 'hQ' prefix is added before base64 decoding and decrypting. Normally this option is not needed, but if there appear to be communications issues between the fwknop client and the fwknopd server in GnuPG mode, then this option can be useful to ensure that encrypted SPA data is sent through the GnuPG decryption routine. The 'hQ' prefix is a heuristic derived from the file 'magic' database for describing data encrypted with GnuPG, and the fwknop client normally strips this data from outgoing SPA packets (unless the --Include-gpg-prefix option is used).

GPG_PATH: <path>
    Specify a path to the gpg binary (commonly at /usr/bin/gpg). This can be used to switch between gpg vs. gpg2, or provide a path to a custom compiled version of gpg for testing purposes.

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

REQUIRE_SOURCE_ADDRESS
    Force all SPA packets to contain a real IP address within the encrypted data. This makes it impossible to use the -s command line argument on the fwknop command line, so either -R has to be used to automatically resolve the external address (if the client behind a NAT) or the client must know the external IP.

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, and is not applicable in SPA mode.

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, and is not applicable in SPA mode.

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.

DEPENDENCIES
fwknopd 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
fwknop(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/