:man source: Fwknop Server
:man manual: 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 '@sysconfdir@/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
    '@sysconfdir@/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
    '@sysconfdir@/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
    '@localstatedir@/fwknop/digest.cache').

*-D, --dump-config*::
    Dump the configuration values that *fwknopd* derives from the
    '@sysconfdir@/fwknop/fwknopd.conf' (or override files) and
    '@sysconfdir@/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 ('@sysconfdir@/fwknop/fwknopd.conf', and
    '@sysconfdir@/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 '@localstatedir@/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
    '@sysconfdir@/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
    '@sysconfdir@/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
    '@localstatedir@/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 '@sysconfdir@/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 '@sysconfdir@/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 '@sysconfdir@/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
    '@localstatedir@/fwknop/digest.cache'.

*-r, --run-dir*='<path>'::
    Specify the directory where *fwknopd* writes run time state files. The
    default is '@localstatedir@'.

*-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 '@sysconfdir@/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 '@sysconfdir@/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 '@sysconfdir@/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 '@sysconfdir@/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 '@sysconfdir@/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
    '@sysconfdir@/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*.

*ALLOW_ANY_USER_AGENT* '<Y/N>'::
    When *fwknopd* is configured to acquire SPA data from HTTP requests (i.e.
    when ``ENABLE_SPA_OVER_HTTP'' is set to ``Y''), control whether to require
    the User-Agent from the client to start with the string 'Fwknop'. The
    default is ``N'' to require this, but if set to ``Y'', then *fwknopd* will
    allow any User-Agent string to be set on incoming SPA packets.

*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
    one of ``LOG_LOCAL{0-7}'' or ``LOG_DAEMON'' (the default).

*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 '@localstatedir@'.

ACCESS.CONF VARIABLES
~~~~~~~~~~~~~~~~~~~~~
This section describes the access control directives in the
'@sysconfdir@/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
    '@sysconfdir@/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 '@sysconfdir@/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 '@sysconfdir@/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 '@sysconfdir@/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 '@sysconfdir@/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 '@sysconfdir@/fwknop/access.conf' then *fwknopd* will default to
    using '/usr/bin/gpg'.

FILES
-----
*@sysconfdir@/fwknop/fwknopd.conf*::
The main configuration file for fwknop.

*@sysconfdir@/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'.
