other versions
- wheezy 2.0.0rc2-2+deb7u2
- wheezy-backports 2.5.1-1~bpo70+1
- jessie 2.6.0-2.1+b1
- testing 2.6.9-1+b1
- unstable 2.6.9-1+b1
FWKNOPD(8) | Fwknop Server | FWKNOPD(8) |
NAME¶
fwknopd - Firewall Knock Operator DaemonSYNOPSIS¶
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.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).
-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/run/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.
--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.
-l, --locale=<locale>
Set/override the system default locale
setting.
-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.
-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/run/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/run/fwknop/digest.cache.
-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.
-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 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.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, ipfw, or pf). You will want to make sure to check these to make sure they have appropriate values. See the /etc/fwknop/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).
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_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
/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.
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 /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).
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.
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 10000, 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).
TCPSERV_PORT <port>
Set the port number that the
“dummy” TCP server listens on. This server is only spawned when
“ENABLE_TCP_SERVER” is set to “Y”.
SYSLOG_IDENTITY <identity>
Override syslog identity on message logged by
fwknopd. The defaults are usually ok.
SYSLOG_FACILITY <facility>
Override syslog facility. The
“SYSLOG_FACILITY” variable can be set to
ACCESS.CONF VARIABLES¶
This section describes the access control directives in the /etc/fwknop/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.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”)
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.
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, or SHA512. This is an optional field, and if not
specified then fwknopd defaults to using SHA256 if the access stanza
requires an HMAC.
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 and set
it via the -a argument.
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.
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_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 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¶
/etc/fwknop/fwknopd.confThe 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.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¶
fwknopd(8), iptables(8), pf(4), pfctl(8), ipfw(8), gpg(1), libfko documentation.$ git clone https://github.com/mrash/fwknop.git fwknop.git
AUTHORS¶
Damien Stuart <dstuart@dstuart.org>, Michael Rash <mbr@cipherdyne.org>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 http://www.cipherdyne.org/fwknop/docs/contributors.html 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.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), and the latest version may be downloaded from http://www.cipherdyne.org.06/30/2013 | Fwknop Server |