1FWKNOPD(8) System Manager's Manual FWKNOPD(8)
2
6 fwknopd - Firewall Knock Operator (server component)
7
9 fwknopd [options]
10
12 fwknopd is the server component for the FireWall Knock Operator, and is
13 responsible for monitoring Single Packet Authorization (SPA) packets
14 that are generated by fwknop clients, modifying an iptables or ipfw
15 policy to allow the desired access after decrypting a valid SPA packet,
16 and removing access after a configurable timeout. The main application
17 of this program is to protect services such as SSH with an additional
18 layer of security in order to make the exploitation of vulnerabilities
19 (both 0-day and unpatched code) much more difficult.
20 The main configuration for fwknopd is maintained within two files:
22 fwknop.conf and access.conf within the /etc/fwknop directory, and con‐
23 figuration variables within these files are desribed below.
24
26 -c, --config <config-file>
27 When run in server mode fwknop references the file
28 /etc/fwknop/fwknop.conf for various run-time configuration vari‐
29 ables. The path to this file can be changed through the use of
30 the --config command line option.
31 -i, --intf <interface>
33 Manually specify interface on which to sniff, e.g. "-i eth0".
34 This option is not usually needed because the PCAP_INTF keyword
35 in /etc/fwknop/fwknop.conf file defines the sniffing interface.
36 --fw-list
38 List all active rules in the FWKNOP Netfilter chain(s).
39 --fw-flush
41 Flush all active rules in the FWKNOP Netfilter chain(s).
42 -O, --Override-config <file>
44 Override config variable values that are normally read from the
45 /etc/fwknop/fwknop.conf file with values from the specified
46 file. Multiple override config files can be given as a comma
47 separated list.
48 -D, --Dump-config
50 Dump the configuration values that fwknopd derives from the
51 /etc/fwknop/fwknop.conf (or other override files) on STDERR.
52 -o, --os
54 Parse Netfilter logs and fingerprint operating systems from
55 which tcp SYN packets have been logged.
56 --fw-log <file>
58 Specify the path to the Netfilter log file that is parsed when
59 running in --os mode.
60 -K, --Kill
62 Kill the current fwknop process along with knopwatchd and
63 knopmd. This provides a quick and easy way to stop all fwknop
64 processes without having to look in the process table or appeal
65 to the fwknop init script.
66 -R, --Restart
68 Restart the currently running fwknop processes. This option
69 will preserve the command line options that were supplied to the
70 original fwknop process.
71 -S, --Status
73 Display the status of any fwknop processes that may or not be
74 running.
75 -l, --locale <locale>
77 Provide a locale setting other than the default "C" locale.
78 --no-locale
80 Do not set the locale at all so that the default system locale
81 will apply.
82 -v, --verbose
84 Run fwknop in verbose mode.
85 -h, --help
87 Display usage information and exit.
88 -V, --Version
90 Display version information and exit.
91
93 /etc/fwknop/fwknop.conf
94 The main configuration file for fwknop.
95 /etc/fwknop/access.conf
97 Defines all knock sequences and access control directives.
98 /etc/fwknop/pf.os
100 Defines p0f signatures used by fwknop.
101
103 fwknop references the file /etc/fwknop/fwknop.conf for configuration
104 variables such as the path to the firewall logfile, the sleep interval
105 fwknop uses to check for new log messages, and paths to system bina‐
106 ries, etc. The fwknop config file does not define any access control
107 directives; they are located in the file /etc/fwknop/access.conf.
108 Access control directives define encryption keys and level of access
109 that is granted to an fwknop client that has generated the appropriate
110 encrypted message. This file is referenced for this information when
111 run in either the single packet authorization mode, or the legacy port
112 knocking mode.
113 SOURCE: <IP,..,IP/NET,..,NET/ANY>
115 This defines the source address from which an authorization
116 packet (or legacy knock sequence) will be accepted. The string
117 "ANY" is also accepted if a valid authorization packet should be
118 honored from any source IP. Every authorization stanza in
119 /etc/fwknop/access.conf definition must start with the SOURCE
120 keyword. Networks can be specified in either CIDR (e.g.
121 "192.168.10.0/24") or regular (e.g.
122 "192.168.10.0/255.255.255.0") notation, and individual IP
123 addresses can be specified as well. Also, multiple IP's and/or
124 networks can be defined as a comma separated list (e.g.
125 "192.168.10.0/24, 10.1.1.123")
126 DATA_COLLECT_MODE: PCAP|FILE_PCAP|ULOG_PCAP|ENCRYPT_SEQUENCE
128 If DATA_COLLECT_MODE is set to "PCAP", fwknop sniffs the wire
129 directly via libpcap to capture authorization packets. If set
130 to "FILE_PCAP", fwknop reads a pcap-formatted file (defined by
131 the PCAP_PKT_FILE keyword in the fwknop.conf file) that is writ‐
132 ten to by a separate sniffer process. If set to "ULOG_PCAP",
133 fwknop collects packets via the Netfilter ulogd pcap writer.
134 This requires that packets are logged via the ULOG target in the
135 Netfilter policy. If set to ENCRYPT_SEQUENCE, fwknop falls back
136 to the legacy port knocking method of network authorization.
137 ENABLE_CMD_EXEC
139 This instructs fwknop to accept complete commands that are con‐
140 tained within an authorization packet. Any such command will be
141 executed as root by the fwknop server.
142 CMD_REGEX: <regex>
144 If ENABLE_CMD_EXEC is specified, the CMD_REGEX keyword instructs
145 fwknop to restrict command execution to only those command that
146 match the given regular expression.
147 KEY: <8 or more chars>
149 Define the encryption key for an ENCRYPT_SEQUENCE block. This
150 variable is required for all encrypted sequences (each encrypted
151 sequence may have its own unique key), and must be provided at
152 execution to an fwknop client attempting to gain access. When
153 run in client mode, fwknop will prompt the user for the encryp‐
154 tion key, or a path to the key may be provided on the command
155 line with --get-key <file>.
156 OPEN_PORTS: <proto/port>, ..., <proto/port>
158 Define a set of ports and protocols (tcp or udp) that will be
159 opened if a valid knock sequence is seen. This variable is
160 required for shared knock sequences since the port information
161 is not sent within the sequence, and optional for encrypted
162 knock sequences which can include the port and protocol within
163 the sequence.
164 GPG_DECRYPT_ID: <keyID>
166 Define a GnuPG key ID to use for decrypting SPA messages that
167 have been encrypted by an fwknop client. This keyword is
168 required for authentication that is based on gpg keys. The gpg
169 key ring on the client must have imported and signed the fwknopd
170 server key, and vice versa. It is ok to use a sensitive per‐
171 sonal gpg key on the client, but each fwknopd server should have
172 its own gpg key that is generated specifically for fwknop commu‐
173 nications. The reason for this is that the decryption password
174 for the server key must be placed within the
175 /etc/fwknop/access.conf file for fwknopd to function (it has to
176 be able to decrypt SPA messages that have been encrypted with
177 the server's public key). For more information on using fwknop
178 with GnuPG keys, see the following link: http://www.cipher‐
179 dyne.org/fwknop/docs/gpghowto.html
180 GPG DECRYPT_PW: <decrypt password>
182 Specify the decryption password for the gpg key defined by the
183 GPG_DECRYPT_ID above. This is a required field for gpg-based
184 authentication.
185 GPG_REMOTE_ID: <keyID,...,keyID>
187 Define a list of gpg key ID's that are required to have signed
188 any incoming SPA message that has been encrypted with the
189 fwknopd server key. This ensures that the verification of the
190 remote user is accomplished via a strong cryptographic mecha‐
191 nism.
192 GPG_HOME_DIR: <path>
194 Define the path to the GnuPG directory to be used by the fwknopd
195 server. If this keyword is not specified within
196 /etc/fwknop/access.conf then fwknopd will default to using the
197 /root/.gnupg directory for the server key(s).
198 GPG_USE_OPTIONS
200 By default, fwknopd instructs gpg to not reference any options
201 file when decrypting incoming SPA packets that have been
202 encrypted with GnuPG by the fwknop client. This argument re-
203 enables options in gpg.
204 GPG_NO_REQUIRE_PREFIX
206 This option controls whether the GnuPG 'hQ' prefix is added
207 before base64 decoding and decrypting. Normally this option is
208 not needed, but if there appear to be communications issues
209 between the fwknop client and the fwknopd server in GnuPG mode,
210 then this option can be useful to ensure that encrypted SPA data
211 is sent through the GnuPG decryption routine. The 'hQ' prefix
212 is a heuristic derived from the file 'magic' database for
213 describing data encrypted with GnuPG, and the fwknop client nor‐
214 mally strips this data from outgoing SPA packets (unless the
215 --Include-gpg-prefix option is used).
216 GPG_PATH: <path>
218 Specify a path to the gpg binary (commonly at /usr/bin/gpg).
219 This can be used to switch between gpg vs. gpg2, or provide a
220 path to a custom compiled version of gpg for testing purposes.
221 FW_ACCESS_TIMEOUT: <seconds>
223 Define the length of time access will be granted by fwknop
224 through the firewall after a valid knock sequence from a source
225 IP address. If FW_ACCESS_TIMEOUT is not set then the default
226 timeout of 300 seconds (5 minutes) will automatically be set.
227 REQUIRE_USERNAME: <username>
229 Require a specific username from the client system. This user‐
230 name is sent across the network in an encrypted knock sequence
231 to the fwknop server. If there are multiple users on the client
232 system, only a knock sequence that is initiated by the required
233 username will be honored. This variable is optional and is only
234 valid with an encrypted sequence definition.
235 REQUIRE_SOURCE_ADDRESS
237 Force all SPA packets to contain a real IP address within the
238 encrypted data. This makes it impossible to use the -s command
239 line argument on the fwknop command line, so either -R has to be
240 used to automatically resolve the external address (if the
241 client behind a NAT) or the client must know the external IP.
242 REQUIRE_OS: <operating system>
244 Require a specific operating system fingerprint match (e.g.
245 "Linux:2.4::Linux 2.4/2.6" or "OpenBSD:3.0-3.5::OpenBSD 3.0-3.5"
246 before a knock sequence will be accepted. The fingerprints are
247 listed in /etc/fwknop/pf.os. Note that the corresponding knock
248 sequence must utilize the tcp protocol (this is only be an issue
249 for shared sequences since encrypted sequences use tcp by
250 default) since OS fingerprinting requires tcp syn packets. This
251 variable is optional, and is not applicable in SPA mode.
252 REQUIRE_OS_REGEX: <regex>
254 Require an operating system fingerprint that matches <regex>,
255 e.g. "linux" or "*bsd". Note that the regex will be matched
256 case in- sensitively. This variable is optional, and is not
257 applicable in SPA mode.
258 ENCRYPT_SEQUENCE
260 Expect that all port knock sequences originating from the SOURCE
261 will be encrypted. Fwknop will try to decrypt all such
262 sequences. ENCRYPT_SEQUENCE does not accept any arguments.
263 Either this variable or the "SHARED_SEQUENCE" variable is
264 required for each SOURCE block.
265 SHARED_SEQUENCE: <proto/port>, ..., <proto/port>
267 Define the sequence of ports (together with their associated
268 protocol; tcp or udp) that will be sent to the destination knock
269 server. This sequence is not encrypted, and source IP will be
270 allowed to connect through the destination firewall ruleset to a
271 set of tcp or udp ports (defined by the OPEN_PORTS variable).
272 Using an encrypted sequence is much more secure. Either this
273 variable or the "ENCRYPT_SEQUENCE" variable above is required
274 for each SOURCE block.
275 KNOCK_INTERVAL: <seconds>
277 Define the interval of time in which a port knock sequence will
278 be honored. I.e. the number of seconds after the first connec‐
279 tion attempt the last connection attempt in the sequence must be
280 received for the knock sequence to be accepted by the destina‐
281 tion fwknop daemon. If a KNOCK_INTERVAL is not specified then
282 the default interval of 60 seconds will automatically be set.
283 KNOCK_LIMIT: <number>
285 Define the maximum number of times a knock sequence will be hon‐
286 ored. Note that repetitive access to the fwknop server will
287 eventually be restricted if this option is used.
288 PORT_OFFSET: <offset>
290 Encrypted knock sequences take place over a range of 256 ports
291 starting at a default port of 61000. This value can be changed
292 through the use of the PORT_OFFSET variable. The PORT_OFFSET is
293 optional and will be set to 61000 by fwknop if it is not speci‐
294 fied in /etc/fwknop/access.conf.
295 MIN_TIME_DIFF: <seconds>
297 Set the minimum number of seconds that must pass between succes‐
298 sive connection attempts in a shared knock sequence. This vari‐
299 able is optional.
300 MAX_TIME_DIFF: <seconds>
302 Set the maximum number of seconds that must pass between succes‐
303 sive connection attempts in a shared knock sequence. This vari‐
304 able is optional.
305
307 fwknopd requires perl. To take advantage of all of the features in
308 fwknop when run in server mode a functioning Netfilter firewall is
309 required on the underlying operating system. If fwknop is being run in
310 the legacy port knocking mode, then Netfilter must log packets via sys‐
311 log, and ideally the --log-tcp-options argument will be specified in
312 the iptables logging rule so that fwknop will be able to use a strategy
313 similar to p0f to passively fingerprint operating systems.
314
316 fwknop can be run in debug mode with the --debug command line option.
317 This will disable daemon mode execution, and print verbose information
318 to the screen on STDERR as packets are received.
319
321 fwknop(8), iptables(8), gpg(1), gpg-agent(1), knopmd(8), knopwatchd(8)
322 p0f(1),
323
325 Michael Rash <mbr@cipherdyne.org>
326
328 The phrase "Single Packet Authorization" was coined by MadHat, see:
329 http://www.nmrc.org/ The term "port knocking" was coined by Martin
330 Krzywinski, see: http://www.portknocking.org/
331 The original p0f passive OS fingerprinter was written by Michal
332 Zalewski, and is available here: http://lcamtuf.coredump.cx/p0f.shtml
333
335 Send bug reports to mbr@cipherdyne.org. Suggestions and/or comments
336 are always welcome as well.
337
339 fwknop is distributed under the GNU General Public License (GPL), and
340 the latest version may be downloaded from http://www.cipherdyne.org/
341Linux Jun, 2007 FWKNOPD(8)