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 authenticating
       and decrypting a valid SPA packet (in that order), and removing access
       after a configurable timeout.

       The main application of this program is to conceal 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.
       In addition, services that are concealed in this fashion naturally
       cannot be scanned for with Nmap or Shodan.

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

       Additional information may be found in the tutorial "Single Packet
       Authorization: A Comprehensive Guide to Strong Service Concealment with
       fwknop" available online (see:
       http://www.cipherdyne.org/fwknop/docs/fwknop-tutorial.html).

COMMAND-LINE OPTIONS
       -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 only firewall rules that any running fwknopd daemon has
           created and then exit.

       -a, --access-file=<access-file>
           Specify the location of the access.conf file. If this option is not
           given, fwknopd will use the compile-time default location
           (typically /etc/fwknop/access.conf).

       --access-folder=<access-folder>
           Specify the location of the access.conf folder. If this option is
           given, rather than load a single access.conf file, all the .conf
           files in the given folders are processed.

       -c, --config=<config-file>
           Specify the location of the fwknopd.conf file. If this option is
           not given, fwknopd 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, --digest-file=<digest-file>
           Specify the location of the digest.cache file. If this option is
           not given, fwknopd will use the compile-time default location
           (typically /var/fwknop/digest.cache).

       -D, --dump-config
           Dump the configuration values that fwknopd derives from the
           /etc/fwknop/fwknopd.conf (or override files) and
           /etc/fwknop/access.conf on stderr.

       --dump-serv-err-codes
           Dump all possible fwknopd error codes to stdout and exit. This
           option is rarely needed in practice, and was added to assist with
           test coverage.

       --fault-injection-tag=<tag>
           This option is only used for fault injection testing when fwknop is
           compiled to support the libfiu library (see:
           http://blitiri.com.ar/p/libfiu/). Under normal circumstances this
           option is not used, and any packaged version of fwknop will not
           have code compiled in so this capability is not enabled at run
           time. It is documented here for completeness. version of fwknop
           will not have code compiled in to enable this capability at run
           time. It is documented here for completeness.

       -A, --afl-fuzzing
           Instruct fwknopd to acquire SPA packets directly from stdin in
           support of fuzzing operations from the American Fuzzy Lop (AFL)
           fuzzer written by Michal Zalewski. This requires that fwknop is
           compiled with the --enable-afl-fuzzing argument to the configure
           script as this allows encryption/digest short circuiting in a
           manner necessary for AFL to function properly. The benefit of this
           strategy is that AFL can fuzz the SPA packet decoding routines
           implemented by libfko.

       --fw-list-all
           List all firewall rules including those that have nothing to do
           with fwknopd.

       --fw-flush
           Flush any firewall rules created by a running fwknopd process. This
           option allows the used to easily delete fwknopd firewall rules
           without having to wait for them to be timed out.

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

       --exit-parse-config
           Parse config files (/etc/fwknop/fwknopd.conf, and
           /etc/fwknop/access.conf) and then exit. This provides a way to test
           whether the config files are properly structured without having to
           start processing network traffic.

       --exit-parse-digest-cache
           Parse the digest cache file /var/fwknop/digest.cache and exit. This
           validates the structure of the digest cache file without having to
           start processing network traffic. Note that the standard
           configuration files are also parsed in this mode.

       -l, --locale=<locale>
           Set/override the system default locale setting.

       --no-ipt-check-support
           Disable the usage of the iptables -C option. This is not normally
           needed, and is only useful on older Linux distributions where
           iptables does not have -C support.

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

       --key-gen
           Have fwknopd generate both Rijndael and HMAC keys that can be used
           for SPA packet encryption and authentication. These keys are
           derived from /dev/urandom and then base64 encoded before being
           printed to stdout, and are meant to be manually included in a
           stanza within the /etc/fwknop/access.conf file. Such keys are
           generally more secure than passphrases.

       --key-gen-file=<file>
           Write generated keys to the specified file. Note that the file is
           overwritten if it already exists. If this option is not given, then
           --key-gen writes the keys to stdout.

       --key-len=<length>
           Specify the number of bytes for a generated Rijndael key. The
           maximum size is currently 128 bytes.

       --hmac-key-len=<length>
           Specify the number of bytes for a generated HMAC key. The maximum
           size is currently 128 bytes.

       -p, --pid-file=<pid-file>
           Specify the location of the fwknopd.pid file. If this option is not
           given, fwknopd will use the compile-time default location
           (typically /var/fwknop/fwknopd.pid).

       -P, --pcap-filter=<filter>
           Specify a Berkeley packet filter statement on the fwknopd command
           line. This overrides the value of the PCAP_FILTER variable taken
           from the /etc/fwknop/fwknopd.conf file.

       --pcap-file=<pcap-file>
           This option instructs fwknopd to read packet data from a pcap file
           instead of sniffing an interface directly. This mode is usually
           used for debugging purposes, and will disable SPA packet age
           checking unless it is manually enabled in the
           /etc/fwknop/fwknopd.conf file.

       --pcap-any-direction
           Allow fwknopd to sniff SPA packets regardless of whether they are
           received on the sniffing interface or sent from the sniffing
           interface. In the later case, this can be useful to have fwknopd
           sniff SPA packets that are forwarded through a system and destined
           for a different network. If the sniffing interface is the egress
           interface for such packets (and hence SPA packets are sent by this
           interface instead of received), then this option will need to used
           in order for fwknopd to see them. The default is to only sniff
           packets that are received on the sniffing interface. Note that this
           setting is independent of promiscuous mode.

       -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 /etc/fwknop/access.conf files. This will also
           force a flush of the current "FWKNOP" iptables 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/fwknop/digest.cache.

       -r, --run-dir=<path>
           Specify the directory where fwknopd writes run time state files.
           The default is /var.

       -S, --status
           Display the status of any fwknopd processes that may or not be
           running. If there is an existing fwknopd process then 0 is returned
           for the exit status and 1 is returned otherwise.

       --syslog-enable
           Allow messages to be sent to syslog even if the foreground mode is
           set.

       -t, --test
           Run fwknopd in test mode. This instructs fwknopd to acquire and
           process SPA packets, but not manipulate firewall rules or execute
           commands that are provided by SPA clients. This option is mostly
           useful for the fuzzing tests in the test suite to ensure broad code
           coverage under adverse conditions.

       -U, --udp-server
           Run fwknopd in UDP server mode so that SPA packets are acquired via
           a UDP socket directly without having to use libpcap. See the
           discussion of the "ENABLE_UDP_SERVER" configuration variable below
           for more information.

       -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 /etc/fwknop/fwknopd.conf file for configuration
       variables to define 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 or set any
       encryption or authentication keys.

       The access control directives are contained in the
       /etc/fwknop/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. You will want to make sure to check these to make sure they
       have appropriate values, but sensible defaults are provided for most
       systems. See the /etc/fwknop/fwknopd.conf file for additional 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.

       RULES_CHECK_THRESHOLD <count>
           Defines the number of times firewall rule expiration times must be
           checked before a "deep" check is run. This allows fwknopd to remove
           rules that contain a proper exp<time> even if a third party program
           added them instead of fwknopd. The default value for this variable
           is 20, and this typically results in this check being run every two
           seconds or so. To disable this type of checking altogether, set
           this variable to zero.

       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 /etc/fwknop/fwknopd.conf file),
           but if you want fwknopd to use the SNAT target, you must also
           define an IP address with the "SNAT_TRANSLATE_IP" variable. Note
           that this variable is generally deprecated in favor of the
           "FORCE_SNAT" variable in the /etc/fwknop/access.conf file which
           enables per-stanza control over the SNAT IP.

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

       EXIT_AT_INTF_DOWN <Y/N>
           When fwknopd is sniffing an interface, if the interface is
           administratively downed or unplugged, fwknopd will cleanly exit and
           an assumption is made that any process monitoring infrastructure
           like systemd or upstart will restart it. However, if fwknopd is not
           being monitored by systemd, upstart, or anything else, this
           behavior can be disabled with the "EXIT_AT_INTF_DOWN" variable. If
           disabled, fwknopd will try to recover when a downed interface comes
           back up.

       ENABLE_RULE_PREPEND <Y/N>
           For systems running iptables or firewalld, have fwknopd insert new
           SPA rules at the beginning of the relevant chain (such as
           "FWKNOP_INPUT") instead of appending them to the end of the chain.
           This causes newly created rules to have precedence over older ones.

       ENABLE_NAT_DNS <Y/N>
           Allow fwknopd to resolve hostnames in NAT access messages.

       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 stanza in
           /etc/fwknop/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).

       GPG_EXE <path>
           Specify the path to GPG, and defaults to /usr/bin/gpg if not set.

       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_X_FORWARDED_FOR <Y/N>
           Allows fwknopd to use the X-Forwarded-for header from a captured
           SPA packet over HTTP as the source IP. This can happen when using
           SPA through an HTTP proxy.

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

       ENABLE_UDP_SERVER <Y/N>
           Enable the fwknopd UDP server. This instructs fwknopd to acquire
           SPA packets via a UDP socket directly without having to use
           libpcap. When this mode is enabled, fwknop should be compiled with
           --enable-udp-server (passed to the configure script) so that
           libpcap can be removed as a dependency. As one would expect, when
           the UDP server is used, no incoming packets are ever acknowledged
           by fwknopd and therefore collecting SPA packets in this mode is a
           good alternative to sniffing the wire directly.

       UDPSERV_PORT <port>
           Set the port number that the UDP server listens on. This server is
           only spawned when "ENABLE_UDP_SERVER" is set to "Y".

       PCAP_DISPATCH_COUNT <count>
           Sets the number of packets that are processed when the
           pcap_dispatch() call is made. The default is zero, since this
           allows fwknopd to process as many packets as possible in the
           corresponding callback where the SPA handling routine is called for
           packets that pass a set of prerequisite checks. However, if fwknopd
           is running on a platform with an old version of libpcap, it may be
           necessary to change this value to a positive non-zero integer. More
           information can be found in the pcap_dispatch(3) man page.

       PCAP_LOOP_SLEEP <microseconds>
           Sets the number of microseconds to passed as an argument to
           usleep() in the pcap loop. The default is 100000, or 1/10th of a
           second.

       ENABLE_PCAP_ANY_DIRECTION <Y/N>
           Controls whether fwknopd is permitted to sniff SPA packets
           regardless of whether they are received on the sniffing interface
           or sent from the sniffing interface. In the later case, this can be
           useful to have fwknopd sniff SPA packets that are forwarded through
           a system and destined for a different network. If the sniffing
           interface is the egress interface for such packets, then this
           variable will need to be set to "Y" in order for fwknopd to see
           them. The default is "N" so that fwknopd only looks for SPA packets
           that are received on the sniffing interface (note that this is
           independent of promiscuous mode).

       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

       ENABLE_DESTINATION_RULE <Y/N>
           Controls whether fwknopd will set the destination field on the
           firewall rule to the destination address specified on the incoming
           SPA packet. This is useful for interfaces with multiple IP
           addresses hosting separate services. If "ENABLE_IPT_OUTPUT" is set
           to "Y", the source field of the firewall rule is set. FORWARD and
           SNAT rules are not affected however, DNAT rules will also have
           their destination field set. The default is "N", which sets the
           destination field to 0.0.0.0/0 (any).

       FWKNOP_RUN_DIR <path>
           Specify the directory where fwknopd writes run time state files.
           The default is /var.

   ACCESS.CONF VARIABLES
       This section describes the access control directives in the
       /etc/fwknop/access.conf file. Theses directives define encryption and
       authentication keys, and the level of access that is granted to fwknop
       clients that have generated an appropriate encrypted and authenticated
       SPA packet.

       The access.conf variables described below provide the access directives
       for the SPA packets with a source (or embedded 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
           /etc/fwknop/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")

       DESTINATION <IP,..,IP/NET,..,NET/ANY>
           This defines the destination address for which the SPA packet will
           be accepted. The string "ANY" is also accepted if a valid SPA
           packet should be honored to any destination IP. 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 <passphrase>
           Define the symmetric key used for decrypting an incoming SPA packet
           that is encrypted by the fwknop client with Rijndael. The actual
           encryption key that is used is derived from the standard PBKDF1
           algorithm. This variable is required for all SPA packets unless
           GnuPG is used instead (see the GPG variables below).

       KEY_BASE64 <base64 encoded passphrase>
           Same as the KEY option above, but specify the symmetric key as a
           base64 encoded string. This allows non-ascii characters to be
           included in the base64-decoded key.

       HMAC_KEY <key>
           Specify the HMAC key for authenticated encryption of SPA packets.
           This supports both Rijndael and GPG encryption modes, and is
           applied according to the encrypt-then-authenticate model.

       HMAC_KEY_BASE64 <base64 encoded key>
           Specify the HMAC key as a base64 encoded string. This allows
           non-ascii characters to be included in the base64-decoded key.

       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.

       %include <file>
           Have fwknopd import an additional access.conf file. This allows
           more access stanzas to be defined in other locations in the
           filesystem, and this can be advantageous in some scenarios by
           letting non-privileged users define their own encryption and
           authentication keys for SPA operations. This way, users do not need
           write access to the main /etc/fwknop/access.conf file to change
           keys around or define new ones.

       %include_folder <directory>
           Similarly to the %include option above, the %include_folder
           directive has fwknopd import all .conf files from the specified
           directory. There is also command line support for this via the
           access-folder option.

       ENCRYPTION_MODE <mode>
           Specify the encryption mode when AES is used. The default is CBC
           mode, but other modes can be selected such as OFB and CFB. In
           general, it is recommended to not use this variable and leave it as
           the default. Note that the string "legacy" can be specified in
           order to generate SPA packets with the old initialization vector
           strategy used by versions of fwknop before 2.5. With the 2.5
           release, fwknop uses PBKDF1 for key derivation.

       HMAC_DIGEST_TYPE <digest algorithm>
           Specify the digest algorithm for incoming SPA packet
           authentication. Must be one of MD5, SHA1, SHA256, SHA384, SHA512,
           SHA3_256, or SHA3_512. This is an optional field, and if not
           specified then fwknopd defaults to using SHA256 if the access
           stanza requires an HMAC.

       ACCESS_EXPIRE <MM/DD/YYYY>
           Defines an expiration date for the access stanza in MM/DD/YYYY
           format. All SPA packets that match an expired stanza will be
           ignored. This parameter is optional.

       ACCESS_EXPIRE_EPOCH <seconds>
           Defines an expiration date for the access stanza as the epoch time,
           and is useful if a more accurate expiration time needs to be given
           than the day resolution offered by the ACCESS_EXPIRE variable
           above. All SPA packets that match an expired stanza will be
           ignored. This parameter is optional.

       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.

       ENABLE_CMD_SUDO_EXEC <Y/N>
           sudo provides a powerful means of restricting the sets of commands
           that users can execute via the "sudoers" file. By enabling this
           feature (and in "ENABLE_CMD_EXEC" mode), all incoming commands from
           valid SPA packets will be prefixed by "/path/to/sudo -u <user> -g
           <group>" where the path to sudo is set by the "SUDO_EXE" variable,
           "<user>" is set by the "CMD_SUDO_EXEC_USER" variable (default is
           "root" if not set), and "<group>" is set by "CMD_SUDO_EXEC_GROUP"
           (default is also "root" if not set).

       CMD_EXEC_USER <username>
           Specify the user (via setuid) that will execute a command contained
           within a SPA packet. If this variable is not given, fwknopd will
           execute the command as the user it is running as (most likely
           root). Setting this to a non-root user such as "nobody" is highly
           recommended if elevated permissions are not needed.

       CMD_SUDO_EXEC_USER <username>
           Specify the user (via "sudo -u <user>") that will execute a command
           contained within a SPA packet. If this variable is not given,
           fwknopd will assume the command should be executed as root.

       CMD_EXEC_GROUP <groupname>
           Specify the group (via setgid) that will execute a command
           contained within a SPA packet. If this variable is not given,
           fwknopd will execute the command as the user it is running as (most
           likely root). Setting this to a non-root user such as "nobody" is
           highly recommended if elevated permissions are not needed.

       CMD_SUDO_EXEC_GROUP <groupname>
           Specify the group (via "sudo -g <group>") that will execute a
           command contained within a SPA packet. If this variable is not
           given, fwknopd will assume the command should be executed as root.

       CMD_CYCLE_OPEN <command>
           Specify a command open/close cycle to be executed upon receipt of a
           valid SPA packet. This directive sets the initial command, and is
           meant to be used in conjunction with the "CMD_CYCLE_CLOSE" variable
           below. The main application of this feature is to allow fwknopd to
           interact with firewall or ACL's that are not natively supported,
           and facilitate the same access model as for the main supported
           firewalls such as iptables. That is, a command is executed to open
           the firewall or ACL, and then a corresponding close command is
           executed after a timer expires. Both the "CMD_CYCLE_OPEN" and
           "CMD_CYCLE_CLOSE" variables support special substitution strings to
           allow values to be taken from the SPA payload and used on the
           command line of the executed command. These strings begin with a
           "$" character, and include "$IP" (the allow IP decrypted from the
           SPA payload), "$SRC" (synonym for "$IP") , "$PKT_SRC" (the source
           IP in the network layer header of the SPA packet), "$DST" (the
           destination IP), "$PORT" (the allow port), and "$PROTO" (the allow
           protocol), "$TIMEOUT" (set the client timeout if specified).

       CMD_CYCLE_CLOSE <command>
           Specify the close command that corresponds to the open command set
           by the "CMD_CYCLE_OPEN" variable described above. The same string
           substitutions such as "$IP", "$PORT", and "$PROTO" are supported.
           In addition, the special value "NONE" can be set to allow no close
           command to be executed after the open command. This might be handy
           in certain situations where, say, indefinite access is desired and
           allowed.

       CMD_CYCLE_TIMER <seconds>
           Set the number of seconds after which the close command set in
           "CMD_CYCLE_CLOSE" will be executed. This defines the open/close
           timer interval.

       SUDO_EXE <path>
           Define the path to the sudo binary. Default is "/usr/bin/sudo".

       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 and set it
           via the -a argument.

       REQUIRE_SOURCE_ADDRESS <Y/N>
           Synonym for "REQUIRE_SOURCE_ADDRESS".

       FORCE_NAT <IP> <PORT>
           For any valid SPA packet, force the requested connection to be
           NAT'd through to the specified (usually internal) IP and port
           value. This is useful if there are multiple internal systems
           running a service such as SSHD, and you want to give transparent
           access to only one internal system for each stanza in the
           access.conf file. This way, multiple external users can each
           directly access only one internal system per SPA key.

       FORCE_SNAT <IP>
           For any valid SPA packet, add an SNAT rule in addition to any DNAT
           rule created with a corresponding (required) FORCE_NAT variable.
           This is analogous to "SNAT_TRANSLATE_IP" from the
           /etc/fwknop/fwknopd.conf file except that it is per access stanza
           and overrides any value set with "SNAT_TRANSLATE_IP". This is
           useful for situations where an incoming NAT'd connection may be
           otherwise unanswerable due to routing constraints (i.e. the system
           receiving the SPA authenticated connection has a default route to a
           different device than the SPA system itself).

       FORCE_MASQUERADE <Y/N>
           This is similar to the "FORCE_SNAT" variable, except that it is not
           necessary to also specify an IP address for SNAT rules because the
           MASQUERADE target is used instead.

       FORWARD_ALL <Y/N>
           In NAT scenarios, control whether all traffic is forwarded through
           the fwknopd system as opposed to just forwarding connections to
           specific services as requested by the fwknop client.

       DISABLE_DNAT <Y/N>
           Control whether DNAT rules are created in FORCE_NAT scenarios. This
           is mainly used in conjunction with the FORWARD_ALL variable to
           allow fwknopd to act essentially as an SPA gateway. I.e., the
           fwknop client is used to gain access via SPA to the broader
           Internet after being granted an IP via DHCP, but prior to sending
           the SPA packet all traffic is blocked by default to the Internet.

       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_ALLOW_NO_PW <Y/N>
           Allow fwknopd to leverage a GnuPG key pair that does not have an
           associated password. While this may sound like a controversial
           deployment mode, in automated environments it makes sense because
           "there is usually no way to store a password more securely than on
           the secret keyring itself" according to:
           "http://www.gnupg.org/faq/GnuPG-FAQ.html#how-can-i-use-gnupg-in-an-automated-environment".
           Using this feature and removing the passphrase from a GnuPG key
           pair is useful in some environments where libgpgme is forced to use
           gpg-agent and/or pinentry to collect a passphrase.

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

       GPG_DISABLE_SIG <Y/N>
           Disable signature verification for incoming SPA messages. This is
           not a recommended setting, and 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. Signature
           verification is enabled by default, and can only be disabled if
           "GPG_DISABLE_SIG" is set to Y (not a recommended setting). Separate
           multiple entries with a comma.

       GPG_FINGERPRINT_ID <keyID,...,keyID>
           Specify a set of full-length GnuPG key fingerprints instead of the
           shorter key identifiers set with the "GPG_REMOTE_ID" variable. Here
           is an example fingerprint for one of the fwknop test suite keys:
           00CC95F05BC146B6AC4038C9E36F443C6A3FAD56.

       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) for incoming SPA
           packets handled by the matching access.conf stanza.

       GPG_EXE <path>
           Define the path to the GnuPG executable. If this keyword is not
           specified within /etc/fwknop/access.conf then fwknopd will default
           to using /usr/bin/gpg.

FILES
       /etc/fwknop/fwknopd.conf
           The main configuration file for fwknop.

       /etc/fwknop/access.conf
           Defines all knock sequences and access control directives.

DEPENDENCIES
       fwknopd requires libfko which is normally included with both source and
       binary distributions, and is a dedicated library developed by the
       fwknop project.

       For packet sniffing, fwknopd currently requires libpcap, but future
       versions will (optionally) remove this as a dependency.

       For GPG functionality, GnuPG must also be correctly installed and
       configured along with the libgpgme library.

       To take advantage of all of the authentication and access management
       features of the fwknopd daemon/service a functioning iptables, ipfw, or
       pf firewall is required 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.

       The most comprehensive way to gain diagnostic information on fwknopd is
       to run the test suite test-fwknop.pl script located in the test/
       directory in the fwknop sources. The test suite runs sends fwknop
       through a large number of run time tests, has valgrind support,
       validates both SPA encryption and HMAC results against OpenSSL, and
       even has its own built in fuzzer for SPA communications.

SEE ALSO
       fwknopd(8), iptables(8), pf(4), pfctl(8), ipfw(8), gpg(1), libfko
       documentation.

       More information on Single Packet Authorization can be found in the
       paper "Single Packet Authorization with fwknop" available at
       http://www.cipherdyne.org/fwknop/docs/SPA.html. A comprehensive
       tutorial on fwknop operations and theory can be found at
       http://www.cipherdyne.org/fwknop/docs/fwknop-tutorial.html. This
       tutorial also includes information about the design of fwknop that may
       be worth reading for those interested in why fwknop is different from
       other SPA implementations.

       fwknop uses the git versioning system as its source code repository
       along with Github for tracking of issues and milestones:

               $ git clone https://github.com/mrash/fwknop.git fwknop.git

       Additional commentary on Single Packet Authorization can be found via
       Michael Rash's Twitter feed: http://twitter.com/michaelrash,
       @michaelrash

AUTHORS
       The primary developers of fwknop are Michael Rash (project creator)
       <mbr@cipherdyne.org>, Damien Stuart <dstuart@dstuart.org>, and Jonathan
       Bennett <jbennett@incomsystems.biz>.

CONTRIBUTORS
       This "C" version of fwknop 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 https://github.com/mrash/fwknop/blob/master/CREDITS to view
       the online list of contributors. A few contributors deserve to be
       singled out including: Franck Joncourt, Max Kastanas, Vlad Glagolev,
       Sean Greven, Hank Leininger, Fernando Arnaboldi, and Erik Gomez.

       The phrase "Single Packet Authorization" was coined by MadHat and
       Simple Nomad at the BlackHat Briefings of 2005.

BUGS
       Send bug reports to dstuart@dstuart.org or mbr@cipherdyne.org, or open
       a new issue on Github (see https://github.com/mrash/fwknop.git).
       Suggestions and/or comments are always welcome as well. Additional
       information may be found in the fwknop mailing list archives (see:
       https://lists.sourceforge.net/lists/listinfo/fwknop-discuss).

DISTRIBUTION
       fwknopd is distributed under the GNU General Public License (GPL v2+),
       and the latest version may be downloaded from
       http://www.cipherdyne.org.

Fwknop Server                     08/06/2018                        FWKNOPD(8)