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