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/