documentation of modules config, contents, cryptography

minor code fixes

include/config.h

@@ -5,36 +5,60 @@
 #ifndef PDF_SIGIL_CONFIG_H
 #define PDF_SIGIL_CONFIG_H
 
-
-// maximum bytes to read from the beginning of file to look for the "%PDF-x.y"
+/** @brief maximum bytes to read from the beginning of the file to look for
+ *         the "%PDF-x.y"
+ *
+ */
 #define HEADER_SEARCH_OFFSET        1024
 
-// maximum bytes to read from the end of file to look for the "startxref"
+/** @brief maximum bytes to read from the end of file to look for the "startxref"
+ *
+ */
 #define XREF_SEARCH_OFFSET          1024
 
-// capacity to choose for the first xref allocation
+/** @brief capacity to choose for the first xref allocation
+ *
+ */
 #define XREF_PREALLOCATION          10
 
-// capacity to choose for the first allocation in array of fields
+/** @brief capacity to choose for the first allocation in array of fields
+ *
+ */
 #define REF_ARRAY_PREALLOCATION     10
 
-// capacity to choose for the first allocation of array for certificates
+/** @brief capacity to choose for the first allocation of array for certificates
+ *
+ */
 #define CERT_HEX_PREALLOCATION      1024
 
-// capacity to choose for the first allocation of array for contents
+/** @brief capacity to choose for the first allocation of array for contents
+ *
+ */
 #define CONTENTS_PREALLOCATION      1024
 
-// threshold in bytes for loading whole file into buffer
+/** @brief threshold in bytes for loading whole file into buffer
+ *
+ */
 #define THRESHOLD_FILE_BUFFERING    10485760
 
-// maximum number of file updates, preventing forever loop in processing
-// previous cross-reference sections (caused by cyclic links)
+/** @brief maximum number of file updates, preventing forever loop in processing
+ *         previous cross-reference sections (caused by cyclic links)
+ *
+ */
 #define MAX_FILE_UPDATES            1024
 
-// maximum size we give to hash function at once
+/** @brief maximum size we give to hash function at once
+ *
+ */
 #define HASH_UPDATE_SIZE            1024
 
-// validate values
+/** @brief Tests for the config module
+ *
+ * @param verbosity output level - 0 means nothing, 1 prints module names with
+ *                  the overall module result, and 2 prints also each test inside
+ *                  of the module
+ * @return 0 if success, 1 if failed
+ */
 int sigil_config_self_test(int verbosity);
 
 #endif /* PDF_SIGIL_CONFIG_H */

include/contents.h

@@ -7,9 +7,20 @@
 
 #include "types.h"
 
-
+/** @brief Load the data from Contents entry in the signature dictionary
+ *
+ * @param sgl context
+ * @return ERR_NONE if success
+ */
 sigil_err_t parse_contents(sigil_t *sgl);
 
+/** @brief Tests for the contents module
+ *
+ * @param verbosity output level - 0 means nothing, 1 prints module names with
+ *                  the overall module result, and 2 prints also each test inside
+ *                  of the module
+ * @return 0 if success, 1 if failed
+ */
 int sigil_contents_self_test(int verbosity);
 
 #endif //PDF_SIGIL_CONTENTS_H

include/cryptography.h

@@ -7,23 +7,66 @@
 
 #include "types.h"
 
-
+/** @brief Converts hexadecimal characters to the decimal value. Operates with
+ *         characters both on input and output, 2 chars on the input produces
+ *         1 char on the output
+ *
+ * @param in input - hexadecimal characters
+ * @param in_len length of the input
+ * @param out output buffer
+ * @param out_len length of the output written (without the terminating null)
+ * @return ERR_NONE if success
+ */
 sigil_err_t hex_to_dec(const char *in, size_t in_len, unsigned char *out, size_t *out_len);
 
 void print_computed_hash(sigil_t *sgl);
 
+/** @brief Compute a message digest (hash) for the PKCS#1 signature type
+ *
+ * @param sgl context
+ * @return ERR_NONE if success
+ */
 sigil_err_t compute_digest_pkcs1(sigil_t *sgl);
 
+/** @brief Load certificates from the hex form to the X.509 object
+ *
+ * @param sgl context
+ * @return ERR_NONE if success
+ */
 sigil_err_t load_certificates(sigil_t *sgl);
 
+/** @brief Get the original message digest from the loaded hexadecimal form of the
+ *         Contents entry from the signature dictionary
+ *
+ * @param sgl context
+ * @return ERR_NONE if success
+ */
 sigil_err_t load_digest(sigil_t *sgl);
 
+/** @brief Verify validity of the signing certificate. If present, it is using
+ *         the other provided certificates to build the chain of trust. Does
+ *         save the result inside of the context (NOT the return value)
+ *
+ * @param sgl context
+ * @return ERR_NONE if success
+ */
 sigil_err_t verify_signing_certificate(sigil_t *sgl);
 
+/** @brief Compare the message digest from the signature with the computed one.
+ *         Does save the result inside of the context (NOT the return value)
+ *
+ * @param sgl context
+ * @return ERR_NONE if success
+ */
 sigil_err_t compare_digest(sigil_t *sgl);
 
-sigil_err_t verify_digest(sigil_t *sgl, int *result);
-
+/** @brief Tests for the cryptography module
+ *
+ * @param verbosity output level - 0 means nothing, 1 prints module names with
+ *                  the overall module result, and 2 prints also each test inside
+ *                  of the module
+ * @return 0 if success, 1 if failed
+ */
 int sigil_cryptography_self_test(int verbosity);
 
 #endif /* PDF_SIGIL_CRYPTOGRAPHY_H */

lib/contents.c

@@ -70,4 +70,22 @@ sigil_err_t parse_contents(sigil_t *sgl)
 
         position++;
     }
+}
+
+int sigil_contents_self_test(int verbosity)
+{
+    print_module_name("contents", verbosity);
+
+    // place for possible later tests
+    // ...
+
+    // all tests done
+    print_module_result(1, verbosity);
+    return 0;
+
+failed:
+    print_test_result(0, verbosity);
+    print_module_result(0, verbosity);
+
+    return 1;
 }
\ No newline at end of file

lib/cryptography.c

@@ -399,18 +399,20 @@ sigil_err_t compare_digest(sigil_t *sgl)
     return ERR_NONE;
 }
 
-sigil_err_t verify_digest(sigil_t *sgl, int *result)
+int sigil_cryptography_self_test(int verbosity)
 {
-    sigil_err_t err;
+    print_module_name("cryptography", verbosity);
 
-    if (sgl == NULL || result == NULL)
-        return ERR_PARAMETER;
+    // place for possible later tests
+    // ...
 
-    *result = 1;
+    // all tests done
+    print_module_result(1, verbosity);
+    return 0;
 
-    err = compute_digest_pkcs1(sgl);
-    if (err != ERR_NONE)
-        return err;
+failed:
+    print_test_result(0, verbosity);
+    print_module_result(0, verbosity);
 
-    return compare_digest(sgl);
-}
+    return 1;
+}
\ No newline at end of file

lib/sigil.c

@@ -247,7 +247,11 @@ static sigil_err_t sigil_verify_adbe_x509_rsa_sha1(sigil_t *sgl)
     if (err != ERR_NONE)
         return err;
 
-    return verify_digest(sgl, &(sgl->result_digest_comparison));
+    err = compute_digest_pkcs1(sgl);
+    if (err != ERR_NONE)
+        return err;
+
+    return compare_digest(sgl);
 }
 
 sigil_err_t sigil_verify(sigil_t *sgl)

test/test.c

@@ -5,6 +5,8 @@
 #include "catalog.h"
 #include "cert.h"
 #include "config.h"
+#include "contents.h"
+#include "cryptography.h"
 #include "header.h"
 #include "sigil.h"
 #include "trailer.h"
@@ -64,6 +66,10 @@ int main(int argc, char **argv)
         failed++;
     if (sigil_cert_self_test(verbosity) != 0)
         failed++;
+    if (sigil_contents_self_test(verbosity) != 0)
+        failed++;
+    if (sigil_cryptography_self_test(verbosity) != 0)
+        failed++;
     if (sigil_sigil_self_test(verbosity) != 0)
         failed++;