FWKNOPD(8) Fwknop Server FWKNOPD(8)
NAME
fwknopd - Firewall Knock Operator Daemon
SYNOPSIS
fwknopd [options]
DESCRIPTION
fwknopd is the server component for the FireWall Knock Operator, and is responsible for monitoring and processing 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 /etc/fwknop)The configuration variables within these files are desribed below.
COMMAND-LINE OPTIONS
-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
/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
/etc/fwknop/fwknopd.conf.
-C, --packet-limit=<n>
Specify the number of candidate SPA packets to process and exit when this limit is reached.
-D, --Dump-config
Dump the configuration values that fwknopd derives from the fwknop.conf (or override files) and access.conf on stderr.
-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.
-f, --foreground
Run fwknopd in the foreground instead of becoming a daemon. When run in the foreground, message that would go to the log would instead
be sent to stderr. This mode is usually used when testing and/or debugging.
--fw-list
List all firewall rules that any running fwknopd daemon has created and then exit.
-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.
-l, --locale=<locale>
Set/override the system default locale setting.
-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.
-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
/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. This can option can be specified multiple times to increase the verbosity of the output to the system log
file (or to the screen if running in the foreground).
-h, --help
Display usage information and exit.
-V, --Version
Display version information and exit.
FWKNOPD CONFIG AND ACCESS VARIABLES
fwknopd references the fwknopd.conf file for configuration variables that define its operational parameters (what network interface and
port to sniff, what features to enable/disable, etc.). The fwknopd.conf 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 SPA message.
FWKNOPD.CONF VARIABLES
This section list the more prominent configuration variables used by fwknopd. It is not a complete list. There are directives for the type
of firewall used by fwknopd (i.e. iptables or ipfw). You will want to make sure to check these to make sure they have appropriate values.
See the fwknopd.conf file for the full list and corresponding details.
PCAP_INTF <interface>
Specify the ethernet interface on which fwknopd will sniff packets.
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. It is a good idea to leave this feature on to reduce the possibility of being vulnerable to a replay attack.
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).
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".
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).
LOCALE <locale>
Set the locale (via the LC_ALL variable). This can be set to override the default system locale.
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 when this is enabled,
the "PCAP_FILTER" variable would need to be updated to sniff traffic over TCP/80 connections and a web server should be running on the
same server as fwknopd.
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
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 any proto/port request specified 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 30 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
on the fwknopd server as the user specified by the "CMD_EXEC_USER" or as the user that started fwknopd if that is not set.
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.
FILES
fwknop.conf
The main configuration file for fwknop.
access.conf
Defines all knock sequences and access control directives.
DEPENDENCIES
The fwknopd daemon requires a functioning Netfilter firewall on the underlying operating system.
DIAGNOSTICS
fwknopd can be run in debug mode by combining the -f, --foreground and the -v, --verbose command line options. 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), libfko docmentation.
AUTHOR
Damien Stuart <dstuart@dstuart.org>, Michael Rash <mbr@cipherdyne.org>
CREDITS
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).
BUGS
Send bug reports to dstuart@dstuart.org. Suggestions and/or comments are always welcome as well.
DISTRIBUTION
fwknopd is distributed under the GNU General Public License (GPL), and the latest version may be downloaded from http://www.cipherdyne.org.
Fwknop Server 08/28/2010 FWKNOPD(8)