Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
FWKNOPD(8)			 Fwknop	Server			    FWKNOPD(8)

NAME
       fwknopd - Firewall Knock	Operator Daemon

SYNOPSIS
       fwknopd [options]

DESCRIPTION
       fwknopd is the server component for the FireWall	Knock Operator,	and is
       responsible for monitoring and processing Single	Packet Authorization
       (SPA) packets that are generated	by fwknop clients, modifying a
       firewall	or ACL policy to allow the desired access after	authenticating
       and decrypting a	valid SPA packet (in that order), and removing access
       after a configurable timeout.

       The main	application of this program is to conceal services such	as SSH
       with an additional layer	of security in order to	make the exploitation
       of vulnerabilities (both	0-day and unpatched code) much more difficult.
       In addition, services that are concealed	in this	fashion	naturally
       cannot be scanned for with Nmap or Shodan.

       The main	configuration for fwknopd is maintained	within two files:
       fwknopd.conf and	access.conf. The default location for these files is
       determined at package configuration (typically /usr/local/etc/fwknop).
       The configuration variables within these	files are described below.

       Additional information may be found in the tutorial Single Packet
       Authorization: A	Comprehensive Guide to Strong Service Concealment with
       fwknop available	online here:
       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 /usr/local/etc/fwknop/access.conf).

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

       -c, --config=_config-file_
	   Specify the location	of the fwknopd.conf file. If this option is
	   not given, fwknopd will use the default location (typically
	   /usr/local/etc/fwknop/fwknopd.conf.

       -C, --packet-limit=_n_
	   Specify the number of candidate SPA packets to process and exit
	   when	this limit is reached.

       -d, --digest-file=_digest-file_
	   Specify the location	of the digest.cache file. If this option is
	   not given, fwknopd will use the compile-time	default	location
	   (typically /var/fwknop/digest.cache).

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

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

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

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

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

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

       -K, --kill
	   Kill	the current fwknopd process. This provides a quick and easy
	   way to stop fwknopd without having to look in the process table.

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

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

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

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

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

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

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

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

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

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

       -P, --pcap-filter=_filter_
	   Specify a Berkeley packet filter statement on the fwknopd command
	   line. This overrides	the value of the PCAP_FILTER variable taken
	   from	the /usr/local/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
	   /usr/local/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 /usr/local/etc/fwknop/access.conf files. This will
	   also	force a	flush of the current "FWKNOP" iptables chain(s).

       --rotate-digest-cache
	   Rotate the digest cache file	by renaming it to "<name>-old",	and
	   starting a new one. The digest cache	file is	typically found	in
	   /var/fwknop/digest.cache.

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

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

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

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

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

       -v, --verbose
	   Run fwknopd in verbose mode.	This can option	can be specified
	   multiple times to increase the verbosity of the output to the
	   system log file (or to the screen if	running	in the foreground).

       -h, --help
	   Display usage information and exit.

       -V, --Version
	   Display version information and exit.

FWKNOPD	CONFIG AND ACCESS VARIABLES
       fwknopd references the /usr/local/etc/fwknop/fwknopd.conf file for
       configuration variables to define operational parameters	(what network
       interface and port to sniff, what features to enable/disable, etc.).
       The fwknopd.conf	file does not define any access	control	directives or
       set any encryption or authenitcation keys.

       The access control directives are contained in the
       /usr/local/etc/fwknop/access.conf file. Access control directives
       define encryption keys and level	of access that is granted to an	fwknop
       client that has generated the appropriate encrypted SPA message.

   FWKNOPD.CONF	VARIABLES
       This section list the more prominent configuration variables used by
       fwknopd.	You will want to make sure to check these to make sure they
       have appropriate	values,	but sensible defaults are provided for most
       systems.	See the	/usr/local/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
	   /usr/local/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
	   /usr/local/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.

       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
	   /usr/local/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_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 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).

       SYSLOG_IDENTITY _identity_
	   Override syslog identity on message logged by fwknopd. The defaults
	   are usually ok.

       SYSLOG_FACILITY _facility_
	   Override syslog facility. The "SYSLOG_FACILITY" variable can	be set
	   to

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

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

   ACCESS.CONF VARIABLES
       This section describes the access control directives in the
       /usr/local/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
	   /usr/local/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 adventageous in some scenarios by
	   letting non-privledged users	define their own encryption and
	   authentication keys for SPA operations. This	way, users do not need
	   write access	to the main /usr/local/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, or
	   SHA512. 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
	   /usr/local/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 /usr/local/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
	   /usr/local/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 /usr/local/etc/fwknop/access.conf then fwknopd
	   will	default	to using /usr/bin/gpg.

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

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

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

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

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

       To take advantage of all	of the authentication and access management
       features	of the fwknopd daemon/service a	functioning iptables, ipfw, or
       pf firewall is required on the underlying operating system.

DIAGNOSTICS
       fwknopd can be run in debug mode	by combining the -f, --foreground and
       the -v, --verbose command line options. This will disable daemon	mode
       execution, and print verbose information	to the screen on stderr	as
       packets are received.

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

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

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

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

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

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

AUTHORS
       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	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), and
       the latest version may be downloaded from http://www.cipherdyne.org.

Fwknop Server			  12/23/2015			    FWKNOPD(8)

NAME | SYNOPSIS | DESCRIPTION | COMMAND-LINE OPTIONS | FWKNOPD CONFIG AND ACCESS VARIABLES | FILES | DEPENDENCIES | DIAGNOSTICS | SEE ALSO | AUTHORS | CONTRIBUTORS | BUGS | DISTRIBUTION

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=fwknopd&sektion=8&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help