diff --git a/.travis.yml b/.travis.yml index 57236f6bc..d1a14d4c6 100644 --- a/.travis.yml +++ b/.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 diff --git a/.travis/all-tests.sh b/.travis/all-tests.sh index b21ba5780..333a81cae 100755 --- a/.travis/all-tests.sh +++ b/.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 diff --git a/docs/.Doxyfile b/docs/.Doxyfile index 7d2458ba9..14f29e8f6 100644 --- a/docs/.Doxyfile +++ b/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 diff --git a/src/common/common.h b/src/common/common.h index 396764467..fddba73cf 100644 --- a/src/common/common.h +++ b/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 diff --git a/src/common/rand.h b/src/common/rand.h index 860d70659..ed11a3dc0 100644 --- a/src/common/rand.h +++ b/src/common/rand.h @@ -7,7 +7,6 @@ #define __OQS_RANDOM_H #include -#define HAVE_BOOL #include #include @@ -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 n : number of integers to generate + * @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 */ 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); /*********************************************************** diff --git a/src/crypto/aes/aes.h b/src/crypto/aes/aes.h index f90574243..be4d7d619 100644 --- a/src/crypto/aes/aes.h +++ b/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); diff --git a/src/crypto/rand_urandom_aesctr/rand_urandom_aesctr.h b/src/crypto/rand_urandom_aesctr/rand_urandom_aesctr.h index d13df4f1f..ced16be7b 100644 --- a/src/crypto/rand_urandom_aesctr/rand_urandom_aesctr.h +++ b/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 diff --git a/src/crypto/rand_urandom_chacha20/rand_urandom_chacha20.h b/src/crypto/rand_urandom_chacha20/rand_urandom_chacha20.h index 961708518..d8dca6aa5 100644 --- a/src/crypto/rand_urandom_chacha20/rand_urandom_chacha20.h +++ b/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 diff --git a/src/kex/kex.h b/src/kex/kex.h index 253da712d..badaaacdd 100644 --- a/src/kex/kex.h +++ b/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 diff --git a/src/kex_code_mcbits/kex_code_mcbits.h b/src/kex_code_mcbits/kex_code_mcbits.h index 17df644a9..ffd37956c 100644 --- a/src/kex_code_mcbits/kex_code_mcbits.h +++ b/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 diff --git a/src/kex_ntru/kex_ntru.c b/src/kex_ntru/kex_ntru.c index d2d340333..82046b667 100644 --- a/src/kex_ntru/kex_ntru.c +++ b/src/kex_ntru/kex_ntru.c @@ -13,6 +13,7 @@ #include #include +#define HAVE_BOOL #include #if defined(_WIN32) diff --git a/src/kex_ntru/kex_ntru.h b/src/kex_ntru/kex_ntru.h index 2339d1381..76c301133 100755 --- a/src/kex_ntru/kex_ntru.h +++ b/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 diff --git a/src/kex_ntru/ntru_crypto_platform.h b/src/kex_ntru/ntru_crypto_platform.h index b18ff6a27..e3656b100 100644 --- a/src/kex_ntru/ntru_crypto_platform.h +++ b/src/kex_ntru/ntru_crypto_platform.h @@ -14,7 +14,7 @@ * You can copy, modify, distribute and perform the work, even for commercial * purposes, all without asking permission. You should have received a copy of * the creative commons license (CC0 1.0 universal) along with this program. - * See the license file for more information. + * See the license file for more information. * * *********************************************************************************/ diff --git a/src/kex_rlwe_newhope/kex_rlwe_newhope.h b/src/kex_rlwe_newhope/kex_rlwe_newhope.h index 9172772ca..67407bd0c 100644 --- a/src/kex_rlwe_newhope/kex_rlwe_newhope.h +++ b/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 diff --git a/src/kex_sidh_msr/kex_sidh_msr.h b/src/kex_sidh_msr/kex_sidh_msr.h index bda602b87..7560b6a10 100644 --- a/src/kex_sidh_msr/kex_sidh_msr.h +++ b/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 diff --git a/src/sig/sig.h b/src/sig/sig.h index 4ae64ee71..6ab04b33e 100644 --- a/src/sig/sig.h +++ b/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) - (const OQS_SIG *s, uint8_t *priv, uint8_t *pub); + OQS_STATUS(*keygen)(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) - (const OQS_SIG *s, const uint8_t *priv, const uint8_t *msg, const size_t msg_len, uint8_t *sig, size_t *sig_len); + 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); /** * 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) - (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); + 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); + // clang-format on /** * Pointer to a function for freeing the allocated signature structure @@ -146,9 +151,9 @@ OQS_SIG *OQS_SIG_new(OQS_RAND *rand, enum OQS_SIG_algid algid); /** * Generates a new signature key pair. * @param s Pointer to the signature object. - * @param priv Pointer where the generated private key will be stored. Caller + * @param priv Pointer where the generated private key will be stored. Caller * must have allocated s->priv_key_len bytes. - * @param pub Pointer where the generated public key will be stored. Caller + * @param pub Pointer where the generated public key will be stored. Caller * must have allocated s->pub_key_len bytes. * @return OQS_SUCCESS on success, or OQS_ERROR on failure */ @@ -161,7 +166,7 @@ OQS_STATUS OQS_SIG_keygen(const OQS_SIG *s, uint8_t *priv, uint8_t *pub); * @param msg Pointer to the message to sign. * @param msg_len Length of the message to sign `msg`. * @param sig Pointer where the generated signature will be stored. Caller must have allocated `s->max_sig_len` bytes. - * @param sig_len Pointer to the length of the generated signature. + * @param sig_len Pointer to the length of the generated signature. * @return OQS_SUCCESS on success, or OQS_ERROR on failure */ OQS_STATUS OQS_SIG_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); @@ -173,7 +178,7 @@ OQS_STATUS OQS_SIG_sign(const OQS_SIG *s, const uint8_t *priv, const uint8_t *ms * @param msg Pointer to the signed message. * @param msg_len Length of the signed message `msg`. * @param sig Pointer to the signature. - * @param sig_len Length of the signature. + * @param sig_len Length of the signature. * @return OQS_SUCCESS on success, or OQS_ERROR on failure */ OQS_STATUS OQS_SIG_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);