1FWKNOPD(8)                       Fwknop Server                      FWKNOPD(8)
2
3
4

NAME

6       fwknopd - Firewall Knock Operator Daemon
7

SYNOPSIS

9       fwknopd [options]
10

DESCRIPTION

12       fwknopd is the server component for the FireWall Knock Operator, and is
13       responsible for monitoring and processing Single Packet Authorization
14       (SPA) packets that are generated by fwknop clients, modifying a
15       firewall or ACL policy to allow the desired access after authenticating
16       and decrypting a valid SPA packet (in that order), and removing access
17       after a configurable timeout.
18
19       The main application of this program is to conceal services such as SSH
20       with an additional layer of security in order to make the exploitation
21       of vulnerabilities (both 0-day and unpatched code) much more difficult.
22       In addition, services that are concealed in this fashion naturally
23       cannot be scanned for with Nmap or Shodan.
24
25       The main configuration for fwknopd is maintained within two files:
26       fwknopd.conf and access.conf. The default location for these files is
27       determined at package configuration (typically /etc/fwknop). The
28       configuration variables within these files are described below.
29
30       Additional information may be found in the tutorial “Single Packet
31       Authorization: A Comprehensive Guide to Strong Service Concealment with
32       fwknop” available online (see:
33       http://www.cipherdyne.org/fwknop/docs/fwknop-tutorial.html).
34

COMMAND-LINE OPTIONS

36       -i, --interface=<interface>
37           Manually specify interface on which to sniff, e.g. “-i eth0”. This
38           option is not usually needed because the “PCAP_INTF” keyword in the
39           fwknopd.conf file defines the sniffing interface.
40
41       -f, --foreground
42           Run fwknopd in the foreground instead of becoming a daemon. When
43           run in the foreground, message that would go to the log would
44           instead be sent to stderr. This mode is usually used when testing
45           and/or debugging.
46
47       --fw-list
48           List only firewall rules that any running fwknopd daemon has
49           created and then exit.
50
51       -a, --access-file=<access-file>
52           Specify the location of the access.conf file. If this option is not
53           given, fwknopd will use the compile-time default location
54           (typically /etc/fwknop/access.conf).
55
56       --access-folder=<access-folder>
57           Specify the location of the access.conf folder. If this option is
58           given, rather than load a single access.conf file, all the .conf
59           files in the given folders are processed.
60
61       -c, --config=<config-file>
62           Specify the location of the fwknopd.conf file. If this option is
63           not given, fwknopd will use the default location (typically
64           /etc/fwknop/fwknopd.conf.
65
66       -C, --packet-limit=<n>
67           Specify the number of candidate SPA packets to process and exit
68           when this limit is reached.
69
70       -d, --digest-file=<digest-file>
71           Specify the location of the digest.cache file. If this option is
72           not given, fwknopd will use the compile-time default location
73           (typically /var/fwknop/digest.cache).
74
75       -D, --dump-config
76           Dump the configuration values that fwknopd derives from the
77           /etc/fwknop/fwknopd.conf (or override files) and
78           /etc/fwknop/access.conf on stderr.
79
80       --dump-serv-err-codes
81           Dump all possible fwknopd error codes to stdout and exit. This
82           option is rarely needed in practice, and was added to assist with
83           test coverage.
84
85       --fault-injection-tag=<tag>
86           This option is only used for fault injection testing when fwknop is
87           compiled to support the libfiu library (see:
88           http://blitiri.com.ar/p/libfiu/). Under normal circumstances this
89           option is not used, and any packaged version of fwknop will not
90           have code compiled in so this capability is not enabled at run
91           time. It is documented here for completeness. version of fwknop
92           will not have code compiled in to enable this capability at run
93           time. It is documented here for completeness.
94
95       -A, --afl-fuzzing
96           Instruct fwknopd to acquire SPA packets directly from stdin in
97           support of fuzzing operations from the American Fuzzy Lop (AFL)
98           fuzzer written by Michal Zalewski. This requires that fwknop is
99           compiled with the --enable-afl-fuzzing argument to the configure
100           script as this allows encryption/digest short circuiting in a
101           manner necessary for AFL to function properly. The benefit of this
102           strategy is that AFL can fuzz the SPA packet decoding routines
103           implemented by libfko.
104
105       --fw-list-all
106           List all firewall rules including those that have nothing to do
107           with fwknopd.
108
109       --fw-flush
110           Flush any firewall rules created by a running fwknopd process. This
111           option allows the used to easily delete fwknopd firewall rules
112           without having to wait for them to be timed out.
113
114       -K, --kill
115           Kill the current fwknopd process. This provides a quick and easy
116           way to stop fwknopd without having to look in the process table.
117
118       --exit-parse-config
119           Parse config files (/etc/fwknop/fwknopd.conf, and
120           /etc/fwknop/access.conf) and then exit. This provides a way to test
121           whether the config files are properly structured without having to
122           start processing network traffic.
123
124       --exit-parse-digest-cache
125           Parse the digest cache file /var/fwknop/digest.cache and exit. This
126           validates the structure of the digest cache file without having to
127           start processing network traffic. Note that the standard
128           configuration files are also parsed in this mode.
129
130       -l, --locale=<locale>
131           Set/override the system default locale setting.
132
133       --no-ipt-check-support
134           Disable the usage of the iptables -C option. This is not normally
135           needed, and is only useful on older Linux distributions where
136           iptables does not have -C support.
137
138       -O, --override-config=<file>
139           Override config variable values that are normally read from the
140           /etc/fwknop/fwknopd.conf file with values from the specified file.
141           Multiple override config files can be given as a comma-separated
142           list.
143
144       --key-gen
145           Have fwknopd generate both Rijndael and HMAC keys that can be used
146           for SPA packet encryption and authentication. These keys are
147           derived from /dev/urandom and then base64 encoded before being
148           printed to stdout, and are meant to be manually included in a
149           stanza within the /etc/fwknop/access.conf file. Such keys are
150           generally more secure than passphrases.
151
152       --key-gen-file=<file>
153           Write generated keys to the specified file. Note that the file is
154           overwritten if it already exists. If this option is not given, then
155           --key-gen writes the keys to stdout.
156
157       --key-len=<length>
158           Specify the number of bytes for a generated Rijndael key. The
159           maximum size is currently 128 bytes.
160
161       --hmac-key-len=<length>
162           Specify the number of bytes for a generated HMAC key. The maximum
163           size is currently 128 bytes.
164
165       -p, --pid-file=<pid-file>
166           Specify the location of the fwknopd.pid file. If this option is not
167           given, fwknopd will use the compile-time default location
168           (typically /var/fwknop/fwknopd.pid).
169
170       -P, --pcap-filter=<filter>
171           Specify a Berkeley packet filter statement on the fwknopd command
172           line. This overrides the value of the PCAP_FILTER variable taken
173           from the /etc/fwknop/fwknopd.conf file.
174
175       --pcap-file=<pcap-file>
176           This option instructs fwknopd to read packet data from a pcap file
177           instead of sniffing an interface directly. This mode is usually
178           used for debugging purposes, and will disable SPA packet age
179           checking unless it is manually enabled in the
180           /etc/fwknop/fwknopd.conf file.
181
182       --pcap-any-direction
183           Allow fwknopd to sniff SPA packets regardless of whether they are
184           received on the sniffing interface or sent from the sniffing
185           interface. In the later case, this can be useful to have fwknopd
186           sniff SPA packets that are forwarded through a system and destined
187           for a different network. If the sniffing interface is the egress
188           interface for such packets (and hence SPA packets are sent by this
189           interface instead of received), then this option will need to used
190           in order for fwknopd to see them. The default is to only sniff
191           packets that are received on the sniffing interface. Note that this
192           setting is independent of promiscuous mode.
193
194       -R, --restart
195           Restart the currently running fwknopd processes. This option will
196           preserve the command line options that were supplied to the
197           original fwknopd process but will force fwknopd to re-read the
198           fwknopd.conf and /etc/fwknop/access.conf files. This will also
199           force a flush of the current “FWKNOP” iptables chain(s).
200
201       --rotate-digest-cache
202           Rotate the digest cache file by renaming it to “<name>-old”, and
203           starting a new one. The digest cache file is typically found in
204           /var/fwknop/digest.cache.
205
206       -r, --run-dir=<path>
207           Specify the directory where fwknopd writes run time state files.
208           The default is /var.
209
210       -S, --status
211           Display the status of any fwknopd processes that may or not be
212           running. If there is an existing fwknopd process then 0 is returned
213           for the exit status and 1 is returned otherwise.
214
215       --syslog-enable
216           Allow messages to be sent to syslog even if the foreground mode is
217           set.
218
219       -t, --test
220           Run fwknopd in test mode. This instructs fwknopd to acquire and
221           process SPA packets, but not manipulate firewall rules or execute
222           commands that are provided by SPA clients. This option is mostly
223           useful for the fuzzing tests in the test suite to ensure broad code
224           coverage under adverse conditions.
225
226       -U, --udp-server
227           Run fwknopd in UDP server mode so that SPA packets are acquired via
228           a UDP socket directly without having to use libpcap. See the
229           discussion of the “ENABLE_UDP_SERVER” configuration variable below
230           for more information.
231
232       -v, --verbose
233           Run fwknopd in verbose mode. This can option can be specified
234           multiple times to increase the verbosity of the output to the
235           system log file (or to the screen if running in the foreground).
236
237       -h, --help
238           Display usage information and exit.
239
240       -V, --Version
241           Display version information and exit.
242

FWKNOPD CONFIG AND ACCESS VARIABLES

244       fwknopd references the /etc/fwknop/fwknopd.conf file for configuration
245       variables to define operational parameters (what network interface and
246       port to sniff, what features to enable/disable, etc.). The fwknopd.conf
247       file does not define any access control directives or set any
248       encryption or authentication keys.
249
250       The access control directives are contained in the
251       /etc/fwknop/access.conf file. Access control directives define
252       encryption keys and level of access that is granted to an fwknop client
253       that has generated the appropriate encrypted SPA message.
254
255   FWKNOPD.CONF VARIABLES
256       This section list the more prominent configuration variables used by
257       fwknopd. You will want to make sure to check these to make sure they
258       have appropriate values, but sensible defaults are provided for most
259       systems. See the /etc/fwknop/fwknopd.conf file for additional details.
260
261       PCAP_INTF <interface>
262           Specify the ethernet interface on which fwknopd will sniff packets.
263
264       ENABLE_PCAP_PROMISC <Y/N>
265           By default fwknopd puts the pcap interface into promiscuous mode.
266           Set this to “N” to disable that behavior (non-promiscuous).
267
268       PCAP_FILTER <pcap filter spec>
269           Define the filter used for PCAP modes; fwknopd defaults to UDP port
270           62201. However, if an fwknop client uses the --rand-port option to
271           send the SPA packet over a random port, then this variable should
272           be updated to something like “udp dst portrange 10000-65535”.
273
274       ENABLE_SPA_PACKET_AGING <Y/N>
275           This instructs fwknopd to not honor SPA packets that have an old
276           time stamp. The value for “old” is defined by the
277           “MAX_SPA_PACKET_AGE” variable. If “ENABLE_SPA_PACKET_AGING” is set
278           to “N”, fwknopd will not use the client time stamp at all.
279
280       MAX_SPA_PACKET_AGE <seconds>
281           Defines the maximum age (in seconds) that an SPA packet will be
282           accepted. This requires that the client system is in relatively
283           close time synchronization with the fwknopd server system (NTP is
284           good). The default age is 120 seconds (two minutes).
285
286       ENABLE_DIGEST_PERSISTENCE <Y/N>
287           Track digest sums associated with previous SPA packets processed by
288           fwknopd. This allows digest sums to remain persistent across
289           executions of fwknopd. The default is “Y”. If set to “N”, fwknopd
290           will not check incoming SPA packet data against any previously save
291           digests. It is a good idea to leave this feature on to reduce the
292           possibility of being vulnerable to a replay attack.
293
294       RULES_CHECK_THRESHOLD <count>
295           Defines the number of times firewall rule expiration times must be
296           checked before a "deep" check is run. This allows fwknopd to remove
297           rules that contain a proper exp<time> even if a third party program
298           added them instead of fwknopd. The default value for this variable
299           is 20, and this typically results in this check being run every two
300           seconds or so. To disable this type of checking altogether, set
301           this variable to zero.
302
303       ENABLE_IPT_FORWARDING <Y/N>
304           Allow SPA clients to request access to services through an iptables
305           firewall instead of just to it (i.e. access through the
306           FWKNOP_FORWARD chain instead of the INPUT chain).
307
308       ENABLE_IPT_LOCAL_NAT <Y/N>
309           Allow SPA clients to request access to a local socket via NAT. This
310           still puts an ACCEPT rule into the FWKNOP_INPUT chain, but a
311           different port is translated via DNAT rules to the real one. So,
312           the user would do “ssh -p <port>” to access the local service (see
313           the --NAT-local and --NAT-rand-port on the fwknop client command
314           line).
315
316       ENABLE_IPT_SNAT <Y/N>
317           Set this to “Y” to enable a corresponding SNAT rule. By default, if
318           forwarding access is enabled (see the “ENABLE_IPT_FORWARDING”
319           variable above), then fwknopd creates DNAT rules for incoming
320           connections, but does not also complement these rules with SNAT
321           rules at the same time. In some situations, internal systems may
322           not have a route back out for the source address of the incoming
323           connection, so it is necessary to also apply SNAT rules so that the
324           internal systems see the IP of the internal interface where fwknopd
325           is running.
326
327       SNAT_TRANSLATE_IP <ip_address>
328           Specify the IP address for SNAT. This functionality is only enabled
329           when “ENABLE_IPT_SNAT” is set to “Y” and by default SNAT rules are
330           built with the MASQUERADE target (since then the internal IP does
331           not have to be defined here in the /etc/fwknop/fwknopd.conf file),
332           but if you want fwknopd to use the SNAT target, you must also
333           define an IP address with the “SNAT_TRANSLATE_IP” variable. Note
334           that this variable is generally deprecated in favor of the
335           “FORCE_SNAT” variable in the /etc/fwknop/access.conf file which
336           enables per-stanza control over the SNAT IP.
337
338       ENABLE_IPT_OUTPUT <Y/N>
339           Add ACCEPT rules to the FWKNOP_OUTPUT chain. This is usually only
340           useful if there are no state tracking rules to allow connection
341           responses out and the OUTPUT chain has a default-drop stance.
342
343       MAX_SNIFF_BYTES <bytes>
344           Specify the the maximum number of bytes to sniff per frame. 1500 is
345           the default.
346
347       FLUSH_IPT_AT_INIT <Y/N>
348           Flush all existing rules in the fwknop chains at fwknopd start
349           time. The default is “Y”.
350
351       FLUSH_IPT_AT_EXIT <Y/N>
352           Flush all existing rules in the fwknop chains when fwknopd is
353           stopped or otherwise exits cleanly. The default is “Y”.
354
355       EXIT_AT_INTF_DOWN <Y/N>
356           When fwknopd is sniffing an interface, if the interface is
357           administratively downed or unplugged, fwknopd will cleanly exit and
358           an assumption is made that any process monitoring infrastructure
359           like systemd or upstart will restart it. However, if fwknopd is not
360           being monitored by systemd, upstart, or anything else, this
361           behavior can be disabled with the “EXIT_AT_INTF_DOWN” variable. If
362           disabled, fwknopd will try to recover when a downed interface comes
363           back up.
364
365       ENABLE_RULE_PREPEND <Y/N>
366           For systems running iptables or firewalld, have fwknopd insert new
367           SPA rules at the beginning of the relevant chain (such as
368           “FWKNOP_INPUT”) instead of appending them to the end of the chain.
369           This causes newly created rules to have precedence over older ones.
370
371       ENABLE_NAT_DNS <Y/N>
372           Allow fwknopd to resolve hostnames in NAT access messages.
373
374       GPG_HOME_DIR <path>
375           If GPG keys are used instead of a Rijndael symmetric key, this is
376           the default GPG keys directory. Note that each access stanza in
377           /etc/fwknop/access.conf can specify its own GPG directory to
378           override this default. If not set here or in an access.conf stanza,
379           then the $HOME/.gnupg directory of the user running fwknopd (most
380           likely root).
381
382       GPG_EXE <path>
383           Specify the path to GPG, and defaults to /usr/bin/gpg if not set.
384
385       LOCALE <locale>
386           Set the locale (via the LC_ALL variable). This can be set to
387           override the default system locale.
388
389       ENABLE_SPA_OVER_HTTP <Y/N>
390           Allow fwknopd to acquire SPA data from HTTP requests (generated
391           with the fwknop client in --HTTP mode). Note that when this is
392           enabled, the “PCAP_FILTER” variable would need to be updated to
393           sniff traffic over TCP/80 connections and a web server should be
394           running on the same server as fwknopd.
395
396       ENABLE_X_FORWARDED_FOR <Y/N>
397           Allows fwknopd to use the X-Forwarded-for header from a captured
398           SPA packet over HTTP as the source IP. This can happen when using
399           SPA through an HTTP proxy.
400
401       ENABLE_TCP_SERVER <Y/N>
402           Enable the fwknopd TCP server. This is a "dummy" TCP server that
403           will accept TCP connection requests on the specified TCPSERV_PORT.
404           If set to "Y", fwknopd will fork off a child process to listen for,
405           and accept incoming TCP request. This server only accepts the
406           request. It does not otherwise communicate. This is only to allow
407           the incoming SPA over TCP packet which is detected via PCAP. The
408           connection is closed after 1 second regardless. Note that fwknopd
409           still only gets its data via pcap, so the filter defined by
410           PCAP_FILTER needs to be updated to include this TCP port.
411
412       TCPSERV_PORT <port>
413           Set the port number that the “dummy” TCP server listens on. This
414           server is only spawned when “ENABLE_TCP_SERVER” is set to “Y”.
415
416       ENABLE_UDP_SERVER <Y/N>
417           Enable the fwknopd UDP server. This instructs fwknopd to acquire
418           SPA packets via a UDP socket directly without having to use
419           libpcap. When this mode is enabled, fwknop should be compiled with
420           --enable-udp-server (passed to the configure script) so that
421           libpcap can be removed as a dependency. As one would expect, when
422           the UDP server is used, no incoming packets are ever acknowledged
423           by fwknopd and therefore collecting SPA packets in this mode is a
424           good alternative to sniffing the wire directly.
425
426       UDPSERV_PORT <port>
427           Set the port number that the UDP server listens on. This server is
428           only spawned when “ENABLE_UDP_SERVER” is set to “Y”.
429
430       PCAP_DISPATCH_COUNT <count>
431           Sets the number of packets that are processed when the
432           pcap_dispatch() call is made. The default is zero, since this
433           allows fwknopd to process as many packets as possible in the
434           corresponding callback where the SPA handling routine is called for
435           packets that pass a set of prerequisite checks. However, if fwknopd
436           is running on a platform with an old version of libpcap, it may be
437           necessary to change this value to a positive non-zero integer. More
438           information can be found in the pcap_dispatch(3) man page.
439
440       PCAP_LOOP_SLEEP <microseconds>
441           Sets the number of microseconds to passed as an argument to
442           usleep() in the pcap loop. The default is 100000, or 1/10th of a
443           second.
444
445       ENABLE_PCAP_ANY_DIRECTION <Y/N>
446           Controls whether fwknopd is permitted to sniff SPA packets
447           regardless of whether they are received on the sniffing interface
448           or sent from the sniffing interface. In the later case, this can be
449           useful to have fwknopd sniff SPA packets that are forwarded through
450           a system and destined for a different network. If the sniffing
451           interface is the egress interface for such packets, then this
452           variable will need to be set to "Y" in order for fwknopd to see
453           them. The default is "N" so that fwknopd only looks for SPA packets
454           that are received on the sniffing interface (note that this is
455           independent of promiscuous mode).
456
457       SYSLOG_IDENTITY <identity>
458           Override syslog identity on message logged by fwknopd. The defaults
459           are usually ok.
460
461       SYSLOG_FACILITY <facility>
462           Override syslog facility. The “SYSLOG_FACILITY” variable can be set
463           to
464
465       ENABLE_DESTINATION_RULE <Y/N>
466           Controls whether fwknopd will set the destination field on the
467           firewall rule to the destination address specified on the incoming
468           SPA packet. This is useful for interfaces with multiple IP
469           addresses hosting separate services. If “ENABLE_IPT_OUTPUT” is set
470           to “Y”, the source field of the firewall rule is set. FORWARD and
471           SNAT rules are not affected however, DNAT rules will also have
472           their destination field set. The default is “N”, which sets the
473           destination field to 0.0.0.0/0 (any).
474
475       FWKNOP_RUN_DIR <path>
476           Specify the directory where fwknopd writes run time state files.
477           The default is /var.
478
479   ACCESS.CONF VARIABLES
480       This section describes the access control directives in the
481       /etc/fwknop/access.conf file. Theses directives define encryption and
482       authentication keys, and the level of access that is granted to fwknop
483       clients that have generated an appropriate encrypted and authenticated
484       SPA packet.
485
486       The access.conf variables described below provide the access directives
487       for the SPA packets with a source (or embedded request) IP that matches
488       an address or network range defined by the “SOURCE” variable. All
489       variables following “SOURCE” apply to the source stanza. Each “SOURCE”
490       directive starts a new stanza.
491
492       SOURCE <IP,..,IP/NET,..,NET/ANY>
493           This defines the source address from which the SPA packet will be
494           accepted. The string “ANY” is also accepted if a valid SPA packet
495           should be honored from any source IP. Every authorization stanza in
496           /etc/fwknop/access.conf definition must start with the “SOURCE”
497           keyword. Networks should be specified in CIDR notation (e.g.
498           “192.168.10.0/24”), and individual IP addresses can be specified as
499           well. Also, multiple IP’s and/or networks can be defined as a comma
500           separated list (e.g. “192.168.10.0/24,10.1.1.123”)
501
502       DESTINATION <IP,..,IP/NET,..,NET/ANY>
503           This defines the destination address for which the SPA packet will
504           be accepted. The string “ANY” is also accepted if a valid SPA
505           packet should be honored to any destination IP. Networks should be
506           specified in CIDR notation (e.g. “192.168.10.0/24”), and individual
507           IP addresses can be specified as well. Also, multiple IP’s and/or
508           networks can be defined as a comma separated list (e.g.
509           “192.168.10.0/24,10.1.1.123”)
510
511       OPEN_PORTS <proto/port>,...,<proto/port>
512           Define a set of ports and protocols (tcp or udp) that will be
513           opened if a valid knock sequence is seen. If this entry is not set,
514           fwknopd will attempt to honor any proto/port request specified in
515           the SPA data (unless of it matches any “RESTRICT_PORTS” entries).
516           Multiple entries are comma-separated.
517
518       RESTRICT_PORTS <proto/port>,...,<proto/port>
519           Define a set of ports and protocols (tcp or udp) that are
520           explicitly not allowed regardless of the validity of the incoming
521           SPA packet. Multiple entries are comma-separated.
522
523       KEY <passphrase>
524           Define the symmetric key used for decrypting an incoming SPA packet
525           that is encrypted by the fwknop client with Rijndael. The actual
526           encryption key that is used is derived from the standard PBKDF1
527           algorithm. This variable is required for all SPA packets unless
528           GnuPG is used instead (see the GPG variables below).
529
530       KEY_BASE64 <base64 encoded passphrase>
531           Same as the KEY option above, but specify the symmetric key as a
532           base64 encoded string. This allows non-ascii characters to be
533           included in the base64-decoded key.
534
535       HMAC_KEY <key>
536           Specify the HMAC key for authenticated encryption of SPA packets.
537           This supports both Rijndael and GPG encryption modes, and is
538           applied according to the encrypt-then-authenticate model.
539
540       HMAC_KEY_BASE64 <base64 encoded key>
541           Specify the HMAC key as a base64 encoded string. This allows
542           non-ascii characters to be included in the base64-decoded key.
543
544       FW_ACCESS_TIMEOUT <seconds>
545           Define the length of time access will be granted by fwknopd through
546           the firewall after a valid knock sequence from a source IP address.
547           If “FW_ACCESS_TIMEOUT” is not set then the default timeout of 30
548           seconds will automatically be set.
549
550       %include <file>
551           Have fwknopd import an additional access.conf file. This allows
552           more access stanzas to be defined in other locations in the
553           filesystem, and this can be advantageous in some scenarios by
554           letting non-privileged users define their own encryption and
555           authentication keys for SPA operations. This way, users do not need
556           write access to the main /etc/fwknop/access.conf file to change
557           keys around or define new ones.
558
559       %include_folder <directory>
560           Similarly to the %include option above, the %include_folder
561           directive has fwknopd import all .conf files from the specified
562           directory. There is also command line support for this via the
563           access-folder option.
564
565       ENCRYPTION_MODE <mode>
566           Specify the encryption mode when AES is used. The default is CBC
567           mode, but other modes can be selected such as OFB and CFB. In
568           general, it is recommended to not use this variable and leave it as
569           the default. Note that the string “legacy” can be specified in
570           order to generate SPA packets with the old initialization vector
571           strategy used by versions of fwknop before 2.5. With the 2.5
572           release, fwknop uses PBKDF1 for key derivation.
573
574       HMAC_DIGEST_TYPE <digest algorithm>
575           Specify the digest algorithm for incoming SPA packet
576           authentication. Must be one of MD5, SHA1, SHA256, SHA384, SHA512,
577           SHA3_256, or SHA3_512. This is an optional field, and if not
578           specified then fwknopd defaults to using SHA256 if the access
579           stanza requires an HMAC.
580
581       ACCESS_EXPIRE <MM/DD/YYYY>
582           Defines an expiration date for the access stanza in MM/DD/YYYY
583           format. All SPA packets that match an expired stanza will be
584           ignored. This parameter is optional.
585
586       ACCESS_EXPIRE_EPOCH <seconds>
587           Defines an expiration date for the access stanza as the epoch time,
588           and is useful if a more accurate expiration time needs to be given
589           than the day resolution offered by the ACCESS_EXPIRE variable
590           above. All SPA packets that match an expired stanza will be
591           ignored. This parameter is optional.
592
593       ENABLE_CMD_EXEC <Y/N>
594           This instructs fwknopd to accept complete commands that are
595           contained within an authorization packet. Any such command will be
596           executed on the fwknopd server as the user specified by the
597           “CMD_EXEC_USER” or as the user that started fwknopd if that is not
598           set.
599
600       ENABLE_CMD_SUDO_EXEC <Y/N>
601           sudo provides a powerful means of restricting the sets of commands
602           that users can execute via the “sudoers” file. By enabling this
603           feature (and in “ENABLE_CMD_EXEC” mode), all incoming commands from
604           valid SPA packets will be prefixed by “/path/to/sudo -u <user> -g
605           <group>” where the path to sudo is set by the “SUDO_EXE” variable,
606           “<user>” is set by the “CMD_SUDO_EXEC_USER” variable (default is
607           “root” if not set), and “<group>” is set by “CMD_SUDO_EXEC_GROUP”
608           (default is also “root” if not set).
609
610       CMD_EXEC_USER <username>
611           Specify the user (via setuid) that will execute a command contained
612           within a SPA packet. If this variable is not given, fwknopd will
613           execute the command as the user it is running as (most likely
614           root). Setting this to a non-root user such as “nobody” is highly
615           recommended if elevated permissions are not needed.
616
617       CMD_SUDO_EXEC_USER <username>
618           Specify the user (via “sudo -u <user>”) that will execute a command
619           contained within a SPA packet. If this variable is not given,
620           fwknopd will assume the command should be executed as root.
621
622       CMD_EXEC_GROUP <groupname>
623           Specify the group (via setgid) that will execute a command
624           contained within a SPA packet. If this variable is not given,
625           fwknopd will execute the command as the user it is running as (most
626           likely root). Setting this to a non-root user such as “nobody” is
627           highly recommended if elevated permissions are not needed.
628
629       CMD_SUDO_EXEC_GROUP <groupname>
630           Specify the group (via “sudo -g <group>”) that will execute a
631           command contained within a SPA packet. If this variable is not
632           given, fwknopd will assume the command should be executed as root.
633
634       CMD_CYCLE_OPEN <command>
635           Specify a command open/close cycle to be executed upon receipt of a
636           valid SPA packet. This directive sets the initial command, and is
637           meant to be used in conjunction with the “CMD_CYCLE_CLOSE” variable
638           below. The main application of this feature is to allow fwknopd to
639           interact with firewall or ACL’s that are not natively supported,
640           and facilitate the same access model as for the main supported
641           firewalls such as iptables. That is, a command is executed to open
642           the firewall or ACL, and then a corresponding close command is
643           executed after a timer expires. Both the “CMD_CYCLE_OPEN” and
644           “CMD_CYCLE_CLOSE” variables support special substitution strings to
645           allow values to be taken from the SPA payload and used on the
646           command line of the executed command. These strings begin with a
647           “$” character, and include “$IP” (the allow IP decrypted from the
648           SPA payload), “$SRC” (synonym for “$IP”) , “$PKT_SRC” (the source
649           IP in the network layer header of the SPA packet), “$DST” (the
650           destination IP), “$PORT” (the allow port), and “$PROTO” (the allow
651           protocol), “$TIMEOUT” (set the client timeout if specified).
652
653       CMD_CYCLE_CLOSE <command>
654           Specify the close command that corresponds to the open command set
655           by the “CMD_CYCLE_OPEN” variable described above. The same string
656           substitutions such as “$IP”, “$PORT”, and “$PROTO” are supported.
657           In addition, the special value “NONE” can be set to allow no close
658           command to be executed after the open command. This might be handy
659           in certain situations where, say, indefinite access is desired and
660           allowed.
661
662       CMD_CYCLE_TIMER <seconds>
663           Set the number of seconds after which the close command set in
664           “CMD_CYCLE_CLOSE” will be executed. This defines the open/close
665           timer interval.
666
667       SUDO_EXE <path>
668           Define the path to the sudo binary. Default is “/usr/bin/sudo”.
669
670       REQUIRE_USERNAME <username>
671           Require a specific username from the client system as encoded in
672           the SPA data. This variable is optional and if not specified, the
673           username data in the SPA data is ignored.
674
675       REQUIRE_SOURCE_ADDRESS <Y/N>
676           Force all SPA packets to contain a real IP address within the
677           encrypted data. This makes it impossible to use the -s command line
678           argument on the fwknop client command line, so either -R has to be
679           used to automatically resolve the external address (if the client
680           behind a NAT) or the client must know the external IP and set it
681           via the -a argument.
682
683       REQUIRE_SOURCE_ADDRESS <Y/N>
684           Synonym for “REQUIRE_SOURCE_ADDRESS”.
685
686       FORCE_NAT <IP> <PORT>
687           For any valid SPA packet, force the requested connection to be
688           NAT’d through to the specified (usually internal) IP and port
689           value. This is useful if there are multiple internal systems
690           running a service such as SSHD, and you want to give transparent
691           access to only one internal system for each stanza in the
692           access.conf file. This way, multiple external users can each
693           directly access only one internal system per SPA key.
694
695       FORCE_SNAT <IP>
696           For any valid SPA packet, add an SNAT rule in addition to any DNAT
697           rule created with a corresponding (required) FORCE_NAT variable.
698           This is analogous to “SNAT_TRANSLATE_IP” from the
699           /etc/fwknop/fwknopd.conf file except that it is per access stanza
700           and overrides any value set with “SNAT_TRANSLATE_IP”. This is
701           useful for situations where an incoming NAT’d connection may be
702           otherwise unanswerable due to routing constraints (i.e. the system
703           receiving the SPA authenticated connection has a default route to a
704           different device than the SPA system itself).
705
706       FORCE_MASQUERADE <Y/N>
707           This is similar to the “FORCE_SNAT” variable, except that it is not
708           necessary to also specify an IP address for SNAT rules because the
709           MASQUERADE target is used instead.
710
711       FORWARD_ALL <Y/N>
712           In NAT scenarios, control whether all traffic is forwarded through
713           the fwknopd system as opposed to just forwarding connections to
714           specific services as requested by the fwknop client.
715
716       DISABLE_DNAT <Y/N>
717           Control whether DNAT rules are created in FORCE_NAT scenarios. This
718           is mainly used in conjunction with the FORWARD_ALL variable to
719           allow fwknopd to act essentially as an SPA gateway. I.e., the
720           fwknop client is used to gain access via SPA to the broader
721           Internet after being granted an IP via DHCP, but prior to sending
722           the SPA packet all traffic is blocked by default to the Internet.
723
724       GPG_DECRYPT_ID <keyID>
725           Define a GnuPG key ID to use for decrypting SPA messages that have
726           been encrypted by an fwknop client. This keyword is required for
727           authentication that is based on GPG keys. The GPG key ring on the
728           client must have imported and signed the fwknopd server key, and
729           vice versa. It is ok to use a sensitive personal GPG key on the
730           client, but each fwknopd server should have its own GPG key that is
731           generated specifically for fwknop communications. The reason for
732           this is that the decryption password for the server key must be
733           placed within the /etc/fwknop/access.conf file for fwknopd to
734           function (it has to be able to decrypt SPA messages that have been
735           encrypted with the server’s public key). For more information on
736           using fwknop with GnuPG keys, see the following link:
737http://www.cipherdyne.org/fwknop/docs/gpghowto.html”.
738
739       GPG_DECRYPT_PW <decrypt password>
740           Specify the decryption password for the gpg key defined by the
741           “GPG_DECRYPT_ID” above. This is a required field for gpg-based
742           authentication.
743
744       GPG_ALLOW_NO_PW <Y/N>
745           Allow fwknopd to leverage a GnuPG key pair that does not have an
746           associated password. While this may sound like a controversial
747           deployment mode, in automated environments it makes sense because
748           "there is usually no way to store a password more securely than on
749           the secret keyring itself" according to:
750http://www.gnupg.org/faq/GnuPG-FAQ.html#how-can-i-use-gnupg-in-an-automated-environment”.
751           Using this feature and removing the passphrase from a GnuPG key
752           pair is useful in some environments where libgpgme is forced to use
753           gpg-agent and/or pinentry to collect a passphrase.
754
755       GPG_REQUIRE_SIG <Y/N>
756           With this setting set to Y, fwknopd check all GPG-encrypted SPA
757           messages for a signature (signed by the sender’s key). If the
758           incoming message is not signed, the decryption process will fail.
759           If not set, the default is Y.
760
761       GPG_DISABLE_SIG <Y/N>
762           Disable signature verification for incoming SPA messages. This is
763           not a recommended setting, and the default is N.
764
765       GPG_IGNORE_SIG_VERIFY_ERROR <Y/N>
766           Setting this will allow fwknopd to accept incoming GPG-encrypted
767           packets that are signed, but the signature did not pass
768           verification (i.e. the signer key was expired, etc.). This setting
769           only applies if the GPG_REQUIRE_SIG is also set to Y.
770
771       GPG_REMOTE_ID <keyID,...,keyID>
772           Define a list of gpg key ID’s that are required to have signed any
773           incoming SPA message that has been encrypted with the fwknopd
774           server key. This ensures that the verification of the remote user
775           is accomplished via a strong cryptographic mechanism. Signature
776           verification is enabled by default, and can only be disabled if
777           “GPG_DISABLE_SIG” is set to Y (not a recommended setting). Separate
778           multiple entries with a comma.
779
780       GPG_FINGERPRINT_ID <keyID,...,keyID>
781           Specify a set of full-length GnuPG key fingerprints instead of the
782           shorter key identifiers set with the “GPG_REMOTE_ID” variable. Here
783           is an example fingerprint for one of the fwknop test suite keys:
784           00CC95F05BC146B6AC4038C9E36F443C6A3FAD56.
785
786       GPG_HOME_DIR <path>
787           Define the path to the GnuPG directory to be used by the fwknopd
788           server. If this keyword is not specified within
789           /etc/fwknop/access.conf then fwknopd will default to using the
790           /root/.gnupg directory for the server key(s) for incoming SPA
791           packets handled by the matching access.conf stanza.
792
793       GPG_EXE <path>
794           Define the path to the GnuPG executable. If this keyword is not
795           specified within /etc/fwknop/access.conf then fwknopd will default
796           to using /usr/bin/gpg.
797

FILES

799       /etc/fwknop/fwknopd.conf
800           The main configuration file for fwknop.
801
802       /etc/fwknop/access.conf
803           Defines all knock sequences and access control directives.
804

DEPENDENCIES

806       fwknopd requires libfko which is normally included with both source and
807       binary distributions, and is a dedicated library developed by the
808       fwknop project.
809
810       For packet sniffing, fwknopd currently requires libpcap, but future
811       versions will (optionally) remove this as a dependency.
812
813       For GPG functionality, GnuPG must also be correctly installed and
814       configured along with the libgpgme library.
815
816       To take advantage of all of the authentication and access management
817       features of the fwknopd daemon/service a functioning iptables, ipfw, or
818       pf firewall is required on the underlying operating system.
819

DIAGNOSTICS

821       fwknopd can be run in debug mode by combining the -f, --foreground and
822       the -v, --verbose command line options. This will disable daemon mode
823       execution, and print verbose information to the screen on stderr as
824       packets are received.
825
826       The most comprehensive way to gain diagnostic information on fwknopd is
827       to run the test suite test-fwknop.pl script located in the test/
828       directory in the fwknop sources. The test suite runs sends fwknop
829       through a large number of run time tests, has valgrind support,
830       validates both SPA encryption and HMAC results against OpenSSL, and
831       even has its own built in fuzzer for SPA communications.
832

SEE ALSO

834       fwknopd(8), iptables(8), pf(4), pfctl(8), ipfw(8), gpg(1), libfko
835       documentation.
836
837       More information on Single Packet Authorization can be found in the
838       paper “Single Packet Authorization with fwknop” available at
839       http://www.cipherdyne.org/fwknop/docs/SPA.html. A comprehensive
840       tutorial on fwknop operations and theory can be found at
841       http://www.cipherdyne.org/fwknop/docs/fwknop-tutorial.html. This
842       tutorial also includes information about the design of fwknop that may
843       be worth reading for those interested in why fwknop is different from
844       other SPA implementations.
845
846       fwknop uses the git versioning system as its source code repository
847       along with Github for tracking of issues and milestones:
848
849               $ git clone https://github.com/mrash/fwknop.git fwknop.git
850
851       Additional commentary on Single Packet Authorization can be found via
852       Michael Rash’s Twitter feed: http://twitter.com/michaelrash,
853       @michaelrash
854

AUTHORS

856       The primary developers of fwknop are Michael Rash (project creator)
857       <mbr@cipherdyne.org>, Damien Stuart <dstuart@dstuart.org>, and Jonathan
858       Bennett <jbennett@incomsystems.biz>.
859

CONTRIBUTORS

861       This “C” version of fwknop was derived from the original Perl-based
862       version on which many people who are active in the open source
863       community have contributed. See the CREDITS file in the fwknop sources,
864       or visit https://github.com/mrash/fwknop/blob/master/CREDITS to view
865       the online list of contributors. A few contributors deserve to be
866       singled out including: Franck Joncourt, Max Kastanas, Vlad Glagolev,
867       Sean Greven, Hank Leininger, Fernando Arnaboldi, and Erik Gomez.
868
869       The phrase “Single Packet Authorization” was coined by MadHat and
870       Simple Nomad at the BlackHat Briefings of 2005.
871

BUGS

873       Send bug reports to dstuart@dstuart.org or mbr@cipherdyne.org, or open
874       a new issue on Github (see https://github.com/mrash/fwknop.git).
875       Suggestions and/or comments are always welcome as well. Additional
876       information may be found in the fwknop mailing list archives (see:
877       https://lists.sourceforge.net/lists/listinfo/fwknop-discuss).
878

DISTRIBUTION

880       fwknopd is distributed under the GNU General Public License (GPL v2+),
881       and the latest version may be downloaded from
882       http://www.cipherdyne.org.
883
884
885
886Fwknop Server                     08/06/2018                        FWKNOPD(8)
Impressum