Make doxygen mandatory and fix undocumented functions / add deprecation notices (#329)

* Make doxygen mandatory and fix undocumented functions / add deprecation notices

* NTRU needs HAVE_BOOL in the right spot

* Add doxygen to Travis environment

* Prettyprint

* Doxygen build changes

* Doxygen / prettyprint incompatibility

.travis.yml

@@ -17,6 +17,9 @@ matrix:
       apt:
         sources:
         - ubuntu-toolchain-r-test
+        packages:
+        - doxygen
+        - graphviz
     before_install:
     - sh .travis/install-clang-format-linux.sh
   - os: linux
@@ -30,6 +33,8 @@ matrix:
         - ubuntu-toolchain-r-test
         packages:
         - gcc-4.9
+        - doxygen
+        - graphviz
     before_install:
     - sh .travis/install-clang-format-linux.sh
   - os: linux
@@ -41,6 +46,8 @@ matrix:
         - ubuntu-toolchain-r-test
         packages:
         - gcc-5
+        - doxygen
+        - graphviz
   - os: linux
     compiler: gcc
     env:
@@ -53,11 +60,16 @@ matrix:
         packages:
         - gcc-6
         - libssl-dev
+        - doxygen
+        - graphviz
   - os: osx
     compiler: clang
     env:
     - CC_OVERRIDE=clang
     - AES_NI=0
+    before_install:
+    - brew update
+    - brew install libsodium doxygen graphviz
   - os: osx
     compiler: clang
     env:
@@ -68,7 +80,7 @@ matrix:
     - ENABLE_CODE_MCBITS=1
     before_install:
     - brew update
-    - brew install libsodium
+    - brew install libsodium doxygen graphviz
 
 script:
   - .travis/all-tests.sh

.travis/all-tests.sh

@@ -78,6 +78,7 @@ autoreconf -i
 ./configure --enable-silent-rules ${enable_disable_str}
 make clean
 make
+make docs
 make test
 
 for f in $(ls .travis/*-check.sh); do

docs/.Doxyfile

@@ -763,7 +763,7 @@ WARN_NO_PARAMDOC       = NO
 # a warning is encountered.
 # The default value is: NO.
 
-WARN_AS_ERROR          = NO
+WARN_AS_ERROR          = YES
 
 # The WARN_FORMAT tag determines the format of the warning messages that doxygen
 # can produce. The string should contain the $file, $line, and $text tags, which
@@ -874,7 +874,13 @@ RECURSIVE              = NO
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                =
+EXCLUDE                = include/oqs/kex.h \
+                         include/oqs/kex_ntru.h \
+                         include/oqs/kex_code_mcbits.h \
+                         include/oqs/kex_rlwe_newhope.h \
+                         include/oqs/kex_sidh_msr.h \
+                         include/oqs/rand_urandom_aesctr.h \
+                         include/oqs/rand_urandom_chacha20.h
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded

src/common/common.h

@@ -84,13 +84,21 @@ void OQS_MEM_secure_free(void *ptr, size_t len);
  */
 void OQS_MEM_insecure_free(void *ptr);
 
+/**
+ * Function to print a message to standard error.  Workaround on Android to print
+ * directly to stdout.
+ */
 #if __ANDROID__
-//android workaround
 #define eprintf(...) printf(__VA_ARGS__);
 #else
 #define eprintf(...) fprintf(stderr, __VA_ARGS__);
 #endif
 
+/**
+ * Macros that indicates a function argument may be unused.  Used to comply with
+ * an API specification but when an implementation doesn't actually use the argument
+ * and we'd get a compiler warning otherwise.
+ */
 #if defined(_WIN32)
 #define UNUSED
 // __attribute__ not supported in VS

src/common/rand.h

@@ -7,7 +7,6 @@
 #define __OQS_RANDOM_H
 
 #include <stdbool.h>
-#define HAVE_BOOL
 #include <stddef.h>
 #include <stdint.h>
 
@@ -74,19 +73,30 @@ void OQS_randombytes_system(uint8_t *random_array, size_t bytes_to_read);
  ********************/
 
 /************************************************************
- *** START DEPRECATED CODE *** expected removal Aug. 2018 ***
+ *** START DEPRECATED CODE *** expected removal Sep. 2018 ***
  ************************************************************/
 
+/** Algorithm identifiers
+ *
+ * @deprecated Expected removal Sep. 2018
+ */
 enum OQS_RAND_alg_name {
 	OQS_RAND_alg_default,
 	OQS_RAND_alg_urandom_chacha20,
 	OQS_RAND_alg_urandom_aesctr,
 };
 
+/**
+ * OQS PRNG object
+ *
+ * @deprecated Expected removal Sep. 2018
+ */
 typedef struct OQS_RAND OQS_RAND;
 
 /**
  * OQS PRNG object
+ *
+ * @deprecated Expected removal Sep. 2018
  */
 struct OQS_RAND {
 
@@ -114,54 +124,157 @@ struct OQS_RAND {
 
 	/**
 	 * Function which returns an 8-bit random unsigned integer
+	 *
+	 * @param r PRNG object
 	 */
 	uint8_t (*rand_8)(OQS_RAND *r);
 
 	/**
 	 * Function which returns an 32-bit random unsigned integer
+	 *
+	 * @param r PRNG object
 	 */
 	uint32_t (*rand_32)(OQS_RAND *r);
 
 	/**
 	 * Function which returns an 64-bit random unsigned integer
+	 *
+	 * @param r PRNG object
 	 */
 	uint64_t (*rand_64)(OQS_RAND *r);
 
 	/**
 	 * Function which generates n random 8-bit unsigned integers
 	 *
-	 * @param out : pointer to an array large enough to store the output integers (\f$\text{size} \geq n\f$)
+	 * @param r PRNG object
-	 * @param n : number of integers to generate
+	 * @param out pointer to an array large enough to store the output integers (\f$\text{size} \geq n\f$)
+	 * @param n number of integers to generate
 	 */
 	void (*rand_n)(OQS_RAND *r, uint8_t *out, size_t n);
 
 	/**
 	 * Pointer to a function for freeing the allocated key exchange structure
 	 *
-	 * @param k : Key exchange structure
+	 * @param r PRNG object
-	 *
 	 */
 	void (*free)(OQS_RAND *r);
 };
 
+/**
+ * Construct a new PRNG object
+ *
+ * @param alg_name Algorithm identifier
+ * @deprecated Expected removal Sep. 2018
+ */
 OQS_RAND *OQS_RAND_new(enum OQS_RAND_alg_name alg_name);
 
+/**
+ * Function which returns an 8-bit random unsigned integer
+ *
+ * @param r PRNG object
+ * @deprecated Expected removal Sep. 2018
+ */
 uint8_t OQS_RAND_8(OQS_RAND *r);
+
+/**
+ * Function which returns an 32-bit random unsigned integer
+ *
+ * @param r PRNG object
+ * @deprecated Expected removal Sep. 2018
+ */
 uint32_t OQS_RAND_32(OQS_RAND *r);
+
+/**
+ * Function which returns an 64-bit random unsigned integer
+ *
+ * @param r PRNG object
+ * @deprecated Expected removal Sep. 2018
+ */
 uint64_t OQS_RAND_64(OQS_RAND *r);
+
+/**
+ * Function which generates n random 8-bit unsigned integers
+ *
+ * @param r PRNG object
+ * @param out pointer to an array large enough to store the output integers (\f$\text{size} \geq n\f$)
+ * @param n number of integers to generate
+ * @deprecated Expected removal Sep. 2018
+ */
 void OQS_RAND_n(OQS_RAND *r, uint8_t *out, size_t n);
 
+/**
+ * Pointer to a function for freeing the allocated key exchange structure
+ *
+ * @param r PRNG object
+ * @deprecated Expected removal Sep. 2018
+ */
 void OQS_RAND_free(OQS_RAND *r);
 
+/**
+ * Internal function for statistical testing
+ *
+ * @param b undocumented
+ * @param occurrences undocumented
+ * @deprecated Expected removal Sep. 2018
+ */
 void OQS_RAND_test_record_occurrence(const unsigned char b, unsigned long occurrences[256]);
+
+/**
+ * Internal function for statistical testing
+ *
+ * @param occurrences undocumented
+ * @return undocumented
+ * @deprecated Expected removal Sep. 2018
+ */
 double OQS_RAND_test_statistical_distance_from_uniform(const unsigned long occurrences[256]);
 
+/**
+ * Parameter for statistical testing.
+ *
+ * @deprecated Expected removal Sep. 2018
+ */
 #define ZSCORE_SPARSE (999.999)
+
+/**
+ * Parameter for statistical testing.
+ *
+ * @deprecated Expected removal Sep. 2018
+ */
 #define ZSCORE_BIGNEG (-100.0)
+
+/**
+ * Parameter for statistical testing.
+ *
+ * @deprecated Expected removal Sep. 2018
+ */
 #define ZSCORE_BIGPOS (+100.0)
+
+/**
+ * Internal function for statistical testing
+ *
+ * @param occurrences undocumented
+ * @return undocumented
+ * @deprecated Expected removal Sep. 2018
+ */
 double OQS_RAND_zscore_deviation_from_uniform(const unsigned long occurrences[256]);
+
+/**
+ * Internal function for statistical testing
+ *
+ * @param occurrences undocumented
+ * @param indent undocumented
+ * @deprecated Expected removal Sep. 2018
+ */
 void OQS_RAND_report_statistics(const unsigned long occurrences[256], const char *indent);
 
+/**
+ * undocumented
+ *
+ * @param buf undocumented
+ * @param n undocumented
+ * @return undocumented
+ * @deprecated Expected removal Sep. 2018
+ */
 OQS_STATUS OQS_RAND_get_system_entropy(uint8_t *buf, size_t n);
 
 /***********************************************************

src/crypto/aes/aes.h

@@ -14,7 +14,7 @@
  *
  * @param key            Initial Key.
  * @param schedule       Abstract data structure for a key schedule.
- * @param forEncryption  1 if key schedule is for encryption, 0 if for decryption.
+ * @param for_encryption 1 if key schedule is for encryption, 0 if for decryption.
  */
 void OQS_AES128_load_schedule(const uint8_t *key, void **schedule, int for_encryption);
 
@@ -43,7 +43,7 @@ void OQS_AES128_ECB_enc(const uint8_t *plaintext, const size_t plaintext_len, co
  * @param ciphertext     Ciphertext to be decrypted.
  * @param ciphertext_len Length on the ciphertext in bytes. Must be a multiple of 16.
  * @param key            Key to be used for encryption.
- * @param ciphertext     Pointer to a block of memory which >= in size to the ciphertext block. The result will be written here.
+ * @param plaintext      Pointer to a block of memory which >= in size to the ciphertext block. The result will be written here.
  */
 void OQS_AES128_ECB_dec(const uint8_t *ciphertext, const size_t ciphertext_len, const uint8_t *key, uint8_t *plaintext);
 

src/crypto/rand_urandom_aesctr/rand_urandom_aesctr.h

@@ -1,6 +1,7 @@
 /**
  * \file rand_urandom_aesctr.h
  * \brief Header for the chacha implementation of OQS_RAND
+ * \deprecated Expected removal Sep. 2018
  */
 
 #ifndef __OQS_RAND_URANDOM_AESCTR_H

src/crypto/rand_urandom_chacha20/rand_urandom_chacha20.h

@@ -1,6 +1,7 @@
 /**
  * \file rand_urandom_chacha20.h
  * \brief Header for the chacha implementation of OQS_RAND
+ * \deprecated Expected removal Sep. 2018
  */
 
 #ifndef __OQS_RAND_URANDOM_CHACHA20_H

src/kex/kex.h

@@ -1,6 +1,7 @@
 /**
  * \file kex.h
  * \brief Header defining the API for generic OQS Key exchange
+ * \deprecated Expected removal Sep. 2018
  */
 
 #ifndef __OQS_KEX_H

src/kex_code_mcbits/kex_code_mcbits.h

@@ -1,6 +1,7 @@
 /**
  * \file kex_code_mcbits.h
  * \brief Header for code-based key exchange protocol McBits
+ * \deprecated Expected removal Sep. 2018
  */
 
 #ifndef __OQS_KEX_CODE_MCBITS_H

src/kex_ntru/kex_ntru.c

@@ -13,6 +13,7 @@
 #include <oqs/kex_ntru.h>
 #include <oqs/rand.h>
 
+#define HAVE_BOOL
 #include <ntru_crypto.h>
 
 #if defined(_WIN32)

src/kex_ntru/kex_ntru.h

@@ -1,6 +1,7 @@
 /**
  * \file kex_ntru.h
  * \brief Header for the NTRU implementation of OQS_KEX
+ * \deprecated Expected removal Sep. 2018
  */
 
 #ifndef __OQS_KEX_NTRU_H

src/kex_rlwe_newhope/kex_rlwe_newhope.h

@@ -1,6 +1,7 @@
 /**
  * \file kex_rlwe_newhope.h
  * \brief Header for ring-LWE key exchange protocol NewHope
+ * \deprecated Expected removal Sep. 2018
  */
 
 #ifndef __OQS_KEX_RLWE_NEWHOPE_H

src/kex_sidh_msr/kex_sidh_msr.h

@@ -1,6 +1,7 @@
 /**
  * \file kex_sidh_msr.h
  * \brief Header for SIDH key exchange protocol from the Microsoft SIDH library
+ * \deprecated Expected removal Sep. 2018
  */
 
 #ifndef __OQS_KEX_SIDH_MSR_H

src/sig/sig.h

@@ -1,6 +1,7 @@
 /**
  * \file sig.h
  * \brief Header defining the API for generic OQS Signature
+ * \deprecated Expected removal Sep. 2018
  */
 
 #ifndef __OQS_SIG_H
@@ -43,6 +44,10 @@ enum OQS_SIG_algid {
  * OQS signature object
  */
 typedef struct OQS_SIG OQS_SIG; // so the code below compiles...
+
+/**
+ * OQS signature object
+ */
 struct OQS_SIG {
 
 	/**
@@ -87,6 +92,8 @@ struct OQS_SIG {
 	 */
 	void *ctx;
 
+	// clang-format and doxygen don't work together nicely on these three functions
+	// clang-format off
 	/**
 	 * Pointer to a function for public and private signature key generation.
 	 *
@@ -95,8 +102,7 @@ struct OQS_SIG {
 	 * @param pub              The signer's public key.
 	 * @return                 OQS_SUCCESS on success, or OQS_ERROR on failure.
 	 */
-	OQS_STATUS(*keygen)
+	OQS_STATUS(*keygen)(const OQS_SIG *s, uint8_t *priv, uint8_t *pub);
-	(const OQS_SIG *s, uint8_t *priv, uint8_t *pub);
 
 	/**
 	 * Pointer to a function for signature generation.
@@ -109,8 +115,7 @@ struct OQS_SIG {
 	 * @param sig_len          In: length of sig, out: length of the generated signature.
 	 * @return                 OQS_SUCCESS on success, or OQS_ERROR on failure.
 	 */
-	OQS_STATUS(*sign)
+	OQS_STATUS(*sign)(const OQS_SIG *s, const uint8_t *priv, const uint8_t *msg, const size_t msg_len, uint8_t *sig, size_t *sig_len);
-	(const OQS_SIG *s, const uint8_t *priv, const uint8_t *msg, const size_t msg_len, uint8_t *sig, size_t *sig_len);
 
 	/**
 	 * Pointer to a function for signature verification.
@@ -123,8 +128,8 @@ struct OQS_SIG {
 	 * @param sig_len          Length of the signature to verify.
 	 * @return                 OQS_SUCCESS on success, or OQS_ERROR on failure.
 	 */
-	OQS_STATUS(*verify)
+	OQS_STATUS(*verify)(const OQS_SIG *s, const uint8_t *pub, const uint8_t *msg, const size_t msg_len, const uint8_t *sig, const size_t sig_len);
-	(const OQS_SIG *s, const uint8_t *pub, const uint8_t *msg, const size_t msg_len, const uint8_t *sig, const size_t sig_len);
+	// clang-format on
 
 	/**
 	 * Pointer to a function for freeing the allocated signature structure