Man Linux: Main Page and Category List

NAME

       fwknopd - Firewall Knock Operator (server component)

SYNOPSIS

       fwknopd [options]

DESCRIPTION

       fwknopd is the server component for the FireWall Knock Operator, and is
       responsible for monitoring Single Packet  Authorization  (SPA)  packets
       that  are  generated  by  fwknop clients, modifying an iptables or ipfw
       policy to allow the desired access after decrypting a valid SPA packet,
       and removing access after a configurable timeout.  The main application
       of this program is 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.

       The main configuration for fwknopd  is  maintained  within  two  files:
       fwknop.conf  and  access.conf  within  the  /etc/fwknop  directory, and
       configuration variables within these files are desribed below.

OPTIONS

       -c, --config <config-file>
              When  run  in   server   mode   fwknop   references   the   file
              /etc/fwknop/fwknop.conf   for   various  run-time  configuration
              variables.  The path to this file can be changed through the use
              of the --config command line option.

       -i, --intf <interface>
              Manually  specify  interface  on which to sniff, e.g. "-i eth0".
              This option is not usually needed because the PCAP_INTF  keyword
              in  /etc/fwknop/fwknop.conf file defines the sniffing interface.

       --fw-list
              List all active rules in the FWKNOP Netfilter chain(s).

       --fw-flush
              Flush all active rules in the FWKNOP Netfilter chain(s).

       -O, --Override-config <file>
              Override config variable values that are normally read from  the
              /etc/fwknop/fwknop.conf  file  with  values  from  the specified
              file.  Multiple override config files can be given  as  a  comma
              separated list.

       -D, --Dump-config
              Dump  the  configuration  values  that  fwknopd derives from the
              /etc/fwknop/fwknop.conf (or other override files) on STDERR.

       -o, --os
              Parse Netfilter logs  and  fingerprint  operating  systems  from
              which tcp SYN packets have been logged.

       --fw-log <file>
              Specify  the  path to the Netfilter log file that is parsed when
              running in --os mode.

       -K, --Kill
              Kill the  current  fwknop  process  along  with  knopwatchd  and
              knopmd.   This  provides a quick and easy way to stop all fwknop
              processes without having to look in the process table or  appeal
              to the fwknop init script.

       -R, --Restart
              Restart  the  currently  running  fwknop processes.  This option
              will preserve the command line options that were supplied to the
              original fwknop process.

       -S, --Status
              Display  the  status  of any fwknop processes that may or not be
              running.

       -l,  --locale <locale>
              Provide a locale setting other than the default "C" locale.

       --no-locale
              Do not set the locale at all so that the default  system  locale
              will apply.

       -v, --verbose
              Run fwknop in verbose mode.

       -h, --help
              Display usage information and exit.

       -V, --Version
              Display version information and exit.

FILES

       /etc/fwknop/fwknop.conf
              The main configuration file for fwknop.

       /etc/fwknop/access.conf
              Defines all knock sequences and access control directives.

       /etc/fwknop/pf.os
              Defines p0f signatures used by fwknop.

FWKNOP CONFIG AND ACCESS VARIABLES

       fwknop  references  the  file /etc/fwknop/fwknop.conf for configuration
       variables such as the path to the firewall logfile, the sleep  interval
       fwknop  uses  to  check  for  new  log  messages,  and  paths to system
       binaries, etc.  The fwknop config  file  does  not  define  any  access
       control     directives;     they    are    located    in    the    file
       /etc/fwknop/access.conf.  Access control directives  define  encryption
       keys  and  level of access that is granted to an fwknop client that has
       generated the appropriate encrypted message.  This file  is  referenced
       for this information when run in either the single packet authorization
       mode, or the legacy port knocking mode.

       SOURCE: <IP,..,IP/NET,..,NET/ANY>
              This defines the source  address  from  which  an  authorization
              packet  (or legacy knock sequence) will be accepted.  The string
              "ANY" is also accepted if a valid authorization packet should be
              honored  from  any  source  IP.   Every  authorization stanza in
              /etc/fwknop/access.conf definition must start  with  the  SOURCE
              keyword.   Networks  can  be  specified  in  either  CIDR  (e.g.
              "192.168.10.0/24")          or           regular           (e.g.
              "192.168.10.0/255.255.255.0")   notation,   and   individual  IP
              addresses can be specified as well.  Also, multiple IP’s  and/or
              networks  can  be  defined  as  a  comma  separated  list  (e.g.
              "192.168.10.0/24, 10.1.1.123")

       DATA_COLLECT_MODE: PCAP|FILE_PCAP|ULOG_PCAP|ENCRYPT_SEQUENCE
              If DATA_COLLECT_MODE is set to "PCAP", fwknop  sniffs  the  wire
              directly  via  libpcap to capture authorization packets.  If set
              to "FILE_PCAP", fwknop reads a pcap-formatted file  (defined  by
              the  PCAP_PKT_FILE  keyword  in  the  fwknop.conf  file) that is
              written  to  by  a  separate  sniffer  process.    If   set   to
              "ULOG_PCAP",  fwknop  collects  packets  via the Netfilter ulogd
              pcap writer.  This requires that packets are logged via the ULOG
              target  in  the  Netfilter  policy.  If set to ENCRYPT_SEQUENCE,
              fwknop falls back to the legacy port knocking method of  network
              authorization.

       ENABLE_CMD_EXEC
              This  instructs  fwknop  to  accept  complete  commands that are
              contained within an authorization packet.  Any such command will
              be executed as root by the fwknop server.

       CMD_REGEX: <regex>
              If ENABLE_CMD_EXEC is specified, the CMD_REGEX keyword instructs
              fwknop to restrict command execution to only those command  that
              match the given regular expression.

       KEY: <8 or more chars>
              Define  the  encryption key for an ENCRYPT_SEQUENCE block.  This
              variable is required for all encrypted sequences (each encrypted
              sequence  may  have its own unique key), and must be provided at
              execution to an fwknop client attempting to gain  access.   When
              run  in  client  mode,  fwknop  will  prompt  the  user  for the
              encryption key, or a path to the key  may  be  provided  on  the
              command line with --get-key <file>.

       OPEN_PORTS: <proto/port>, ..., <proto/port>
              Define  a  set  of ports and protocols (tcp or udp) that will be
              opened if a valid knock sequence  is  seen.   This  variable  is
              required  for  shared knock sequences since the port information
              is not sent within the  sequence,  and  optional  for  encrypted
              knock  sequences  which can include the port and protocol within
              the sequence.

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

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

       GPG_USE_OPTIONS
              By default, fwknopd instructs gpg to not reference  any  options
              file  when  decrypting  incoming  SPA  packets  that  have  been
              encrypted with GnuPG by the fwknop client.   This  argument  re-
              enables options in gpg.

       GPG_NO_REQUIRE_PREFIX
              This  option  controls  whether  the  GnuPG ’hQ’ prefix is added
              before base64 decoding and decrypting.  Normally this option  is
              not  needed,  but  if  there  appear to be communications issues
              between the fwknop client and the fwknopd server in GnuPG  mode,
              then this option can be useful to ensure that encrypted SPA data
              is sent through the GnuPG decryption routine.  The  ’hQ’  prefix
              is  a  heuristic  derived  from  the  file  ’magic’ database for
              describing data encrypted with  GnuPG,  and  the  fwknop  client
              normally  strips this data from outgoing SPA packets (unless the
              --Include-gpg-prefix option is used).

       GPG_PATH: <path>
              Specify a path to the gpg  binary  (commonly  at  /usr/bin/gpg).
              This  can  be  used to switch between gpg vs. gpg2, or provide a
              path to a custom compiled version of gpg for testing purposes.

       FW_ACCESS_TIMEOUT: <seconds>
              Define the length of time  access  will  be  granted  by  fwknop
              through  the firewall after a valid knock sequence from a source
              IP address.  If FW_ACCESS_TIMEOUT is not set  then  the  default
              timeout of 300 seconds (5 minutes) will automatically be set.

       REQUIRE_USERNAME: <username>
              Require  a  specific  username  from  the  client  system.  This
              username is sent  across  the  network  in  an  encrypted  knock
              sequence  to  the fwknop server.  If there are multiple users on
              the client system, only a knock sequence that  is  initiated  by
              the  required  username  will  be  honored.   This  variable  is
              optional  and  is  only  valid  with   an   encrypted   sequence
              definition.

       REQUIRE_SOURCE_ADDRESS
              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 command line, so either -R has to be
              used to automatically  resolve  the  external  address  (if  the
              client behind a NAT) or the client must know the external IP.

       REQUIRE_OS: <operating system>
              Require  a  specific  operating  system  fingerprint match (e.g.
              "Linux:2.4::Linux 2.4/2.6" or "OpenBSD:3.0-3.5::OpenBSD 3.0-3.5"
              before  a knock sequence will be accepted.  The fingerprints are
              listed in /etc/fwknop/pf.os.  Note that the corresponding  knock
              sequence must utilize the tcp protocol (this is only be an issue
              for shared  sequences  since  encrypted  sequences  use  tcp  by
              default) since OS fingerprinting requires tcp syn packets.  This
              variable is optional, and is not applicable in SPA mode.

       REQUIRE_OS_REGEX: <regex>
              Require an operating system fingerprint  that  matches  <regex>,
              e.g.   "linux"  or  "*bsd".  Note that the regex will be matched
              case in- sensitively.  This variable is  optional,  and  is  not
              applicable in SPA mode.

       ENCRYPT_SEQUENCE
              Expect that all port knock sequences originating from the SOURCE
              will  be  encrypted.   Fwknop  will  try  to  decrypt  all  such
              sequences.   ENCRYPT_SEQUENCE  does  not  accept  any arguments.
              Either  this  variable  or  the  "SHARED_SEQUENCE"  variable  is
              required for each SOURCE block.

       SHARED_SEQUENCE: <proto/port>, ..., <proto/port>
              Define  the  sequence  of  ports (together with their associated
              protocol; tcp or udp) that will be sent to the destination knock
              server.   This  sequence is not encrypted, and source IP will be
              allowed to connect through the destination firewall ruleset to a
              set  of  tcp  or udp ports (defined by the OPEN_PORTS variable).
              Using an encrypted sequence is much more  secure.   Either  this
              variable  or  the  "ENCRYPT_SEQUENCE" variable above is required
              for each SOURCE block.

       KNOCK_INTERVAL: <seconds>
              Define the interval of time in which a port knock sequence  will
              be  honored.   I.e.  the  number  of  seconds  after  the  first
              connection attempt the last connection attempt in  the  sequence
              must  be  received  for the knock sequence to be accepted by the
              destination fwknop daemon.  If a KNOCK_INTERVAL is not specified
              then  the  default  interval of 60 seconds will automatically be
              set.

       KNOCK_LIMIT: <number>
              Define the maximum number of times  a  knock  sequence  will  be
              honored.   Note that repetitive access to the fwknop server will
              eventually be restricted if this option is used.

       PORT_OFFSET: <offset>
              Encrypted knock sequences take place over a range of  256  ports
              starting  at a default port of 61000.  This value can be changed
              through the use of the PORT_OFFSET variable.  The PORT_OFFSET is
              optional  and  will  be  set  to  61000  by  fwknop if it is not
              specified in /etc/fwknop/access.conf.

       MIN_TIME_DIFF: <seconds>
              Set the  minimum  number  of  seconds  that  must  pass  between
              successive connection attempts in a shared knock sequence.  This
              variable is optional.

       MAX_TIME_DIFF: <seconds>
              Set the  maximum  number  of  seconds  that  must  pass  between
              successive connection attempts in a shared knock sequence.  This
              variable is optional.

DEPENDENCIES

       fwknopd requires perl.  To take advantage of all  of  the  features  in
       fwknop  when  run  in  server  mode a functioning Netfilter firewall is
       required on the underlying operating system.  If fwknop is being run in
       the  legacy  port  knocking  mode,  then Netfilter must log packets via
       syslog, and ideally the --log-tcp-options argument will be specified in
       the iptables logging rule so that fwknop will be able to use a strategy
       similar to p0f to passively fingerprint operating systems.

DIAGNOSTICS

       fwknop can be run in debug mode with the --debug command  line  option.
       This  will disable daemon mode execution, and print verbose information
       to the screen on STDERR as packets are received.

SEE ALSO

       fwknop(8), iptables(8), gpg(1), gpg-agent(1), knopmd(8),  knopwatchd(8)
       p0f(1),

AUTHOR

       Michael Rash <mbr@cipherdyne.org>

CREDITS

       The  phrase  "Single  Packet  Authorization" was coined by MadHat, see:
       http://www.nmrc.org/ The term "port  knocking"  was  coined  by  Martin
       Krzywinski, see: http://www.portknocking.org/
        The  original  p0f  passive  OS  fingerprinter  was  written by Michal
       Zalewski, and is available here: http://lcamtuf.coredump.cx/p0f.shtml

BUGS

       Send bug reports to 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/