Initial Doxygen config file and work on documenting libfko functions

lib/fko_context.h

@@ -1,10 +1,11 @@
+/**
+ *
+ * \file fko_context.h
+ *
+ * \brief fko context definiton.
+ */
+
 /*
- *****************************************************************************
- *
- * File:    fko_context.h
- *
- * Purpose: fko context definition.
- *
  *  Fwknop is developed primarily by the people listed in the file 'AUTHORS'.
  *  Copyright (C) 2009-2015 fwknop developers and contributors. For a full
  *  list of contributors, see the file 'CREDITS'.
@@ -37,12 +38,16 @@
   #include <gpgme.h>
 #endif
 
-#if HAVE_LIBGPGME
-/* Stucture to hold a list of the gpg signature information
- * we are interested in.
-*/
+#if HAVE_LIBGPGME || DOXYGEN
+
+/**
+ *
+ * \struct fko_gpg_sig
+ *
+ * \brief Stucture to hold a list of the gpg signature information we are interested in.
+ */
 struct fko_gpg_sig {
-    struct fko_gpg_sig *next;
+    struct fko_gpg_sig *next; /**< link to next member */
     gpgme_sigsum_t      summary;
     gpgme_error_t       status;
     gpgme_validity_t    validity;
@@ -52,11 +57,16 @@ struct fko_gpg_sig {
 typedef struct fko_gpg_sig *fko_gpg_sig_t;
 #endif /* HAVE_LIBGPGME */
 
-/* The pieces we need to make an FKO  SPA data packet.
-*/
+/**
+ *
+ * \struct fko_context
+ *
+ * \brief The pieces we need to make an FKO SPA data packet.
+ */
 struct fko_context {
+    /** \name FKO SPA user-definable message data */
 
-    /* FKO SPA user-definable message data */
+    /*@{*/
     char           *rand_val;
     char           *username;
     time_t          timestamp;
@@ -65,26 +75,30 @@ struct fko_context {
     char           *nat_access;
     char           *server_auth;
     unsigned int    client_timeout;
-
-    /* FKO SPA user-settable message encoding types */
+    /*@}*/
+    /** \name FKO SPA user-settable message encoding types */
+    /*@{*/
     short  digest_type;
     short  encryption_type;
     int    encryption_mode;
     short  hmac_type;
-
-    /* Computed or predefined data */
+    /*@}*/
+    /** \name Computed or predefined data */
+    /*@{*/
     char           *version;
     char           *digest;
     int             digest_len;
-
-    /* Digest of raw encrypted/base64 data - this is used
-     * for replay attack detection
+    /*@}*/
+    /** \name Digest of raw encrypted/base64 data 
+     * This is used for replay attack detection
     */
+    /*@{*/
     char           *raw_digest;
     short           raw_digest_type;
     int             raw_digest_len;
-
-    /* Computed processed data (encodings, etc.) */
+    /*@}*/
+    /** \name Computed processed data (encodings, etc.) */
+    /*@{*/
     char           *encoded_msg;
     int             encoded_msg_len;
     char           *encrypted_msg;
@@ -93,13 +107,15 @@ struct fko_context {
     int             msg_hmac_len;
     int             added_salted_str;
     int             added_gpg_prefix;
-
-    /* State info */
+    /*@}*/
+    /** \name State info */
+    /*@{*/
     unsigned int    state;
     unsigned char   initval;
-
+    /*@}*/
 #if HAVE_LIBGPGME
-    /* For gpgme support */
+    /** \name For gpgme support */
+    /*@{*/
     char           *gpg_exe;
     char           *gpg_recipient;
     char           *gpg_signer;
@@ -117,6 +133,7 @@ struct fko_context {
     fko_gpg_sig_t   gpg_sigs;
 
     gpgme_error_t   gpg_err;
+    /*@}*/
 #endif /* HAVE_LIBGPGME */
 };
 

lib/hmac.h

@@ -34,7 +34,18 @@
 #include "digest.h"
 
 #define MAX_DIGEST_BLOCK_LEN    SHA512_BLOCK_LEN
-
+/**
+ * \brief Generate MD5 based HMAC
+ *
+ * This function generates an HMAC verification hash, based on MD5
+ *
+ * \param msg Pointer to the message to be signed
+ * \param msg_len size of the message string
+ * \param hmac Pointer to the hmac buffer, where the final hmac will be stored
+ * \param hmac_key Pointer to the key to be used for generating the hmac
+ * \param hmac_key_len Size of the hmac key
+ *
+ */
 void hmac_md5(const char *msg, const unsigned int msg_len,
         unsigned char *hmac, const char *hmac_key, const int hmac_key_len);
 void hmac_sha1(const char *msg, const unsigned int msg_len,

server/access.c

@@ -1362,7 +1362,11 @@ acc_data_is_valid(fko_srv_options_t *opts,
 
     return(1);
 }
-
+/**
+ * \brief Parses an access folder
+ *
+ * This function processes all the *.conf files in the specified directory.
+ */
 int
 parse_access_folder(fko_srv_options_t *opts, char *access_folder, int *depth)
 {