fwknop - Firewall Knock Operator
fwknop -A <'proto/ports'>
-R|-a|-s -D <'host'> [options]
fwknop implements an authorization scheme known as Single
Packet Authorization (SPA) for strong service concealment. SPA requires only
a single packet which is encrypted, non-replayable, and authenticated via an
HMAC in order to communicate desired access to a service that is hidden
behind a firewall in a default-drop filtering stance. The main application
of SPA is to use a firewall to drop all attempts to connect to services such
as SSH in order to make the exploitation of vulnerabilities (both
0-day and unpatched code) more difficult. Any service that is concealed by
SPA naturally cannot be scanned for with Nmap. The fwknop project
natively supports four different firewalls: iptables,
firewalld, PF, and ipfw across Linux, OpenBSD, FreeBSD,
and Mac OS X. There is also support for custom scripts so that fwknop can be
made to support other infrastructure such as ipset or
nftables.
SPA is essentially next generation Port Knocking (PK), but solves
many of the limitations exhibited by PK while retaining its core benefits.
PK limitations include a general difficulty in protecting against replay
attacks, asymmetric ciphers and HMAC schemes are not usually possible to
reliably support, and it is trivially easy to mount a DoS attack against a
PK server just by spoofing an additional packet into a PK sequence as it
traverses the network (thereby convincing the PK server that the client
doesn’t know the proper sequence). All of these limitation are solved
by SPA. At the same time, SPA hides services behind a default-drop firewall
policy, acquires SPA data passively (usually via libpcap or other means),
and implements standard cryptographic operations for SPA packet
authentication and encryption/decryption.
This is the manual page for the fwknop client which is
responsible for constructing SPA packets and sending them over the network.
The server side is implemented by the fwknopd daemon which sniffs the
network for SPA packets and interacts with the local firewall to allow SPA
authenticated connections. It is recommended to read the fwknopd(8)
manual page as well. Further detailed information may be found in the
tutorial “Single Packet Authorization: A Comprehensive Guide to
Strong Service Concealment with fwknop” available online (see:
http://www.cipherdyne.org/fwknop/docs/fwknop-tutorial.html).
SPA packets generated by fwknop leverage HMAC for
authenticated encryption in the encrypt-then-authenticate model. Although
the usage of an HMAC is currently optional (enabled via the
--use-hmac command line switch), it is highly recommended for three
reasons: 1) without an HMAC, cryptographically strong authentication
is not possible with fwknop unless GnuPG is used, but even then an
HMAC should still be applied, 2) an HMAC applied after encryption
protects against cryptanalytic CBC-mode padding oracle attacks such as the
Vaudenay attack and related trickery (like the more recent "Lucky
13" attack against SSL), and 3) the code required by the
fwknopd daemon to verify an HMAC is much more simplistic than the
code required to decrypt an SPA packet, so an SPA packet without a proper
HMAC isn’t even sent through the decryption routines. Reason
3) is why an HMAC should still be used even when SPA packets are
encrypted with GnuPG due to the fact that SPA data is not sent through
libgpgme functions unless the HMAC checks out first. GnuPG and
libgpgme are relatively complex bodies of code, and therefore limiting the
ability of a potential attacker to interact with this code through an HMAC
operation helps to maintain a stronger security stance. Generating an HMAC
for SPA communications requires a dedicated key in addition to the normal
encryption key, and both can be generated with the --key-gen
option.
fwknop encrypts SPA packets either with the Rijndael
block cipher or via GnuPG and associated asymmetric cipher. If the
symmetric encryption method is chosen, then as usual the encryption key is
shared between the client and server (see the fwknopd
/etc/fwknop/access.conf file for details). The actual encryption key
used for Rijndael encryption is generated via the standard PBKDF1 key
derivation algorithm, and CBC mode is set. If the GnuPG method is chosen,
then the encryption keys are derived from GnuPG key rings. SPA packets
generated by fwknop running as a client adhere to the following format
(before encryption and the HMAC is applied):
random data (16 digits)
username
timestamp
software version
mode (command mode (0) or access mode (1))
if command mode => command to execute
else access mode => IP,proto,port
message digest (SHA512 / SHA384 / SHA256 / SHA1 / MD5 / SHA3_256 / SHA3_512)
Each of the above fields are separated by a ":"
character due to the variable length of several of the fields, and those
that might contain ":" characters are base64 encoded. The message
digest (SHA256 by default) is part of the data to be encrypted and is
independent of the HMAC which is appended to the SPA packet data after
encryption. The 16 digits of random data (about 53 bits) ensures that no two
SPA packets are identical, and this is in addition to and independent of
using PBKDF1 for key derivation for Rijndael in CBC mode (which uses an
8-byte random "salt" value). Because fwknopd tracks the
SHA256 digest of all incoming valid SPA packets and throws out duplicates,
replay attacks are not feasible against fwknop. Syslog alerts are
generated if a replay is detected.
By default, the fwknop client sends authorization packets
over UDP port 62201, but this can be altered with the --server-port
argument (this requires fwknopd to be configured to acquire SPA data
over the selected port). Also, fwknop can send the SPA packet over a
random port via the --rand-port argument. See fwknopd(8) for
further details. See the EXAMPLES section for example invocations of
the fwknop client.
The fwknop client is quite portable, and is known to run on
various Linux distributions (all major distros and embedded ones such as
OpenWRT as well), FreeBSD, OpenBSD, Mac OS X, and Cygwin on Windows. There
is also a library libfko that both fwknop and fwknopd
use for SPA packet encryption/decryption and HMAC authentication operations.
This library can be used to allow third party applications to use SPA
subject to the terms of the GNU General Public License (GPL v2+).
These required arguments can be specified via command-line or from
within the ~/.fwknoprc file (see -n, --named-config option and
the FWKNOPRC FILE section below).
-A, --access=<port list>
Provide a list of ports and protocols to access on a
remote computer running fwknopd. The format of this list is
“+<proto>/<port>...<proto>/<port>+”,
e.g. “tcp/22,udp/53”. NOTE: The vast majority of usages
for fwknop require the -A argument, but sending full commands
with the --server-cmd argument via an SPA packet to be executed by
fwknopd does not require this argument.
-D, --destination=<hostname/IP-address>
Direct the fwknop client to authenticate with the
fwknopd daemon/service at the specified destination hostname or IP
address. The connection mode is discovered by the fwknopd
daemon/service when it decrypts and parses the authentication packet.
-R|-a|-s
One of these options (see below) is required to tell the
remote
fwknopd daemon what IP should be allowed through the firewall.
It is recommend to use the
-R or
-a options instead of
-s
in order to harden SPA communications against possible
Man-In-The-Middle (MITM) attacks, and on the server side set
REQUIRE_SOURCE_ADDRESS variable in the
/etc/fwknop/access.conf
file. Note that the most secure option is
-a so that
fwknop does
not have to issue any HTTPS request to
https://www.cipherdyne.org/cgi-bin/myip in order to resolve the
externally routable IP address. Using
-a requires that the user already
knows what the external IP is for the network where fwknop is running.
-h, --help
Print a usage summary message and exit.
-G, --get-key=<file>
Load an encryption key/password from the specified file.
The key file contains a line for each destination hostname or IP address, a
colon (":"), optional space and the password, followed by a newline.
Note that the last line has to have a terminating newline character. Also
note: though this is a convenience, having a file on your system with clear
text passwords is not a good idea and is not recommended. Having the
fwknop client prompt you for the key is generally more secure. Note
also that if a key is stored on disk, the fwknop rc file is a more
powerful mechanism for specifying not only the key but other options as
well.
--stdin
Read the encryption key/password from stdin. This can be
used to send the data via a pipe for example. This command is similar to --fd
0.
--fd=<number>
Specify the file descriptor number to read the
key/password from. This command avoids the user being prompted for a password
if none has been found in the user specific stanza, or none has been supplied
on the command line. A file descriptor set to 0 is similar to the stdin
command.
--get-hmac-key=<file>
Load an HMAC key/password from the specified file.
Similarly to the format for the --get-key option, the HMAC key file
contains a line for each destination hostname or IP address, a colon
(":"), optional space and the password, followed by a newline. Note
that the last line has to have a terminating newline character. Also note:
though this is a convenience, having a file on your system with clear text
passwords is not a good idea and is not recommended. Having the fwknop
client prompt you for the HMAC key is generally more secure. Note also that if
a key is stored on disk, the fwknop rc file is a more powerful
mechanism for specifying not only the HMAC key but other options as
well.
--key-gen
Have fwknop generate both Rijndael and HMAC keys
that can be used for SPA packet encryption and authentication. These keys are
derived from /dev/urandom and then base64 encoded before being printed to
stdout, and are meant to be included within the
“$HOME/.fwknoprc” file (or the file referenced by
--get-key). Such keys are generally more secure than passphrases that
are typed in from the command line.
--key-gen-file=<file>
Write generated keys to the specified file. Note that the
file is overwritten if it already exists. If this option is not given, then
--key-gen writes the keys to stdout.
--key-len=<length>
Specify the number of bytes for a generated Rijndael key.
The maximum size is currently 128 bytes.
--hmac-key-len=<length>
Specify the number of bytes for a generated HMAC key. The
maximum size is currently 128 bytes.
-l, --last-cmd
Execute fwknop with the command-line arguments
from the previous invocation (if any). The previous arguments are parsed out
of the ~/.fwknop.run file.
-n, --named-config=<stanza name>
Specify the name of the configuration stanza in the
“$HOME/.fwknoprc” file to pull configuration and command
directives. These named stanzas alleviate the need for remembering the various
command-line arguments for frequently used invocations of fwknop. See
the section labeled, FWKNOPRC FILE below for a list of the valid configuration
directives in the .fwknoprc file.
--key-rijndael=<key>
Specify the Rijndael key on the command line. Since the
key may be visible to utilities such as ps under Unix, this form should
only be used where security is not critical. Having the fwknop client
either prompt you for the key or acquire via the
“$HOME/.fwknoprc” file is generally more secure.
--key-base64-rijndael=<key>
Specify the base64 encoded Rijndael key. Since the key
may be visible to utilities such as ps under Unix, this form should
only be used where security is not critical. Having the fwknop client
either prompt you for the key or acquire via the
“$HOME/.fwknoprc” file is generally more secure.
--key-base64-hmac=<key>
Specify the base64 encoded HMAC key. Since the key may be
visible to utilities such as ps under Unix, this form should only be
used where security is not critical. Having the fwknop client either
prompt you for the key or acquire via the “$HOME/.fwknoprc” file
is generally more secure.
--key-hmac=<key>
Specify the raw HMAC key (not base64 encoded). Since the
key may be visible to utilities such as ps under Unix, this form should
only be used where security is not critical. Having the fwknop client
either prompt you for the key or acquire via the
“$HOME/.fwknoprc” file is generally more secure.
--rc-file=<file>
Specify path to the fwknop rc file (default is
“$HOME/.fwknoprc”).
--no-rc-file
Perform fwknop client operations without
referencing the “$HOME/.fwknoprc” file.
--no-home-dir
Do not allow the fwknop client to look for the
home directory associated with the user.
--save-rc-stanza=<stanza name>
Save command line arguments to the
“$HOME/.fwknoprc” stanza specified with the -n option. If
the -n option is omitted, then the stanza name will default to the
destination server value (hostname or IP) given with the -D
argument.
--force-stanza
Used with --save-rc-stanza to overwrite all of the
variables for the specified stanza
--stanza-list
Dump a list of the stanzas found in
“$HOME/.fwknoprc”.
--show-last
Display the last command-line arguments used by
fwknop.
-E, --save-args-file=<file>
Save command line arguments to a specified file path.
Without this option, and when --no-save-args is not also specified,
then the default save args path is ~/.fwknop.run.
--no-save-args
Do not save the command line arguments given when
fwknop is executed.
-T, --test
Test mode. Generate the SPA packet data, but do not send
it. Instead, print a break-down of the SPA data fields, then run the data
through the decryption and decoding process and print the break-down again.
This is primarily a debugging feature.
-B, --save-packet=<file>
Instruct the fwknop client to write a newly
created SPA packet out to the specified file so that it can be examined
off-line.
-b, --save-packet-append
Append the generated packet data to the file specified
with the -B option.
--fault-injection-tag=<tag>
This option is only used for fault injection testing when
fwknop is compiled to support the libfiu library (see:
http://blitiri.com.ar/p/libfiu/). Under normal circumstances this
option is not used, and any packaged version of fwknop will not have code
compiled in so this capability is not enabled at run time. It is documented
here for completeness.
-v, --verbose
Run the fwknop client in verbose mode. This causes
fwknop to print some extra information about the current command and
the resulting SPA data.
-V, --version
Display version information and exit.
--use-hmac
Set HMAC mode for authenticated encryption of SPA
communications. As of fwknop 2.5, this is an optional feature, but this
will become the default in a future release.
-a, --allow-ip=<IP-address>
Specify IP address that should be permitted through the
destination
fwknopd server firewall (this IP is encrypted within the
SPA packet itself). This is useful to prevent a MITM attack where a SPA packet
can be intercepted en-route and sent from a different IP than the original.
Hence, if the
fwknopd server trusts the source address on the SPA
packet IP header then the attacker gains access. The
-a option puts the
source address within the encrypted SPA packet, and so thwarts this attack.
The
-a option is also useful to specify the IP that will be granted
access when the SPA packet itself is spoofed with the
--spoof-src
option. Another related option is
-R (see below) which instructs the
fwknop client to automatically resolve the externally routable IP
address the local system is connected to by querying
https://www.cipherdyne.org/cgi-bin/myip. This returns the actual IP
address it sees from the calling system.
-g, --gpg-encryption
Use GPG encryption on the SPA packet (default if not
specified is Rijndael). Note: Use of this option will also require a
GPG recipient (see --gpg-recipient along with other GPG-related options
below).
--hmac-digest-type=<digest>
Set the HMAC digest algorithm for authenticated
encryption of SPA packets. Choices are: MD5, SHA1, SHA256
(the default), SHA384, SHA512, SHA3_256, and
SHA3_512.
-N, --nat-access=<internalIP:forwardPort>
The fwknopd server offers the ability to provide
SPA access through an iptables firewall to an internal service by interfacing
with the iptables NAT capabilities. So, if the fwknopd server is
protecting an internal network on an RFC-1918 address space, an external
fwknop client can request that the server port forward an external port
to an internal IP, i.e. “+--NAT-access 192.168.10.2,55000+”. In
this case, access will be granted to 192.168.10.2 via port 55000 to whatever
service is requested via the --access argument (usually tcp/22). Hence,
after sending such an SPA packet, one would then do “ssh -p 55000
user@host” and the connection would be forwarded on through to the
internal 192.168.10.2 system automatically. Note that the port
“55000” can be randomly generated via the --nat-rand-port
argument (described later).
--nat-local
On the fwknopd server, a NAT operation can apply
to the local system instead of being forwarded through the system. That is,
for iptables firewalls, a connection to, say, port 55,000 can be translated to
port 22 on the local system. By making use of the --nat-local argument,
the fwknop client can be made to request such access. This means that
any external attacker would only see a connection over port 55,000 instead of
the expected port 22 after the SPA packet is sent.
--nat-port
Usually fwknop is used to request access to a
specific port such as tcp/22 on a system running fwknopd. However, by
using the --nat-port argument, it is possible to request access to a
(again, such as tcp/22), but have this access granted via the specified port
(so, the -p argument would then be used on the SSH client
command line). See the --nat-local and --nat-access command line
arguments to fwknop for additional details on gaining access to
services via a NAT operation.
--nat-rand-port
Usually fwknop is used to request access to a
specific port such as tcp/22 on a system running fwknopd. However, by
using the --nat-rand-port argument, it is possible to request access to
a particular service (again, such as tcp/22), but have this access granted via
a random translated port. That is, once the fwknop client has been
executed in this mode and the random port selected by fwknop is
displayed, the destination port used by the follow-on client must be changed
to match this random port. For SSH, this is accomplished via the
-p argument. See the --nat-local and --nat-access command
line arguments to fwknop for additional details on gaining access to
services via a NAT operation.
-p, --server-port=<port>
Specify the port number where fwknopd accepts
packets via libpcap or ulogd pcap writer. By default fwknopd looks for
authorization packets over UDP port 62201.
-P, --server-proto=<protocol>
Set the protocol (udp, tcp, http, udpraw, tcpraw, or
icmp) for the outgoing SPA packet. Note: The
udpraw,
tcpraw, and
icmp modes use raw sockets and thus require root access to run. Also
note: The
tcp mode expects to establish a TCP connection to the server
before sending the SPA packet. This is not normally done, but is useful for
compatibility with the Tor for strong anonymity; see
http://tor.eff.org/. In this case, the
fwknopd server will need
to be configured to listen on the target TCP port (which is 62201 by
default).
-Q, --spoof-src=<IP>
Spoof the source address from which the fwknop
client sends SPA packets. This requires root on the client side access since a
raw socket is required to accomplish this. Note that the --spoof-user
argument can be given in this mode in order to pass any
REQUIRE_USERNAME keyword that might be specified in
/etc/fwknop/access.conf.
-r, --rand-port
Instruct the fwknop client to send an SPA packet
over a random destination port between 10,000 and 65535. The fwknopd
server must use a PCAP_FILTER variable that is configured to accept
such packets. For example, the PCAP_FILTER variable could be set to:
“+udp dst portrange 10000-65535+”.
-R, --resolve-ip-https
This is an important option, and instructs the
fwknop client to issue an HTTPS request to a script running on
cipherdyne.org that returns the client’s IP address (as seen by
the web server). In some cases, this is needed to determine the IP address
that should be allowed through the firewall policy at the remote
fwknopd server side. This option is useful if the
fwknop client
is being used on a system that is behind an obscure NAT address, and the
external Internet facing IP is not known to the user. The full resolution URL
is:
https://www.cipherdyne.org/cgi-bin/myip, and is accessed by
fwknop via
wget in
--secure-protocol mode. Note that it
is generally more secure to use the
-a option if the externally
routable IP address for the client is already known to the user since this
eliminates the need for
fwknop to issue any sort of HTTPS
request.
--resolve-url <url>
Override the default URL used for resolving the source IP
address. For best results, the URL specified here should point to a web
service that provides just an IP address in the body of the HTTP
response.
--resolve-http-only
This option forces the fwknop client to resolve
the external IP via HTTP instead of HTTPS. There are some circumstances where
this might be necessary such as when wget is not available (or
hasn’t been compiled with SSL support), but generally this is not
recommended since it opens the possibility of a MITM attack through
manipulation of the IP resolution HTTP response. Either specify the IP
manually with -a, or use -R and omit this option.
-w, --wget-cmd=<wget full path>
Manually set the full path to the wget command.
Normally the configure script finds the wget command, but this
option can be used to specify the path if it is located in a non-standard
place.
-s, --source-ip
Instruct the fwknop client to form an SPA packet
that contains the special-case IP address “+0.0.0.0+” which will
inform the destination fwknopd SPA server to use the source IP address
from which the SPA packet originates as the IP that will be allowed through
upon modification of the firewall ruleset. This option is useful if the
fwknop client is deployed on a machine that is behind a NAT device and
the external IP is not known. However, usage of this option is not
recommended, and either the -a or -R options should be used
instead. The permit-address options -s, -R and -a are
mutually exclusive.
-S, --source-port=<port>
Set the source port for outgoing SPA packet.
--server-resolve-ipv4
This option forces the fwknop client to only
accept an IPv4 address from DNS when a hostname is used for the SPA server.
This is necessary in some cases where DNS may return both IPv6 and IPv4
addresses.
-f, --fw-timeout=<seconds>
Specify the length of time (seconds) that the remote
firewall rule that grants access to a service is to remain active. The default
maintained by fwknopd is 30 seconds, but any established connection can
be kept open after the initial accept rule is deleted through the use of a
connection tracking mechanism that may be offered by the firewall.
-C, --server-cmd=<command to execute>
Instead of requesting access to a service with an SPA
packet, the --server-cmd argument specifies a command that will be
executed by the fwknopd server. The command is encrypted within the SPA
packet and sniffed off the wire (as usual) by the fwknopd server.
-H, --http-proxy=<proxy-host>[:port]
Specify an HTTP proxy that the fwknop client will
use to send the SPA packet through. Using this option will automatically set
the SPA packet transmission mode (usually set via the --server-proto
argument) to "http". You can also specify the proxy port by adding
":<port>" to the proxy host name or ip.
-m, --digest-type=<digest>
Specify the message digest algorithm to use in the SPA
data. Choices are: MD5, SHA1, SHA256 (the default),
SHA384, and SHA512, SHA3_256, and SHA3_512.
-M, --encryption-mode=<mode>
Specify the encryption mode when AES is used for
encrypting SPA packets. The default is CBC mode, but others can be chosen such
as CFB or OFB as long as this is also specified in the
/etc/fwknop/access.conf file on the server side via the ENCRYPTION_MODE
variable. In general, it is recommended to not include this argument and let
the default (CBC) apply. Note that the string “legacy” can be
specified in order to generate SPA packets with the old initialization vector
strategy used by versions of fwknop prior to 2.5. With the 2.5 release,
fwknop generates initialization vectors in a manner that is compatible
with OpenSSL via the PBKDF1 algorithm.
--time-offset-plus=<time>
By default, the fwknopd daemon on the server side
enforces time synchronization between the clocks running on client and server
systems. The fwknop client places the local time within each SPA packet
as a time stamp to be validated by the fwknopd server after decryption.
However, in some circumstances, if the clocks are out of sync and the user on
the client system does not have the required access to change the local clock
setting, it can be difficult to construct and SPA packet with a time stamp the
server will accept. In this situation, the --time-offset-plus option
can allow the user to specify an offset (e.g. “60sec”
“60min” “2days” etc.) that is added to the local
time.
--time-offset-minus=<time>
This is similar to the --time-offset-plus option
(see above), but subtracts the specified time offset instead of adding it to
the local time stamp.
-u, --user-agent=<user-agent-string>
Set the HTTP User-Agent for resolving the external IP via
-R, or for sending SPA packets over HTTP.
--use-wget-user-agent
By default when the fwknop client resolves the
external IP with wget via SSL, it sets the User-Agent to
“Fwknop/<version>” unless it was already manually
specified with the --user-agent option mentioned above. However, the
--user-wget-user-agent option lets the default wget User-Agent
string apply without influence from fwknop.
-U, --spoof-user=<user>
Specify the username that is included within SPA packet.
This allows the fwknop client to satisfy any non-root
REQUIRE_USERNAME keyword on the fwknopd server (--spoof-src mode
requires that the fwknop client is executed as root).
--icmp-type=<type>
In -P icmp mode, specify the ICMP type value that
will be set in the SPA packet ICMP header. The default is echo reply.
--icmp-code=<code>
In -P icmp mode, specify the ICMP code value that
will be set in the SPA packet ICMP header. The default is zero.
Note that the usage of GPG for SPA encryption/decryption can and
should involve GPG keys that are signed by each side (client and server).
The basic procedure for this involves the following steps after the client
key has been transferred to the server and vice-versa:
[spaserver]# gpg --import client.asc
[spaserver]# gpg --edit-key 1234ABCD
Command> sign
[spaclient]$ gpg --import server.asc
[spaclient]$ gpg --edit-key ABCD1234
Command> sign
More comprehensive information on this can be found here:
http://www.cipherdyne.org/fwknop/docs/gpghowto.html.
--gpg-agent
Instruct fwknop to acquire GnuPG key password from
a running gpg-agent instance (if available).
--gpg-home-dir=<dir>
Specify the path to the GnuPG directory; normally this
path is derived from the home directory of the user that is running the
fwknop client (so the default is ~/.gnupg). This is useful when
a “root” user wishes to log into a remote machine whose sshd
daemon/service does not permit root login.
--gpg-recipient=<key ID or Name>
Specify the GnuPG key ID, e.g. “+1234ABCD+”
(see the output of "gpg—list-keys") or the key name
(associated email address) of the recipient of the Single Packet Authorization
message. This key is imported by the fwknopd server and the associated
private key is used to decrypt the SPA packet. The recipient’s key must
first be imported into the client GnuPG key ring.
--gpg-signer-key=<key ID or Name>
Specify the GnuPG key ID, e.g. “+ABCD1234+”
(see the output of "gpg --list-keys") or the key name to use when
signing the SPA message. The user is prompted for the associated GnuPG
password to create the signature. This adds a cryptographically strong
mechanism to allow the fwknopd daemon on the remote server to
authenticate who created the SPA message.
--gpg-no-signing-pw
Instruct fwknop to not acquire a passphrase for
usage of GnuPG signing key. This option is provided to make SPA packet
construction easier for client-side operations in automated environments where
the passphrase for the signing key has been removed from the GnuPG key ring.
However, it is usually better to leverage gpg-agent instead of using
this option.
The .fwknoprc file is used to set various parameters to
override default program parameters at runtime. It also allows for
additional named configuration stanzas for setting program parameters
for a particular invocation.
The fwknop client will create this file if it does not
exist in the user’s home directory. This initial version has some
sample directives that are commented out. It is up to the user to edit this
file to meet their needs.
The .fwknoprc file contains a default configuration area or
stanza which holds global configuration directives that override the program
defaults. You can edit this file and create additional named stanzas
that can be specified with the -n or --named-config option.
Parameters defined in the named stanzas will override any matching
default stanza directives. Note that command-line options will still
override any corresponding .fwknoprc directives.
There are directives to match most of the command-line parameters
fwknop supports. Here is the current list of each directive along
with a brief description and its matching command-line option(s):
SPA_SERVER <hostname/IP-address>
Specify the hostname or IP of the destination
(fwknopd) server (-D, --destination).
ALLOW_IP <IP-address>
Specify the address to allow within the SPA data. Note:
This parameter covers the -a, -s, and -R command-line
options. You can specify a hostname or IP address (the -a option),
specify the word "source" to tell the fwknopd server to
accept the source IP of the packet as the IP to allow (the -s option),
or use the word "resolve" to have fwknop resolve the external
network IP via HTTP request (the -R option).
ACCESS <port list>
Set the one or more protocol/ports to open on the
firewall (-A, --access). The format of this list is
“+<proto>/<port>...<proto>/<port>+”,
e.g. “tcp/22,udp/53”.
SPA_SERVER_PORT <port>
Set the server port to use for sending the SPA packet
(-p, --server-port).
SPA_SERVER_PROTO <protocol>
Set the protocol to use for sending the SPA packet
(-P, --server-proto).
KEY <passphrase>
This is the passphrase that is used for SPA packet
encryption and applies to both Rijndael or GPG encryption modes. The actual
encryption key that is used for Rijndael is derived from the PBKDF1 algorithm,
and the GPG key is derived from the specified GPG key ring.
KEY_BASE64 <base64 encoded passphrase>
Specify the encryption passphrase as a base64 encoded
string. This allows non-ascii characters to be included in the base64-decoded
key.
USE_HMAC <Y/N>
Set HMAC mode for authenticated encryption of SPA
packets. This will have fwknop prompt the user for a dedicated HMAC key
that is independent of the encryption key. Alternatively, the HMAC key can be
specified with the HMAC_KEY or HMAC_KEY_BASE64 directives (see
below).
HMAC_KEY <key>
Specify the HMAC key for authenticated encryption of SPA
packets. This supports both Rijndael and GPG encryption modes, and is applied
according to the encrypt-then-authenticate model.
HMAC_KEY_BASE64 <base64 encoded key>
Specify the HMAC key as a base64 encoded string. This
allows non-ascii characters to be included in the base64-decoded key.
HMAC_DIGEST_TYPE <digest algorithm>
Set the HMAC digest algorithm used for authenticated
encryption of SPA packets. Choices are: MD5, SHA1, SHA256
(the default), SHA384, SHA512, SHA3_256, and
SHA3_512.
SPA_SOURCE_PORT <port>
Set the source port to use for sending the SPA packet
(-S, --source-port).
FW_TIMEOUT <seconds>
Set the firewall rule timeout value (-f,
--fw-timeout).
RESOLVE_IP_HTTPS <Y/N>
Set to
Y to automatically resolve the externally
routable IP associated with the
fwknop client. This is done over SSL
via
wget in
--secure-protocol mode against the IP resolution
service available at
https://www.cipherdyne.org/cgi-bin/myip.
RESOLVE_HTTP_ONLY <Y/N>
When the fwknop client is instructed to resolve
the external client IP, this option can be used to force an HTTP
connection instead of an HTTPS connection when set to Y. This
option is useful when wget is not installed on the local OS, or when it
is not compiled against an SSL library.
RESOLVE_URL <url>
Set to a URL that will be used for resolving the source
IP address (--resolve-url).
WGET_CMD <wget full path>
Set the full path to the wget command (used for
client IP resolution).
TIME_OFFSET <time>
Set a value to apply to the timestamp in the SPA packet.
This can be either a positive or negative value
(--time-offset-plus/minus).
ENCRYPTION_MODE <mode>
Specify the encryption mode when AES is used. This
variable is a synonym for the -M, --encryption-mode command line
argument. In general, it is recommended to not include this argument and let
the default (CBC) apply. Note that the string “legacy” can be
specified in order to generate SPA packets with the old initialization vector
strategy used by versions of fwknop prior to 2.5.
DIGEST_TYPE <digest algorithm>
Set the SPA message digest type (-m,
--digest-type). Choices are: MD5, SHA1, SHA256 (the
default), SHA384, SHA512, SHA3_256, and
SHA3_512.
USE_GPG <Y/N>
Set to Y to specify the use of GPG for encryption
(--gpg-encryption).
USE_GPG_AGENT <Y/N>
Set to Y to have fwknop interface with a
GPG agent instance for the GPG key password (--gpg-agent). Agent
information itself is specified with the GPG_AGENT_INFO environmental
variable.
GPG_SIGNING_PW <passphrase>
This is the passphrase that is used for signing SPA
packet data in GPG encryption mode, and is a synonym for the KEY
variable (i.e. the signing passphrase can be specified with the KEY
variable instead). The SPA packet is encrypted with the remote server key and
signed with the local client key.
GPG_SIGNING_PW_BASE64 <base64 encoded
passphrase>
Specify the GPG signing passphrase as a base64 encoded
string. This allows non-ascii characters to be included in the base64-decoded
key.
GPG_SIGNER <key ID or Name>
Specify the GPG key name or ID for signing the
GPG-encrypted SPA data (--gpg-signer-key).
GPG_RECIPIENT <key ID or Name>
Specify the GPG key name or ID for the recipient of the
GPG-encrypted SPA data (--gpg-recipient-key).
GPG_HOMEDIR <dir>
Specify the GPG home directory (--gpg-home-dir).
Defaults to ~/.gnupg.
GPG_EXE <path>
Specify the path to GPG (--gpg-exe). Defaults to
/usr/bin/gpg.
SPOOF_USER <user>
Set the username in the SPA data to the specified value
(-U, --spoof-user).
SPOOF_SOURCE_IP <IP>
Set the source IP of the outgoing SPA packet to the
specified value (-Q, --spoof-source).
RAND_PORT <Y/N>
Send the SPA packet over a randomly assigned port (-r,
--rand-port).
KEY_FILE <file>
Load an encryption key/password from a file (-G,
--get-key).
HTTP_USER_AGENT <agent string>
Set the HTTP User-Agent for resolving the external IP via
-R, or for sending SPA packets over HTTP (-u, --user-agent).
USE_WGET_USER_AGENT <Y/N>
Allow default wget User-Agent string to be used
when resolving the external IP instead of a User-Agent supplied by the
fwknop client.
NAT_ACCESS <internalIP:forwardPort>
Gain NAT access to an internal service protected by the
fwknop server (-N, --nat-access).
NAT_LOCAL <Y/N>
Access a local service via a forwarded port on the
fwknopd server system (--nat-local).
NAT_PORT <port>
Specify the port to forward to access a service via NAT
(--nat-port).
NAT_RAND_PORT <Y/N>
Have the fwknop client assign a random port for NAT
access (--nat-rand-port).
SPOOF_USER, GPG_AGENT_INFO (only used in
--gpg-agent mode).
Because fwknop places the IP to be allowed through the
firewall within the encrypted SPA payload (unless -s is used which is
not recommended and can be prohibited in the fwknopd server
configuration), SPA packets can easily be spoofed, and this is a good thing
in this context. That is, the source IP of an SPA packet is ignored by the
fwknopd daemon (when the REQUIRE_SOURCE_ADDRESS variable is
set in the /etc/fwknop/access.conf file) and only the IP that is
contained within an authenticated and properly decrypted SPA packet is
granted access through the firewall. This makes it possible to make it
appear as though, say, www.yahoo.com is trying to authenticate to a target
system but in reality the actual connection will come from a seemingly
unrelated IP.
The following examples illustrate the command line arguments that
could be supplied to the fwknop client in a few situations:
The most effective and easiest way to use fwknop is to have
the client generate both an encryption key and an HMAC key, and then save
them to the “$HOME/.fwknoprc” file along with access request
specifics. The keys will also need to be transferred to the system where
fwknopd is running. The also client supports a separate set of
encryption and HMAC keys for each SPA destination if multiple fwknopd
servers are running on different systems.
So, assuming that the IP 2.2.2.2 is the system where
fwknopd is deployed and SSH is protected by the firewall on that
system in a default-drop stance, run the client like so to generate
encryption and HMAC keys:
$ fwknop -A tcp/22 --use-hmac -R -D 2.2.2.2 --key-gen --save-rc-stanza --verbose
[+] Wrote Rijndael and HMAC keys to rc file: /home/user/.fwknoprc
With the access request arguments and encryption and HMAC keys
generated and saved in “$HOME/.fwknoprc”, the keys themselves
need to be transferred to the 2.2.2.2 system where fwknopd is
running. As always, this should be done via some secure means such as SSH
before SPA is enabled and SSHD is blocked by the firewall. Here is what the
new 2.2.2.2 stanza looks like in the ~/.fwknoprc file:
$ tail -n 8 /home/user/.fwknoprc
[2.2.2.2]
ACCESS tcp/22
SPA_SERVER 2.2.2.2
KEY_BASE64 HvUtIOramehLGKimD4ECXOzinaH4h3U8H1WXum7b54Q=
HMAC_KEY_BASE64 DLeLf93a3yBT2vhEpM+dWlirGta5GU+jdyG5uXp4461HgOtbqMem4gX0Bp2PJGzYZlbbcavcOM00UPm+0GqkXA==
USE_HMAC Y
VERBOSE Y
RESOLVE_IP_HTTPS Y
The keys are base64 encoded blobs of random data, and both the
KEY_BASE64 and HMAC_KEY_BASE64 lines should be copied verbatim
and placed within the /etc/fwknop/access.conf file on 2.2.2.2.
Once this is done, fwknopd can be started on that system, a
default-drop policy against SSH connections can be put in place, and then
access to SSH is managed via fwknop. To access SSH, just use the -n
argument to reference the 2.2.2.2 stanza out of the .fwknoprc file
(some --verbose output is included for illustration):
$ fwknop -n 2.2.2.2
FKO Field Values:
=================
Random Value: 8950423288486978
Username: mbr
Timestamp: 1370194770
FKO Version: 2.5
Message Type: 1 (Access msg)
Message String: 1.1.1.1,tcp/22
Nat Access: <NULL>
Server Auth: <NULL>
Client Timeout: 0 (seconds)
Digest Type: 3 (SHA256)
HMAC Type: 3 (SHA256)
Encryption Type: 1 (Rijndael)
Encryption Mode: 2 (CBC)
...
$ ssh -l user 2.2.2.2
user@2.2.2.2's password:
The most common usage of fwknop is to gain access to SSH
running on a remote system that has the fwknopd daemon deployed along
with a default-drop firewall policy. The following command illustrates this
where IP 1.1.1.1 is the IP to be allowed through the firewall running
on 3.3.3.3 (note that the /etc/fwknop/access.conf file
consumed by fwknopd will need to have matching encryption and HMAC
keys, and configuration specifics can be found in the fwknopd(8)
manual page). Also, note the examples below prompt the user to supply the
encryption and HMAC keys via stdin instead of writing them to disk as in the
case of using the “$HOME/.fwknoprc” file in the example above.
However, all of the following examples can be converted to using the
~/.fwknoprc file just by adding the --save-rc-stanza argument:
$ fwknop -A tcp/22 --use-hmac -a 1.1.1.1 -D 3.3.3.3
Enter encryption key:
Enter HMAC key:
$ ssh -l user 3.3.3.3
user@3.3.3.3's password:
If the --verbose flag is added to the command line, then
some SPA packet specifics are printed to stdout (not all output is shown for
brevity):
$ fwknop -A tcp/22 --use-hmac -a 1.1.1.1 -D 3.3.3.3 --verbose
Enter encryption key:
Enter HMAC key:
Random Value: 1916307060193417
Username: mbr
Timestamp: 1368498909
FKO Version: 2.5
Message Type: 1 (Access msg)
Message String: 1.1.1.1,tcp/22
Nat Access: <NULL>
Server Auth: <NULL>
Client Timeout: 0 (seconds)
Digest Type: 3 (SHA256)
HMAC Type: 3 (SHA256)
Encryption Type: 1 (Rijndael)
Encryption Mode: 2 (CBC)
Simultaneous access to multiple services is also supported, and
here is an example of requesting access to both SSH and
OpenVPN on 3.3.3.3:
$ fwknop -A "tcp/22,tcp/1194" --use-hmac -a 1.1.1.1 -D 3.3.3.3
There are many cases where an fwknop client is deployed on
a network behind a NAT device and the externally routable IP is not known to
the user. In this case, use the IP resolution service available at
https://www.cipherdyne.org/cgi-bin/myip via the -R command
line switch in order to derive the external client IP address. This is a
safer method of acquiring the client IP address than using the -s
option mentioned earlier in this manual page because the source IP is put
within the encrypted packet instead of having the fwknopd daemon
grant the requested access from whatever IP address the SPA packet
originates (i.e. using -s opens the possibility of a MITM
attack):
$ fwknop -A tcp/22 --use-hmac -R -D 3.3.3.3
Use the Single Packet Authorization mode to gain access to
SSH and this time use GnuPG keys to encrypt and decrypt:
$ fwknop -A tcp/22 --use-hmac --gpg-sign ABCD1234 --gpg--recipient 1234ABCD -R -D 3.3.3.3
Instruct the fwknop server running at 3.3.3.3 to allow 1.1.1.1 to
connect to SSH, but spoof the authorization packet from an IP
associated with www.yahoo.com (requires root on the fwknop
client OS):
# fwknop --spoof-src "www.yahoo.com" -A tcp/22 --use-hmac -a 1.1.1.1 -D 3.3.3.3
When fwknopd is running on an iptables firewall with
systems deployed behind it, it is possible to take advantage of the NAT
capabilities offered by iptables in order to transparently reach systems
behind the firewall via SPA. Here is an example where the fwknop
client is used to gain access to SSH running on the non-routable IP
192.168.10.23 that is deployed on the network behind 3.3.3.3.
In this case, the SSH connection made to 3.3.3.3 is translated via
NAT to the 192.168.10.2 system automatically:
$ fwknop -A tcp/22 -N 192.168.10.2:22 -R -D 3.3.3.3
With the 2.5 release, fwknop underwent significant
changes in its usage of cryptography including the addition of support for
HMAC authenticated encryption for both Rijndael and GnuPG modes, ensuring
the proper usage of PBKDF1 for key derivation when SPA packets are encrypted
with Rijndael, and several bugs were fixed from previous versions of fwknop.
In general, this implies that when Rijndael is used, SPA packets produced by
the 2.5 release are incompatible with previous versions of fwknop.
The GnuPG encryption mode is unaffected by these updates. However, even with
Rijndael is used, backwards compatibility is supported through setting the
legacy encryption mode with -M on the fwknop client command
line and/or the ENCRYPTION_MODE variable in the
/etc/fwknop/access.conf file. This way, a pre-2.5 server can decrypt
SPA packets produced by a 2.5 and later client (set -M legacy), and a
2.5 and later server can decrypt SPA packets produced by pre-2.5 clients
(set ENCRYPTION_MODE legacy in the access.conf file). Note that HMAC
is only supported as of 2.5 and is an optional feature, so backwards
compatibility is only for configurations that don’t use an HMAC on
either side. It is strongly recommended to upgrade all fwknop clients and
servers to 2.5 and use the new HMAC mode for properly authenticated SPA
communications. The backwards compatibility support is used to make it
easier to upgrade clients and servers with a phased approach.
For emphasis, if the fwknopd server is upgraded to 2.5 (or
later), but older clients cannot be upgraded at the same time, then for each
SOURCE stanza in the /etc/fwknop/access.conf file, add the
following line:
In addition, if the KEY variable has an encryption key
longer than 16 bytes, it will need to be truncated to 16 characters in the
access.conf file in order for pre-2.5 clients to work properly. This
limitation is fixed in 2.5, and provides additional motivation for upgrading
all clients and servers to 2.5 or later.
Now, flipping the scenario around, if the fwknop clients
are upgraded but the fwknopd server is still at a pre-2.5 version,
then add the -M legacy argument to the fwknop command line:
$ fwknop -A tcp/22 -M legacy -R -D 2.2.2.2
The fwknop client requires libfko which is normally
included with both source and binary distributions, and is a dedicated
library developed by the fwknop project. Whenever the fwknopd server
is used, libpcap is a required dependency. However, the upcoming
2.6 release will offer a UDP listener mode along with privilege
separation support and will not require libpcap in this mode. In UDP
listener mode, even though fwknopd binds to a UDP port, SPA packets are
never acknowledged so from an attacker’s perspective there is no
difference between fwknopd sniffing the wire passively vs. listening on a
UDP socket in terms of what can be scanned for.
For GPG functionality, GnuPG must also be correctly installed and
configured along with the libgpgme library.
To take advantage of all of the authentication and access
management features of the fwknopd daemon/service a functioning
iptables, ipfw, or pf firewall is required on the
underlying operating system.
The most comprehensive way to gain diagnostic information on
fwknop is to run the test suite test-fwknop.pl script located
in the test/ directory in the fwknop sources. The test suite sends
fwknop through a large number of run time tests, has valgrind
support, validates both SPA encryption and HMAC results against OpenSSL, and
even has its own built in fuzzer for SPA communications (and fwknop in
version 2.6.4 supports the American Fuzzy Lop (AFL) from Michal
Zalewski as well). For more basic diagnostic information, fwknop can
be executed with the -T (or --test) command line option. This
will have fwknop simply create and print the SPA packet information,
then run it through a decrypt/decode cycle and print it again. In addition,
the --verbose command line switch is useful to see various SPA packet
specifics printed to stdout.
fwknopd(8), iptables(8), pf(4), pfctl(8), ipfw(8), gpg(1), libfko
documentation.
More information on Single Packet Authorization can be found in
the paper “Single Packet Authorization with fwknop” available
at http://www.cipherdyne.org/fwknop/docs/SPA.html. A comprehensive
tutorial on fwknop operations and theory can be found at
http://www.cipherdyne.org/fwknop/docs/fwknop-tutorial.html. This
tutorial also includes information about the design of fwknop that
may be worth reading for those interested in why fwknop is different from
other SPA implementations.
fwknop uses the git versioning system as its source
code repository along with Github for tracking of issues and
milestones:
$ git clone https://github.com/mrash/fwknop.git fwknop.git
Additional commentary on Single Packet Authorization can be found
via Michael Rash’s Twitter feed: http://twitter.com/michaelrash,
@michaelrash
The primary developers of fwknop are Michael Rash (project
creator) <mbr@cipherdyne.org>, Damien Stuart
<dstuart@dstuart.org>, and Jonathan Bennett
<jbennett@incomsystems.biz>.
This “C” version of fwknop was derived from the
original Perl-based version on which many people who are active in the open
source community have contributed. See the CREDITS file in the fwknop
sources, or visit https://github.com/mrash/fwknop/blob/master/CREDITS
to view the online list of contributors. A few contributors deserve to be
singled out including: Franck Joncourt, Max Kastanas, Vlad Glagolev, Sean
Greven, Hank Leininger, Fernando Arnaboldi, and Erik Gomez.
The phrase “Single Packet Authorization” was coined
by MadHat and Simple Nomad at the BlackHat Briefings of 2005.
fwknop is distributed under the GNU General Public License
(GPL v2+), and the latest version may be downloaded from
http://www.cipherdyne.org.