Documentation updates and minor tweaks. Made it version 1.10.0 consistent in caonfigure.ac and fko.h.

git-svn-id: file:///home/mbr/svn/fwknop/trunk@47 510a4753-2344-4c79-9c09-4d669213fbeb

ChangeLog

@@ -1,6 +1,6 @@
 2008-12-21  Damien Stuart  <dstuart@dstuart.org>
 
-	Build 2.0.0 alpha
+	Build 1.10.0 alpha
 
     * autogen.sh: created.
     * autoconf/automake: Initial configuration created.

configure.ac

@@ -3,7 +3,7 @@ dnl Process thie file with autoconf to produce teh configure script
 AC_PREREQ(2.61)
 
 m4_define(my_package, [fwknop])
-m4_define(my_version, [1.10.0-alpha])
+m4_define(my_version, [1.10.01-alpha])
 m4_define(my_bug_email, [dstuart@dstuart.org])
 
 AC_INIT(my_package, my_version, my_bug_email)

doc/libfko.texi

@@ -147,10 +147,10 @@ provides the functions for managing the @acronym{SPA} data used by those
 programs. 
 
 @sp 1
+@noindent
 For more information on fwknop and @acronym{SPA}, go to
 @uref{http://www.cipherdyn.org/fwknop}. 
 
-
 @menu
 * Getting Started::               Purpose of the manual, and how to use it
 * Features::                      Reasons to install and use libfko
@@ -268,12 +268,24 @@ The digest of the previous fields (including the delimiters).
 @end deftypevar
 
 With all fields defined, a complete (unencoded) @acronym{SPA} message would
-look like this (Note: the line is broken for readability and the username,
-message, nat_access, and server_auth fields are not base64-encoded):
+look something like the followin example (Note: The line is broken for
+readability and the username, message, nat_access, and server_auth fields
+are not base64-encoded):
+
+@sp 1
 @example
 8307540982176539:juser:1230665172:1.1.10:0.0.0.0,tcp/22:192.168.1.2,22:
 crypt,mypw:120:xswj8V0zMR7/7MV9pQRarSKWG1l9Zfjv+kbXaKrJ+RA
 @end example
+@sp 1
+
+For most of the fields, you need not be too concerned about the format as
+libfko handles that.  The exceptions are the @code{spa_message},
+@code{spa_nat_access}, and @code{spa_server_auth}.  The formats for these
+are not handled by libfko during creation.  However, they are checked for
+format validity during the endcoding and decoding (when parsing incoming)
+@acronym{SPA} data.  More information on the specifics of the formats for
+these fields can be found in @ref{SPA Messages}.
 
 @node Preparation
 @chapter Preparation
@@ -293,6 +305,7 @@ in your programs.
 @section libfko Header
 @cindex header file
 @cindex include file
+@cindex fko.h
 
 All interfaces (data types and functions) of the library are defined
 in the header file `fko.h'.  You must include this in all programs
@@ -441,12 +454,19 @@ of encryption:
 @deftypevar int fko_encryption_type_t
 @table @code
 @item FKO_ENCRYPTION_RIJNDAEL (default)
-@item FKO_ENCRYPTION_GPG  (not yet suppported by libfko)
+@item FKO_ENCRYPTION_GPG
 @end table
 @end deftypevar
 
-At present, libfko only supports the default Rijndael encryption algorithm.
-Support for GnuPG will be added in a future release of libfko.
+As indicated, libfko only uses Rijndael encryption by default.  Rijndael
+encryption is sufficient for most users and produces a much smaller data
+packet than @acronym{GPG} (around 146 bytes or so compared to around 1K for
+@acronym{GPG}).
+
+However, some may prefer the level of protection provided by @acronym{GPG}.
+When selected, additional parameters such as @emph{recipient} and @emph{signer}
+will need to be set as well. See @ref{Setting SPA Data} for detail on
+setting these and other @acronym{SPA} data fields.
 
 @node Using libfko
 @chapter Using libfko
@@ -621,6 +641,14 @@ parameters as well.  Setting the ``type'' parameters first is recommended
 @item spa_message -- @emph{(must be explicitly set)}
 @end itemize
 
+@noindent
+@emph{If using gpg encryption:}
+
+@itemize @bullet
+@item gpg_recipient -- @emph{(must be explicitly set)}
+@item gpg_signer -- @emph{(must be explicitly set)}
+@end itemize
+
 When a context is initialized, some of the @acronym{SPA} data fields are
 pre-set with default values (@pxref{SPA Data Format}).  For fields such
 as @code{rand_val}, @code{username}, @code{timestamp}, @code{message_type},
@@ -631,7 +659,8 @@ parameters are described in detail in @ref{Setting SPA Data}.
 
 @noindent
 @strong{Note}: Attempts to call any ``@code{fko_}'' function on a context that
-has not been initialized will return a status of
+has not been initialized can have undefined consequences.  Libfko will attempt
+to recover, and if succussful, will return a status of
 @code{FKO_ERROR_CTX_NOT_INITIALIZED}.
 
 A common @acronym{SPA} message is a simple access request.  This request asks
@@ -639,8 +668,8 @@ the fwknop server to create a temporary firewall rule to allow a particular
 IP address access to a particular port.  Assuming the defaults are fine
 for this, all we need to do is create the context, set the message data
 field, call the @code{fko_spa_data_final} function to encode and encrypt,
-process the message, then destroy the context.  Here is a contrived chunk of
-code demonstrating this:
+process the message, then destroy the context.  Below, we havea contrived bit
+of code demonstrating this:
 
 @example
 int
@@ -671,6 +700,18 @@ main(int argc, char **argv)
         exit(1);
     @}
 
+    /* Let us assume we are using GPG encryption.  So we need to
+     * set the encrypeion type and set the required GPG parameters
+     * (we can skip checking return values for brevity).
+    */
+    fko_set_spa_encryption_type(ctx, FKO_ENCRYPTION_GPG);
+
+    /* Key for the recipient */
+    fko_set_gpg_recipient(ctx, "recip@@some.where");
+
+    /* Key for the signer */
+    fko_set_gpg_signer(ctx, "me@@right.here");
+
     /* Finalize the SPA data */
     rc = fko_spa_data_final(ctx);
     if(rc != FKO_SUCCESS)
@@ -790,6 +831,26 @@ as it will be called automatically by other functions during normal
 processing (most notably @code{fko_spa_data_final}).
 @end deftypefun
 
+@cindex gpg-specific functions
+@noindent
+@emph{GPG-specific functions:}
+
+@deftypefun int fko_set_gpg_recipient (@w{fko_ctx_t @var{ctx}, const char @var{recipient}});
+Sets the @acronym{GPG} key for the recipient.  This would be the recipient's
+public key used to encyrpt the @acronym{SPA} data.  You can use the user name 
+("recip@@the.dest.com") or the key ID ("5EXXXXCC").  At present, multiple
+recipients are not supported.
+@end deftypefun
+
+@deftypefun int fko_set_gpg_signer (@w{fko_ctx_t @var{ctx}, const char @var{signer}});
+Sets the @acronym{GPG} key for signing the data.  This would be the sender's
+key used to sign the @acronym{SPA} data. You can use the user name or key ID.
+@end deftypefun
+
+@noindent
+@strong{Note}: On a libfko build without @acronym{GPG} support, the
+GPG-related functions above will simply return the FKO_ERROR_UNSUPPORTED_FEATURE
+error code.
 
 @node Retrieving SPA Data
 @section Retrieving SPA Data
@@ -893,6 +954,24 @@ that is being created in a new context.  For data parsed from an external
 source, the version string will be whatever the provided data was set to.
 @end deftypefun
 
+@cindex gpg-specific functions
+@noindent
+@emph{GPG-specific functions:}
+
+@deftypefun char* fko_get_gpg_recipient (@w{fko_ctx_t @var{ctx}});
+Returns a pointer to the string containing the @acronym{GPG} key for the
+recipient (as set with @emph{fko_set_gpg_recipient}).
+@end deftypefun
+
+@deftypefun char* fko_get_gpg_signer (@w{fko_ctx_t @var{ctx}});
+Returns a pointer to the string containing the @acronym{GPG} key for the
+signer of the @acronym{SPA} data (as set with @emph{fko_set_gpg_signer}).
+@end deftypefun
+
+@noindent
+@strong{Note}:  On a libfko build without @acronym{GPG} support, the
+GPG-related functions above will simply return NULL.
+
 @node Utility Functions
 @section Utility Functions
 @cindex utility functions
@@ -996,7 +1075,11 @@ Invalid SPA access mesage format
 Invalid SPA nat_access mesage format
 @item FKO_ERROR_INVALID_ENCRYPTION_TYPE
 Invalid encryption type
-@item FKO_ERROR_DECRYPTION_SIZE_ERROR
+@item FKO_ERROR_WRONG_ENCRYPTION_TYPE
+Wrong or inappropriate encryption type for this operation
+@item FKO_ERROR_MISSING_GPG_KEY_DATA
+Missing GPG key data (signer or recipient not set)
+@item FKO_ERROR_DECRYPTION_SIZE
 Unexpected or invalid size for decrypted data
 @item FKO_ERROR_DIGEST_VERIFICATION_FAILED
 The computed digest did not match the digest in the spa data

fko/fko.h

@@ -28,7 +28,7 @@
 
 /* General params
 */
-#define FKO_PROTOCOL_VERSION "1.9.10" /* The fwknop protocol version */
+#define FKO_PROTOCOL_VERSION "1.10.0" /* The fwknop protocol version */
 
 /* Supported FKO Message types...
 */
@@ -83,7 +83,7 @@ typedef enum {
     FKO_ERROR_INVALID_ENCRYPTION_TYPE,
     FKO_ERROR_WRONG_ENCRYPTION_TYPE,
     FKO_ERROR_MISSING_GPG_KEY_DATA,
-    FKO_ERROR_DECRYPTION_SIZE_ERROR,
+    FKO_ERROR_DECRYPTION_SIZE,
     FKO_ERROR_DIGEST_VERIFICATION_FAILED,
 /* Add more errors above this line */
     FKO_ERROR_UNSUPPORTED_FEATURE,

fko/fko_encryption.c

@@ -139,7 +139,7 @@ _rijndael_decrypt(fko_ctx_t ctx, const char *dec_key, int b64_len)
      * length of the encrypted version.
     */
     if(pt_len < (cipher_len - 32))
-        return(FKO_ERROR_DECRYPTION_SIZE_ERROR);
+        return(FKO_ERROR_DECRYPTION_SIZE);
 
     /* Call fko_decode and return the results.
     */

fko/fko_error.c

@@ -30,25 +30,46 @@
 *       defined in fko.h.
 */
 static const char *fko_err_msgs[] = {
+
+    /* FKO_SUCCESS */
     "Success",
+    /* FKO_ERROR_CTX_NOT_INITIALIZED */
     "FKO Context is not initialized",
+    /* FKO_ERROR_MEMORY_ALLOCATION */
     "Unable to allocate memory",
+    /* FKO_ERROR_INVALID_DATA */
     "Args contain invalid data",
+    /* FKO_ERROR_DATA_TOO_LARGE */
     "Value or Size of the data exceeded the max allowed",
+    /* FKO_ERROR_USERNAME_UNKNOWN */
     "Unable to determine username",
+    /* FKO_ERROR_INCOMPLETE_SPA_DATA */
     "Missing or incomplete SPA data",
+    /* FKO_ERROR_MISSING_ENCODED_DATA */
     "There is no encoded data to process",
+    /* FKO_ERROR_INVALID_DIGEST_TYPE */
     "Invalid digest type",
+    /* FKO_ERROR_INVALID_ALLOW_IP */
     "Invalid allow IP address in the SPA mesage data",
+    /* FKO_ERROR_INVALID_SPA_COMMAND_MSG */
     "Invalid SPA command mesage format",
+    /* FKO_ERROR_INVALID_SPA_ACCESS_MSG */
     "Invalid SPA access mesage format",
+    /* FKO_ERROR_INVALID_SPA_NAT_ACCESS_MSG */
     "Invalid SPA nat_access mesage format",
+    /* FKO_ERROR_INVALID_ENCRYPTION_TYPE */
     "Invalid encryption type",
+    /* FKO_ERROR_WRONG_ENCRYPTION_TYPE */
     "Wrong or inappropriate encryption type for this operation",
+    /* FKO_ERROR_MISSING_GPG_KEY_DATA */
     "Missing GPG key data (signer or recipient not set)",
+    /* FKO_ERROR_DECRYPTION_SIZE */
     "Unexpected or invalid size for decrypted data",
+    /* FKO_ERROR_DIGEST_VERIFICATION_FAILED */
     "The computed digest did not match the digest in the spa data",
+    /* FKO_ERROR_UNSUPPORTED_FEATURE */
     "Unsupported or unimplemented feature or function",
+    /* FKO_ERROR_UNKNOWN */
     "Unknown/Unclassified error",
     0
 };