From 63b4da38dcd320e18b74641fac42ddad11876aa4 Mon Sep 17 00:00:00 2001 From: Damien Stuart Date: Sat, 19 Jun 2010 01:15:19 +0000 Subject: [PATCH] Mostly documentation file updates. git-svn-id: file:///home/mbr/svn/fwknop/trunk@218 510a4753-2344-4c79-9c09-4d669213fbeb --- README | 24 +++++++++++++++++++++++- TODO | 14 +++----------- doc/README | 21 +++++++++++++++++++++ doc/fwknop.man.asciidoc | 11 ++++++----- doc/libfko.texi | 8 ++++---- 5 files changed, 57 insertions(+), 21 deletions(-) diff --git a/README b/README index 1045af1c..531527ad 100644 --- a/README +++ b/README @@ -24,7 +24,24 @@ This first version is planned to be compatible with fwknop version 1.9.x. BUILDING libfko =============== This distribution uses GNU autoconf for setting up the build. Please see -the `INSTALL' file for details. +the `INSTALL' file for the general basics on using autoconf. + +There are some "configure" options that are specific to fwknop. They are +(extracted from ./configure --help): + + --with-gpgme support for gpg encryption using libgpgme + [default=check] + --with-gpgme-prefix=PFX prefix where GPGME is installed (optional) + --with-gpg=/path/to/gpg Specify path to the gpg executable that gpgme will + use [default=check path] + --with-iptables=/path/to/iptables + Specify path to the iptables executable + [default=check path] + --with-ipfw=/path/to/ipfw + Specify path to the ipfw executable [default=check + path] + --with-sh=/path/to/sh Specify path to the sh executable [default=check + path] NOTE FOR DEVELOPERS @@ -34,3 +51,8 @@ run the "autogen.sh" script in the top of the distribution directory in ' order to generate the autoconf (and other) meta files, and the `configure' script. +The fwknop and fwknopd man page nroff sources are included in their +respective directorys (client and server). These nroff files are derived +from the asciidoc sources in the 'docs' directory. See the README in docs +for details. + diff --git a/TODO b/TODO index 685abfb2..4b983d9d 100644 --- a/TODO +++ b/TODO @@ -5,28 +5,20 @@ To whom it may concern, this is -*- outline -*- mode. ** Get it out there and get feedback. * The fwknop C client: -** Config file support. -** Command-line options and features ala fwknop Perl client: -*** Server Auth support (maybe). +** Config file support (~/.fwknoprc ?). +** Server Auth support (maybe). * The fwknopd server: ** Sniffer support to acquire SPA packet data ala the fwknopd Perl server: *** Packets acquired via a file (supports the ulogd pcap writer). ** SPA packet decryption: -*** Username restrictions. -** Firewall rule manipulation upon receipt of a valid SPA packet: -*** Initially manipulate firewall rules by executing the firewall binary directly. -*** Should concentrate on iptables, but ipfw and pf support eventually. -*** User-defined firewall rule timeouts. -*** NAT rules to internal systems. +*** Add support for ipfw and pf support eventually. ** Test on embedded platforms - especially OpenWRT on a Linksys router. -** Process monitoring daemon (can probably just use knopwatchd since it is C already). * Nice to haves: ** Binary packages: *** Redhat RPMS *** Debian .deb -*** Solaris pkg ** Linux/Unix platform: *** A GNOME or KDE GUI app for the client. ** Windows platform: diff --git a/doc/README b/doc/README index 590080f2..bed99ef8 100644 --- a/doc/README +++ b/doc/README @@ -17,3 +17,24 @@ items on succesive line without intervening lines (i.e. the AUTHORS section of the generated man page). In those cases, simply change the ".sp" between those lines to ".br". +Generating HTML versions of the documentation: + +Here are some of the commands used to create/generate HTML versions of +the fwknop documentation. + +For the libfko API doc, you could just do a "make html" to create a +libfki.html directory with a reasonable set of HTML pages. You can also +use "texi2html" which give a bit more flexibility. For example: + + texi2html --noheader --nomenu --toc-links libfko.texi + +Will generate a single HTML document. With this, the table of contents is +put at the end of the document, but it is not hard to edit the file and to +relocate it to the top. + +For creating HTML versions of the man pages, simply use the "-f xhtml" +option to the "a2x" command: + + a2x -f xhtml fwknopd.man.asciidoc + + diff --git a/doc/fwknop.man.asciidoc b/doc/fwknop.man.asciidoc index f4a211b8..c2ebc511 100644 --- a/doc/fwknop.man.asciidoc +++ b/doc/fwknop.man.asciidoc @@ -106,7 +106,8 @@ REQUIRED ARGUMENTS One of these options (see below) is required to tell the remote *fwknopd* daemon what IP should be let through the local firewall. It is recommend to use the *-R* or *-a* options instead of *-s* in order - to harden SPA communications against possible MITM attacks. + to harden SPA communications against possible Man-In-The-Middle (MITM) + attacks. GENERAL OPTIONS @@ -400,7 +401,7 @@ associated with www.yahoo.com: DEPENDENCIES ------------ *fwknop* requires 'libfko' (which is normally included with both source and -binary distributions. +binary distributions). For GPG functionality, GnuPG must also be correctly installed and configured. @@ -417,14 +418,14 @@ then run it through a decrypt/decode cycle and print it again. SEE ALSO -------- -fwknopd(8), iptables(8), gpg(1), gpg-agent(1), libfko documentation. +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'. -AUTHOR ------- +AUTHORS +------- Damien Stuart Michael Rash diff --git a/doc/libfko.texi b/doc/libfko.texi index bb3ff930..6e268296 100644 --- a/doc/libfko.texi +++ b/doc/libfko.texi @@ -525,7 +525,7 @@ rc = fko_new(&ctx); if(rc != FKO_SUCCESS) @{ - fprintf(stderr, "Error %i from fko_new: %s\n", fko_errstr(rc)); + fprintf(stderr, "Error %i from fko_new: %s\n", rc, fko_errstr(rc)); exit(1); @} @end example @@ -569,7 +569,7 @@ rc = fko_new_with_data(&ctx, spa_data, key); if(rc != FKO_SUCCESS) @{ - fprintf(stderr, "Error %i from fko_new_with_data\n"); + fprintf(stderr, "Error %i from fko_new_with_data: %s\n", rc, fkoerrstr(rc)); exit(1); @} @end example @@ -594,7 +594,7 @@ rc = fko_new_with_data(&ctx, spa_data, NULL); if(rc != FKO_SUCCESS) @{ - fprintf(stderr, "Error %i from fko_new_with_data\n"); + fprintf(stderr, "Error from fko_new_with_data: %s\n", fko_errstr(rc)); exit(1); @} @@ -615,7 +615,7 @@ rc = fko_decrypt_spa_data(ctx, key); if(rc != FKO_SUCCESS) @{ - fprintf(stderr, "Error %i from fko_decrypt_spa_data\n"); + fprintf(stderr, "Error from fko_decrypt_spa_data: %s\n", fko_errstr(rc)); exit(1); @} @end example