: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 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 '@sysconfdir@/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
    '@sysconfdir@/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
    '@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, --Dump-config*::
    Dump the configuration values that *fwknopd* derives from the
    'fwknopd.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
    'fwknopd.conf' file with values from the specified file.  Multiple
    override config files can be given as a comma-separated list.

*-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 'fwknopd.conf' file.

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


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
-----
*fwknopd.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'.


