1FWKNOP(8) Fwknop Client FWKNOP(8)
2
6 fwknop - Firewall Knock Operator
7
9 fwknop -A <'proto/ports'> -R|-a|-s -D <'host'> [options]
10
12 fwknop implements an authorization scheme known as Single Packet
13 Authorization (SPA) for strong service concealment. SPA requires only a
14 single packet which is encrypted, non-replayable, and authenticated via
15 an HMAC in order to communicate desired access to a service that is
16 hidden behind a firewall in a default-drop filtering stance. The main
17 application of SPA is to use a firewall to drop all attempts to connect
18 to services such as SSH in order to make the exploitation of
19 vulnerabilities (both 0-day and unpatched code) more difficult. Any
20 service that is concealed by SPA naturally cannot be scanned for with
21 Nmap. The fwknop project natively supports four different firewalls:
22 iptables, firewalld, PF, and ipfw across Linux, OpenBSD, FreeBSD, and
23 Mac OS X. There is also support for custom scripts so that fwknop can
24 be made to support other infrastructure such as ipset or nftables.
25 SPA is essentially next generation Port Knocking (PK), but solves many
27 of the limitations exhibited by PK while retaining its core benefits.
28 PK limitations include a general difficulty in protecting against
29 replay attacks, asymmetric ciphers and HMAC schemes are not usually
30 possible to reliably support, and it is trivially easy to mount a DoS
31 attack against a PK server just by spoofing an additional packet into a
32 PK sequence as it traverses the network (thereby convincing the PK
33 server that the client doesn’t know the proper sequence). All of these
34 limitation are solved by SPA. At the same time, SPA hides services
35 behind a default-drop firewall policy, acquires SPA data passively
36 (usually via libpcap or other means), and implements standard
37 cryptographic operations for SPA packet authentication and
38 encryption/decryption.
39 This is the manual page for the fwknop client which is responsible for
41 constructing SPA packets and sending them over the network. The server
42 side is implemented by the fwknopd daemon which sniffs the network for
43 SPA packets and interacts with the local firewall to allow SPA
44 authenticated connections. It is recommended to read the fwknopd(8)
45 manual page as well. Further detailed information may be found in the
46 tutorial “Single Packet Authorization: A Comprehensive Guide to Strong
47 Service Concealment with fwknop” available online (see:
48 http://www.cipherdyne.org/fwknop/docs/fwknop-tutorial.html).
49 SPA packets generated by fwknop leverage HMAC for authenticated
51 encryption in the encrypt-then-authenticate model. Although the usage
52 of an HMAC is currently optional (enabled via the --use-hmac command
53 line switch), it is highly recommended for three reasons: 1) without an
54 HMAC, cryptographically strong authentication is not possible with
55 fwknop unless GnuPG is used, but even then an HMAC should still be
56 applied, 2) an HMAC applied after encryption protects against
57 cryptanalytic CBC-mode padding oracle attacks such as the Vaudenay
58 attack and related trickery (like the more recent "Lucky 13" attack
59 against SSL), and 3) the code required by the fwknopd daemon to verify
60 an HMAC is much more simplistic than the code required to decrypt an
61 SPA packet, so an SPA packet without a proper HMAC isn’t even sent
62 through the decryption routines. Reason 3) is why an HMAC should still
63 be used even when SPA packets are encrypted with GnuPG due to the fact
64 that SPA data is not sent through libgpgme functions unless the HMAC
65 checks out first. GnuPG and libgpgme are relatively complex bodies of
66 code, and therefore limiting the ability of a potential attacker to
67 interact with this code through an HMAC operation helps to maintain a
68 stronger security stance. Generating an HMAC for SPA communications
69 requires a dedicated key in addition to the normal encryption key, and
70 both can be generated with the --key-gen option.
71 fwknop encrypts SPA packets either with the Rijndael block cipher or
73 via GnuPG and associated asymmetric cipher. If the symmetric encryption
74 method is chosen, then as usual the encryption key is shared between
75 the client and server (see the fwknopd /etc/fwknop/access.conf file for
76 details). The actual encryption key used for Rijndael encryption is
77 generated via the standard PBKDF1 key derivation algorithm, and CBC
78 mode is set. If the GnuPG method is chosen, then the encryption keys
79 are derived from GnuPG key rings. SPA packets generated by fwknop
80 running as a client adhere to the following format (before encryption
81 and the HMAC is applied):
82 random data (16 digits)
84 username
85 timestamp
86 software version
87 mode (command mode (0) or access mode (1))
88 if command mode => command to execute
89 else access mode => IP,proto,port
90 message digest (SHA512 / SHA384 / SHA256 / SHA1 / MD5 / SHA3_256 / SHA3_512)
91 Each of the above fields are separated by a ":" character due to the
93 variable length of several of the fields, and those that might contain
94 ":" characters are base64 encoded. The message digest (SHA256 by
95 default) is part of the data to be encrypted and is independent of the
96 HMAC which is appended to the SPA packet data after encryption. The 16
97 digits of random data (about 53 bits) ensures that no two SPA packets
98 are identical, and this is in addition to and independent of using
99 PBKDF1 for key derivation for Rijndael in CBC mode (which uses an
100 8-byte random "salt" value). Because fwknopd tracks the SHA256 digest
101 of all incoming valid SPA packets and throws out duplicates, replay
102 attacks are not feasible against fwknop. Syslog alerts are generated if
103 a replay is detected.
104 By default, the fwknop client sends authorization packets over UDP port
106 62201, but this can be altered with the --server-port argument (this
107 requires fwknopd to be configured to acquire SPA data over the selected
108 port). Also, fwknop can send the SPA packet over a random port via the
109 --rand-port argument. See fwknopd(8) for further details. See the
110 EXAMPLES section for example invocations of the fwknop client.
111 The fwknop client is quite portable, and is known to run on various
113 Linux distributions (all major distros and embedded ones such as
114 OpenWRT as well), FreeBSD, OpenBSD, Mac OS X, and Cygwin on Windows.
115 There is also a library libfko that both fwknop and fwknopd use for SPA
116 packet encryption/decryption and HMAC authentication operations. This
117 library can be used to allow third party applications to use SPA
118 subject to the terms of the GNU General Public License (GPL v2+).
119
121 These required arguments can be specified via command-line or from
122 within the ~/.fwknoprc file (see -n, --named-config option and the
123 FWKNOPRC FILE section below).
124 -A, --access=<port list>
126 Provide a list of ports and protocols to access on a remote
127 computer running fwknopd. The format of this list is
128 “+<proto>/<port>...<proto>/<port>+”, e.g. “tcp/22,udp/53”. NOTE:
129 The vast majority of usages for fwknop require the -A argument, but
130 sending full commands with the --server-cmd argument via an SPA
131 packet to be executed by fwknopd does not require this argument.
132 -D, --destination=<hostname/IP-address>
134 Direct the fwknop client to authenticate with the fwknopd
135 daemon/service at the specified destination hostname or IP address.
136 The connection mode is discovered by the fwknopd daemon/service
137 when it decrypts and parses the authentication packet.
138 -R|-a|-s
140 One of these options (see below) is required to tell the remote
141 fwknopd daemon what IP should be allowed through the firewall. It
142 is recommend to use the -R or -a options instead of -s in order to
143 harden SPA communications against possible Man-In-The-Middle (MITM)
144 attacks, and on the server side set REQUIRE_SOURCE_ADDRESS variable
145 in the /etc/fwknop/access.conf file. Note that the most secure
146 option is -a so that fwknop does not have to issue any HTTPS
147 request to https://www.cipherdyne.org/cgi-bin/myip in order to
148 resolve the externally routable IP address. Using -a requires that
149 the user already knows what the external IP is for the network
150 where fwknop is running.
151
153 -h, --help
154 Print a usage summary message and exit.
155 -G, --get-key=<file>
157 Load an encryption key/password from the specified file. The key
158 file contains a line for each destination hostname or IP address, a
159 colon (":"), optional space and the password, followed by a
160 newline. Note that the last line has to have a terminating newline
161 character. Also note: though this is a convenience, having a file
162 on your system with clear text passwords is not a good idea and is
163 not recommended. Having the fwknop client prompt you for the key is
164 generally more secure. Note also that if a key is stored on disk,
165 the fwknop rc file is a more powerful mechanism for specifying not
166 only the key but other options as well.
167 --stdin
169 Read the encryption key/password from stdin. This can be used to
170 send the data via a pipe for example. This command is similar to
171 --fd 0.
172 --fd=<number>
174 Specify the file descriptor number to read the key/password from.
175 This command avoids the user being prompted for a password if none
176 has been found in the user specific stanza, or none has been
177 supplied on the command line. A file descriptor set to 0 is similar
178 to the stdin command.
179 --get-hmac-key=<file>
181 Load an HMAC key/password from the specified file. Similarly to the
182 format for the --get-key option, the HMAC key file contains a line
183 for each destination hostname or IP address, a colon (":"),
184 optional space and the password, followed by a newline. Note that
185 the last line has to have a terminating newline character. Also
186 note: though this is a convenience, having a file on your system
187 with clear text passwords is not a good idea and is not
188 recommended. Having the fwknop client prompt you for the HMAC key
189 is generally more secure. Note also that if a key is stored on
190 disk, the fwknop rc file is a more powerful mechanism for
191 specifying not only the HMAC key but other options as well.
192 --key-gen
194 Have fwknop generate both Rijndael and HMAC keys that can be used
195 for SPA packet encryption and authentication. These keys are
196 derived from /dev/urandom and then base64 encoded before being
197 printed to stdout, and are meant to be included within the
198 “$HOME/.fwknoprc” file (or the file referenced by --get-key). Such
199 keys are generally more secure than passphrases that are typed in
200 from the command line.
201 --key-gen-file=<file>
203 Write generated keys to the specified file. Note that the file is
204 overwritten if it already exists. If this option is not given, then
205 --key-gen writes the keys to stdout.
206 --key-len=<length>
208 Specify the number of bytes for a generated Rijndael key. The
209 maximum size is currently 128 bytes.
210 --hmac-key-len=<length>
212 Specify the number of bytes for a generated HMAC key. The maximum
213 size is currently 128 bytes.
214 -l, --last-cmd
216 Execute fwknop with the command-line arguments from the previous
217 invocation (if any). The previous arguments are parsed out of the
218 ~/.fwknop.run file.
219 -n, --named-config=<stanza name>
221 Specify the name of the configuration stanza in the
222 “$HOME/.fwknoprc” file to pull configuration and command
223 directives. These named stanzas alleviate the need for remembering
224 the various command-line arguments for frequently used invocations
225 of fwknop. See the section labeled, FWKNOPRC FILE below for a list
226 of the valid configuration directives in the .fwknoprc file.
227 --key-rijndael=<key>
229 Specify the Rijndael key on the command line. Since the key may be
230 visible to utilities such as ps under Unix, this form should only
231 be used where security is not critical. Having the fwknop client
232 either prompt you for the key or acquire via the “$HOME/.fwknoprc”
233 file is generally more secure.
234 --key-base64-rijndael=<key>
236 Specify the base64 encoded Rijndael key. Since the key may be
237 visible to utilities such as ps under Unix, this form should only
238 be used where security is not critical. Having the fwknop client
239 either prompt you for the key or acquire via the “$HOME/.fwknoprc”
240 file is generally more secure.
241 --key-base64-hmac=<key>
243 Specify the base64 encoded HMAC key. Since the key may be visible
244 to utilities such as ps under Unix, this form should only be used
245 where security is not critical. Having the fwknop client either
246 prompt you for the key or acquire via the “$HOME/.fwknoprc” file is
247 generally more secure.
248 --key-hmac=<key>
250 Specify the raw HMAC key (not base64 encoded). Since the key may be
251 visible to utilities such as ps under Unix, this form should only
252 be used where security is not critical. Having the fwknop client
253 either prompt you for the key or acquire via the “$HOME/.fwknoprc”
254 file is generally more secure.
255 --rc-file=<file>
257 Specify path to the fwknop rc file (default is “$HOME/.fwknoprc”).
258 --no-rc-file
260 Perform fwknop client operations without referencing the
261 “$HOME/.fwknoprc” file.
262 --no-home-dir
264 Do not allow the fwknop client to look for the home directory
265 associated with the user.
266 --save-rc-stanza=<stanza name>
268 Save command line arguments to the “$HOME/.fwknoprc” stanza
269 specified with the -n option. If the -n option is omitted, then the
270 stanza name will default to the destination server value (hostname
271 or IP) given with the -D argument.
272 --force-stanza
274 Used with --save-rc-stanza to overwrite all of the variables for
275 the specified stanza
276 --stanza-list
278 Dump a list of the stanzas found in “$HOME/.fwknoprc”.
279 --show-last
281 Display the last command-line arguments used by fwknop.
282 -E, --save-args-file=<file>
284 Save command line arguments to a specified file path. Without this
285 option, and when --no-save-args is not also specified, then the
286 default save args path is ~/.fwknop.run.
287 --no-save-args
289 Do not save the command line arguments given when fwknop is
290 executed.
291 -T, --test
293 Test mode. Generate the SPA packet data, but do not send it.
294 Instead, print a break-down of the SPA data fields, then run the
295 data through the decryption and decoding process and print the
296 break-down again. This is primarily a debugging feature.
297 -B, --save-packet=<file>
299 Instruct the fwknop client to write a newly created SPA packet out
300 to the specified file so that it can be examined off-line.
301 -b, --save-packet-append
303 Append the generated packet data to the file specified with the -B
304 option.
305 --fault-injection-tag=<tag>
307 This option is only used for fault injection testing when fwknop is
308 compiled to support the libfiu library (see:
309 http://blitiri.com.ar/p/libfiu/). Under normal circumstances this
310 option is not used, and any packaged version of fwknop will not
311 have code compiled in so this capability is not enabled at run
312 time. It is documented here for completeness.
313 -v, --verbose
315 Run the fwknop client in verbose mode. This causes fwknop to print
316 some extra information about the current command and the resulting
317 SPA data.
318 -V, --version
320 Display version information and exit.
321
323 --use-hmac
324 Set HMAC mode for authenticated encryption of SPA communications.
325 As of fwknop 2.5, this is an optional feature, but this will become
326 the default in a future release.
327 -a, --allow-ip=<IP-address>
329 Specify IP address that should be permitted through the destination
330 fwknopd server firewall (this IP is encrypted within the SPA packet
331 itself). This is useful to prevent a MITM attack where a SPA packet
332 can be intercepted en-route and sent from a different IP than the
333 original. Hence, if the fwknopd server trusts the source address on
334 the SPA packet IP header then the attacker gains access. The -a
335 option puts the source address within the encrypted SPA packet, and
336 so thwarts this attack. The -a option is also useful to specify the
337 IP that will be granted access when the SPA packet itself is
338 spoofed with the --spoof-src option. Another related option is -R
339 (see below) which instructs the fwknop client to automatically
340 resolve the externally routable IP address the local system is
341 connected to by querying https://www.cipherdyne.org/cgi-bin/myip.
342 This returns the actual IP address it sees from the calling system.
343 -g, --gpg-encryption
345 Use GPG encryption on the SPA packet (default if not specified is
346 Rijndael). Note: Use of this option will also require a GPG
347 recipient (see --gpg-recipient along with other GPG-related options
348 below).
349 --hmac-digest-type=<digest>
351 Set the HMAC digest algorithm for authenticated encryption of SPA
352 packets. Choices are: MD5, SHA1, SHA256 (the default), SHA384,
353 SHA512, SHA3_256, and SHA3_512.
354 -N, --nat-access=<internalIP:forwardPort>
356 The fwknopd server offers the ability to provide SPA access through
357 an iptables firewall to an internal service by interfacing with the
358 iptables NAT capabilities. So, if the fwknopd server is protecting
359 an internal network on an RFC-1918 address space, an external
360 fwknop client can request that the server port forward an external
361 port to an internal IP, i.e. “+--NAT-access 192.168.10.2,55000+”.
362 In this case, access will be granted to 192.168.10.2 via port 55000
363 to whatever service is requested via the --access argument (usually
364 tcp/22). Hence, after sending such an SPA packet, one would then do
365 “ssh -p 55000 user@host” and the connection would be forwarded on
366 through to the internal 192.168.10.2 system automatically. Note
367 that the port “55000” can be randomly generated via the
368 --nat-rand-port argument (described later).
369 --nat-local
371 On the fwknopd server, a NAT operation can apply to the local
372 system instead of being forwarded through the system. That is, for
373 iptables firewalls, a connection to, say, port 55,000 can be
374 translated to port 22 on the local system. By making use of the
375 --nat-local argument, the fwknop client can be made to request such
376 access. This means that any external attacker would only see a
377 connection over port 55,000 instead of the expected port 22 after
378 the SPA packet is sent.
379 --nat-port
381 Usually fwknop is used to request access to a specific port such as
382 tcp/22 on a system running fwknopd. However, by using the
383 --nat-port argument, it is possible to request access to a (again,
384 such as tcp/22), but have this access granted via the specified
385 port (so, the -p argument would then be used on the SSH client
386 command line). See the --nat-local and --nat-access command line
387 arguments to fwknop for additional details on gaining access to
388 services via a NAT operation.
389 --nat-rand-port
391 Usually fwknop is used to request access to a specific port such as
392 tcp/22 on a system running fwknopd. However, by using the
393 --nat-rand-port argument, it is possible to request access to a
394 particular service (again, such as tcp/22), but have this access
395 granted via a random translated port. That is, once the fwknop
396 client has been executed in this mode and the random port selected
397 by fwknop is displayed, the destination port used by the follow-on
398 client must be changed to match this random port. For SSH, this is
399 accomplished via the -p argument. See the --nat-local and
400 --nat-access command line arguments to fwknop for additional
401 details on gaining access to services via a NAT operation.
402 -p, --server-port=<port>
404 Specify the port number where fwknopd accepts packets via libpcap
405 or ulogd pcap writer. By default fwknopd looks for authorization
406 packets over UDP port 62201.
407 -P, --server-proto=<protocol>
409 Set the protocol (udp, tcp, http, udpraw, tcpraw, or icmp) for the
410 outgoing SPA packet. Note: The udpraw, tcpraw, and icmp modes use
411 raw sockets and thus require root access to run. Also note: The tcp
412 mode expects to establish a TCP connection to the server before
413 sending the SPA packet. This is not normally done, but is useful
414 for compatibility with the Tor for strong anonymity; see
415 http://tor.eff.org/. In this case, the fwknopd server will need to
416 be configured to listen on the target TCP port (which is 62201 by
417 default).
418 -Q, --spoof-src=<IP>
420 Spoof the source address from which the fwknop client sends SPA
421 packets. This requires root on the client side access since a raw
422 socket is required to accomplish this. Note that the --spoof-user
423 argument can be given in this mode in order to pass any
424 REQUIRE_USERNAME keyword that might be specified in
425 /etc/fwknop/access.conf.
426 -r, --rand-port
428 Instruct the fwknop client to send an SPA packet over a random
429 destination port between 10,000 and 65535. The fwknopd server must
430 use a PCAP_FILTER variable that is configured to accept such
431 packets. For example, the PCAP_FILTER variable could be set to:
432 “+udp dst portrange 10000-65535+”.
433 -R, --resolve-ip-https
435 This is an important option, and instructs the fwknop client to
436 issue an HTTPS request to a script running on cipherdyne.org that
437 returns the client’s IP address (as seen by the web server). In
438 some cases, this is needed to determine the IP address that should
439 be allowed through the firewall policy at the remote fwknopd server
440 side. This option is useful if the fwknop client is being used on a
441 system that is behind an obscure NAT address, and the external
442 Internet facing IP is not known to the user. The full resolution
443 URL is: https://www.cipherdyne.org/cgi-bin/myip, and is accessed by
444 fwknop via wget in --secure-protocol mode. Note that it is
445 generally more secure to use the -a option if the externally
446 routable IP address for the client is already known to the user
447 since this eliminates the need for fwknop to issue any sort of
448 HTTPS request.
449 --resolve-url <url>
451 Override the default URL used for resolving the source IP address.
452 For best results, the URL specified here should point to a web
453 service that provides just an IP address in the body of the HTTP
454 response.
455 --resolve-http-only
457 This option forces the fwknop client to resolve the external IP via
458 HTTP instead of HTTPS. There are some circumstances where this
459 might be necessary such as when wget is not available (or hasn’t
460 been compiled with SSL support), but generally this is not
461 recommended since it opens the possibility of a MITM attack through
462 manipulation of the IP resolution HTTP response. Either specify the
463 IP manually with -a, or use -R and omit this option.
464 -w, --wget-cmd=<wget full path>
466 Manually set the full path to the wget command. Normally the
467 configure script finds the wget command, but this option can be
468 used to specify the path if it is located in a non-standard place.
469 -s, --source-ip
471 Instruct the fwknop client to form an SPA packet that contains the
472 special-case IP address “+0.0.0.0+” which will inform the
473 destination fwknopd SPA server to use the source IP address from
474 which the SPA packet originates as the IP that will be allowed
475 through upon modification of the firewall ruleset. This option is
476 useful if the fwknop client is deployed on a machine that is behind
477 a NAT device and the external IP is not known. However, usage of
478 this option is not recommended, and either the -a or -R options
479 should be used instead. The permit-address options -s, -R and -a
480 are mutually exclusive.
481 -S, --source-port=<port>
483 Set the source port for outgoing SPA packet.
484 --server-resolve-ipv4
486 This option forces the fwknop client to only accept an IPv4 address
487 from DNS when a hostname is used for the SPA server. This is
488 necessary in some cases where DNS may return both IPv6 and IPv4
489 addresses.
490 -f, --fw-timeout=<seconds>
492 Specify the length of time (seconds) that the remote firewall rule
493 that grants access to a service is to remain active. The default
494 maintained by fwknopd is 30 seconds, but any established connection
495 can be kept open after the initial accept rule is deleted through
496 the use of a connection tracking mechanism that may be offered by
497 the firewall.
498 -C, --server-cmd=<command to execute>
500 Instead of requesting access to a service with an SPA packet, the
501 --server-cmd argument specifies a command that will be executed by
502 the fwknopd server. The command is encrypted within the SPA packet
503 and sniffed off the wire (as usual) by the fwknopd server.
504 -H, --http-proxy=<proxy-host>[:port]
506 Specify an HTTP proxy that the fwknop client will use to send the
507 SPA packet through. Using this option will automatically set the
508 SPA packet transmission mode (usually set via the --server-proto
509 argument) to "http". You can also specify the proxy port by adding
510 ":<port>" to the proxy host name or ip.
511 -m, --digest-type=<digest>
513 Specify the message digest algorithm to use in the SPA data.
514 Choices are: MD5, SHA1, SHA256 (the default), SHA384, and SHA512,
515 SHA3_256, and SHA3_512.
516 -M, --encryption-mode=<mode>
518 Specify the encryption mode when AES is used for encrypting SPA
519 packets. The default is CBC mode, but others can be chosen such as
520 CFB or OFB as long as this is also specified in the
521 /etc/fwknop/access.conf file on the server side via the
522 ENCRYPTION_MODE variable. In general, it is recommended to not
523 include this argument and let the default (CBC) apply. Note that
524 the string “legacy” can be specified in order to generate SPA
525 packets with the old initialization vector strategy used by
526 versions of fwknop prior to 2.5. With the 2.5 release, fwknop
527 generates initialization vectors in a manner that is compatible
528 with OpenSSL via the PBKDF1 algorithm.
529 --time-offset-plus=<time>
531 By default, the fwknopd daemon on the server side enforces time
532 synchronization between the clocks running on client and server
533 systems. The fwknop client places the local time within each SPA
534 packet as a time stamp to be validated by the fwknopd server after
535 decryption. However, in some circumstances, if the clocks are out
536 of sync and the user on the client system does not have the
537 required access to change the local clock setting, it can be
538 difficult to construct and SPA packet with a time stamp the server
539 will accept. In this situation, the --time-offset-plus option can
540 allow the user to specify an offset (e.g. “60sec” “60min” “2days”
541 etc.) that is added to the local time.
542 --time-offset-minus=<time>
544 This is similar to the --time-offset-plus option (see above), but
545 subtracts the specified time offset instead of adding it to the
546 local time stamp.
547 -u, --user-agent=<user-agent-string>
549 Set the HTTP User-Agent for resolving the external IP via -R, or
550 for sending SPA packets over HTTP.
551 --use-wget-user-agent
553 By default when the fwknop client resolves the external IP with
554 wget via SSL, it sets the User-Agent to “Fwknop/<version>” unless
555 it was already manually specified with the --user-agent option
556 mentioned above. However, the --user-wget-user-agent option lets
557 the default wget User-Agent string apply without influence from
558 fwknop.
559 -U, --spoof-user=<user>
561 Specify the username that is included within SPA packet. This
562 allows the fwknop client to satisfy any non-root REQUIRE_USERNAME
563 keyword on the fwknopd server (--spoof-src mode requires that the
564 fwknop client is executed as root).
565 --icmp-type=<type>
567 In -P icmp mode, specify the ICMP type value that will be set in
568 the SPA packet ICMP header. The default is echo reply.
569 --icmp-code=<code>
571 In -P icmp mode, specify the ICMP code value that will be set in
572 the SPA packet ICMP header. The default is zero.
573
575 Note that the usage of GPG for SPA encryption/decryption can and should
576 involve GPG keys that are signed by each side (client and server). The
577 basic procedure for this involves the following steps after the client
578 key has been transferred to the server and vice-versa:
579 [spaserver]# gpg --import client.asc
581 [spaserver]# gpg --edit-key 1234ABCD
582 Command> sign
583 [spaclient]$ gpg --import server.asc
585 [spaclient]$ gpg --edit-key ABCD1234
586 Command> sign
587 More comprehensive information on this can be found here:
589 http://www.cipherdyne.org/fwknop/docs/gpghowto.html.
590 --gpg-agent
592 Instruct fwknop to acquire GnuPG key password from a running
593 gpg-agent instance (if available).
594 --gpg-home-dir=<dir>
596 Specify the path to the GnuPG directory; normally this path is
597 derived from the home directory of the user that is running the
598 fwknop client (so the default is ~/.gnupg). This is useful when a
599 “root” user wishes to log into a remote machine whose sshd
600 daemon/service does not permit root login.
601 --gpg-recipient=<key ID or Name>
603 Specify the GnuPG key ID, e.g. “+1234ABCD+” (see the output of
604 "gpg—list-keys") or the key name (associated email address) of the
605 recipient of the Single Packet Authorization message. This key is
606 imported by the fwknopd server and the associated private key is
607 used to decrypt the SPA packet. The recipient’s key must first be
608 imported into the client GnuPG key ring.
609 --gpg-signer-key=<key ID or Name>
611 Specify the GnuPG key ID, e.g. “+ABCD1234+” (see the output of "gpg
612 --list-keys") or the key name to use when signing the SPA message.
613 The user is prompted for the associated GnuPG password to create
614 the signature. This adds a cryptographically strong mechanism to
615 allow the fwknopd daemon on the remote server to authenticate who
616 created the SPA message.
617 --gpg-no-signing-pw
619 Instruct fwknop to not acquire a passphrase for usage of GnuPG
620 signing key. This option is provided to make SPA packet
621 construction easier for client-side operations in automated
622 environments where the passphrase for the signing key has been
623 removed from the GnuPG key ring. However, it is usually better to
624 leverage gpg-agent instead of using this option.
625
627 The .fwknoprc file is used to set various parameters to override
628 default program parameters at runtime. It also allows for additional
629 named configuration stanzas for setting program parameters for a
630 particular invocation.
631 The fwknop client will create this file if it does not exist in the
633 user’s home directory. This initial version has some sample directives
634 that are commented out. It is up to the user to edit this file to meet
635 their needs.
636 The .fwknoprc file contains a default configuration area or stanza
638 which holds global configuration directives that override the program
639 defaults. You can edit this file and create additional named stanzas
640 that can be specified with the -n or --named-config option. Parameters
641 defined in the named stanzas will override any matching default stanza
642 directives. Note that command-line options will still override any
643 corresponding .fwknoprc directives.
644 There are directives to match most of the command-line parameters
646 fwknop supports. Here is the current list of each directive along with
647 a brief description and its matching command-line option(s):
648 SPA_SERVER <hostname/IP-address>
650 Specify the hostname or IP of the destination (fwknopd) server (-D,
651 --destination).
652 ALLOW_IP <IP-address>
654 Specify the address to allow within the SPA data. Note: This
655 parameter covers the -a, -s, and -R command-line options. You can
656 specify a hostname or IP address (the -a option), specify the word
657 "source" to tell the fwknopd server to accept the source IP of the
658 packet as the IP to allow (the -s option), or use the word
659 "resolve" to have fwknop resolve the external network IP via HTTP
660 request (the -R option).
661 ACCESS <port list>
663 Set the one or more protocol/ports to open on the firewall (-A,
664 --access). The format of this list is
665 “+<proto>/<port>...<proto>/<port>+”, e.g. “tcp/22,udp/53”.
666 SPA_SERVER_PORT <port>
668 Set the server port to use for sending the SPA packet (-p,
669 --server-port).
670 SPA_SERVER_PROTO <protocol>
672 Set the protocol to use for sending the SPA packet (-P,
673 --server-proto).
674 KEY <passphrase>
676 This is the passphrase that is used for SPA packet encryption and
677 applies to both Rijndael or GPG encryption modes. The actual
678 encryption key that is used for Rijndael is derived from the PBKDF1
679 algorithm, and the GPG key is derived from the specified GPG key
680 ring.
681 KEY_BASE64 <base64 encoded passphrase>
683 Specify the encryption passphrase as a base64 encoded string. This
684 allows non-ascii characters to be included in the base64-decoded
685 key.
686 USE_HMAC <Y/N>
688 Set HMAC mode for authenticated encryption of SPA packets. This
689 will have fwknop prompt the user for a dedicated HMAC key that is
690 independent of the encryption key. Alternatively, the HMAC key can
691 be specified with the HMAC_KEY or HMAC_KEY_BASE64 directives (see
692 below).
693 HMAC_KEY <key>
695 Specify the HMAC key for authenticated encryption of SPA packets.
696 This supports both Rijndael and GPG encryption modes, and is
697 applied according to the encrypt-then-authenticate model.
698 HMAC_KEY_BASE64 <base64 encoded key>
700 Specify the HMAC key as a base64 encoded string. This allows
701 non-ascii characters to be included in the base64-decoded key.
702 HMAC_DIGEST_TYPE <digest algorithm>
704 Set the HMAC digest algorithm used for authenticated encryption of
705 SPA packets. Choices are: MD5, SHA1, SHA256 (the default), SHA384,
706 SHA512, SHA3_256, and SHA3_512.
707 SPA_SOURCE_PORT <port>
709 Set the source port to use for sending the SPA packet (-S,
710 --source-port).
711 FW_TIMEOUT <seconds>
713 Set the firewall rule timeout value (-f, --fw-timeout).
714 RESOLVE_IP_HTTPS <Y/N>
716 Set to Y to automatically resolve the externally routable IP
717 associated with the fwknop client. This is done over SSL via wget
718 in --secure-protocol mode against the IP resolution service
719 available at https://www.cipherdyne.org/cgi-bin/myip.
720 RESOLVE_HTTP_ONLY <Y/N>
722 When the fwknop client is instructed to resolve the external client
723 IP, this option can be used to force an HTTP connection instead of
724 an HTTPS connection when set to Y. This option is useful when wget
725 is not installed on the local OS, or when it is not compiled
726 against an SSL library.
727 RESOLVE_URL <url>
729 Set to a URL that will be used for resolving the source IP address
730 (--resolve-url).
731 WGET_CMD <wget full path>
733 Set the full path to the wget command (used for client IP
734 resolution).
735 TIME_OFFSET <time>
737 Set a value to apply to the timestamp in the SPA packet. This can
738 be either a positive or negative value (--time-offset-plus/minus).
739 ENCRYPTION_MODE <mode>
741 Specify the encryption mode when AES is used. This variable is a
742 synonym for the -M, --encryption-mode command line argument. In
743 general, it is recommended to not include this argument and let the
744 default (CBC) apply. Note that the string “legacy” can be specified
745 in order to generate SPA packets with the old initialization vector
746 strategy used by versions of fwknop prior to 2.5.
747 DIGEST_TYPE <digest algorithm>
749 Set the SPA message digest type (-m, --digest-type). Choices are:
750 MD5, SHA1, SHA256 (the default), SHA384, SHA512, SHA3_256, and
751 SHA3_512.
752 USE_GPG <Y/N>
754 Set to Y to specify the use of GPG for encryption
755 (--gpg-encryption).
756 USE_GPG_AGENT <Y/N>
758 Set to Y to have fwknop interface with a GPG agent instance for the
759 GPG key password (--gpg-agent). Agent information itself is
760 specified with the GPG_AGENT_INFO environmental variable.
761 GPG_SIGNING_PW <passphrase>
763 This is the passphrase that is used for signing SPA packet data in
764 GPG encryption mode, and is a synonym for the KEY variable (i.e.
765 the signing passphrase can be specified with the KEY variable
766 instead). The SPA packet is encrypted with the remote server key
767 and signed with the local client key.
768 GPG_SIGNING_PW_BASE64 <base64 encoded passphrase>
770 Specify the GPG signing passphrase as a base64 encoded string. This
771 allows non-ascii characters to be included in the base64-decoded
772 key.
773 GPG_SIGNER <key ID or Name>
775 Specify the GPG key name or ID for signing the GPG-encrypted SPA
776 data (--gpg-signer-key).
777 GPG_RECIPIENT <key ID or Name>
779 Specify the GPG key name or ID for the recipient of the
780 GPG-encrypted SPA data (--gpg-recipient-key).
781 GPG_HOMEDIR <dir>
783 Specify the GPG home directory (--gpg-home-dir). Defaults to
784 ~/.gnupg.
785 GPG_EXE <path>
787 Specify the path to GPG (--gpg-exe). Defaults to /usr/bin/gpg.
788 SPOOF_USER <user>
790 Set the username in the SPA data to the specified value (-U,
791 --spoof-user).
792 SPOOF_SOURCE_IP <IP>
794 Set the source IP of the outgoing SPA packet to the specified value
795 (-Q, --spoof-source).
796 RAND_PORT <Y/N>
798 Send the SPA packet over a randomly assigned port (-r,
799 --rand-port).
800 KEY_FILE <file>
802 Load an encryption key/password from a file (-G, --get-key).
803 HTTP_USER_AGENT <agent string>
805 Set the HTTP User-Agent for resolving the external IP via -R, or
806 for sending SPA packets over HTTP (-u, --user-agent).
807 USE_WGET_USER_AGENT <Y/N>
809 Allow default wget User-Agent string to be used when resolving the
810 external IP instead of a User-Agent supplied by the fwknop client.
811 NAT_ACCESS <internalIP:forwardPort>
813 Gain NAT access to an internal service protected by the fwknop
814 server (-N, --nat-access).
815 NAT_LOCAL <Y/N>
817 Access a local service via a forwarded port on the fwknopd server
818 system (--nat-local).
819 NAT_PORT <port>
821 Specify the port to forward to access a service via NAT
822 (--nat-port).
823 NAT_RAND_PORT <Y/N>
825 Have the fwknop client assign a random port for NAT access
826 (--nat-rand-port).
827
829 SPOOF_USER, GPG_AGENT_INFO (only used in --gpg-agent mode).
830
832 Because fwknop places the IP to be allowed through the firewall within
833 the encrypted SPA payload (unless -s is used which is not recommended
834 and can be prohibited in the fwknopd server configuration), SPA packets
835 can easily be spoofed, and this is a good thing in this context. That
836 is, the source IP of an SPA packet is ignored by the fwknopd daemon
837 (when the REQUIRE_SOURCE_ADDRESS variable is set in the
838 /etc/fwknop/access.conf file) and only the IP that is contained within
839 an authenticated and properly decrypted SPA packet is granted access
840 through the firewall. This makes it possible to make it appear as
841 though, say, www.yahoo.com is trying to authenticate to a target system
842 but in reality the actual connection will come from a seemingly
843 unrelated IP.
844
846 The following examples illustrate the command line arguments that could
847 be supplied to the fwknop client in a few situations:
848 Quick start
850 The most effective and easiest way to use fwknop is to have the client
851 generate both an encryption key and an HMAC key, and then save them to
852 the “$HOME/.fwknoprc” file along with access request specifics. The
853 keys will also need to be transferred to the system where fwknopd is
854 running. The also client supports a separate set of encryption and HMAC
855 keys for each SPA destination if multiple fwknopd servers are running
856 on different systems.
857 So, assuming that the IP 2.2.2.2 is the system where fwknopd is
859 deployed and SSH is protected by the firewall on that system in a
860 default-drop stance, run the client like so to generate encryption and
861 HMAC keys:
862 $ fwknop -A tcp/22 --use-hmac -R -D 2.2.2.2 --key-gen --save-rc-stanza --verbose
864 [+] Wrote Rijndael and HMAC keys to rc file: /home/user/.fwknoprc
865 With the access request arguments and encryption and HMAC keys
867 generated and saved in “$HOME/.fwknoprc”, the keys themselves need to
868 be transferred to the 2.2.2.2 system where fwknopd is running. As
869 always, this should be done via some secure means such as SSH before
870 SPA is enabled and SSHD is blocked by the firewall. Here is what the
871 new 2.2.2.2 stanza looks like in the ~/.fwknoprc file:
872 $ tail -n 8 /home/user/.fwknoprc
874 [2.2.2.2]
875 ACCESS tcp/22
876 SPA_SERVER 2.2.2.2
877 KEY_BASE64 HvUtIOramehLGKimD4ECXOzinaH4h3U8H1WXum7b54Q=
878 HMAC_KEY_BASE64 DLeLf93a3yBT2vhEpM+dWlirGta5GU+jdyG5uXp4461HgOtbqMem4gX0Bp2PJGzYZlbbcavcOM00UPm+0GqkXA==
879 USE_HMAC Y
880 VERBOSE Y
881 RESOLVE_IP_HTTPS Y
882 The keys are base64 encoded blobs of random data, and both the
884 KEY_BASE64 and HMAC_KEY_BASE64 lines should be copied verbatim and
885 placed within the /etc/fwknop/access.conf file on 2.2.2.2. Once this is
886 done, fwknopd can be started on that system, a default-drop policy
887 against SSH connections can be put in place, and then access to SSH is
888 managed via fwknop. To access SSH, just use the -n argument to
889 reference the 2.2.2.2 stanza out of the .fwknoprc file (some --verbose
890 output is included for illustration):
891 $ fwknop -n 2.2.2.2
893 FKO Field Values:
895 =================
896 Random Value: 8950423288486978
898 Username: mbr
899 Timestamp: 1370194770
900 FKO Version: 2.5
901 Message Type: 1 (Access msg)
902 Message String: 1.1.1.1,tcp/22
903 Nat Access: <NULL>
904 Server Auth: <NULL>
905 Client Timeout: 0 (seconds)
906 Digest Type: 3 (SHA256)
907 HMAC Type: 3 (SHA256)
908 Encryption Type: 1 (Rijndael)
909 Encryption Mode: 2 (CBC)
910 ...
911 $ ssh -l user 2.2.2.2
913 user@2.2.2.2's password:
914 Access mode examples
916 The most common usage of fwknop is to gain access to SSH running on a
917 remote system that has the fwknopd daemon deployed along with a
918 default-drop firewall policy. The following command illustrates this
919 where IP 1.1.1.1 is the IP to be allowed through the firewall running
920 on 3.3.3.3 (note that the /etc/fwknop/access.conf file consumed by
921 fwknopd will need to have matching encryption and HMAC keys, and
922 configuration specifics can be found in the fwknopd(8) manual page).
923 Also, note the examples below prompt the user to supply the encryption
924 and HMAC keys via stdin instead of writing them to disk as in the case
925 of using the “$HOME/.fwknoprc” file in the example above. However, all
926 of the following examples can be converted to using the ~/.fwknoprc
927 file just by adding the --save-rc-stanza argument:
928 $ fwknop -A tcp/22 --use-hmac -a 1.1.1.1 -D 3.3.3.3
930 Enter encryption key:
931 Enter HMAC key:
932 $ ssh -l user 3.3.3.3
933 user@3.3.3.3's password:
934 If the --verbose flag is added to the command line, then some SPA
936 packet specifics are printed to stdout (not all output is shown for
937 brevity):
938 $ fwknop -A tcp/22 --use-hmac -a 1.1.1.1 -D 3.3.3.3 --verbose
940 Enter encryption key:
941 Enter HMAC key:
942 Random Value: 1916307060193417
944 Username: mbr
945 Timestamp: 1368498909
946 FKO Version: 2.5
947 Message Type: 1 (Access msg)
948 Message String: 1.1.1.1,tcp/22
949 Nat Access: <NULL>
950 Server Auth: <NULL>
951 Client Timeout: 0 (seconds)
952 Digest Type: 3 (SHA256)
953 HMAC Type: 3 (SHA256)
954 Encryption Type: 1 (Rijndael)
955 Encryption Mode: 2 (CBC)
956 Simultaneous access to multiple services is also supported, and here is
958 an example of requesting access to both SSH and OpenVPN on 3.3.3.3:
959 $ fwknop -A "tcp/22,tcp/1194" --use-hmac -a 1.1.1.1 -D 3.3.3.3
961 There are many cases where an fwknop client is deployed on a network
963 behind a NAT device and the externally routable IP is not known to the
964 user. In this case, use the IP resolution service available at
965 https://www.cipherdyne.org/cgi-bin/myip via the -R command line switch
966 in order to derive the external client IP address. This is a safer
967 method of acquiring the client IP address than using the -s option
968 mentioned earlier in this manual page because the source IP is put
969 within the encrypted packet instead of having the fwknopd daemon grant
970 the requested access from whatever IP address the SPA packet originates
971 (i.e. using -s opens the possibility of a MITM attack):
972 $ fwknop -A tcp/22 --use-hmac -R -D 3.3.3.3
974 Use the Single Packet Authorization mode to gain access to SSH and this
976 time use GnuPG keys to encrypt and decrypt:
977 $ fwknop -A tcp/22 --use-hmac --gpg-sign ABCD1234 --gpg--recipient 1234ABCD -R -D 3.3.3.3
979 Instruct the fwknop server running at 3.3.3.3 to allow 1.1.1.1 to
981 connect to SSH, but spoof the authorization packet from an IP
982 associated with www.yahoo.com (requires root on the fwknop client OS):
983 # fwknop --spoof-src "www.yahoo.com" -A tcp/22 --use-hmac -a 1.1.1.1 -D 3.3.3.3
985 When fwknopd is running on an iptables firewall with systems deployed
987 behind it, it is possible to take advantage of the NAT capabilities
988 offered by iptables in order to transparently reach systems behind the
989 firewall via SPA. Here is an example where the fwknop client is used to
990 gain access to SSH running on the non-routable IP 192.168.10.23 that is
991 deployed on the network behind 3.3.3.3. In this case, the SSH
992 connection made to 3.3.3.3 is translated via NAT to the 192.168.10.2
993 system automatically:
994 $ fwknop -A tcp/22 -N 192.168.10.2:22 -R -D 3.3.3.3
996
998 With the 2.5 release, fwknop underwent significant changes in its usage
999 of cryptography including the addition of support for HMAC
1000 authenticated encryption for both Rijndael and GnuPG modes, ensuring
1001 the proper usage of PBKDF1 for key derivation when SPA packets are
1002 encrypted with Rijndael, and several bugs were fixed from previous
1003 versions of fwknop. In general, this implies that when Rijndael is
1004 used, SPA packets produced by the 2.5 release are incompatible with
1005 previous versions of fwknop. The GnuPG encryption mode is unaffected by
1006 these updates. However, even with Rijndael is used, backwards
1007 compatibility is supported through setting the legacy encryption mode
1008 with -M on the fwknop client command line and/or the ENCRYPTION_MODE
1009 variable in the /etc/fwknop/access.conf file. This way, a pre-2.5
1010 server can decrypt SPA packets produced by a 2.5 and later client (set
1011 -M legacy), and a 2.5 and later server can decrypt SPA packets produced
1012 by pre-2.5 clients (set ENCRYPTION_MODE legacy in the access.conf
1013 file). Note that HMAC is only supported as of 2.5 and is an optional
1014 feature, so backwards compatibility is only for configurations that
1015 don’t use an HMAC on either side. It is strongly recommended to upgrade
1016 all fwknop clients and servers to 2.5 and use the new HMAC mode for
1017 properly authenticated SPA communications. The backwards compatibility
1018 support is used to make it easier to upgrade clients and servers with a
1019 phased approach.
1020 For emphasis, if the fwknopd server is upgraded to 2.5 (or later), but
1022 older clients cannot be upgraded at the same time, then for each SOURCE
1023 stanza in the /etc/fwknop/access.conf file, add the following line:
1024 ENCRYPTION_MODE legacy
1026 In addition, if the KEY variable has an encryption key longer than 16
1028 bytes, it will need to be truncated to 16 characters in the access.conf
1029 file in order for pre-2.5 clients to work properly. This limitation is
1030 fixed in 2.5, and provides additional motivation for upgrading all
1031 clients and servers to 2.5 or later.
1032 Now, flipping the scenario around, if the fwknop clients are upgraded
1034 but the fwknopd server is still at a pre-2.5 version, then add the -M
1035 legacy argument to the fwknop command line:
1036 $ fwknop -A tcp/22 -M legacy -R -D 2.2.2.2
1038
1040 The fwknop client requires libfko which is normally included with both
1041 source and binary distributions, and is a dedicated library developed
1042 by the fwknop project. Whenever the fwknopd server is used, libpcap is
1043 a required dependency. However, the upcoming 2.6 release will offer a
1044 UDP listener mode along with privilege separation support and will not
1045 require libpcap in this mode. In UDP listener mode, even though fwknopd
1046 binds to a UDP port, SPA packets are never acknowledged so from an
1047 attacker’s perspective there is no difference between fwknopd sniffing
1048 the wire passively vs. listening on a UDP socket in terms of what can
1049 be scanned for.
1050 For GPG functionality, GnuPG must also be correctly installed and
1052 configured along with the libgpgme library.
1053 To take advantage of all of the authentication and access management
1055 features of the fwknopd daemon/service a functioning iptables, ipfw, or
1056 pf firewall is required on the underlying operating system.
1057
1059 The most comprehensive way to gain diagnostic information on fwknop is
1060 to run the test suite test-fwknop.pl script located in the test/
1061 directory in the fwknop sources. The test suite sends fwknop through a
1062 large number of run time tests, has valgrind support, validates both
1063 SPA encryption and HMAC results against OpenSSL, and even has its own
1064 built in fuzzer for SPA communications (and fwknop in version 2.6.4
1065 supports the American Fuzzy Lop (AFL) from Michal Zalewski as well).
1066 For more basic diagnostic information, fwknop can be executed with the
1067 -T (or --test) command line option. This will have fwknop simply create
1068 and print the SPA packet information, then run it through a
1069 decrypt/decode cycle and print it again. In addition, the --verbose
1070 command line switch is useful to see various SPA packet specifics
1071 printed to stdout.
1072
1074 fwknopd(8), iptables(8), pf(4), pfctl(8), ipfw(8), gpg(1), libfko
1075 documentation.
1076 More information on Single Packet Authorization can be found in the
1078 paper “Single Packet Authorization with fwknop” available at
1079 http://www.cipherdyne.org/fwknop/docs/SPA.html. A comprehensive
1080 tutorial on fwknop operations and theory can be found at
1081 http://www.cipherdyne.org/fwknop/docs/fwknop-tutorial.html. This
1082 tutorial also includes information about the design of fwknop that may
1083 be worth reading for those interested in why fwknop is different from
1084 other SPA implementations.
1085 fwknop uses the git versioning system as its source code repository
1087 along with Github for tracking of issues and milestones:
1088 $ git clone https://github.com/mrash/fwknop.git fwknop.git
1090 Additional commentary on Single Packet Authorization can be found via
1092 Michael Rash’s Twitter feed: http://twitter.com/michaelrash,
1093 @michaelrash
1094
1096 The primary developers of fwknop are Michael Rash (project creator)
1097 <mbr@cipherdyne.org>, Damien Stuart <dstuart@dstuart.org>, and Jonathan
1098 Bennett <jbennett@incomsystems.biz>.
1099
1101 This “C” version of fwknop was derived from the original Perl-based
1102 version on which many people who are active in the open source
1103 community have contributed. See the CREDITS file in the fwknop sources,
1104 or visit https://github.com/mrash/fwknop/blob/master/CREDITS to view
1105 the online list of contributors. A few contributors deserve to be
1106 singled out including: Franck Joncourt, Max Kastanas, Vlad Glagolev,
1107 Sean Greven, Hank Leininger, Fernando Arnaboldi, and Erik Gomez.
1108 The phrase “Single Packet Authorization” was coined by MadHat and
1110 Simple Nomad at the BlackHat Briefings of 2005.
1111
1113 Send bug reports to dstuart@dstuart.org or mbr@cipherdyne.org, or open
1114 a new issue on Github (see https://github.com/mrash/fwknop.git).
1115 Suggestions and/or comments are always welcome as well. Additional
1116 information may be found in the fwknop mailing list archives (see:
1117 https://lists.sourceforge.net/lists/listinfo/fwknop-discuss).
1118
1120 fwknop is distributed under the GNU General Public License (GPL v2+),
1121 and the latest version may be downloaded from
1122 http://www.cipherdyne.org.
1123Fwknop Client 08/06/2018 FWKNOP(8)