diff --git a/Makefile.am b/Makefile.am index 337e4f3e..d882a282 100644 --- a/Makefile.am +++ b/Makefile.am @@ -16,7 +16,6 @@ SUBDIRS = \ EXTRA_DIST = \ fwknop.spec \ - perl/legacy \ perl/FKO/README \ perl/FKO/inc/Devel/CheckLib.pm \ perl/FKO/MANIFEST \ diff --git a/doc/fwknopd.man.asciidoc b/doc/fwknopd.man.asciidoc index 92646321..460e68c5 100644 --- a/doc/fwknopd.man.asciidoc +++ b/doc/fwknopd.man.asciidoc @@ -17,13 +17,14 @@ SYNOPSIS 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 a firewall or acl -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. +is responsible for monitoring and processing Single Packet Authorization +(SPA) packets that are generated by *fwknop* clients, modifying a firewall +or ACL 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: 'fwknopd.conf' and 'access.conf'. The default location for these files @@ -47,27 +48,32 @@ COMMAND-LINE OPTIONS Specify the number of candidate SPA packets to process and exit when this limit is reached. +*-D, --Dump-config*:: + Dump the configuration values that *fwknopd* derives from the + 'fwknop.conf' (or override files) and 'access.conf' on stderr. + *-i, --interface*='':: Manually specify interface on which to sniff, e.g. ``-i eth0''. This option is not usually needed because the ``PCAP_INTF'' keyword in the 'fwknopd.conf' file defines the sniffing interface. -*-O, --Override-config*='':: - Override config variable values that are normally read from the - '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 - 'fwknop.conf' (or override files) and 'access.conf' on STDERR. +*-f, --foreground*:: + Run *fwknopd* in the foreground instead of becoming a daemon. When run + in the foreground, message that would go to the log would instead be + sent to stderr. This mode is usually used when testing and/or debugging. *-K, --Kill*:: Kill the current *fwknopd* process. This provides a quick and easy way to stop *fwknopd* without having to look in the process table. -*-l, --locale*='':: +*-l, --locale*='':: Set/override the system default locale setting. +*-O, --Override-config*='':: + Override config variable values that are normally read from the + 'fwknop.conf' file with values from the specified file. Multiple + override config files can be given as a comma-separated list. + *-R, --Restart*:: Restart the currently running *fwknopd* processes. This option will preserve the command line options that were supplied to the @@ -85,7 +91,9 @@ COMMAND-LINE OPTIONS running. *-v, --verbose*:: - Run *fwknopd* in verbose mode. + Run *fwknopd* in verbose mode. This can option acn 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. @@ -96,16 +104,15 @@ COMMAND-LINE OPTIONS FWKNOPD CONFIG AND ACCESS VARIABLES ----------------------------------- -*fwknopd* references the 'fwknopd.conf' file 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. +*fwknopd* references the 'fwknopd.conf' file for configuration variables +that define its 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. The access control directives are contained in the 'access.conf' file. Access control directives define encryption keys and level of access that is granted to an fwknop client that has generated the appropriate encrypted -message. +SPA message. FWKNOPS.CONF VARIABLES ~~~~~~~~~~~~~~~~~~~~~~ @@ -113,16 +120,8 @@ This section list the more prominent configuration variables used by *fwknopd*. It is not a complete list. See the 'fwknopd.conf' file for the full list and corresponding details. -*FIREWALL_TYPE* '':: - Define the firewall type. The default is 'iptables' for Linux systems, - but this can be set to 'ipfw' for BSD systems. Also supported is - 'external_cmd' to allow *fwknopd* to invoke an external command instead - of interfacing with the firewall at all. - *PCAP_INTF* '':: - Define the ethernet interface on which *fwknopd* will sniff packets. - Note that this is only used if the ``AUTH_MODE'' keyword above is set - to ``PCAP''. + Specify the ethernet interface on which *fwknopd* will sniff packets. *ENABLE_PCAP_PROMISC* '':: By default *fwknopd* puts the pcap interface into promiscuous mode. Set @@ -151,15 +150,13 @@ the full list and corresponding details. *fwknopd*. This allows digest sums to remain persistent across executions of *fwknopd*. The default is ``Y''. If set to ``N'', *fwknopd* will not check incoming SPA packet data against any - previously save digests. + previously save digests. It is a good idea to leave this feature on + to reduce the possibility of being vulnerable to a replay attack. *ENABLE_IPT_FORWARDING* '':: Allow SPA clients to request access to services through an iptables firewall instead of just to it (i.e. access through the FWKNOP_FORWARD - chain instead of the INPUT chain). This also requires the - ``ENABLE_FORWARD_ACCESS'' variable to be set in the 'access.conf' - file for the specific ``SOURCE'' stanzas that should be allowed for - forwarding access. + chain instead of the INPUT chain). *ENABLE_IPT_LOCAL_NAT* '>Y/N>':: Allow SPA clients to request access to a local socket via NAT. This @@ -203,22 +200,6 @@ the full list and corresponding details. Flush all existing rules in the fwknop chains when *fwknopd* is stopped or otherwise exits cleanly. The default is ``Y''. -*IPFW_RULE_NUM* '':: - If running on 'ipfw' firewalls, this variable defines the rule number - that *fwknopd* uses to insert an ipfw 'pass' rule. - -*IPFW_SET_NUM* '':: - If running on 'ipfw' firewalls, this variable defines the rule set - that will be used to store expired rules that still have a dynamic - rule associated to them. That set will be disabled by *fwknopd* and - should not be enabled while *fwknopd* is running. Not used when ipfw - isn't using dynamic rules. - -*IPFW_DYNAMIC_INTERVAL* '':: - For 'ipfw' firewalls set the interval (in seconds) over those rules - that have no remaining dynamic rules associated with them will be - removed. - *GPG_HOME_DIR* '':: If GPG keys are used instead of a Rijndael symmetric key, this is the default GPG keys directory. Note that each access block in @@ -233,9 +214,10 @@ the full list and corresponding details. *ENABLE_SPA_OVER_HTTP* '':: Allow *fwknopd* to acquire SPA data from HTTP requests (generated with - the fwknop client in *--HTTP* mode). Note that the ``PCAP_FILTER'' - variable would need to be updated when this is enabled to sniff traffic - over TCP/80 connections. + 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_TCP_SERVER* '':: Enable the fwknopd TCP server. This is a "dummy" TCP server that will @@ -287,9 +269,9 @@ directive starts a new stanza. *OPEN_PORTS*: ',...,':: Define a set of ports and protocols (tcp or udp) that will be opened if a valid knock sequence is seen. If this entry is not set, - *fwknopd* will attempt to honor the request specifed in the SPA data - (unless of it matches any ``RESTRICT_PORTS'' entries). Multiple entries - are comma-separated. + *fwknopd* will attempt to honor any proto/port request specifed in the + SPA data (unless of it matches any ``RESTRICT_PORTS'' entries). Multiple + entries are comma-separated. *RESTRICT_PORTS*: ',...,':: Define a set of ports and protocols (tcp or udp) that are explicitly @@ -308,9 +290,10 @@ directive starts a new stanza. will automatically be set. *ENABLE_CMD_EXEC*: '':: - This instructs *fwknopd* to accept complete commands that are - contained within an authorization packet. Any such command will - be executed as root by the *fwknopd* server. + This instructs *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 the ``CMD_EXEC_USER'' or + as the user that started *fwknopd* if that is not set. *CMD_EXEC_USER*: '':: This specifies the user that will execute commands contained within a SPA @@ -395,9 +378,10 @@ underlying operating system. DIAGNOSTICS ----------- -*fwknopd* 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. +*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. SEE ALSO diff --git a/server/fwknopd.8 b/server/fwknopd.8 index 554a5990..ad9d4519 100644 --- a/server/fwknopd.8 +++ b/server/fwknopd.8 @@ -2,12 +2,12 @@ .\" Title: fwknopd .\" Author: [see the "AUTHOR" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 07/08/2010 +.\" Date: 07/09/2010 .\" Manual: Fwknop Server .\" Source: Fwknop Server .\" Language: English .\" -.TH "FWKNOPD" "8" "07/08/2010" "Fwknop Server" "Fwknop Server" +.TH "FWKNOPD" "8" "07/09/2010" "Fwknop Server" "Fwknop Server" .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- @@ -25,7 +25,9 @@ fwknopd \- Firewall Knock Operator Daemon \fBfwknopd\fR [\fIoptions\fR] .SH "DESCRIPTION" .sp -\fBfwknopd\fR is the server component for the FireWall Knock Operator, and is responsible for monitoring Single Packet Authorization (SPA) packets that are generated by \fBfwknop\fR clients, modifying a firewall or acl 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 \fISSH\fR with an additional layer of security in order to make the exploitation of vulnerabilities (both 0\-day and unpatched code) much more difficult\&. +\fBfwknopd\fR is the server component for the FireWall Knock Operator, and is responsible for monitoring and processing Single Packet Authorization (SPA) packets that are generated by \fBfwknop\fR clients, modifying a firewall or ACL policy to allow the desired access after decrypting a valid SPA packet, and removing access after a configurable timeout\&. +.sp +The main application of this program is to protect services such as \fISSH\fR with an additional layer of security in order to make the exploitation of vulnerabilities (both 0\-day and unpatched code) much more difficult\&. .sp The main configuration for \fBfwknopd\fR is maintained within two files: \fIfwknopd\&.conf\fR and \fIaccess\&.conf\fR\&. The default location for these files is determined at package configuration (typically \fI/etc/fwknop\fR)The configuration variables within these files are desribed below\&. .SH "COMMAND-LINE OPTIONS" @@ -55,20 +57,6 @@ will use the default location (typically Specify the number of candidate SPA packets to process and exit when this limit is reached\&. .RE .PP -\fB\-i, \-\-interface\fR=\fI\fR -.RS 4 -Manually specify interface on which to sniff, e\&.g\&. \(lq\-i eth0\(rq\&. This option is not usually needed because the \(lqPCAP_INTF\(rq keyword in the -\fIfwknopd\&.conf\fR -file defines the sniffing interface\&. -.RE -.PP -\fB\-O, \-\-Override\-config\fR=\fI\fR -.RS 4 -Override config variable values that are normally read from the -\fIfwknop\&.conf\fR -file with values from the specified file\&. Multiple override config files can be given as a comma\-separated list\&. -.RE -.PP \fB\-D, \-\-Dump\-config\fR .RS 4 Dump the configuration values that @@ -77,7 +65,21 @@ derives from the \fIfwknop\&.conf\fR (or override files) and \fIaccess\&.conf\fR -on STDERR\&. +on stderr\&. +.RE +.PP +\fB\-i, \-\-interface\fR=\fI\fR +.RS 4 +Manually specify interface on which to sniff, e\&.g\&. \(lq\-i eth0\(rq\&. This option is not usually needed because the \(lqPCAP_INTF\(rq keyword in the +\fIfwknopd\&.conf\fR +file defines the sniffing interface\&. +.RE +.PP +\fB\-f, \-\-foreground\fR +.RS 4 +Run +\fBfwknopd\fR +in the foreground instead of becoming a daemon\&. When run in the foreground, message that would go to the log would instead be sent to stderr\&. This mode is usually used when testing and/or debugging\&. .RE .PP \fB\-K, \-\-Kill\fR @@ -94,6 +96,13 @@ without having to look in the process table\&. Set/override the system default locale setting\&. .RE .PP +\fB\-O, \-\-Override\-config\fR=\fI\fR +.RS 4 +Override config variable values that are normally read from the +\fIfwknop\&.conf\fR +file with values from the specified file\&. Multiple override config files can be given as a comma\-separated list\&. +.RE +.PP \fB\-R, \-\-Restart\fR .RS 4 Restart the currently running @@ -126,7 +135,7 @@ processes that may or not be running\&. .RS 4 Run \fBfwknopd\fR -in verbose mode\&. +in verbose mode\&. This can option acn 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)\&. .RE .PP \fB\-h, \-\-help\fR @@ -140,31 +149,18 @@ Display version information and exit\&. .RE .SH "FWKNOPD CONFIG AND ACCESS VARIABLES" .sp -\fBfwknopd\fR references the \fIfwknopd\&.conf\fR file 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\&. +\fBfwknopd\fR references the \fIfwknopd\&.conf\fR file for configuration variables that define its operational parameters (what network interface and port to sniff, what features to enable/disable, etc\&.)\&. The \fIfwknopd\&.conf\fR file does not define any access control directives\&. .sp -The access control directives are contained in the \fIaccess\&.conf\fR file\&. Access control directives define encryption keys and level of access that is granted to an fwknop client that has generated the appropriate encrypted message\&. +The access control directives are contained in the \fIaccess\&.conf\fR file\&. Access control directives define encryption keys and level of access that is granted to an fwknop client that has generated the appropriate encrypted SPA message\&. .SS "FWKNOPS\&.CONF VARIABLES" .sp This section list the more prominent configuration variables used by \fBfwknopd\fR\&. It is not a complete list\&. See the \fIfwknopd\&.conf\fR file for the full list and corresponding details\&. .PP -\fBFIREWALL_TYPE\fR \fI\fR -.RS 4 -Define the firewall type\&. The default is -\fIiptables\fR -for Linux systems, but this can be set to -\fIipfw\fR -for BSD systems\&. Also supported is -\fIexternal_cmd\fR -to allow -\fBfwknopd\fR -to invoke an external command instead of interfacing with the firewall at all\&. -.RE -.PP \fBPCAP_INTF\fR \fI\fR .RS 4 -Define the ethernet interface on which +Specify the ethernet interface on which \fBfwknopd\fR -will sniff packets\&. Note that this is only used if the \(lqAUTH_MODE\(rq keyword above is set to \(lqPCAP\(rq\&. +will sniff packets\&. .RE .PP \fBENABLE_PCAP_PROMISC\fR \fI\fR @@ -209,14 +205,12 @@ Track digest sums associated with previous SPA packets processed by \fBfwknopd\fR\&. This allows digest sums to remain persistent across executions of \fBfwknopd\fR\&. The default is \(lqY\(rq\&. If set to \(lqN\(rq, \fBfwknopd\fR -will not check incoming SPA packet data against any previously save digests\&. +will not check incoming SPA packet data against any previously save digests\&. It is a good idea to leave this feature on to reduce the possibility of being vulnerable to a replay attack\&. .RE .PP \fBENABLE_IPT_FORWARDING\fR \fI\fR .RS 4 -Allow SPA clients to request access to services through an iptables firewall instead of just to it (i\&.e\&. access through the FWKNOP_FORWARD chain instead of the INPUT chain)\&. This also requires the \(lqENABLE_FORWARD_ACCESS\(rq variable to be set in the -\fIaccess\&.conf\fR -file for the specific \(lqSOURCE\(rq stanzas that should be allowed for forwarding access\&. +Allow SPA clients to request access to services through an iptables firewall instead of just to it (i\&.e\&. access through the FWKNOP_FORWARD chain instead of the INPUT chain)\&. .RE .PP \fBENABLE_IPT_LOCAL_NAT\fR \fI>Y/N>\fR @@ -272,35 +266,6 @@ Flush all existing rules in the fwknop chains when is stopped or otherwise exits cleanly\&. The default is \(lqY\(rq\&. .RE .PP -\fBIPFW_RULE_NUM\fR \fI\fR -.RS 4 -If running on -\fIipfw\fR -firewalls, this variable defines the rule number that -\fBfwknopd\fR -uses to insert an ipfw -\fIpass\fR -rule\&. -.RE -.PP -\fBIPFW_SET_NUM\fR \fI\fR -.RS 4 -If running on -\fIipfw\fR -firewalls, this variable defines the rule set that will be used to store expired rules that still have a dynamic rule associated to them\&. That set will be disabled by -\fBfwknopd\fR -and should not be enabled while -\fBfwknopd\fR -is running\&. Not used when ipfw isn\(cqt using dynamic rules\&. -.RE -.PP -\fBIPFW_DYNAMIC_INTERVAL\fR \fI\fR -.RS 4 -For -\fIipfw\fR -firewalls set the interval (in seconds) over those rules that have no remaining dynamic rules associated with them will be removed\&. -.RE -.PP \fBGPG_HOME_DIR\fR \fI\fR .RS 4 If GPG keys are used instead of a Rijndael symmetric key, this is the default GPG keys directory\&. Note that each access block in @@ -325,7 +290,8 @@ Allow \fBfwknopd\fR to acquire SPA data from HTTP requests (generated with the fwknop client in \fB\-\-HTTP\fR -mode)\&. Note that the \(lqPCAP_FILTER\(rq variable would need to be updated when this is enabled to sniff traffic over TCP/80 connections\&. +mode)\&. Note that when this is enabled, the \(lqPCAP_FILTER\(rq 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 +\fBfwknopd\fR\&. .RE .PP \fBENABLE_TCP_SERVER\fR \fI\fR @@ -365,7 +331,7 @@ definition must start with the \(lqSOURCE\(rq keyword\&. Networks should be spec .RS 4 Define a set of ports and protocols (tcp or udp) that will be opened if a valid knock sequence is seen\&. If this entry is not set, \fBfwknopd\fR -will attempt to honor the request specifed in the SPA data (unless of it matches any \(lqRESTRICT_PORTS\(rq entries)\&. Multiple entries are comma\-separated\&. +will attempt to honor any proto/port request specifed in the SPA data (unless of it matches any \(lqRESTRICT_PORTS\(rq entries)\&. Multiple entries are comma\-separated\&. .RE .PP \fBRESTRICT_PORTS\fR: \fI,\&...,\fR @@ -391,9 +357,11 @@ through the firewall after a valid knock sequence from a source IP address\&. If .RS 4 This instructs \fBfwknopd\fR -to accept complete commands that are contained within an authorization packet\&. Any such command will be executed as root by the +to accept complete commands that are contained within an authorization packet\&. Any such command will be executed on the \fBfwknopd\fR -server\&. +server as the user specified by the \(lqCMD_EXEC_USER\(rq or as the user that started +\fBfwknopd\fR +if that is not set\&. .RE .PP \fBCMD_EXEC_USER\fR: \fI\fR @@ -488,7 +456,7 @@ Defines all knock sequences and access control directives\&. The \fBfwknopd\fR daemon requires a functioning Netfilter firewall on the underlying operating system\&. .SH "DIAGNOSTICS" .sp -\fBfwknopd\fR can be run in debug mode with the \fB\-\-debug\fR command line option\&. This will disable daemon mode execution, and print verbose information to the screen on STDERR as packets are received\&. +\fBfwknopd\fR can be run in debug mode by combining the \fB\-f, \-\-foreground\fR and the \fB\-v, \-\-verbose\fR command line options\&. This will disable daemon mode execution, and print verbose information to the screen on stderr as packets are received\&. .SH "SEE ALSO" .sp fwknop(8), iptables(8), libfko docmentation\&. diff --git a/server/fwknopd.c b/server/fwknopd.c index 21688fed..d7aef353 100644 --- a/server/fwknopd.c +++ b/server/fwknopd.c @@ -92,7 +92,6 @@ main(int argc, char **argv) */ if(opts.status == 1) { - //old_pid = get_running_pid(&opts); old_pid = write_pid_file(&opts); if(old_pid > 0) diff --git a/server/fwknopd.conf b/server/fwknopd.conf index da68b9e4..e6e6593c 100644 --- a/server/fwknopd.conf +++ b/server/fwknopd.conf @@ -69,9 +69,7 @@ ENABLE_DIGEST_PERSISTENCE Y; # Allow SPA clients to request access to services through an iptables # firewall instead of just to it (i.e. access through the FWKNOP_FORWARD -# chain instead of the INPUT chain). This also requires the -# ENABLE_FORWARD_ACCESS variable to be set in the access.conf file for the -# specific SOURCE stanzas that should be allowed for forwarding access. +# chain instead of the INPUT chain). # ENABLE_IPT_FORWARDING N; @@ -116,29 +114,6 @@ MAX_SNIFF_BYTES 1500; FLUSH_IPT_AT_INIT Y; FLUSH_IPT_AT_EXIT Y; -# If running on ipfw firewalls, this variable defines the rule number that -# fwknopd uses to insert an ipfw pass rule. -# -# NOTE: Not supported yet. -# -#IPFW_RULE_NUM 1; - -# If running on ipfw firewalls, this variable defines the rule set that will -# be used to store expired rules that still have a dynamic rule associated -# to them. That set will be disabled by fwknop and should not be enabled -# while fwknop is running. Not used when ipfw isn't using dynamic rules. -# -# NOTE: Not supported yet. -# -#IPFW_SET_NUM 1; - -# For ipfw firewalls set the interval (in seconds) over which rules that -# have no remaining dynamic rules associated with them will be removed. -# -# NOTE: Not supported yet. -# -#IPFW_DYNAMIC_INTERVAL 60; ### seconds - # If GPG keys are used instead of a Rijndael symmetric key, this is # the default GPG keys directory. Note that each access block in # fwknop access.conf can specify its own GPG directory to override @@ -274,7 +249,7 @@ IPT_DNAT_ACCESS DNAT, nat, PREROUTING, 1, FWKNOP_PREROUTING, 1; IPT_SNAT_ACCESS SNAT, nat, POSTROUTING, 1, FWKNOP_POSTROUTING, 1; IPT_MASQUERADE_ACCESS MASQUERADE, nat, POSTROUTING, 1, FWKNOP_POSTROUTING, 1; -# Directories - These will override compile-time defaults. +# Directories - These can override compile-time defaults. # #FWKNOP_RUN_DIR /var/run/fwknop; #FWKNOP_CONF_DIR /etc/fwknop; @@ -288,6 +263,5 @@ IPT_MASQUERADE_ACCESS MASQUERADE, nat, POSTROUTING, 1, FWKNOP_POSTROUTING, 1; # System binaries # #EXE_IPTABLES /sbin/iptables; -#EXE_IPFW /sbin/ipfw; ### BSD and Mac OS X only ###EOF###