[docs] fwknop client man page update for HMAC material
This commit is contained in:
Michael Rash
parent
e73d13e140
commit
e1a7011bf3
@ -16,40 +16,55 @@ SYNOPSIS
|
||||
DESCRIPTION
|
||||
-----------
|
||||
*fwknop* implements an authorization scheme known as Single Packet
|
||||
Authorization (SPA) for Linux systems running iptables. This mechanism
|
||||
requires only a single encrypted and non-replayed packet to communicate
|
||||
various pieces of information including desired access through an iptables
|
||||
or ipfw policy. The main application of this program is to use iptables
|
||||
in a default-drop stance to protect services such as 'SSH' with an
|
||||
Authorization (SPA) for passive service protection. SPA requires only a single
|
||||
non-replayed encrypted packet together with an HMAC in order to communicate
|
||||
various pieces of information including desired access to a service that is
|
||||
otherwise blocked by a firewall. The main application of SPA is to use a
|
||||
firewall in a default-drop stance to protect services such as 'SSH' with an
|
||||
additional layer of security in order to make the exploitation of
|
||||
vulnerabilities (both 0-day and unpatched code) much more difficult.
|
||||
vulnerabilities (both 0-day and unpatched code) more difficult. In
|
||||
addition, services that are protected in this fashion naturally cannot be
|
||||
scanned for with 'Nmap'.
|
||||
|
||||
An authorization server *fwknopd* passively monitors authorization packets
|
||||
via 'libpcap' and hence there is no ``server'' to which to connect in the
|
||||
traditional sense. Any service protected by *fwknop* is inaccessible (by
|
||||
using 'iptables' or 'ipfw' to intercept packets within the kernel) before
|
||||
authenticating; anyone scanning for the service will not be able to detect
|
||||
that it is even listening. Single Packet Authorization offers many
|
||||
advantages over port knocking, including non-replayability of SPA packets,
|
||||
ability to use asymmetric ciphers (such as Elgamal), and SPA cannot be
|
||||
broken by simply spoofing packets to duplicate ports within the knock
|
||||
sequence on the server to break port knocking authentication.
|
||||
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 supported, 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 lightweight cryptographic operations
|
||||
for SPA packet authentication and encryption/decryption.
|
||||
|
||||
SPA packets can easily be spoofed as well (this is a good thing in this
|
||||
context), and 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.
|
||||
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 it is recommended to read the 'fwknopd(8)' manual page as well.
|
||||
|
||||
Authorization packets are either encrypted with the 'Rijndael' block cipher
|
||||
or via 'GnuPG' and associated asymmetric ciphers. If the symmetric encryption
|
||||
method is chosen, then the encryption key is shared between the client and
|
||||
server (see the fwknopd 'access.conf' file for details). If the GnuPG method
|
||||
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, it is highly recommended for three reasons: '1)' without
|
||||
an HMAC, cryptographically strong authentication is not possible unless GnuPG
|
||||
is used, '2)' an HMAC applied after encryption protects against CBC-mode
|
||||
padding oracle attacks (see the Vaudenay attack and 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 event
|
||||
sent through the decryption routines. Generating an HMAC requires a dedicated
|
||||
key in addition to the normal encryption key.
|
||||
|
||||
*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* 'access.conf' file for details). 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 they are encrypted):
|
||||
format (before encryption and the HMAC is applied):
|
||||
|
||||
..........................
|
||||
random number (16 bytes)
|
||||
random data (16 bytes)
|
||||
username
|
||||
timestamp
|
||||
software version
|
||||
@ -59,27 +74,24 @@ format (before they are encrypted):
|
||||
message digest (SHA512 / SHA384 / SHA256 / SHA1 / MD5)
|
||||
..........................
|
||||
|
||||
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 in all versions of *fwknop* greater than 1.9.1) allows the server
|
||||
to check message integrity after decryption, and the 16 bytes of random data
|
||||
ensures (with high probability) that no two messages are identical. This
|
||||
ensures that replay attacks are not possible against *fwknop*.
|
||||
|
||||
For each packet coming from an *fwknop* client, the *fwknopd* server can
|
||||
cache the digest calculated over the entire packet and compares against
|
||||
previous packet digests in order to detect attempted replay attacks. Syslog
|
||||
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 bytes of random data 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. Because *fwknopd*
|
||||
tracks the SHA256 digest of all incoming valid SPA packets and throws out
|
||||
duplicates, replay attacks are not possible 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. The server
|
||||
must first be configured to acquire the SPA data on the changed protocol-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.
|
||||
|
||||
|
||||
REQUIRED ARGUMENTS
|
||||
------------------
|
||||
These required arguments can be specified via command-line or from within
|
||||
@ -130,8 +142,8 @@ GENERAL OPTIONS
|
||||
with cleartext 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 the key but other
|
||||
options as well.
|
||||
file is a more powerful mechanism for specifying not only the key but
|
||||
other options as well.
|
||||
|
||||
*--get-hmac-key*='<file>'::
|
||||
Load an HMAC key/password from the specified file. Similarly to the
|
||||
@ -143,7 +155,8 @@ GENERAL OPTIONS
|
||||
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 the key but other options as well.
|
||||
mechanism for specifying not only the HMAC key but other options as
|
||||
well.
|
||||
|
||||
*--key-rijndael*='<key>'::
|
||||
Specify the Rijndael key. Since the key may be visible to utilities
|
||||
@ -266,11 +279,12 @@ SPA OPTIONS
|
||||
The default is CBC mode, but others can be chosen such as CFB or OFB
|
||||
as long as this is also specified in the 'access.conf' file on the
|
||||
server side via the ENCRYPTION_MODE variable. In general, it is
|
||||
recommended to not use this argument and just use the default. 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*
|
||||
before 2.5. With the 2.5 release, *fwknop* generates initialization
|
||||
vectors in a manner that is compatible with OpenSSL.
|
||||
recommended to not use this argument and just use the default (CBC).
|
||||
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.
|
||||
|
||||
*--hmac-digest-type*='<digest>'::
|
||||
Set the HMAC digest algorithm (default is sha256). Options are md5, sha1,
|
||||
@ -368,7 +382,9 @@ SPA OPTIONS
|
||||
*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.
|
||||
*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.
|
||||
|
||||
@ -558,6 +574,18 @@ ENVIRONMENT
|
||||
-----------
|
||||
*SPOOF_USER*, *GPG_AGENT_INFO* (only used in *--gpg-agent* mode).
|
||||
|
||||
SPA PACKET SPOOFING
|
||||
-------------------
|
||||
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 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.
|
||||
|
||||
EXAMPLES
|
||||
--------
|
||||
The following examples illustrate the command line arguments that could
|
||||
@ -565,17 +593,23 @@ be supplied to the fwknop client in a few situations:
|
||||
|
||||
Access mode examples
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
Packet contents printed to stdout at the fwknop client when creating
|
||||
an ``access mode'' SPA packet:
|
||||
Packet contents printed to stdout by the fwknop client in *--verbose* mode when
|
||||
creating a normal ``access mode'' SPA packet with a SHA256 HMAC applied:
|
||||
|
||||
..........................
|
||||
Random data: 6565240948266426
|
||||
Username: mbr
|
||||
Timestamp: 1203863233
|
||||
Version: 1.9.2
|
||||
Type: 1 (access mode)
|
||||
Access: 127.0.0.2,tcp/22
|
||||
SHA256 sum: gngquSL8AuM7r27XsR4qPmJhuBo9pG2PYwII06AaJHw
|
||||
Random Value: 1916307060193417
|
||||
Username: mbr
|
||||
Timestamp: 1368498909
|
||||
FKO Version: 2.5.0
|
||||
Message Type: 1 (Access msg)
|
||||
Message String: 127.0.0.2,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)
|
||||
..........................
|
||||
|
||||
Use the Single Packet Authorization mode to gain access to
|
||||
@ -583,7 +617,9 @@ tcp/22 (ssh) and udp/53 running on the system 10.0.0.123 from
|
||||
the IP 192.168.10.4:
|
||||
|
||||
..........................
|
||||
$ fwknop -A "tcp/22,udp/53" -a 192.168.10.4 -D 10.0.0.123
|
||||
$ fwknop -A "tcp/22,udp/53" --use-hmac -a 192.168.10.4 -D 10.0.0.123
|
||||
Enter encryption key:
|
||||
Enter HMAC key:
|
||||
..........................
|
||||
|
||||
Same as above example, but gain access from whatever source IP
|
||||
@ -591,17 +627,22 @@ is seen by the fwknop server (useful if the fwknop client is
|
||||
behind a NAT device):
|
||||
|
||||
..........................
|
||||
$ fwknop -A "tcp/22,udp/53" -s -D 10.0.0.123
|
||||
$ fwknop -A "tcp/22,udp/53" --use-hmac -s -D 10.0.0.123
|
||||
Enter encryption key:
|
||||
Enter HMAC key:
|
||||
..........................
|
||||
|
||||
Same as above example, but use an IP identification website to derive
|
||||
the client IP address. This is a safer method of acquiring the client
|
||||
Same as above example, but use the IP resolution service available at
|
||||
'http://www.cipherdyne.org/cgi-bin/myip' to derive the external client IP
|
||||
address. This is a safer method of acquiring the client
|
||||
IP address than using the *-s* option 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:
|
||||
|
||||
..........................
|
||||
$ fwknop -A "tcp/22,udp/53" -R -D 10.0.0.123
|
||||
$ fwknop -A "tcp/22,udp/53" --use-hmac -R -D 10.0.0.123
|
||||
Enter encryption key:
|
||||
Enter HMAC key:
|
||||
..........................
|
||||
|
||||
Use the Single Packet Authorization mode to gain access to tcp/22
|
||||
@ -609,8 +650,9 @@ Use the Single Packet Authorization mode to gain access to tcp/22
|
||||
to encrypt and decrypt:
|
||||
|
||||
..........................
|
||||
$ fwknop -A "tcp/22,udp/53" --gpg-sign ABCD1234 --gpg--recipient
|
||||
1234ABCD -R -D 10.0.0.123
|
||||
$ fwknop -A "tcp/22,udp/53" --use-hmac --gpg-sign ABCD1234 --gpg--recipient 1234ABCD -R -D 10.0.0.123
|
||||
Enter encryption key:
|
||||
Enter HMAC key:
|
||||
..........................
|
||||
|
||||
Instruct the fwknop server running at 10.0.0.123 to allow 172.16.5.4
|
||||
@ -618,21 +660,24 @@ to connect to TCP/22, but spoof the authorization packet from an IP
|
||||
associated with www.yahoo.com:
|
||||
|
||||
..........................
|
||||
# fwknop --Spoof-src ’www.yahoo.com’ -A tcp/22 -a 172.16.5.4 -D
|
||||
10.0.0.123
|
||||
# fwknop --Spoof-src ’www.yahoo.com’ -A tcp/22 --use-hmac -a 172.16.5.4 -D 10.0.0.123
|
||||
Enter encryption key:
|
||||
Enter HMAC key:
|
||||
..........................
|
||||
|
||||
|
||||
DEPENDENCIES
|
||||
------------
|
||||
*fwknop* requires 'libfko' (which is normally included with both source and
|
||||
binary distributions).
|
||||
binary distributions). Whenever the *fwknopd* server is used, libpcap is a
|
||||
required dependency.
|
||||
|
||||
For GPG functionality, GnuPG must also be correctly installed and configured.
|
||||
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 firewall
|
||||
is required on the underlying operating system.
|
||||
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.
|
||||
|
||||
|
||||
DIAGNOSTICS
|
||||
@ -647,7 +692,12 @@ fwknopd(8), iptables(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'.
|
||||
'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.
|
||||
|
||||
AUTHORS
|
||||
-------
|
||||
@ -667,12 +717,10 @@ Nomad at the BlackHat Briefings of 2005 (see: 'http://www.nmrc.org').
|
||||
|
||||
BUGS
|
||||
----
|
||||
Send bug reports to dstuart@dstuart.org or mbr@cipherdyne.org. Suggestions
|
||||
Send bug reports to dstuart@dstuart.org or mbr@cipherdyne.org. Suggestions
|
||||
and/or comments are always welcome as well.
|
||||
|
||||
DISTRIBUTION
|
||||
------------
|
||||
*fwknop* is distributed under the GNU General Public License (GPL), and
|
||||
the latest version may be downloaded from 'http://www.cipherdyne.org'.
|
||||
|
||||
|
||||
*fwknop* is distributed under the GNU General Public License (GPL) version 2,
|
||||
and the latest version may be downloaded from 'http://www.cipherdyne.org'.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user