FWKNOPD(8)

📦
version 2.6.11 · 3 versions
, in alpine 3.24, arch rolling, epel 10, epel 9, fedora 43, fedora 44, opensuse-leap 16.0

🌸 FWKNOPD(8) 🌸

okay bestie, buckle up — this is the manual page for fwknopd, the Fwknop Server 💅 (that's the FWKNOPD(8) bit at the top of the page if you were wondering, we're folding it in right here so it doesn't get lost ✨)

✨ NAME ✨

fwknopd — Firewall Knock Operator Daemon 🫶

🎀 SYNOPSIS 🎀

fwknopd [options]

🦋 DESCRIPTION 🦋

okay so fwknopd is the server component for the FireWall Knock Operator, and it is literally responsible for monitoring and processing Single Packet Authorization (SPA) packets — the ones generated by fwknop clients 💖 — then modifying a firewall or ACL policy to allow the desired access after authenticating and decrypting a valid SPA packet (in that order, no skipping steps bestie, the order matters 😤), and then removing that access after a configurable timeout. the way it just cleans up after itself? obsessed.

the main application of this program is to conceal services such as SSH with an additional layer of security so that exploiting vulnerabilities (both 0-day and unpatched code, yes really) becomes much more difficult 🔥 and like, bonus: services that are concealed in this fashion naturally cannot be scanned for with Nmap or Shodan. they just can't see you. main character invisibility energy 😌👑

the main configuration for fwknopd lives in two files: fwknopd.conf and access.conf. the default location for these files is determined at package configuration (typically /etc/fwknop). the configuration variables inside these files are described below 💜

more info can 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) 📚

⭐ COMMAND-LINE OPTIONS ⭐

  • -i, --interface=<interface> — manually specify the interface to sniff on, like -i eth0. usually you don't need this because the PCAP_INTF keyword in the fwknopd.conf file already defines the sniffing interface 🧚
  • -f, --foreground — run fwknopd in the foreground instead of becoming a daemon. when it runs in the foreground, messages that would go to the log get sent to stderr instead. this mode is usually used for testing and/or debugging 🐛
  • --fw-list — list only the firewall rules that any running fwknopd daemon has created, then exit. like a little receipts check 🧾
  • -a, --access-file=<access-file> — specify the location of the access.conf file. if you don't give this option, fwknopd uses the compile-time default location (typically /etc/fwknop/access.conf) 💅
  • --access-folder=<access-folder> — specify the location of the access.conf folder. if you give this option, instead of loading a single access.conf file, all the .conf files in the given folders are processed 🗂️
  • -c, --config=<config-file> — specify the location of the fwknopd.conf file. if you don't give this option, fwknopd uses the default location (typically /etc/fwknop/fwknopd.conf) ⚙️
  • -C, --packet-limit=<n> — specify the number of candidate SPA packets to process, and exit when this limit is reached 🔢
  • -d, --digest-file=<digest-file> — specify the location of the digest.cache file. if you don't give this option, fwknopd uses the compile-time default location (typically /var/fwknop/digest.cache) 🍓
  • -D, --dump-config — dump the configuration values that fwknopd derives from /etc/fwknop/fwknopd.conf (or override files) and /etc/fwknop/access.conf onto stderr 📤
  • --dump-serv-err-codes — dump all possible fwknopd error codes to stdout and exit. this option is rarely needed in practice and was added to assist with test coverage 🧪
  • --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's documented here for completeness 🫡
  • -A, --afl-fuzzing — tell fwknopd to acquire SPA packets directly from stdin in support of fuzzing operations from the American Fuzzy Lop (AFL) fuzzer written by Michal Zalewski. this requires that fwknop is compiled with the --enable-afl-fuzzing argument to the configure script, because that allows encryption/digest short circuiting in the manner necessary for AFL to function properly. the benefit of this strategy is that AFL can fuzz the SPA packet decoding routines implemented by libfko 🔬
  • --fw-list-all — list all firewall rules, including the ones that have nothing to do with fwknopd 👀
  • --fw-flush — flush any firewall rules created by a running fwknopd process. this option lets the user easily delete fwknopd firewall rules without having to wait for them to time out ⏰
  • -K, --kill — kill the current fwknopd process. quick and easy way to stop fwknopd without having to go digging around in the process table 💀
  • --exit-parse-config — parse the config files (/etc/fwknop/fwknopd.conf and /etc/fwknop/access.conf) and then exit. this is a way to test whether the config files are properly structured without having to start processing network traffic ✅
  • --exit-parse-digest-cache — parse the digest cache file /var/fwknop/digest.cache and exit. this validates the structure of the digest cache file without having to start processing network traffic. note that the standard configuration files are also parsed in this mode 🗃️
  • -l, --locale=<locale> — set/override the system default locale setting 🌍
  • --no-ipt-check-support — disable the usage of the iptables -C option. this isn't normally needed, and is only useful on older Linux distributions where iptables doesn't have -C support 🐧
  • -O, --override-config=<file> — override config variable values that are normally read from the /etc/fwknop/fwknopd.conf file with values from the specified file. multiple override config files can be given as a comma-separated list 📝
  • --key-gen — have fwknopd 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 they're meant to be manually included in a stanza within the /etc/fwknop/access.conf file. such keys are generally more secure than passphrases 🔑✨
  • --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 📐
  • -p, --pid-file=<pid-file> — specify the location of the fwknopd.pid file. if you don't give this option, fwknopd uses the compile-time default location (typically /var/fwknop/fwknopd.pid) 🪪
  • -P, --pcap-filter=<filter> — specify a Berkeley packet filter statement on the fwknopd command line. this overrides the value of the PCAP_FILTER variable taken from the /etc/fwknop/fwknopd.conf file 🎯
  • --pcap-file=<pcap-file> — this option instructs fwknopd to read packet data from a pcap file instead of sniffing an interface directly. this mode is usually used for debugging purposes, and it will disable SPA packet age checking unless it's manually enabled in the /etc/fwknop/fwknopd.conf file 🎬
  • --pcap-any-direction — allow fwknopd to sniff SPA packets regardless of whether they're received on the sniffing interface or sent from the sniffing interface. in the latter case, this can be useful to have fwknopd sniff SPA packets that are forwarded through a system and destined for a different network. if the sniffing interface is the egress interface for such packets (and hence SPA packets are sent by this interface instead of received), then this option will need to be used in order for fwknopd to see them. the default is to only sniff packets that are received on the sniffing interface. note that this setting is independent of promiscuous mode 👁️👁️
  • -R, --restart — restart the currently running fwknopd processes. this option preserves the command line options that were supplied to the original fwknopd process but forces fwknopd to re-read the fwknopd.conf and /etc/fwknop/access.conf files. this will also force a flush of the current “FWKNOP” iptables chain(s) 🔄
  • --rotate-digest-cache — rotate the digest cache file by renaming it to “<name>-old”, and starting a new one. the digest cache file is typically found in /var/fwknop/digest.cache 🌀
  • -r, --run-dir=<path> — specify the directory where fwknopd writes run time state files. the default is /var 🏠
  • -S, --status — display the status of any fwknopd processes that may or may not be running. if there's an existing fwknopd process then 0 is returned for the exit status, and 1 is returned otherwise 🔍
  • --syslog-enable — allow messages to be sent to syslog even if the foreground mode is set 📨
  • -t, --test — run fwknopd in test mode. this instructs fwknopd to acquire and process SPA packets, but not manipulate firewall rules or execute commands that are provided by SPA clients. mostly useful for the fuzzing tests in the test suite to ensure broad code coverage under adverse conditions 🧫
  • -U, --udp-server — run fwknopd in UDP server mode so that SPA packets are acquired via a UDP socket directly, without having to use libpcap. see the discussion of the “ENABLE_UDP_SERVER” configuration variable below for more information 📡
  • -v, --verbose — run fwknopd in verbose mode. this option can be specified multiple times to increase the verbosity of the output to the system log file (or to the screen if running in the foreground) 🗣️
  • -h, --help — display usage information and exit 💁‍♀️
  • -V, --Version — display version information and exit 🏷️

👑 FWKNOPD CONFIG AND ACCESS VARIABLES 👑

fwknopd references the /etc/fwknop/fwknopd.conf file for configuration variables that define operational parameters (what network interface and port to sniff, what features to enable/disable, etc.). the fwknopd.conf file does not define any access control directives or set any encryption or authentication keys 🚫🔑

the access control directives live in the /etc/fwknop/access.conf file. access control directives define encryption keys and the level of access that is granted to an fwknop client that has generated the appropriate encrypted SPA message 🔐💖

🎀 FWKNOPD.CONF VARIABLES 🎀

Okay bestie, this is the part where we go through the more prominent config variables that fwknopd actually reads 💖. You're gonna wanna double-check these so they have values that make sense for your setup, but ngl, sensible defaults are already baked in for most systems — so like, don't panic. For extra deets, go peek at /etc/fwknop/fwknopd.conf itself. ✨

  • PCAP_INTF <interface> — tells fwknopd which ethernet interface to sniff packets on. That's it. That's the whole vibe check. 🦋
  • ENABLE_PCAP_PROMISC <Y/N> — by default fwknopd puts the pcap interface into promiscuous mode (iconic of it). Set this to N to turn that off (aka non-promiscuous).
  • PCAP_FILTER <pcap filter spec> — the filter used for PCAP modes; fwknopd defaults to UDP port 62201. BUT — and this is important — if an fwknop client uses the --rand-port option to send the SPA packet over a random port, then you gotta update this variable to something like udp dst portrange 10000-65535. Periodt. 💅
  • ENABLE_SPA_PACKET_AGING <Y/N> — this tells fwknopd to not honor SPA packets that have an old time stamp. What counts as "old" is defined by the MAX_SPA_PACKET_AGE variable. And if ENABLE_SPA_PACKET_AGING is set to N, fwknopd won't use the client time stamp at all. Zero time checking. None. 🙈
  • MAX_SPA_PACKET_AGE <seconds> — the maximum age (in seconds) an SPA packet will be accepted. Heads up: this requires the client system to be in relatively close time sync with the fwknopd server system (NTP is good, bestie). Default age is 120 seconds (two minutes). ⭐
  • ENABLE_DIGEST_PERSISTENCE <Y/N> — tracks the digest sums associated with previous SPA packets that fwknopd has processed, which keeps those digest sums persistent across executions of fwknopd. Default is Y. If it's set to N, fwknopd won't check incoming SPA packet data against any previously saved digests — and honestly? It's a good idea to leave this feature on, because it reduces the possibility of being vulnerable to a replay attack. Keep it on, babe. 🔥
  • RULES_CHECK_THRESHOLD <count> — defines how many times firewall rule expiration times must be checked before a "deep" check gets run. This is what lets fwknopd remove rules that contain a proper exp<time> even if a third party program added them instead of fwknopd itself. Default value is 20, and that typically results in this check running every two seconds or so. Wanna disable this type of checking entirely? Set this variable to zero. Done. 💀
  • ENABLE_IPT_FORWARDING <Y/N> — lets SPA clients request access to services through an iptables firewall instead of just to it — meaning access through the FWKNOP_FORWARD chain instead of the INPUT chain. 🧚
  • ENABLE_IPT_LOCAL_NAT <Y/N> — lets SPA clients request access to a local socket via NAT. This still puts an ACCEPT rule into the FWKNOP_INPUT chain, but a different port gets translated via DNAT rules to the real one. So the user would do ssh -p <port> to access the local service (peep the --NAT-local and --NAT-rand-port on the fwknop client command line 😌).
  • ENABLE_IPT_SNAT <Y/N> — set this to Y to enable a corresponding SNAT rule. By default, if forwarding access is enabled (see the ENABLE_IPT_FORWARDING variable above), fwknopd creates DNAT rules for incoming connections but does not also complement those rules with SNAT rules at the same time. Sometimes internal systems don't have a route back out for the source address of the incoming connection — in those situations it's necessary to also apply SNAT rules so the internal systems see the IP of the internal interface where fwknopd is running. 🌸
  • SNAT_TRANSLATE_IP <ip_address> — the IP address for SNAT. This functionality is only enabled when ENABLE_IPT_SNAT is set to Y, and by default SNAT rules are built with the MASQUERADE target (since then the internal IP doesn't have to be defined here in the /etc/fwknop/fwknopd.conf file). But if you want fwknopd to use the SNAT target, you must also define an IP address with the SNAT_TRANSLATE_IP variable. Note that this variable is generally deprecated in favor of the FORCE_SNAT variable in the /etc/fwknop/access.conf file, which enables per-stanza control over the SNAT IP. 👑
  • ENABLE_IPT_OUTPUT <Y/N> — adds ACCEPT rules to the FWKNOP_OUTPUT chain. This is usually only useful if there are no state tracking rules to allow connection responses out, and the OUTPUT chain has a default-drop stance. 🫶
  • MAX_SNIFF_BYTES <bytes> — the maximum number of bytes to sniff per frame. 1500 is the default. ⭐
  • FLUSH_IPT_AT_INIT <Y/N> — flush all existing rules in the fwknop chains at fwknopd start time. Default is Y. 🧹
  • FLUSH_IPT_AT_EXIT <Y/N> — flush all existing rules in the fwknop chains when fwknopd is stopped or otherwise exits cleanly. Default is Y. 🧹
  • EXIT_AT_INTF_DOWN <Y/N> — when fwknopd is sniffing an interface and that interface gets administratively downed or unplugged, fwknopd will cleanly exit, and the assumption is made that some process-monitoring infrastructure like systemd or upstart will restart it. But if fwknopd is not being monitored by systemd, upstart, or anything else, this behavior can be disabled with the EXIT_AT_INTF_DOWN variable. If it's disabled, fwknopd will try to recover when a downed interface comes back up. 😭
  • ENABLE_RULE_PREPEND <Y/N> — for systems running iptables or firewalld, this makes fwknopd insert new SPA rules at the beginning of the relevant chain (such as FWKNOP_INPUT) instead of appending them to the end. This causes newly created rules to have precedence over older ones. New rules, main character energy. 💅
  • ENABLE_NAT_DNS <Y/N> — allows fwknopd to resolve hostnames in NAT access messages. 🦋
  • GPG_HOME_DIR <path> — if GPG keys are used instead of a Rijndael symmetric key, this is the default GPG keys directory. Note that each access stanza in /etc/fwknop/access.conf can specify its own GPG directory to override this default. And if it's not set here or in an access.conf stanza, then it's the $HOME/.gnupg directory of the user running fwknopd (most likely root). 💜
  • GPG_EXE <path> — the path to GPG, defaulting to /usr/bin/gpg if not set. ⭐
  • LOCALE <locale> — sets the locale (via the LC_ALL variable). You can set this to override the default system locale. 🌈
  • ENABLE_SPA_OVER_HTTP <Y/N> — allows fwknopd to acquire SPA data from HTTP requests (generated with the fwknop client in --HTTP mode). Note that when this is enabled, the PCAP_FILTER variable would need to be updated to sniff traffic over TCP/80 connections, and a web server should be running on the same server as fwknopd. 🌸
  • ENABLE_X_FORWARDED_FOR <Y/N> — lets fwknopd use the X-Forwarded-for header from a captured SPA packet over HTTP as the source IP. This can happen when using SPA through an HTTP proxy. 🧚
  • ENABLE_TCP_SERVER <Y/N> — enables the fwknopd TCP server. This is a "dummy" TCP server that will accept TCP connection requests on the specified TCPSERV_PORT. If set to Y, fwknopd will fork off a child process to listen for and accept incoming TCP requests. This server only accepts the request — it does not otherwise communicate. It exists purely to allow the incoming SPA over TCP packet, which is detected via PCAP. The connection is closed after 1 second regardless. Note that fwknopd still only gets its data via pcap, so the filter defined by PCAP_FILTER needs to be updated to include this TCP port. 👀
  • TCPSERV_PORT <port> — the port number that the "dummy" TCP server listens on. This server is only spawned when ENABLE_TCP_SERVER is set to Y. 🔥
  • ENABLE_UDP_SERVER <Y/N> — enables the fwknopd UDP server, which tells fwknopd to acquire SPA packets via a UDP socket directly, without having to use libpcap. When this mode is enabled, fwknop should be compiled with --enable-udp-server (passed to the configure script) so that libpcap can be removed as a dependency. As one would expect, when the UDP server is used, no incoming packets are ever acknowledged by fwknopd — and therefore collecting SPA packets in this mode is a good alternative to sniffing the wire directly. Big slay for low-dependency setups. 💖
  • UDPSERV_PORT <port> — the port number that the UDP server listens on. This server is only spawned when ENABLE_UDP_SERVER is set to Y. ✨
  • PCAP_DISPATCH_COUNT <count> — sets the number of packets that get processed when the pcap_dispatch() call is made. Default is zero, since this allows fwknopd to process as many packets as possible in the corresponding callback, where the SPA handling routine is called for packets that pass a set of prerequisite checks. However, if fwknopd is running on a platform with an old version of libpcap, it may be necessary to change this value to a positive non-zero integer. More info lives in the pcap_dispatch(3) man page. 📖
  • PCAP_LOOP_SLEEP <microseconds> — the number of microseconds passed as an argument to usleep() in the pcap loop. Default is 100000, or 1/10th of a second. 💤
  • ENABLE_PCAP_ANY_DIRECTION <Y/N> — controls whether fwknopd is permitted to sniff SPA packets regardless of whether they're received on the sniffing interface or sent from the sniffing interface. In the latter case, this can be useful to have fwknopd sniff SPA packets that are forwarded through a system and destined for a different network. If the sniffing interface is the egress interface for such packets, then this variable needs to be set to Y in order for fwknopd to see them. Default is N, so fwknopd only looks for SPA packets that are received on the sniffing interface — and note that this is independent of promiscuous mode. 🦋
  • SYSLOG_IDENTITY <identity> — overrides the syslog identity on messages logged by fwknopd. The defaults are usually ok. 😌
  • SYSLOG_FACILITY <facility> — overrides the syslog facility. The SYSLOG_FACILITY variable can be set to
(yeah bestie, the original page literally trails off right there — that's the whole line, no cap 💀)
  • ENABLE_DESTINATION_RULE <Y/N> — controls whether fwknopd will set the destination field on the firewall rule to the destination address specified on the incoming SPA packet. This is useful for interfaces with multiple IP addresses hosting separate services. If ENABLE_IPT_OUTPUT is set to Y, the source field of the firewall rule is set. FORWARD and SNAT rules are not affected, however — but DNAT rules will also have their destination field set. Default is N, which sets the destination field to 0.0.0.0/0 (any). 🌈
  • FWKNOP_RUN_DIR <path> — where fwknopd drops its run-time state files, bestie. Default is /var, so that's where the state lives unless you tell it otherwise 💅

🎀 ACCESS.CONF VARIABLES 🎀

Okay so this section is about the access control directives that live in /etc/fwknop/access.conf — the actual brain of the whole operation. These directives are what define your encryption and authentication keys, plus exactly how much access gets handed to fwknop clients that showed up with a properly encrypted and authenticated SPA packet. Like, they did the handshake, they get the goods. Periodt.

The variables below are the access directives for SPA packets whose source IP (or embedded request IP) matches an address or network range defined by the SOURCE variable. Every variable that follows a SOURCE belongs to that source's stanza — and each SOURCE directive kicks off a brand new stanza. New stanza, new vibe check 🌸

  • SOURCE <IP,..,IP/NET,..,NET/ANY> — this is the one that sets the source address the SPA packet has to come from to be accepted. The string ANY is also accepted, if a valid SPA packet should be honored from any source IP. Heads up: every authorization stanza in /etc/fwknop/access.conf has to start with the SOURCE keyword — it's giving main character energy, it goes first, no exceptions. Networks should be written in CIDR notation (like 192.168.10.0/24), and individual IP addresses work too. You can also list multiple IPs and/or networks as a comma separated list, like 192.168.10.0/24,10.1.1.123 ✨
  • DESTINATION <IP,..,IP/NET,..,NET/ANY> — same idea but for the destination: this defines the destination address for which the SPA packet will be accepted. The string ANY is also accepted here, if a valid SPA packet should be honored to any destination IP. Networks in CIDR notation (like 192.168.10.0/24), individual IPs are fine, and yes you can comma-separate a whole list of IPs and/or networks (like 192.168.10.0/24,10.1.1.123) 🦋
  • OPEN_PORTS <proto/port>,...,<proto/port> — define the set of ports and protocols (tcp or udp) that get opened if a valid knock sequence is seen. If you don't set this entry, fwknopd will attempt to honor any proto/port request that's specified in the SPA data (unless it matches any RESTRICT_PORTS entries, obviously). Multiple entries are comma-separated. No cap, list as many as you want 💅
  • RESTRICT_PORTS <proto/port>,...,<proto/port> — the exact opposite energy: define the set of ports and protocols (tcp or udp) that are explicitly not allowed, regardless of how valid the incoming SPA packet is. Multiple entries are comma-separated. It's the velvet rope 🚫
  • KEY <passphrase> — defines the symmetric key used for decrypting an incoming SPA packet that the fwknop client encrypted with Rijndael. The actual encryption key is derived from the standard PBKDF1 algorithm. This variable is required for all SPA packets unless GnuPG is used instead (scroll down to the GPG variables, bestie) 🔑
  • KEY_BASE64 <base64 encoded passphrase> — same as the KEY option above, but you hand over the symmetric key as a base64 encoded string. This is how you sneak non-ascii characters into the base64-decoded key 🎀
  • HMAC_KEY <key> — sets the HMAC key for authenticated encryption of SPA packets. It supports both Rijndael and GPG encryption modes, and it's applied according to the encrypt-then-authenticate model — authenticate after you encrypt, that's the whole point 👑
  • HMAC_KEY_BASE64 <base64 encoded key> — the HMAC key, but as a base64 encoded string. Same deal: it's how you get non-ascii characters into the base64-decoded key 🌈
  • FW_ACCESS_TIMEOUT <seconds> — how long fwknopd will grant access through the firewall after a valid knock sequence from a source IP address. If FW_ACCESS_TIMEOUT isn't set, then the default timeout of 30 seconds is automatically set for you. Yes, 30 seconds, don't come crying to me when it closes ⏳
  • %include <file> — have fwknopd import an additional access.conf file. This means you can define more access stanzas in other locations on the filesystem, which is genuinely iconic in some scenarios: it lets non-privileged users define their own encryption and authentication keys for SPA operations. So users don't need write access to the main /etc/fwknop/access.conf file just to rotate keys or add new ones. Delegation slay 🫶
  • %include_folder <directory> — just like %include above, except the %include_folder directive has fwknopd import all .conf files from the directory you specify. There's also command line support for this via the access-folder option, iykyk 📁
  • ENCRYPTION_MODE <mode> — specify the encryption mode when AES is used. Default is CBC mode, but other modes can be selected such as OFB and CFB. In general it's recommended that you don't use this variable and just leave it as the default — let the defaults cook 🔥. 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 uses PBKDF1 for key derivation ✨
  • HMAC_DIGEST_TYPE <digest algorithm> — sets the digest algorithm for incoming SPA packet authentication. Must be one of MD5, SHA1, SHA256, SHA384, SHA512, SHA3_256, or SHA3_512. It's optional, and if you don't specify it then fwknopd defaults to using SHA256 if the access stanza requires an HMAC 💜
  • ACCESS_EXPIRE <MM/DD/YYYY> — sets an expiration date for the access stanza, in MM/DD/YYYY format. All SPA packets that match an expired stanza will be ignored. Optional. It's giving limited-time offer ⏰
  • ACCESS_EXPIRE_EPOCH <seconds> — same expiration idea but as the epoch time, which is useful when you need a more accurate expiration than the day resolution offered by ACCESS_EXPIRE above. All SPA packets that match an expired stanza will be ignored. Also optional 🕰️
  • ENABLE_CMD_EXEC <Y/N> — this tells fwknopd to accept complete commands that are contained within an authorization packet. Any such command will be executed on the fwknopd server as the user specified by CMD_EXEC_USER, or as the user that started fwknopd if that's not set. Yes, this executes commands. Handle with care, bestie. 💀
  • ENABLE_CMD_SUDO_EXEC <Y/N> — sudo is a genuinely powerful way of restricting the sets of commands users can execute via the sudoers file. By enabling this feature (and being in ENABLE_CMD_EXEC mode), all incoming commands from valid SPA packets get prefixed by /path/to/sudo -u <user> -g <group> — where the path to sudo is set by the SUDO_EXE variable, <user> is set by the CMD_SUDO_EXEC_USER variable (default is root if not set), and <group> is set by CMD_SUDO_EXEC_GROUP (default is also root if not set) 👑
  • CMD_EXEC_USER <username> — specify the user (via setuid) that will execute a command contained within a SPA packet. If you don't give this variable, fwknopd will execute the command as the user it's running as (most likely root). Setting this to a non-root user such as nobody is highly recommended if elevated permissions aren't needed — like, why would you not, bestie 🧚
  • CMD_SUDO_EXEC_USER <username> — specify the user (via sudo -u <user>) that will execute a command contained within a SPA packet. If you don't give this variable, fwknopd will assume the command should be executed as root 💅
  • CMD_EXEC_GROUP <groupname> — specify the group (via setgid) that will execute a command contained within a SPA packet. If you don't give this variable, fwknopd will execute the command as the user it's running as (most likely root). Setting this to a non-root group... okay so the original says non-root user such as nobody is highly recommended if elevated permissions aren't needed, and honestly the same energy applies 🎀
  • CMD_SUDO_EXEC_GROUP <groupname> — specify the group (via sudo -g <group>) that will execute a command contained within a SPA packet. If you don't give this variable, fwknopd will assume the command should be executed as root 🌸
  • CMD_CYCLE_OPEN <command> — sets a command open/close cycle to run when a valid SPA packet arrives. This directive sets the initial command, and it's meant to be used together with the CMD_CYCLE_CLOSE variable below — they're a package deal, don't split them up 🫶. The main application here is letting fwknopd interact with firewalls or ACLs that aren't natively supported, and get the same access model as the main supported firewalls like iptables. So: a command runs to open the firewall or ACL, and then a corresponding close command runs after a timer expires. Both CMD_CYCLE_OPEN and CMD_CYCLE_CLOSE support special substitution strings so values can be pulled from the SPA payload and used on the command line of the executed command. These strings all start with a $ character, and they include $IP (the allow IP decrypted from the SPA payload), $SRC (synonym for $IP), $PKT_SRC (the source IP in the network layer header of the SPA packet), $DST (the destination IP), $PORT (the allow port), and $PROTO (the allow protocol), $TIMEOUT (set the client timeout if specified) ⭐
  • CMD_CYCLE_CLOSE <command> — sets the close command that corresponds to the open command from CMD_CYCLE_OPEN above. The same string substitutions such as $IP, $PORT, and $PROTO are supported. On top of that, the special value NONE can be set to allow no close command to be executed after the open command — which might be handy in certain situations where, say, indefinite access is desired and allowed. (Indefinite access. Bestie. Be sure. 💀)
  • CMD_CYCLE_TIMER <seconds> — set the number of seconds after which the close command in CMD_CYCLE_CLOSE gets executed. This defines the open/close timer interval ⏱️
  • SUDO_EXE <path> — the path to the sudo binary. Default is /usr/bin/sudo ✨
  • REQUIRE_USERNAME <username> — require a specific username from the client system, as encoded in the SPA data. This variable is optional, and if you don't specify it, the username data in the SPA data is just ignored 🙈
  • REQUIRE_SOURCE_ADDRESS <Y/N> — force all SPA packets to contain a real IP address within the encrypted data. This makes it impossible to use the -s command line argument on the fwknop client command line, so either -R has to be used to automatically resolve the external address (if the client is behind a NAT) or the client must know the external IP and set it via the -a argument 🌐
  • REQUIRE_SOURCE_ADDRESS <Y/N> — synonym for REQUIRE_SOURCE_ADDRESS. Yes bestie. It's a synonym for itself. That's literally what the page says. We don't make the rules, we just report them 😭🎀
  • FORCE_NAT <IP> <PORT> — for any valid SPA packet, force the requested connection to be NAT’d through to the specified (usually internal) IP and port value. This is useful if there are multiple internal systems running a service such as SSHD, and you want to give transparent access to only one internal system for each stanza in the access.conf file. This way, multiple external users can each directly access only one internal system per SPA key. 💅
  • FORCE_SNAT <IP> — for any valid SPA packet, add an SNAT rule in addition to any DNAT rule created with a corresponding (required) FORCE_NAT variable. This is analogous to SNAT_TRANSLATE_IP from the /etc/fwknop/fwknopd.conf file except that it is per access stanza and overrides any value set with SNAT_TRANSLATE_IP. This is useful for situations where an incoming NAT’d connection may be otherwise unanswerable due to routing constraints (i.e. the system receiving the SPA authenticated connection has a default route to a different device than the SPA system itself).
  • FORCE_MASQUERADE <Y/N> — this is similar to the FORCE_SNAT variable, except that it is not necessary to also specify an IP address for SNAT rules because the MASQUERADE target is used instead.
  • FORWARD_ALL <Y/N> — in NAT scenarios, control whether all traffic is forwarded through the fwknopd system as opposed to just forwarding connections to specific services as requested by the fwknop client.
  • DISABLE_DNAT <Y/N> — control whether DNAT rules are created in FORCE_NAT scenarios. This is mainly used in conjunction with the FORWARD_ALL variable to allow fwknopd to act essentially as an SPA gateway. I.e., the fwknop client is used to gain access via SPA to the broader Internet after being granted an IP via DHCP, but prior to sending the SPA packet all traffic is blocked by default to the Internet.
  • GPG_DECRYPT_ID <keyID> — define a GnuPG key ID to use for decrypting SPA messages that have been encrypted by an fwknop client. This keyword is required for authentication that is based on GPG keys. The GPG key ring on the client must have imported and signed the fwknopd server key, and vice versa. It is ok to use a sensitive personal GPG key on the client, but each fwknopd server should have its own GPG key that is generated specifically for fwknop communications. The reason for this is that the decryption password for the server key must be placed within the /etc/fwknop/access.conf file for fwknopd to function (it has to be able to decrypt SPA messages that have been encrypted with the server’s public key). For more information on using fwknop with GnuPG keys, see the following link: http://www.cipherdyne.org/fwknop/docs/gpghowto.html.
  • GPG_DECRYPT_PW <decrypt password> — specify the decryption password for the gpg key defined by the GPG_DECRYPT_ID above. This is a required field for gpg-based authentication.
  • GPG_ALLOW_NO_PW <Y/N> — allow fwknopd to leverage a GnuPG key pair that does not have an associated password. While this may sound like a controversial deployment mode, in automated environments it makes sense because "there is usually no way to store a password more securely than on the secret keyring itself" according to: http://www.gnupg.org/faq/GnuPG-FAQ.html#how-can-i-use-gnupg-in-an-automated-environment. Using this feature and removing the passphrase from a GnuPG key pair is useful in some environments where libgpgme is forced to use gpg-agent and/or pinentry to collect a passphrase.
  • GPG_REQUIRE_SIG <Y/N> — with this setting set to Y, fwknopd check all GPG-encrypted SPA messages for a signature (signed by the sender’s key). If the incoming message is not signed, the decryption process will fail. If not set, the default is Y.
  • GPG_DISABLE_SIG <Y/N> — disable signature verification for incoming SPA messages. This is not a recommended setting, and the default is N.
  • GPG_IGNORE_SIG_VERIFY_ERROR <Y/N> — setting this will allow fwknopd to accept incoming GPG-encrypted packets that are signed, but the signature did not pass verification (i.e. the signer key was expired, etc.). This setting only applies if the GPG_REQUIRE_SIG is also set to Y.
  • GPG_REMOTE_ID <keyID,...,keyID> — define a list of gpg key ID’s that are required to have signed any incoming SPA message that has been encrypted with the fwknopd server key. This ensures that the verification of the remote user is accomplished via a strong cryptographic mechanism. Signature verification is enabled by default, and can only be disabled if GPG_DISABLE_SIG is set to Y (not a recommended setting). Separate multiple entries with a comma.
  • GPG_FINGERPRINT_ID <keyID,...,keyID> — specify a set of full-length GnuPG key fingerprints instead of the shorter key identifiers set with the GPG_REMOTE_ID variable. Here is an example fingerprint for one of the fwknop test suite keys: 00CC95F05BC146B6AC4038C9E36F443C6A3FAD56.
  • GPG_HOME_DIR <path> — define the path to the GnuPG directory to be used by the fwknopd server. If this keyword is not specified within /etc/fwknop/access.conf then fwknopd will default to using the /root/.gnupg directory for the server key(s) for incoming SPA packets handled by the matching access.conf stanza.
  • GPG_EXE <path> — define the path to the GnuPG executable. If this keyword is not specified within /etc/fwknop/access.conf then fwknopd will default to using /usr/bin/gpg.

📁 FILES 📁

  • /etc/fwknop/fwknopd.conf — the main configuration file for fwknop. 🎀
  • /etc/fwknop/access.conf — defines all knock sequences and access control directives. 🦋

🧚 DEPENDENCIES 🧚

fwknopd requires libfko which is normally included with both source and binary distributions, and is a dedicated library developed by the fwknop project.

For packet sniffing, fwknopd currently requires libpcap, but future versions will (optionally) remove this as a dependency.

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. 🔥

🩺 DIAGNOSTICS 🩺

fwknopd can be run in debug mode by combining the -f, --foreground and the -v, --verbose command line options. This will disable daemon mode execution, and print verbose information to the screen on stderr as packets are received. 👀

The most comprehensive way to gain diagnostic information on fwknopd is to run the test suite test-fwknop.pl script located in the test/ directory in the fwknop sources. The test suite runs 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. literally so thorough 💀

👑 SEE ALSO 👑

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 🐦

🫶 AUTHORS 🫶

The primary developers of fwknop are Michael Rash (project creator) <mbr@cipherdyne.org>, Damien Stuart <dstuart@dstuart.org>, and Jonathan Bennett <jbennett@incomsystems.biz>.

🌈 CONTRIBUTORS 🌈

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. iconic origin story fr fr ✨

💀 BUGS 💀

Send bug reports to dstuart@dstuart.org or mbr@cipherdyne.org, or open a new issue on Github (see https://github.com/mrash/fwknop.git). Suggestions and/or comments are always welcome as well. Additional information may be found in the fwknop mailing list archives (see: https://lists.sourceforge.net/lists/listinfo/fwknop-discuss).

🍓 DISTRIBUTION 🍓

fwknopd is distributed under the GNU General Public License (GPL v2+), and the latest version may be downloaded from http://www.cipherdyne.org.

okay bestie, footer shoutout: this one’s the Fwknop Server page, dated 08/06/2018, section FWKNOPD(8) — and that’s a wrap on the whole manual 💖🎀🦋

📦 where this page comes from