fwknopd - Firewall Knock Operator Daemon
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 a firewall or acl
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:
fwknopd.conf and access.conf. The default location for these files
is determined at package configuration (typically <prefix>/etc/fwknop)The
configuration variables within these files are desribed below.
-
-a, --access-file=<access-file>
-
Specify the location of the access.conf file. If this option is
not given, fwkopd will use the compile-time default location (typically
<prefix>/etc/fwknop/access.conf.
-
-c, --config=<config-file>
-
Specify the location of the fwknopd.conf file. If this option is
not given, fwkopd will use the default location (typically
<prefix>/etc/fwknop/fwknopd.conf.
-
-C, --packet-limit=<n>
-
Specify the number of candidate SPA packets to process and exit when
this limit is reached.
-
-i, --interface=<interface>
-
Manually specify interface on which to sniff, e.g. “-i eth0”. This
option is not usually needed because the “PCAP_INTF” keyword in the
fwknopd.conf file defines the sniffing interface.
-
-O, --Override-config=<file>
-
Override config variable values that are normally read from the
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
fwknop.conf (or override files) and access.conf on STDERR.
-
-K, --Kill
-
Kill the current fwknopd process. This provides a quick and easy
way to stop fwknopd without having to look in the process table.
-
-R, --Restart
-
Restart the currently running fwknopd processes. This option
will preserve the command line options that were supplied to the
original fwknopd process but will force fwknopd to re-read the
fwknopd.conf and access.conf files. This will also force a
flush of the current “FWKNOP” Netfilter chain(s).
-
--rotate-digest-cache
-
Rotate the digest cache file by renaming it to “<name>-old”, and
starting a new one. The digest cache file is typically found in
<prefix>/var/run/fwknop/digest.cache.
-
-S, --Status
-
Display the status of any fwknopd processes that may or not be
running.
-
-v, --verbose
-
Run fwknopd in verbose mode.
-
-h, --help
-
Display usage information and exit.
-
-V, --Version
-
Display version information and exit.
5. FWKNOPD CONFIG AND ACCESS VARIABLES
fwknopd references the fwknopd.conf file 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.
The access control directives are contained in the access.conf file.
Access control directives define encryption keys and level of access that
is granted to an fwknop client that has generated the appropriate encrypted
message.
5.1. FWKNOPS.CONF VARIABLES
This section list the more prominent configuration variables used by
fwknopd. It is not a complete list. See the fwknopd.conf file for
the full list and corresponding details.
-
HOSTNAME <hostname>
-
Force hostname to this value. If not set here, fwknopd will attempt
to use gethostname() to determine the local hostname and use that.
-
FIREWALL_TYPE <iptables|ipfw>
-
Define the firewall type. The default is iptables for Linux systems,
but this can be set to ipfw for BSD systems. Also supported is
external_cmd to allow fwknopd to invoke an external command instead
of interfacing with the firewall at all.
-
AUTH_MODE <PCAP|FILE_PCAP|ULOG_PCAP>
-
This defines the general strategy fwknopd uses to authenticate remote
clients. Possible values are PCAP (authenticate via regular pcap;
this is the default and puts the interface in promiscuous mode unless
“ENABLE_PCAP_PROMISC” is turned off), FILE_PCAP (authenticate via
a pcap file that is built by a sniffer), ULOG_PCAP (authenticate via
the ulogd pcap writer). Note: Currently, only PCAP is implemented.
-
PCAP_INTF <interface>
-
Define the ethernet interface on which fwknopd will sniff packets.
Note that this is only used if the “AUTH_MODE” keyword above is set
to “PCAP”.
-
ENABLE_PCAP_PROMISC <Y/N>
-
By default fwknopd puts the pcap interface into promiscuous mode. Set
this to “N” to disable that behavior (non-promiscuous).
-
PCAP_FILTER <pcap filter spec>
-
Define the filter used for PCAP modes; fwknopd defaults to UDP
port 62201. However, if an fwknop client uses the --rand-port option
to send the SPA packet over a random port, then this variable should be
updated to something like “udp dst portrange 10000-65535”.
-
ENABLE_SPA_PACKET_AGING <Y/N>
-
This instructs fwknopd to not honor SPA packets that have an old time
stamp. The value for “old” is defined by the “MAX_SPA_PACKET_AGE”
variable. If “ENABLE_SPA_PACKET_AGING” is set to “N”, fwknopd
will not use the client time stamp at all.
-
MAX_SPA_PACKET_AGE <seconds>
-
Defines the maximum age (in seconds) that an SPA packet will be accepted.
This requires that the client system is in relatively close time
synchronization with the fwknopd server system (NTP is good). The
default age is 120 seconds (two minutes).
-
ENABLE_DIGEST_PERSISTENCE <Y/N>
-
Track digest sums associated with previous SPA packets processed by
fwknopd. This allows digest sums to remain persistent across
executions of fwknopd. The default is “Y”. If set to “N”,
fwknopd will not check incoming SPA packet data against any
previously save digests.
-
ENABLE_IPT_FORWARDING <Y/N>
-
Allow SPA clients to request access to services through an iptables
firewall instead of just to it (i.e. access through the FWKNOP_FORWARD
chain instead of the INPUT chain). This also requires the
“ENABLE_FORWARD_ACCESS” variable to be set in the access.conf
file for the specific “SOURCE” stanzas that should be allowed for
forwarding access.
-
ENABLE_IPT_LOCAL_NAT >Y/N>
-
Allow SPA clients to request access to a local socket via NAT. This
still puts an ACCEPT rule into the FWKNOP_INPUT chain, but a different
port is translated via DNAT rules to the real one. So, the user would
do “ssh -p <port>” to access the local service (see the --NAT-local
and --NAT-rand-port on the fwknop client command line).
-
ENABLE_IPT_SNAT <Y/N>
-
Set this to “Y” to enable a corresponding SNAT rule. By default, if
forwarding access is enabled (see the “ENABLE_IPT_FORWARDING” variable
above), then fwknopd creates DNAT rules for incoming connections, but
does not also complement these rules with SNAT rules at the same time.
In some situations, internal systems may not have a route back out for
the source address of the incoming connection, so it is necessary to
also apply SNAT rules so that the internal systems see the IP of the
internal interface where fwknopd is running.
-
SNAT_TRANSLATE_IP <ip_address>
-
Specify the IP address for SNAT. This functionality is only enabled
when “ENABLE_IPT_SNAT” is set to “Y” and by default SNAT rules are
built with the MASQUERADE target (since then the internal IP does not
have to be defined here in the fwknopd.conf file), but if you want
fwknopd to use the SNAT target, you mus also define an IP address with
the “SNAT_TRANSLATE_IP” variable.
-
ENABLE_IPT_OUTPUT <Y/N>
-
Add ACCEPT rules to the FWKNOP_OUTPUT chain. This is usually only useful
if there are no state tracking rules to allow connection responses out
and the OUTPUT chain has a default-drop stance.
-
MAX_SNIFF_BYTES <bytes>
-
Specify the the maximum number of bytes to sniff per frame. 1500
is the default.
-
FLUSH_IPT_AT_INIT <Y/N>
-
Flush all existing rules in the fwknop chains at fwknopd start time.
The default is “Y”.
-
FLUSH_IPT_AT_EXIT <Y/N>
-
Flush all existing rules in the fwknop chains when fwknopd is stopped
or otherwise exits cleanly. The default is “Y”.
-
IPFW_RULE_NUM <rule_num>
-
If running on ipfw firewalls, this variable defines the rule number
that fwknopd uses to insert an ipfw pass rule.
-
IPFW_SET_NUM <set_num>
-
If running on ipfw firewalls, this variable defines the rule set
that will be used to store expired rules that still have a dynamic
rule associated to them. That set will be disabled by fwknopd and
should not be enabled while fwknopd is running. Not used when ipfw
isn’t using dynamic rules.
-
IPFW_DYNAMIC_INTERVAL <seconds>
-
For ipfw firewalls set the interval (in seconds) over those rules
that have no remaining dynamic rules associated with them will be
removed.
-
PCAP_CMD_TIMEOUT <seconds>
-
Define the timeout for running a command.
-
GPG_HOME_DIR <path>
-
If GPG keys are used instead of a Rijndael symmetric key, this is
the default GPG keys directory. Note that each access block in
access.conf can specify its own GPG directory to override
this default. If not set here or in an access.conf stanza, then
the $HOME/.gnupg directory of the user running fwknopd (most
likely root).
-
PCAP_PKT_FILE </path/to/sniff.pcap>
-
This gets used if AUTH_MODE is set to "FILE_PCAP". This file must
be created by a sniffer process (or something like the ulogd pcap
writer).
-
BLACKLIST <ipaddr/mask,…ipaddr,etc>
-
Define a comma-separated set of IP addresses and/or networks that should
be globally blacklisted. That is, any SPA packet that is from a source
IP (or has an internal --allow-ip) within a blacklisted network will be
ignored.
-
ENABLE_SPA_OVER_HTTP <Y/N>
-
Allow fwknopd to acquire SPA data from HTTP requests (generated with
the fwknop client in --HTTP mode). Note that the “PCAP_FILTER”
variable would need to be updated when this is enabled to sniff traffic
over TCP/80 connections.
-
ENABLE_TCP_SERVER <Y/N>
-
Enable the fwknopd TCP server. This is a "dummy" TCP server that will
accept TCP connection requests on the specified TCPSERV_PORT.
If set to "Y", fwknopd will fork off a child process to listen for, and
accept incoming TCP request. This server only accepts the
request. It does not otherwise communicate. This is only to allow the
incoming SPA over TCP packet which is detected via PCAP. The connection
is closed after 1 second regardless.
Note that fwknopd still only gets its data via pcap, so the filter
defined by PCAP_FILTER needs to be updated to include this TCP port.
-
TCPSERV_PORT <port>
-
Set the port number that the “dummy” TCP server listens on. This server
is only spawned when “ENABLE_TCP_SERVER” is set to “Y”.
-
SYSLOG_IDENTITY <identity>
-
Override syslog identity on message logged by fwknopd. The defaults
are usually ok.
-
SYSLOG_FACILITY <facility>
-
Override syslog facility. The “SYSLOG_FACILITY” variable can be set to
5.2. ACCESS.CONF VARIABLES
This section describes the access control directives in the access.conf
file. Theses directives define encryption keys and level of access that
is granted to fwknop clients that have generated the appropriate
encrypted message.
The access.conf variables described below provide the access directives
for the SPA packets with a source (or embeded request) IP that matches an
address or network range defined by the “SOURCE” variable. All variables
following “SOURCE” apply to the source stanza. Each “SOURCE”
directive starts a new stanza.
-
SOURCE: <IP,..,IP/NET,..,NET/ANY>
-
This defines the source address from which the SPA packet will be
accepted. The string “ANY” is also accepted if a valid SPA packet
should be honored from any source IP. Every authorization stanza in
access.conf definition must start with the “SOURCE” keyword.
Networks should be specified in CIDR notation (e.g. “192.168.10.0/24”),
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”)
-
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. If this entry is not set,
fwknopd will attempt to honor the request specifed in the SPA data
(unless of it matches any “RESTRICT_PORTS” entries). Multiple entries
are comma-separated.
-
RESTRICT_PORTS: <proto/port>,…,<proto/port>
-
Define a set of ports and protocols (tcp or udp) that are explicitly
not allowed regardless of the validity of the incoming SPA packet.
Multiple entries are comma-separated.
-
KEY: <password>
-
Define the key used for decrypting an incoming SPA packet that is using
its built-in (Rijndael) encryption. This variable is required for
all non-GPG-encrypted SPA packets.
-
FW_ACCESS_TIMEOUT: <seconds>
-
Define the length of time access will be granted by fwknopd 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 60 seconds
will automatically be set.
-
ENABLE_CMD_EXEC: <Y/N>
-
This instructs fwknopd to accept complete commands that are
contained within an authorization packet. Any such command will
be executed as root by the fwknopd server.
-
CMD_EXEC_USER: <username>
-
This specifies the user that will execute commands contained within a SPA
packet. If not specified, fwknopd will execute it as the user it is
running as (most likely root). Setting this to a non-root user is highly
recommended.
-
REQUIRE_USERNAME: <username>
-
Require a specific username from the client system as encoded in the SPA
data. This variable is optional and if not specified, the username data
in the SPA data is ignored.
-
REQUIRE_SOURCE_ADDRESS: <Y/N>
-
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 client 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.
-
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 access.conf then
fwknopd will default to using the /root/.gnupg directory for the
server key(s) for incoming SPA packets handled by the matching
access.conf stanza.
-
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 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_REQUIRE_SIG: <Y/N>
-
With this setting set to Y, fwknopd check all GPG-encrypted SPA
messages for a signature (signed by the sender’s key). If the incoming
message is not signed, the decryption process will fail. If not set, the
default is N.
-
GPG_IGNORE_SIG_VERIFY_ERROR: <Y/N>
-
Setting this will allow fwknopd to accept incoming GPG-encrypted packets
that are signed, but the signature did not pass verification (i.e. the
signer key was expired, etc.). This setting only applies if the
GPG_REQUIRE_SIG is also set to Y.
-
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.
This setting only applies if the “GPG_REQUIRE_SIG” is set to Y.
Separate multiple entries with a comma.
-
fwknop.conf
-
The main configuration file for fwknop.
-
access.conf
-
Defines all knock sequences and access control directives.
The fwknopd daemon requires a functioning Netfilter firewall on the
underlying operating system.
fwknopd 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.
fwknop(8), iptables(8), libfko docmentation.
This “C” version of fwknopd was derived from the original Perl-based
version on which many people who are active in the open source community
have contributed. See the CREDITS file in the fwknop sources, or visit
http://www.cipherdyne.org/fwknop/docs/contributors.html to view the online
list of contributors.
The phrase “Single Packet Authorization” was coined by MadHat and Simple
Nomad at the BlackHat Briefings of 2005 (see: http://www.nmrc.org).
Send bug reports to dstuart@dstuart.org. Suggestions and/or comments
are always welcome as well.
fwknopd is distributed under the GNU General Public License (GPL), and
the latest version may be downloaded from http://www.cipherdyne.org.