ChangeLog update for FCS bug fix
[fwknop.git] / perl / legacy / fwknop / fwknop.8
1 .\" Process this file with
2 .\" groff -man -Tascii foo.1
3 .\"
4 .TH FWKNOP 8 "August, 2009" Linux
5 .SH NAME
6 .B fwknop
7 \- Firewall Knock Operator
8 .SH SYNOPSIS
9 .B fwknop \-A <ports> \-R|\-a|\-s \-D <host> [options]
10 .SH DESCRIPTION
11
12 .B fwknop
13 implements an authorization scheme known as Single Packet Authorization (SPA) for
14 Linux systems running iptables, and for Mac OS X and FreeBSD systems running ipfw.
15 This mechanism requires only a single encrypted and non-replayed
16 packet to communicate various pieces of information including desired access
17 through an iptables or ipfw policy.  The main application of this program is to
18 use iptables or ipfw in a default-drop stance to protect services such as
19 .B SSH
20 with an additional layer of security in order to make the exploitation of
21 vulnerabilities (both 0-day and unpatched code) much more difficult.  An
22 authorization server
23 .B fwknopd
24 passively monitors authorization packets via
25 .B libpcap
26 and hence there is no "server" to which to connect in the traditional sense.
27 Any service protected by fwknop is inaccessible (by using iptables or ipfw to intercept
28 packets within the kernel) before authenticating; anyone scanning for
29 the service will not be able to detect that it is even listening.  Single Packet
30 Authorization offers many advantages over port knocking, including non-replayability
31 of SPA packets, ability to use asymmetric ciphers (such as Elgamal), and SPA cannot
32 be broken by simply spoofing packets to duplicate ports within the knock sequence
33 on the server to break port knocking authentication.  SPA packets can easily be
34 spoofed as well (this is a good thing in this context), and this makes it possible
35 to make it appear as though, say, www.yahoo.com is trying to authenticate to a
36 target system but in reality the actual connection will come from a seemingly
37 unrelated IP. Although the default data collection method in Single Packet
38 Authorization mode is to use libpcap to sniff packets off the wire, fwknop can also
39 read packets out of a file that is written by the iptables
40 . B ulogd
41 pcap writer (or a separate sniffer process that is writing packet data to a file).
42 .PP
43 Authorization packets are either encrypted with the Rijndael block cipher
44 or via GnuPG and associated asymmetric ciphers.  If the symmetric encryption
45 method is chosen, then the encryption key is shared between the
46 client and server (see the
47 .I /etc/fwknop/access.conf
48 file).  If the GnuPG
49 method is chosen, then the encryption keys are derived from GnuPG key
50 rings.  SPA packets generated by fwknop running as a client adhere
51 to the following format (before they are encrypted):
52 .PP
53     random number (16 bytes)
54     username
55     timestamp
56     software version
57     mode (command mode (0) or access mode (1))
58     if command mode => command to execute
59     else access mode  => IP,proto,port
60     message digest (SHA256 / SHA1 / MD5)
61 .PP
62 Each of the above fields are separated by a ":" character due to the
63 variable length of several of the fields, and those that might contain
64 ":" characters are base64 encoded.  The message digest (SHA256 by default
65 in all versions of
66 .B fwknop
67 greater than 1.9.1) allows the server to check message integrity after decryption,
68 and the 16 bytes of random data ensures (with high probability) that no two messages
69 are identical.  This ensures that replay attacks are not possible against fwknop.
70 For each packet coming from an
71 .B fwknop
72 client, the
73 .B fwknopd
74 server caches the SHA256 digest calculated over the entire packet and compares against
75 previous packet digests in order to detect attempted replay attacks.  The digest
76 cache file is located at
77 .I /var/log/fwknop/digest.cache
78 and is not rotated so that the detection of duplicate SPA messages is maximized.
79 Both syslog and email alerts are generated if a replay is detected (although
80 this can be tuned via the
81 .B ALERTING_METHODS
82 variable in the
83 .I /etc/fwknop/fwknop.conf
84 file).  By default, the
85 .B fwknop
86 client sends authorization packets over UDP
87 port 62201, but this can be altered with the
88 .B \-\-Server-port
89 argument. The server must first be configured to acquire the SPA data on
90 the changed protocol-port.  Also, fwknop can send the SPA packet over a random
91 port via the \-\-rand-port argument.  See
92 .B fwknopd(8)
93 for further details.  See the
94 .B EXAMPLES
95 section for example invocations of the
96 .B fwknop
97 client.
98
99 .SH REQUIRED ARGUMENTS
100
101 .TP
102 .BR \-D "\fR,\fP " \-\^\-Destination\ \<IP-address>
103 Direct the
104 .B fwknop
105 client to authenticate with the
106 .B fwknopd
107 daemon/service at the destination address <IP> .  The connection mode is discovered by the
108 .B fwknopd
109 daemon/service when it decrypts and parses the authentication packet.
110 .TP
111 .BR \-A "\fR,\fP " \-\^\-Access\ \<port\ list>
112 Provide a list of ports and protocols to access on a remote computer running
113 .B fwknopd.
114 The format of this list is '<proto>/<port>...<proto>/<port>,
115 e.g. "tcp/22,udp/53".
116 .B NOTE:
117 The vast majority of usages for
118 .B fwknop
119 require the \-A argument, but sending full commands with the \-\-Server-cmd
120 argument via an SPA packet to be executed by
121 .B fwknopd
122 does not require this argument.
123 .TP
124 .BR \-R|\-a|\-s
125 One of these options (see below) is required to tell the remote
126 .B fwknopd
127 daemon what IP should be let through the local firewall.  It is recommend to use
128 the \-R or \-a options instead of \-s in order to harden SPA communications against
129 possible MITM attacks.
130
131 .SH OPTIONS
132
133 .TP
134 .BR \-a "\fR,\fP " \-\^\-allow-IP\ \<IP-address>
135 Specify IP address that should be permitted through the destination
136 .B fwknopd
137 server firewall (this IP is encrypted within the SPA packet itself). This is
138 useful to prevent a Man-In-The-Middle (MTIM) attack where an SPA packet can be
139 intercepted en-route and sent from a different IP than the original. Hence, if
140 the
141 .B fwknopd
142 server trusts the source address on the SPA packet IP header then the attacker
143 gains access.  The
144 .B \-a
145 option puts the source address within the encrypted
146 SPA packet, and so thwarts this attack.  The
147 .B \-a
148 option is also useful to specify the IP that will be granted access when SPA
149 packet itself is spoofed with the
150 .B \-\-Spoof-src
151 option.  Another related option is \-R (see below) which instructs the
152 .B fwknop
153 client to automatically resolve the externally routable IP address the local
154 system is connected to by querying the
155 .B http://www.whatismyip.com
156 website.
157 .TP
158 .BR \-R "\fR,\fP " \-\^\-Resolve-external-IP
159 This is an important option, and instructs the
160 .B fwknop
161 client and the
162 .B fwknopd
163 daemon/service to query
164 .B http://www.whatismyip.com
165 to determine the IP address that should be allowed through the iptables policy
166 at the remote
167 .B fwknopd
168 server side.  This is useful if the
169 .B fwknop
170 client is being used on a system that is behind an obscure NAT address.  Note
171 that you can use the
172 .B \-\-URL
173 option to have fwknop resolve an externally routable address by using the
174 specific web service instead of http://www.whatismyip.org (see below).
175 .TP
176
177 .BR \-\^\-NAT-access\ \<internalIP:forwardPort>
178 The
179 .B fwknopd
180 server offers the ability to provide SPA access through an iptables firewall
181 to an internal service by interfacing with the iptables NAT capabilities.  So,
182 if the fwknopd server is protecting an internal network on RFC 1918 address
183 space, an external fwknop client can request that the server port forward an
184 external port to an internal IP, i.e. "\-\-NAT-access 192.168.10.2:55000".  In
185 this case access will be granted to 192.168.10.2 via port 55000 to whatever
186 service is requested via the \-\-Access argument (usually tcp/22). Hence, after
187 sending such an SPA packet, one would then do "ssh \-p 55000 user@host" and
188 the connection would be forwarded on through to the internal 192.168.10.2
189 system automatically.  Note that the port "55000" can be randomly generated
190 via the \-\-NAT-rand-port argument (described later).
191 .TP
192 .BR \-\^\-NAT-local
193 On the
194 .B fwknopd
195 server, a NAT operation can apply to the local system instead of being
196 forwarded through the system.  That is, for iptables firewalls, a connection
197 to, say, port 55,000 can be translated to port 22 on the local system.  By
198 making use of the \-\-NAT-local argument, the fwknop client can be made to
199 request such access.  This means that any external attacker would only see
200 a connection over port 55,000 instead of the expected port 22 after the SPA
201 packet is sent.
202 .TP
203 .BR \-\^\-URL\ \<web\ resolution\ \URL>
204 This option is used in conjunction with the
205 .B \-R
206 option so that fwknop will resolve the externally routable IP address (useful
207 if fwknop is run on a system being a NAT) via a web service URL supplied on
208 the command line. A custom web resolution CGI script is available at the URL
209 below if http://www.whatismyip.org is not available:
210 .B http://www.cipherdyne.org/cgi/clientip.cgi
211 .TP
212 .BR \-\^\-gpg-agent
213 Instruct
214 .B fwknop
215 to acquire GnuPG key password from a running
216 .B gpg-agent
217 instance.
218 .TP
219 .BR \-\^\-gpg-agent-info\ \<connection\ \info>
220 Specify the value of the GPG_AGENT_INFO environment variable as returned
221 by the
222 .B gpg-agent \-\-daemon
223 command. If the
224 .B fwknop \-\-gpg-agent
225 command line argument is used instead of
226 .B \-\-gpg-agent-info,
227 then fwknop assumes that the GPG_AGENT_INFO environment variable has already
228 been set in the current shell.
229 .TP
230 .BR \-\^\-gpg-default-key
231 Use the key that GnuPG defines as the default, i.e. the key that is specified
232 by the
233 .B default-key
234 variable in
235 .I ~/.gnupg/options.
236 If the
237 .B default-key
238 variable is not defined
239 within
240 .I ~/.gnupg/options
241 , then GnuPG tries to use the first suitable key on
242 its key ring.  If the user does not know the password for this key, then the
243 standard password error will be thrown by GnuPG and reported back to the
244 user.
245 .TP
246 .BR \-\^\-gpg-home-dir\ \<dir>
247 Specify the path to the GnuPG directory; normally this path is derived from the
248 home directory of the user that is running the
249 .B fwknop
250 client.  This is useful when a 'root' user wishes to log into a remote machine
251 whose
252 .B sshd
253 daemon/service does not permit 'root' login.
254 .TP
255 .BR \-\^\-gpg-recipient\ \<key\ \ID>
256 Specify the GnuPG key ID, e.g. "1234ABCD" (see the output of "gpg \-\-list-keys")
257 of the recipient of the Single Packet Authorization message.  This key is imported
258 by the
259 .B fwknopd
260 server and the associated private key is used to decrypt the SPA packet.  The
261 recipient's key must first be imported into the client GnuPG key ring.
262 .TP
263 .BR \-\^\-gpg-signing-key\ \<key\ \ID>
264 Specify the GnuPG key ID, e.g. "ABCD1234" (see the output of "gpg \-\-list-keys")
265 to use when signing the SPA message.  The user is prompted for
266 the associated GnuPG password to create the signature.  This
267 adds a cryptographically strong mechanism to allow the
268 .B fwknopd
269 daemon on the remote server to authenticate who created the SPA message.
270 .TP
271 .BR \-\^\-gpg-verbose
272 Instruct
273 .B fwknop
274 to allow all output from the
275 .B gpg
276 process that is used by fwknop in GnuPG mode.  This is primarily used for debugging
277 purposes if it appears that the GnuPG encrypt/decrypt is not performing correctly.
278 .TP
279 .BR \-\^\-gpg-use-options
280 By default the
281 .B fwknop
282 client instructs gpg to not reference any options file in gpg mode, but this
283 command line argument can be used to re-enable them.
284 .TP
285 .BR \-\^\-Home-dir\ \<dir>
286 Specify the path to the user home directory where files such as .fwknop.hosts
287 or .fwknop.run should be stored or retrieved.
288 .TP
289 .BR \-l "\fR,\fP " \-\^\-last-cmd
290 Instruct
291 .B fwknop
292 client to run with the same command line arguments that were used in a previous execution.
293 This option is useful because the clients'
294 .B fwknop
295 command line can be complex and difficult to recall.
296 .TP
297 .BR \-\^\-Last-host\ \<host>
298 Instruct
299 .B fwknop
300 to use the same command line arguments that were used to authenticate to
301 .B host.
302 .TP
303 .BR \-q "\fR,\fP " \-\^\-quiet
304 This option instructs the
305 .B fwknop
306 to be as quiet as possible and only print absolutely necessary information to
307 the terminal.
308 .TP
309 .BR \-s "\fR,\fP " \-\^\-source-ip
310 Instruct the
311 .B fwknop
312 client to form an SPA packet that contains the special-case IP
313 address "0.0.0.0" which will inform the destination
314 .B fwknopd
315 SPA server to use the source IP address from which the SPA packet originates as
316 the IP that will be allowed through upon modification of the firewall ruleset.
317 This option is useful if the fwknop client is deployed on a machine that is
318 behind a NAT device. The permit-address options
319 .B \-s
320 (default),
321 .B \-R
322 and
323 .B \-a
324 are mutually exclusive.
325 .TP
326 .BR \-\^\-Server-port\ \<port>
327 Specify the port number where
328 .B fwknopd
329 accepts packets via libpcap or ulogd pcap writer.  By default fwknopd looks for
330 authorization packets over UDP port 62201.
331 .TP
332 .BR \-\^\-rand-port
333 Instruct the fwknop client to send an SPA packet over a random destination port
334 between 10,000 and 65535.  The fwknopd server must use a PCAP_FILTER variable
335 that is configured to accept such packets.  For example, the PCAP_FILTER variable
336 could be set to:
337 .B udp dst portrange 10000-65535
338 .TP
339 .BR \-\^\-NAT-rand-port
340 Usually fwknop is used to request access to a specific port such as tcp/22 on a
341 system running fwknopd.  However, by using the \-\-NAT-rand-port argument, it is
342 possible to request access to a particular service (again, such as tcp/22), but
343 have this access granted via a random translated port.  That is, once the fwknop
344 client has been executed in this mode and the random port selected by fwknop is
345 displayed, the destination port used by the follow-on client must be changed to
346 match this random port.  For SSH, this is accomplished via the \-p argument.
347 See the \-\-NAT-local and \-\-NAT-access command line arguments to fwknop for
348 additional details on gaining access to services via a NAT operation.
349 .TP
350 .BR \-\^\-Save-packet
351 Instruct the
352 .B fwknop
353 client to write a newly created SPA packet out to a file so that it can be
354 examined off-line.  The default path is
355 .I ~/fwknop_save_packet.<pid>
356 where <pid> is the process ID of the fwknop client process, but this can be
357 changed with the \-\-Save-packet-file argument (see below).
358 .TP
359 .BR \-\^\-Save-packet-file\ \<file>
360 Specify the file to write a new SPA packet to in
361 .I \-\-Save-packet
362 mode.
363 .TP
364 .BR \-\^\-Save-packet-append
365 In
366 .I \-\-Save-packet
367 mode fwknop normally overwrite the file used to save a new SPA packet, but
368 this command line argument instructs fwknop to append a new SPA packet to
369 the file instead.  This is useful for generating large sets of SPA packets
370 in order to test randomness or encryption properties.
371 .TP
372 .BR \-\^\-time-offset-plus\ \<time>
373 By default, the
374 .B fwknopd
375 daemon on the server side enforces time synchronization between the clocks
376 running on client and server systems.  The fwknop client places the local time
377 within each SPA packet as a time stamp to be validated by the fwknopd server
378 after decryption.  However, in some circumstances, if the clocks are out of
379 sync and the user on the client system does not have the required access to
380 change the local clock setting, it can be difficult to construct and SPA
381 packet with a time stamp the server will accept.  In this situation, the
382 \-\-time-offset-plus option can allow the user to specify an offset (e.g.
383 "60sec", "60min", "2days", etc.) that is added to the local time.
384 .TP
385 .BR \-\^\-time-offset-minus\ \<time>
386 This is similar to the \-\-time-offset-plus option (see above), but subtracts
387 the specified time offset instead of adding it to the local time stamp.
388 .TP
389 .BR \-\^\-Show-last-cmd
390 Display the last command-line arguments used by
391 .B fwknop.
392 .TP
393 .BR \-\^\-Show-host-cmd\ \<host>
394 Display the last command-line arguments used to contact a SPA server running on
395 a specific
396 .B host.
397 .TP
398 .BR \-\^\-Spoof-proto\ \<protocol>
399 Send an SPA packet over a raw socket of the specified protocol.  Accepted
400 values are tcp, udp, and icmp.  This is useful if you want to send the SPA
401 packet over an orphaned TCP ACK or an ICMP packet.
402 .TP
403 .BR \-\^\-Spoof-src\ \<IP>
404 Spoof the source address from which the
405 .B fwknop
406 client sends SPA packets.  This requires root on the client side access since a raw socket
407 is required to accomplish this.  Note that the
408 .B \-\-Spoof-user
409 argument can be given in this mode in order to pass any
410 .B REQUIRE_USERNAME
411 keyword that might
412 be specified in
413 .I /etc/fwknop/access.conf.
414 .TP
415 .BR \-\^\-Spoof-user\ \<user>
416 Specify the username that is included within SPA packet.  This allows
417 the
418 .B fwknop
419 client to satisfy any non-root
420 .B REQUIRE_USERNAME
421 keyword on the
422 .B fwknopd
423 server (
424 .B \-\-Spoof-src
425 mode requires that the
426 .B fwknop
427 client is executed as root).
428 .TP
429 .BR \-\^\-icmp-type\ \<type>
430 When using the
431 .B \-\-Spoof-proto
432 argument to send an SPA packet over and ICMP packet, the ICMP type may be set
433 with this command line argument.  The default is "8" for an ICMP echo-request
434 (see also the
435 .B \-\-icmp-code
436 argument below).
437 .TP
438 .BR \-\^\-icmp-code\ \<code>
439 When using the
440 .B \-\-Spoof-proto
441 argument to send an SPA packet over and ICMP packet, the ICMP code may be set
442 with this command line argument.  The default is "0" for an ICMP echo-request
443 (see also the
444 .B \-\-icmp-type
445 argument above).
446 .TP
447 .BR \-\^\-Max-packet-size\ \<size>
448 Instruct
449 .B fwknop
450 to restrict message length to
451 .B size
452 bytes, and the client will not send an SPA packet that is larger than this
453 (i.e. perhaps a long command was included in \-\-Server-cmd mode). This alters
454 the default value of 1500 bytes. See also the
455 MAX_SNIFF_BYTES variable in
456 .B fwknop.conf
457 on the SPA server.
458 .TP
459 .BR \-\^\-HTTP
460 Have the
461 .B fwknop
462 client send an SPA packet as a web request over HTTP.  This requires that the
463 system running
464 .B fwknopd
465 is also running a webserver to receive the SPA web request.  The web request
466 is built as a modified version of base64-encoded data where the "+" and "/"
467 chars are replace with "-" and "_" respectively (to avoid URL encoding issues).
468 .TP
469 .BR \-\^\-HTTP-proxy\ \<proxy\ host>
470 The
471 .I HTTP-proxy
472 option allows the
473 .B fwknop
474 client to send SPA packets through an HTTP proxy when the
475 .I \-\-HTTP
476 option is also used.  The expected format for the argument is
477 .B http://some.host.com
478 and an optional port number is supported with the
479 .B http://some.host.com:PORT
480 format.
481 .TP
482 .BR \-\^\-HTTP-user-agent\ \<agent\ string>
483 Specify the HTTP user-agent whenver the
484 .B fwknop
485 client is used to send an SPA packet over an HTTP request, or when the
486 .I \-\-Resolve-external-IP
487 option is used.  The default user-agent is "Fwknop/VERSION", so "Fwknop/1.9.12"
488 for the 1.9.12 release.
489 .TP
490 .BR \-T "\fR,\fP " \-\^\-TCP-sock
491 Have the
492 .B fwknop
493 client send an SPA packet over an established TCP connection (created by the fwknop
494 client to the specified listening port on the server with the
495 .I --Server-port
496 argument).  This is not normally done, but is useful for compatibility with the Tor
497 for strong anonymity; see
498 .B http://tor.eff.org/.
499 In this case, the
500 .B fwknopd
501 server uses the
502 .B fwknop_serv
503 daemon to listen on a TCP port (62201 by default).
504 .TP
505 .BR \-h "\fR,\fP " \-\^\-help
506 Display usage information and exit.
507 .TP
508 .BR \-V "\fR,\fP " \-\^\-Version
509 Display version information and exit.
510 .TP
511 .BR \-v "\fR,\fP " \-\^\-verbose
512 Run the
513 .B fwknop
514 client in verbose mode.
515 .TP
516 .BR \-\^\-locale\ \<locale>
517 Provide a locale setting other than the default "C" locale.
518 .TP
519 .BR \-\^\-no-locale
520 Do not set the locale at all so that the default system locale will apply.
521 .TP
522 .BR \-\^\-Server-cmd\ \<cmd>
523 .B NOTE:
524 This is for command mode only (i.e. when you want to send a command across
525 to a system running
526 .B fwknopd
527 and have it execute the command). This option is not needed when trying to
528 gain access to a service via the SPA mechanism.  To use this feature, please
529 ensure that ENABLE_CMD_EXEC; is set in the file
530 .I /etc/fwknop/access.conf
531 on the
532 .B fwknopd
533 server you are sending the command to.
534 The \-\-Server-cmd argument allows a complete command (e.g. "ping \-c 1 www.yahoo.com",
535 or "iptables \-t nat \-A PREROUTING \-p tcp \-s 65.x.x.x \-\-dport 443 \-i eth0 \-j DNAT \-\-to 192.168.10.20:443")
536 to be send to an
537 .B fwknop
538 server, which will execute the command as root.  Command execution is enabled only
539 if the
540 .B ENABLE_CMD_EXEC keyword is given in
541 .I /etc/fwknop/access.conf
542 (note that commands can easily be restricted with the
543 .B CMD_REGEX
544 keyword as well).
545 .TP
546
547 .B Legacy Port-knock mode only
548
549 All of the following options in this section are for the traditional port knocking
550 mode mode.  This is a legacy mode and is
551 .B not
552 the preferred or recommended mode next to Single Packet Authorization ( see
553 .B http://www.cipherdyne.org/fwknop/docs/SPA.html
554 for details on why).
555 .RS
556 .TP
557 .BR \-\^\-offset\ \<port>
558 Specify a port offset to use when running
559 .B fwknop
560 in encrypted knock mode.  The default is 61000.
561 .TP
562 .BR \-r "\fR,\fP " \-\^\-rotate-proto
563 Rotate the protocol across tcp and udp for
564 encrypted sequences.  This just adds one more additional layer of obfuscation
565 to an encrypted sequence.
566 .TP
567 .BR \-\^\-Server-mode\ \<mode>
568 This command line switch provides an interface to
569 the old port knocking method if
570 the mode argument is "knock".  If the
571 .B \-\-Server-mode
572 argument is not given then the
573 .B fwknop
574 client defaults to using the SPA method which provides much better
575 security characteristics than port knocking (encrypted or not).
576 .TP
577 .BR \-t "\fR,\fP " \-\^\-time-delay\ \<seconds>
578 Specify a time delay to introduce between successive
579 connection attempts.  This option is used by the
580 .B fwknop
581 client.  On the server side,
582 .B fwknopd
583 uses the variables MIN_TIME_DIFF
584 and MAX_TIME_DIFF to control whether the time delay actually means
585 something (i.e. if the MIN_TIME_DIFF is 2 seconds for a SOURCE block,
586 then the argument to the \-\-time-delay option must be at least 2 at the
587 client side).
588 .TP
589 .BR \-u "\fR,\fP " \-\^\-user-rc\ \<rc-file>
590 The default connection rc file the
591 .B fwknop
592 client uses to know what shared port knocking sequence to send to a destination machine
593 is defined in the file
594 .I ~/.fwknoprc.
595 The path to this file can be changed with the
596 .B \-\-user-rc
597 command line option.
598 .RE
599
600 .SH FILES
601 .TP
602 .B ~/.fwknop.run
603 Contains the last command line arguments that the
604 .B fwknop
605 client was invoked with.
606
607 .TP
608 .B ~/.fwknop.hosts
609 Contains the last command line arguments for individual hosts that the
610 .B fwknop
611 client has been used to gain access to.  By using the
612 .B \-\-Last-host
613 switch, these arguments can be recalled and used.
614
615 .SH ENVIRONMENT:
616
617 .B GPG_AGENT_INFO
618 (only used in \-\-gpg-agent mode).
619
620 .SH EXAMPLES:
621 The following examples illustrate the command line arguments that could
622 be supplied to the
623 .B fwknop
624 client in a few situations:
625
626 .B Access mode examples
627 .RS
628 Packet contents printed to stdout at the
629 .B fwknop
630 client when creating a 'access mode' SPA packet:
631 .PP
632         Random data:    6565240948266426
633         Username:       mbr
634         Timestamp:      1203863233
635         Version:        1.9.2
636         Type:           1 (access mode)
637         Access:         127.0.0.2,tcp/22
638         SHA256 sum:     gngquSL8AuM7r27XsR4qPmJhuBo9pG2PYwII06AaJHw
639 .PP
640
641 Use the Single Packet Authorization mode to gain access to tcp/22 (ssh)
642 and udp/53 running on the system 10.0.0.123 from the IP 192.168.10.4:
643 .PP
644 .B $ fwknop \-A 'tcp/22,udp/53' \-a 192.168.10.4 \-D 10.0.0.123
645 .PP
646 Same as above example, but gain access from whatever source IP is seen
647 by the fwknop server (useful if the fwknop client is behind a NAT device):
648 .PP
649 .B $ fwknop \-A 'tcp/22,udp/53' \-s \-D 10.0.0.123
650 .PP
651 Same as above example, but use the IP identification website http://www.whatismyip.com/
652 to derive the client IP address.  This is a safer method of acquiring the client IP
653 address than using the
654 .B \-s
655 option because the source IP is put within the encrypted
656 packet instead of having the
657 .B fwknopd
658 daemon grant the requested access from whatever IP address the SPA packet originates:
659 .PP
660 .B $ fwknop \-A 'tcp/22,udp/53' \-R \-D 10.0.0.123
661 .PP
662 Use the Single Packet Authorization mode to gain access to tcp/22 (ssh)
663 and udp/53 running on the system 10.0.0.123, and use GnuPG keys to encrypt
664 and decrypt:
665 .PP
666 .B $ fwknop \-A 'tcp/22,udp/53' \-\-gpg-sign ABCD1234 \-\-gpg--recipient 1234ABCD \-R \-D 10.0.0.123
667 .PP
668 Instruct the fwknop server running at 10.0.0.123 to allow 172.16.5.4 to
669 connect to TCP/22, but spoof the authorization packet from an IP associated
670 with www.yahoo.com:
671 .PP
672 .B # fwknop \-\-Spoof-src 'www.yahoo.com' \-A tcp/22 \-a 172.16.5.4 \-D 10.0.0.123
673 .PP
674 .RE
675
676 .B Command mode examples
677 .RS
678 .B NOTE:
679 Please ensure that ENABLE_CMD_EXEC; is set in the file
680 .I /etc/fwknop/access.conf
681 on the
682 .B fwknopd
683 server you are attempting to connect to.
684 Packet contents printed to stdout at the
685 .B fwknop
686 client when creating a 'command mode' SPA packet:
687 .PP
688         Random data:    4621962433020664
689         Username:       mbr
690         Timestamp:      1203864394
691         Version:        1.9.2
692         Type:           0 (command mode)
693         Cmd:            echo "The commands sent \- minus quote charaters around the command" & sleep 10; echo "The End"
694         SHA256 sum:     eN8c8mNArZxF066iulbxlTK4Gt/EO0ALLYwzVzCkXww
695 .PP
696 Instruct the fwknop server running at 10.0.0.123 to send a single ICMP
697 echo request to www.yahoo.com:
698 .PP
699 .B $ fwknop \-\-Server-cmd 'ping \-c 1 www.yahoo.com' \-D 10.0.0.123
700 .PP
701 .RE
702
703 .B Port-knock mode (legacy) examples
704 .RS
705 This connection mode is a legacy mode and is
706 .B not
707 the preferred or recommended mode.
708
709 Packet contents printed to stdout at the
710 .B fwknop
711 client when in 'port-knock mode':
712 <TODO>
713
714 Send an encrypted knock sequence to the IP "10.0.0.123" instructing the
715 fwknop daemon running there to open tcp port 22 to source address
716 192.168.10.4:
717 .PP
718 .B $ fwknop \-\-Server-mode 'knock' \-A tcp/22 \-a 192.168.10.4 \-D 10.0.0.123
719 .PP
720 Same as above, but this time instruct the remote fwknop daemon to open
721 tcp port 22 to whatever source address the encrypted sequence originates
722 from (useful if the fwknop client is behind a NAT device):
723 .PP
724 .B $ fwknop \-\-Server-mode 'knock' \-A tcp/22 \-s \-D 10.0.0.123
725 .PP
726 Same as above, but rotate the knock sequence through the tcp and udp
727 protocols (remember that iptables must be configured to log both tcp and
728 udp packets to the default port range of 61000-61255):
729 .PP
730 .B $ fwknop \-\-Server-mode 'knock' \-A tcp/22 \-s \-r \-D 10.0.0.123
731 .PP
732 Same as above, but change the base port for the encrypted sequence to
733 55000 (the default is 61000):
734 .PP
735 .B $ fwknop \-\-Server-mode 'knock' \-A tcp/22 \-s \-r \-\-offset 55000 \-D 10.0.0.123
736 .PP
737 Send a shared knock sequence to the IP 10.11.11.123.  The fwknop client
738 will read the sequence out of the file
739 .B ~/.fwknoprc
740 and the server will read the sequence out of
741 .B /etc/fwknop/access.conf:
742 .PP
743 .B $ fwknop \-\-Server-mode 'knock' \-D 10.11.11.123
744 .RE
745
746 .SH DEPENDENCIES
747 .B fwknop
748 requires perl.  To take advantage of all of the authentication and access management features of the
749 .B fwknopd
750 daemon/service a functioning iptables firewall is required on the underlying
751 operating system.  If fwknop is being run in the legacy port knocking mode,
752 then iptables must log packets via syslog, and ideally the
753 .B \-\-log-tcp-options
754 argument will be specified in the iptables logging rule so that the
755 .B fwknopd
756 daemon/service will
757 be able to use a strategy similar to
758 .B p0f
759 to passively fingerprint operating systems.
760
761 .SH DIAGNOSTICS
762 .B fwknop
763 can be run in debug mode with the
764 .B \-\-debug
765 command line option.  This will
766 disable daemon mode execution, and print verbose information to the screen
767 on STDERR as packets are received.
768
769 .SH "SEE ALSO"
770 .BR fwknopd (8),
771 .BR iptables (8),
772 .BR gpg (1),
773 .BR gpg-agent (1),
774 .BR knopmd (8),
775 .BR knopwatchd (8)
776 .BR p0f (1),
777 More information on the
778 differences between port knocking and Single Packet Authorization can be found
779 in the paper "Single Packet Authorization with fwknop" available here:
780 .B http://www.cipherdyne.org/fwknop/docs/SPA.html
781
782 .SH AUTHOR
783 Michael Rash <mbr@cipherdyne.org>
784
785 .SH CONTRIBUTORS
786 Many people who are active in the open source community have contributed to fwknop.
787 See the
788 .B CREDITS
789 file in the fwknop sources, or visit
790 .B http://www.cipherdyne.org/fwknop/docs/contributors.html
791 to view the online list of contributors.
792
793 The phrase "Single Packet Authorization" was coined by MadHat and Simple
794 Nomad at the BlackHat Briefings of 2005 (see: http://www.nmrc.org/).
795 The term "port knocking" was coined by Martin Krzywinski (see:
796 http://www.portknocking.org/).  The original p0f passive OS fingerprinter was
797 written by Michal Zalewski, and is available here:
798 .B http://lcamtuf.coredump.cx/p0f.shtml
799
800 .SH BUGS
801 Send bug reports to mbr@cipherdyne.org.  Suggestions and/or comments are
802 always welcome as well.
803
804 .SH DISTRIBUTION
805 .B fwknop
806 is distributed under the GNU General Public License (GPL), and the latest
807 version may be downloaded from
808 .B http://www.cipherdyne.org/
809
810