1FWKNOPD(8) Fwknop Server FWKNOPD(8)
2
6 fwknopd - Firewall Knock Operator Daemon
7
9 fwknopd [options]
10
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 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 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 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
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 -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 --fw-list
48 List only firewall rules that any running fwknopd daemon has
49 created and then exit.
50 -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 --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 -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 -C, --packet-limit=<n>
67 Specify the number of candidate SPA packets to process and exit
68 when this limit is reached.
69 -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 -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 --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 --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 -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 --fw-list-all
106 List all firewall rules including those that have nothing to do
107 with fwknopd.
108 --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 -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 --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 --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 -l, --locale=<locale>
131 Set/override the system default locale setting.
132 --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 -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 --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 --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 --key-len=<length>
158 Specify the number of bytes for a generated Rijndael key. The
159 maximum size is currently 128 bytes.
160 --hmac-key-len=<length>
162 Specify the number of bytes for a generated HMAC key. The maximum
163 size is currently 128 bytes.
164 -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 -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 --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 --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 -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 --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 -r, --run-dir=<path>
207 Specify the directory where fwknopd writes run time state files.
208 The default is /var.
209 -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 --syslog-enable
216 Allow messages to be sent to syslog even if the foreground mode is
217 set.
218 -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 -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 -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 -h, --help
238 Display usage information and exit.
239 -V, --Version
241 Display version information and exit.
242
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 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 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 PCAP_INTF <interface>
262 Specify the ethernet interface on which fwknopd will sniff packets.
263 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 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 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 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 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 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 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 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 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 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 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 MAX_SNIFF_BYTES <bytes>
344 Specify the the maximum number of bytes to sniff per frame. 1500 is
345 the default.
346 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 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 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 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 ENABLE_NAT_DNS <Y/N>
372 Allow fwknopd to resolve hostnames in NAT access messages.
373 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 GPG_EXE <path>
383 Specify the path to GPG, and defaults to /usr/bin/gpg if not set.
384 LOCALE <locale>
386 Set the locale (via the LC_ALL variable). This can be set to
387 override the default system locale.
388 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 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 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 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 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 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 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 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 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 SYSLOG_IDENTITY <identity>
458 Override syslog identity on message logged by fwknopd. The defaults
459 are usually ok.
460 SYSLOG_FACILITY <facility>
462 Override syslog facility. The “SYSLOG_FACILITY” variable can be set
463 to
464 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 FWKNOP_RUN_DIR <path>
476 Specify the directory where fwknopd writes run time state files.
477 The default is /var.
478 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 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 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 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 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 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 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 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 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 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 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 %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 %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 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 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 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 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 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 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 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 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 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 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 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 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 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 SUDO_EXE <path>
668 Define the path to the sudo binary. Default is “/usr/bin/sudo”.
669 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 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 REQUIRE_SOURCE_ADDRESS <Y/N>
684 Synonym for “REQUIRE_SOURCE_ADDRESS”.
685 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 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 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 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 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 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:
737 “http://www.cipherdyne.org/fwknop/docs/gpghowto.html”.
738 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 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:
750 “http://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 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 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 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 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 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 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 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
799 /etc/fwknop/fwknopd.conf
800 The main configuration file for fwknop.
801 /etc/fwknop/access.conf
803 Defines all knock sequences and access control directives.
804
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 For packet sniffing, fwknopd currently requires libpcap, but future
811 versions will (optionally) remove this as a dependency.
812 For GPG functionality, GnuPG must also be correctly installed and
814 configured along with the libgpgme library.
815 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
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 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
834 fwknopd(8), iptables(8), pf(4), pfctl(8), ipfw(8), gpg(1), libfko
835 documentation.
836 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 fwknop uses the git versioning system as its source code repository
847 along with Github for tracking of issues and milestones:
848 $ git clone https://github.com/mrash/fwknop.git fwknop.git
850 Additional commentary on Single Packet Authorization can be found via
852 Michael Rash’s Twitter feed: http://twitter.com/michaelrash,
853 @michaelrash
854
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
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 The phrase “Single Packet Authorization” was coined by MadHat and
870 Simple Nomad at the BlackHat Briefings of 2005.
871
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
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.
883Fwknop Server 08/06/2018 FWKNOPD(8)