2 #############################################################################
4 # [+] fwknop - Firewall Knock Operator [+]
6 # This is the configuration file for fwknop, the Firewall Knock Operator.
7 # The primary authentication and authorization mechanism offered by fwknop
8 # is known as Single Packet Authorization (SPA). More information about
9 # SPA can be found at: http://www.cipherdyne.org/fwknop/docs/SPA.html
11 # Note there are no access control directives in this file. All access
12 # control directives are located in the file
13 # /etc/fwknop/access.conf. You will need to edit the access.conf file in
14 # order for fwknop to function correctly.
16 #############################################################################
18 # $Id: fwknop.conf 1517 2009-08-10 04:09:06Z mbr $
21 ### Supports multiple email addresses (as a comma separated
23 EMAIL_ADDRESSES root@localhost;
28 ### Define the firewall type. The default is "iptables" for Linux systems,
29 ### but this can be set to "ipfw" for *BSD systems. Also supported is
30 ### "external_cmd" to allow fwknop to invoke an external command instead of
31 ### interfacing with the firewall at all
32 FIREWALL_TYPE iptables;
34 ### This defines the general strategy fwknop uses to authenticate remote
35 ### clients. Possible values are "PCAP" (authenticate via regular pcap; this
36 ### is the default and puts the interface in promiscuous mode unless
37 ### ENABLE_PCAP_PROMISC is turned off) FILE_PCAP (authenticate via a pcap file
38 ### that is built by a sniffer), ULOG_PCAP (authenticate via the ulogd pcap
39 ### writer). This variable can also be set to "KNOCK" if you really want to
40 ### use the legacy port knocking mode.
43 ### Define the ethernet interface on which we will sniff packets. Note
44 ### that this is only used if the AUTH_MODE keyword above is set to
48 ### Define whether put the pcap interface in promiscuous mode.
49 ENABLE_PCAP_PROMISC Y;
51 ### Define the filter used for PCAP modes; we default to udp port 62201.
52 ### However, if an fwknop client uses the --rand-port option to send the
53 ### SPA packet over a random port, then this variable should be updated to
54 ### something like "udp dst portrange 10000-65535";
55 PCAP_FILTER udp port 62201;
57 ### This instructs fwknopd to not honor SPA packets that have an old time
58 ### stamp. The value for "old" is defined by the MAX_SPA_PACKET_AGE variable.
59 ### If ENABLE_SPA_PACKET_AGING is set to "N", fwknopd will not use the client
60 ### time stamp at all.
61 ENABLE_SPA_PACKET_AGING Y;
63 ### Defines the maximum age (in seconds) that an SPA packet will be accepted.
64 ### This requires that the client system is in relatively close time
65 ### synchronization with the fwknopd server system (NTP is good). The default
66 ### age is two minutes.
67 MAX_SPA_PACKET_AGE 120;
69 ### Track digest sums associated with previous fwknop process. This allows
70 ### digest sums to remain persistent across executions of fwknop.
71 ENABLE_DIGEST_PERSISTENCE Y;
73 ### Default to using all three of SHA256, SHA1, and MD5 for SPA replay attack
74 ### detection. This is overkill, but performance is not usually a concern.
75 ### Further, the variable can also be set to "SHA1" or "MD5".
78 ### This variable controls whether fwknopd includes the source IP of each SPA
79 ### packet in the DIGEST store. If a replayed SPA message is detected, then
80 ### having this information can provide information about which networks have
81 ### people sniffing your SPA packets.
82 ENABLE_DIGEST_INCLUDE_SRC Y;
84 ### Allow SPA clients to request access to services through an iptables
85 ### firewall instead of just to it (i.e. access through the FWKNOP_FORWARD
86 ### chain instead of the INPUT chain). This also requires the
87 ### ENABLE_FORWARD_ACCESS variable to be set in the access.conf file for the
88 ### specific SOURCE stanzas that should be allowed for forwarding access.
89 ENABLE_IPT_FORWARDING N;
91 ### Allow SPA clients to request access to a local socket via NAT. This still
92 ### puts an ACCEPT rule into the FWKNOP_INPUT chain, but a different port is
93 ### translated via DNAT rules to the real one. So, the user would do
94 ### "ssh -p <port>" to access the local service (see the --NAT-local and
95 ### --NAT-rand-port on the fwknop client command line).
96 ENABLE_IPT_LOCAL_NAT Y;
98 ### By default, if forwarding access is enabled (see the ENABLE_IPT_FORWARDING
99 ### variable above), then fwknop creates DNAT rules for incoming connections,
100 ### but does not also complement these rules with SNAT rules at the same time.
101 ### In some situations, internal systems may not have a route back out for the
102 ### source address of the incoming connection, so it is necessary to also
103 ### apply SNAT rules so that the internal systems see the IP of the internal
104 ### interface where fwknopd is running. This functionality is only enabled
105 ### when ENABLE_IPT_SNAT is set to "Y", and by default SNAT rules are built
106 ### with the MASQUERADE target (since then the internal IP does not have to be
107 ### defined here in the fwknop.conf file), but if you want fwknopd to use the
108 ### SNAT target then also defined an IP address with the SNAT_TRANSLATE_IP
111 SNAT_TRANSLATE_IP _CHANGEME_;
113 ### If ENABLE_IPT_FORWARDING is enabled, but the /proc/sys/net/ipv4/ip_forward
114 ### disables forwarding, then by default enable forwarding
115 ENABLE_PROC_IP_FORWARD Y;
117 ### Add ACCEPT rules to the FWKNOP_OUTPUT chain. This is usually only useful
118 ### if there are no state tracking rules to allow connection responses out and
119 ### the OUTPUT chain has a default-drop stance.
122 ### Force all SPA packets to contain a real IP address within the encrypted
123 ### data. This makes it impossible to use the -s command line argument on
124 ### the fwknop client command line, so either -R has to be used to
125 ### automatically resolve the external address (if the client behind a NAT) or
126 ### the client must know the external IP.
127 REQUIRE_SOURCE_ADDRESS N;
129 ### Config variable to force fwknopd to always treat the sniffing interface as
130 ### the "cooked" interface type on Linux.
131 ENABLE_COOKED_INTF N;
133 ### This pair of variables controls whether fwknopd voluntarily exits and over
134 ### what time interval. When fwknopd exits, knopwatchd will restart it.
135 ### Because fwknop controls the accessibility of services, this feature can be
136 ### used to make sure that the fwknop rules are flushed (see the
137 ### FLUSH_IPT_AT_INIT variable), and the effects of any potential logic (or
138 ### other) bugs are minimized since fwknopd will start "fresh" when knopwatchd
139 ### kicks it off. NOTE: This feature is almost never required since fwknopd is
140 ### generally quite stable, and is mostly offered for the extra paranoid.
141 ENABLE_VOLUNTARY_EXITS N;
142 EXIT_INTERVAL 1440; ### minutes (1 day)
144 ### These variables control whether special checks are run against the
145 ### interface that fwknopd sniffs to acquire SPA packets. The basic strategy
146 ### is for the knoptm daemon to make sure that the sniffing interface exists
147 ### is in the "RUNNING" state, and always has increasing numbers of received
148 ### and transmitted bytes (Linux only). If not then knoptm stops fwknopd once
149 ### the error condition has been cleared (and not before, since fwknopd cannot
150 ### receive packets anyway until then). Then, knopwatchd will restart fwknopd
151 ### so that it can once again receive SPA packets from the interface. The
152 ### typical example for where this become important is when fwknopd has been
153 ### deployed against a ppp interface that is shut down and then restarted.
154 ### Note that usually the RUNNING check is not needed because fwknopd can once
155 ### again receive packet data if the interface is brought back into the RUNNING
156 ### state, but there is little harm in enabling it by default. Another check
157 ### that is enabled by default is to ensure that the number of bytes received
158 ### and transmitted does not decrease.
159 ENABLE_INTF_CHECKS Y;
160 INTF_CHECKS_INTERVAL 20; ### seconds
161 ENABLE_INTF_EXISTS_CHECK Y;
162 ENABLE_INTF_RUNNING_CHECK Y; ### looks for the string "RUNNING"
163 ENABLE_INTF_BYTES_CHECK Y; ### checks for resets in bytes RX/TX counters
165 ### If this feature is enabled, then knoptm will not time out any rules added
166 ### by fwknopd if any connection is in the ESTBALISHED state involving the IP
167 ### that was granted access and a destination port that is specified by the
168 ### CONNTRACK_ESTAB_PORTS variable (which supports comma-separated lists of
170 ENABLE_CONNTRACK_PERSIST N;
171 CONNTRACK_ESTAB_PORTS 0; ### can be "80, 6997, 22", etc.
172 IPT_CONNTRACK_FILE /proc/net/ip_conntrack;
174 ### Specify the the maximum number of bytes to sniff per frame - 1500
175 ### is a good default
176 MAX_SNIFF_BYTES 1500;
178 ### Flush all existing rules in the fwknop chains at fwknop start time.
181 ### If running on ipfw firewalls, this variable defines the rule number that
182 ### fwknopd uses to insert an ipfw pass rule.
185 ### If running on ipfw firewalls, this variable defines the rule set that will
186 ### be used to store expired rules that still have a dynamic rule associated
187 ### to them. That set will be disabled by fwknop and should not be enabled
188 ### while fwknop is running. Not used when ipfw isn't using dynamic rules.
191 ### For ipfw firewalls set the interval (in seconds) over which rules that
192 ### have no remaining dynamic rules associated with them will be removed.
193 IPFW_DYNAMIC_INTERVAL 60; ### seconds
195 ### Define the timeout for running a command
198 ### If GPG keys are used instead of a Rijndael symmetric key, this is
199 ### the default GPG keys directory. Note that each access block in
200 ### /etc/fwknop/access.conf can specify its own GPG directory to override
202 GPG_DEFAULT_HOME_DIR /root/.gnupg;
204 ### This gets used if AUTH_MODE is set to "FILE_PCAP". This file must
205 ### be created by a sniffer process (or something like the ulogd pcap
207 PCAP_PKT_FILE /var/log/sniff.pcap;
209 ### By default fwknopd tests to see if the FKO module has been installed, and
210 ### if so all SPA operations are performed via FKO functions. If this
211 ### variable is set to "N", then fwknopd will fall back to the original perl
212 ### SPA implementation. It is recommended to leave this as "Y" and install
213 ### the libfko library and associated FKO perl module.
216 ### Define a comma-separated set of IP addresses and/or networks that should
217 ### be globally blacklisted. That is, any SPA packet that is from a source
218 ### IP (or has an internal --allow-ip) within a blacklisted network will be
222 ### Defines interval fwknop will use to check for more iptables
223 ### messages (this is only used in the legacy port knocking mode).
224 SLEEP_INTERVAL 2; ### seconds
226 ### TTL values are decremented depending on the number of hops the packet
227 ### has taken before it hits the firewall. We will assume packets will not
228 ### jump through more than 20 hops on average.
231 ### Allow fwknopd to acquire SPA data from HTTP requests (generated with the
232 ### fwknop client in --HTTP mode). Note that the PCAP_FILTER variable would
233 ### need to be updated when this is enabled to sniff traffic over TCP/80
235 ENABLE_SPA_OVER_HTTP N;
237 ### Note that fwknopd still only gets its data via pcap (unless AUTH_MODE is
238 ### set to 'SOCKET'), so the filter defined by PCAP_FILTER needs to be updated
239 ### to include the tcp or udp port if either of these variables are enabled.
243 ### Set the default port number for a "dummy" tcp or udp server (udp is
244 ### best to use since nothing will be sent back to the client, so as far as a
245 ### scanner can tell the port is 'filtered'). The server is only spawned when
246 ### ENABLE_TCP_SERVER or ENABLE_UDP_SERVER is set to "Y".
250 ### Set the locale (via the LC_ALL variable). This can be set to NONE to
251 ### have fwknopd honor the default system locale.
254 ### Set the type of syslog daemon that is used. The SYSLOG_DAEMON variable
255 ### accepts three possible values: syslogd, syslog-ng, or metalog.
256 SYSLOG_DAEMON syslogd;
258 ### syslog facility and priority (the defaults are usually ok)
259 ### The SYSLOG_FACILITY variable can be set to one of LOG_LOCAL{0-7}, and
260 ### SYSLOG_PRIORITY can be set to one of LOG_INFO, LOG_DEBUG, LOG_NOTICE,
261 ### LOG_WARNING, LOG_ERR, LOG_CRIT, LOG_ALERT, or LOG_EMERG
262 SYSLOG_IDENTITY fwknopd;
263 SYSLOG_FACILITY LOG_LOCAL7;
264 SYSLOG_PRIORITY LOG_INFO;
266 ### syslog config for knoptm
267 KNOPTM_SYSLOG_IDENTITY fwknop(knoptm);
268 KNOPTM_SYSLOG_FACILITY LOG_LOCAL7;
269 KNOPTM_SYSLOG_PRIORITY LOG_INFO;
271 ### syslog config for fwknop_serv
272 FWSERV_SYSLOG_IDENTITY fwknop(fwknop_serv);
273 FWSERV_SYSLOG_FACILITY LOG_LOCAL7;
274 FWSERV_SYSLOG_PRIORITY LOG_INFO;
276 ### Allow reporting methods to be enabled/restricted. This keyword can
277 ### accept values of "nosyslog" (don't write any messages to syslog),
278 ### "noemail" (don't send any email messages), or "ALL" (to generate both
279 ### syslog and email messages). "ALL" is the default. Both "nosyslog"
280 ### and "noemail" can be combined with a comma to disable all logging
282 ALERTING_METHODS ALL;
284 ### (Legacy port knocking mode)
285 ### The following variable can be modified to look for logging messages
286 ### that are specific to your firewall configuration (specified by the
287 ### "--log-prefix" for iptables firewalls). For example, if your firewall
288 ### uses the string "Audit" for packets that have been blocked, then you
289 ### could set FW_MSG_SEARCH = "Audit";
292 ### (Legacy port knocking mode)
293 ### This variable controls whether fwknopd parses the /var/log/messages
294 ### file for port knock sequences, or if it assumes that the local syslog
295 ### daemon has been configured to write iptables log messages to the
296 ### fwknopfifo named pipe
297 ENABLE_SYSLOG_FILE Y;
298 IPT_SYSLOG_FILE /var/log/messages;
300 ### This variable defines the number of seconds that the IPTables::ChainMgr
301 ### module should wait for running iptables commands. Normally iptables
302 ### runs extremely fast from the command line (at least for the commands
303 ### that fwknopd executes), so the default of 30 seconds is plenty.
306 ### Set the strategy that the IPTables::ChainMgr module will use for executing
307 ### iptables commands. The default of "waitpid" means that IPTables::ChainMgr
308 ### will use fork(), exec(), and waitpid(), whereas "system" means that
309 ### "system()" will used, and finally "popen" means that iptables will be
310 ### executed via popen().
311 IPT_EXEC_STYLE waitpid;
313 ### Define the number of seconds that the IPTables::ChainMgr policy uses to
314 ### sleep between successive iptables commands. Zero is the default.
317 ### Define the number of times that fwknopd or knoptm will run certain
318 ### critical iptables commands (such as adding a new access rule) if any
319 ### problems are encountered.
322 ### The following four variables control whether a global set of "open" and
323 ### "close" commands are executed after receving a valid SPA packet. These
324 ### variables are used only if FIREWALL_TYPE is set to "external_cmd", but
325 ### the same variables can also exist within the access.conf file so that
326 ### mixed deployments are possible - that is, some SPA packets will operate
327 ### as usual and result in firewall commands being executed, but others will
328 ### result in the commands defined by these variables (in access.conf) being
330 ### The "open" and "close" commands might be manually supplied firewall
331 ### commands, and both support variable substitution of any of the variables
332 ### in the access.conf file with "$VAR". Also, three special variables are
333 ### supported: $SRC, $PORT, and $PROTO, which are derived from actual values
334 ### from within valid SPA packets (as opposed to $SOURCE from access.conf
335 ### which may contain a list of networks instead of a single IP address).
336 ### Here are some examples:
337 ### - Execute a specific iptables command on behalf of the source IP
338 ### in a valid SPA packet to add a new ACCEPT rule, and execute
339 ### another command (to delete the same rule after a timeout):
340 ### EXTERNAL_CMD_OPEN iptables -A INPUT -s $SRC -j ACCEPT
341 ### EXTERNAL_CMD_CLOSE iptables -D INPUT -s $SRC -j ACCEPT
342 ### - Execute a custom binary with the SOURCE and OPEN_PORTS variables
343 ### from the access.conf file as input on the command line, and after
344 ### a timeout execute a different program but use the real SPA source
346 ### EXTERNAL_CMD_OPEN /path/someprog $SOURCE $OPEN_PORTS
347 ### EXTERNAL_CMD_OPEN /path/otherprog $SRC
348 ENABLE_EXTERNAL_CMDS N;
349 EXTERNAL_CMD_OPEN __NONE__;
350 EXTERNAL_CMD_CLOSE __NONE__;
351 EXTERNAL_CMD_ALARM 30;
353 ### if EXTERNAL_CMD_OPEN is used above, then the following two variables can
354 ### be used to enforce a prefix on variable substitutions - useful if there
355 ### are any naming conflicts with the external script and command line
356 ### arguments that are named the same as the variables to be substituted.
357 ENABLE_EXT_CMD_PREFIX N;
358 EXT_CMD_PREFIX FWKNOP_;
361 KNOPWATCHD_CHECK_INTERVAL 5; ### seconds
362 KNOPWATCHD_MAX_RETRIES 10;
364 ### Default minimum for any SPA packet (including both the data link,
365 ### network, and transport layer headers)
368 ### Default minimum message size SPA messages encrypted with GnuPG. The
369 ### fwknopd daemon will not attempt to decrypt any packet with gpg that is not
370 ### at least as large as this value.
371 MIN_GNUPG_MSG_SIZE 400;
373 ### fwknop uses the IPTables::ChainMgr module to add allow rules to a
374 ### custom iptables chain "FWKNOP_INPUT". This chain is called from
375 ### the INPUT chain, and by default no other iptables chains are used.
376 ### However, additional chains can be added (say, if access needs to
377 ### be allowed through the local system via the FORWARD chain) by
378 ### altering the IPT_FORWARD_ACCESS variable below. For a discussion of
379 ### the format followed by these keywords, read on:
380 ### Specify chain names to which iptables blocking rules will be
381 ### added with the IPT_INPUT_ACCESS and IPT_FORWARD_ACCESS keyword.
382 ### The format for these variables is:
383 ### <Target>,<Direction>,<Table>,<From_chain>,<Jump_rule_position>, \
384 ### <To_chain>,<Rule_position>.
385 ### "Target": Can be any legitimate iptables target, but should usually
387 ### "Direction": Can be "src", "dst", or "both", which correspond to the
388 ### INPUT, OUTPUT, and FORWARD chains.
389 ### "Table": Can be any iptables table, but the default is "filter".
390 ### "From_chain": Is the chain from which packets will be jumped.
391 ### "Jump_rule_position": Defines the position within the From_chain where
392 ### the jump rule is added.
393 ### "To_chain": Is the chain to which packets will be jumped. This is the
394 ### main chain where fwknop rules are added.
395 ### "Rule_position": Defines the position where rule are added within the
397 IPT_INPUT_ACCESS ACCEPT, src, filter, INPUT, 1, FWKNOP_INPUT, 1;
398 ### The IPT_OUTPUT_ACCESS variable is only used if ENABLE_IPT_OUTPUT is enabled
399 IPT_OUTPUT_ACCESS ACCEPT, dst, filter, OUTPUT, 1, FWKNOP_OUTPUT, 1;
400 ### The IPT_FORWARD_ACCESS variable is only used if ENABLE_IPT_FORWARDING is enabled
401 IPT_FORWARD_ACCESS ACCEPT, src, filter, FORWARD, 1, FWKNOP_FORWARD, 1;
402 IPT_DNAT_ACCESS DNAT, src, nat, PREROUTING, 1, FWKNOP_PREROUTING, 1;
403 ### The IPT_SNAT_ACCESS variable is not used unless both ENABLE_IPT_SNAT and
404 ### ENABLE_IPT_FORWARDING are enabled. Also, the external static IP must be
405 ### set with the SNAT_TRANSLATE_IP variable. The default is to use the
406 ### IPT_MASQUERADE_ACCESS variable.
407 IPT_SNAT_ACCESS SNAT, src, nat, POSTROUTING, 1, FWKNOP_POSTROUTING, 1;
408 IPT_MASQUERADE_ACCESS MASQUERADE, src, nat, POSTROUTING, 1, FWKNOP_POSTROUTING, 1;
411 FWKNOP_DIR /var/log/fwknop;
412 FWKNOP_RUN_DIR /var/run/fwknop;
413 FWKNOP_LIB_DIR /var/lib/fwknop; # for legacy port knocking mode
414 FWKNOP_MOD_DIR /usr/lib/fwknop;
415 FWKNOP_CONF_DIR /etc/fwknop;
416 FWKNOP_ERR_DIR $FWKNOP_DIR/errs;
419 FW_DATA_FILE $FWKNOP_DIR/fwdata; # legacy port knocking mode
420 ACCESS_CONF $FWKNOP_CONF_DIR/access.conf;
421 P0F_FILE $FWKNOP_CONF_DIR/pf.os; ### p0f-based fingerprints
422 DIGEST_FILE $FWKNOP_DIR/digest.cache;
423 FWKNOP_PID_FILE $FWKNOP_RUN_DIR/fwknopd.pid;
424 FWKNOP_CMDLINE_FILE $FWKNOP_RUN_DIR/fwknopd.cmd;
425 TCPSERV_PID_FILE $FWKNOP_RUN_DIR/fwknop_serv.pid;
426 KNOPWATCHD_PID_FILE $FWKNOP_RUN_DIR/knopwatchd.pid;
427 KNOPMD_PID_FILE $FWKNOP_RUN_DIR/knopmd.pid;
428 KNOPTM_PID_FILE $FWKNOP_RUN_DIR/knoptm.pid;
429 KNOPTM_IP_TIMEOUT_SOCK $FWKNOP_RUN_DIR/knoptm_ip_timeout.sock;
430 FWKNOP_SERV_SOCK $FWKNOP_RUN_DIR/fwknop_serv.sock;
431 KNOPMD_FIFO $FWKNOP_LIB_DIR/fwknopfifo;
432 PROC_IP_FORWARD_FILE /proc/sys/net/ipv4/ip_forward;
434 ### iptables command output and error collection files; these are
435 ### used by IPTables::ChainMgr
436 IPT_OUTPUT_FILE $FWKNOP_DIR/fwknopd.iptout;
437 IPT_ERROR_FILE $FWKNOP_DIR/fwknopd.ipterr;
438 KNOPTM_IPT_OUTPUT_FILE $FWKNOP_DIR/knoptm.iptout;
439 KNOPTM_IPT_ERROR_FILE $FWKNOP_DIR/knoptm.ipterr;
444 sendmailCmd /usr/sbin/sendmail;
446 ifconfigCmd /sbin/ifconfig;
448 iptablesCmd /sbin/iptables;
449 ipfwCmd /sbin/ipfw; ### BSD and Mac OS X only
450 fwknopdCmd /usr/sbin/fwknopd;
451 fwknop_servCmd /usr/sbin/fwknop_serv;
452 knopmdCmd /usr/sbin/knopmd;
453 knoptmCmd /usr/sbin/knoptm;
454 knopwatchdCmd /usr/sbin/knopwatchd;