diff --git a/.github/scripts/cmake-linux b/.github/scripts/cmake-linux index cee6b491..a4ddc94e 100755 --- a/.github/scripts/cmake-linux +++ b/.github/scripts/cmake-linux @@ -33,5 +33,6 @@ cmake -B_build -H. -GNinja \ cmake --build _build --parallel "$NPROC" --target install -- -k 0 cd _build # pushd -ctest -j50 --output-on-failure --rerun-failed --repeat until-pass:6 +ctest -j50 --output-on-failure --rerun-failed --repeat until-pass:6 || + ctest -j50 --output-on-failure --rerun-failed --repeat until-pass:6 cd - # popd diff --git a/.github/scripts/cmake-osx b/.github/scripts/cmake-osx index a13a1811..4a6c3360 100755 --- a/.github/scripts/cmake-osx +++ b/.github/scripts/cmake-osx @@ -31,5 +31,6 @@ cmake -B_build -H. \ cd _build # pushd make "-j$NPROC" -k install -ctest -j50 --output-on-failure --rerun-failed --repeat until-pass:6 +ctest -j50 --output-on-failure --rerun-failed --repeat until-pass:6 || + ctest -j50 --output-on-failure --rerun-failed --repeat until-pass:6 cd - # popd diff --git a/.github/settings.yml b/.github/settings.yml index 03dbc9ce..546b00a5 100644 --- a/.github/settings.yml +++ b/.github/settings.yml @@ -42,6 +42,7 @@ branches: - "docker-bootstrap-node-websocket" - "docker-toxcore-js" - "mypy" + - "netlify/c-toxcore/deploy-preview" - "sonar-scan" # Labels specific to c-toxcore. diff --git a/.doxygen.conf b/docs/Doxyfile similarity index 99% rename from .doxygen.conf rename to docs/Doxyfile index 0e39799d..e31d6705 100644 --- a/.doxygen.conf +++ b/docs/Doxyfile @@ -2236,7 +2236,7 @@ INCLUDE_FILE_PATTERNS = # recursively expanded use the := operator instead of the = operator. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -PREDEFINED = DOXYGEN_SKIP +PREDEFINED = DOXYGEN_IGNORE # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this # tag can be used to specify a list of macro names that should be expanded. The diff --git a/netlify.toml b/netlify.toml index 5b871cdd..4b6aec8c 100644 --- a/netlify.toml +++ b/netlify.toml @@ -5,6 +5,6 @@ command = """\ else \ git clone --depth=1 https://github.com/jothepro/doxygen-awesome-css.git; fi && \ - doxygen .doxygen.conf \ + doxygen docs/Doxyfile \ """ publish = "_docs/html" diff --git a/other/docker/doxygen/Dockerfile b/other/docker/doxygen/Dockerfile index 71e100bf..4b1c4b1a 100644 --- a/other/docker/doxygen/Dockerfile +++ b/other/docker/doxygen/Dockerfile @@ -9,9 +9,9 @@ RUN apk add --no-cache doxygen git graphviz \ && git clone --depth=1 https://github.com/jothepro/doxygen-awesome-css.git /work/doxygen-awesome-css WORKDIR /work COPY . /work/ -RUN cat .doxygen.conf > doxygen.conf \ - && echo "WARN_AS_ERROR = YES" >> doxygen.conf \ - && doxygen doxygen.conf +RUN cat docs/Doxyfile > Doxyfile \ + && echo "WARN_AS_ERROR = YES" >> Doxyfile \ + && doxygen Doxyfile FROM nginx:alpine COPY --from=build /work/_docs/html/ /usr/share/nginx/html/ diff --git a/toxav/toxav.h b/toxav/toxav.h index ecf26e13..ed8f205d 100644 --- a/toxav/toxav.h +++ b/toxav/toxav.h @@ -3,7 +3,7 @@ * Copyright © 2013-2015 Tox project. */ -/** @file toxav.h +/** @file * @brief Public audio/video API for Tox clients. * * This API can handle multiple calls. Each call has its state, in very rare @@ -832,7 +832,7 @@ bool toxav_groupchat_av_enabled(Tox *tox, uint32_t groupnumber); #endif //!TOKSTYLE- -#ifdef DOXYGEN_IGNORE +#ifndef DOXYGEN_IGNORE typedef Toxav_Err_Call TOXAV_ERR_CALL; typedef Toxav_Err_New TOXAV_ERR_NEW; diff --git a/toxcore/crypto_core.c b/toxcore/crypto_core.c index 5fef8cd4..3402395b 100644 --- a/toxcore/crypto_core.c +++ b/toxcore/crypto_core.c @@ -182,11 +182,6 @@ bool public_key_valid(const uint8_t *public_key) return 1; } -/** - * Fast encrypt/decrypt operations. Use if this is not a one-time communication. - * encrypt_precompute does the shared-key generation once so it does not have - * to be performed on every encrypt/decrypt. - */ int32_t encrypt_precompute(const uint8_t *public_key, const uint8_t *secret_key, uint8_t *shared_key) { @@ -320,10 +315,6 @@ int32_t decrypt_data(const uint8_t *public_key, const uint8_t *secret_key, const return ret; } -/** - * Increment the given nonce by 1 in big endian (rightmost byte incremented - * first). - */ void increment_nonce(uint8_t *nonce) { /* TODO(irungentoo): use `increment_nonce_number(nonce, 1)` or @@ -343,10 +334,6 @@ void increment_nonce(uint8_t *nonce) } } -/** - * Increment the given nonce by a given number. The number should be in host - * byte order. - */ void increment_nonce_number(uint8_t *nonce, uint32_t increment) { /* NOTE don't use breaks inside this loop @@ -369,17 +356,11 @@ void increment_nonce_number(uint8_t *nonce, uint32_t increment) } } -/** - * Fill the given nonce with random bytes. - */ void random_nonce(uint8_t *nonce) { random_bytes(nonce, crypto_box_NONCEBYTES); } -/** - * Fill a key CRYPTO_SYMMETRIC_KEY_SIZE big with random bytes. - */ void new_symmetric_key(uint8_t *key) { random_bytes(key, CRYPTO_SYMMETRIC_KEY_SIZE); diff --git a/toxcore/crypto_core.h b/toxcore/crypto_core.h index 1f75ac78..f3709aba 100644 --- a/toxcore/crypto_core.h +++ b/toxcore/crypto_core.h @@ -3,8 +3,8 @@ * Copyright © 2013 Tox project. */ -/** - * Functions for the core crypto. +/** @file + * @brief Functions for the core crypto. */ #ifndef C_TOXCORE_TOXCORE_CRYPTO_CORE_H #define C_TOXCORE_TOXCORE_CRYPTO_CORE_H @@ -18,74 +18,76 @@ extern "C" { #endif /** - * The number of bytes in a Tox public key used for encryption. + * @brief The number of bytes in a Tox public key used for encryption. */ #define CRYPTO_PUBLIC_KEY_SIZE 32 /** - * The number of bytes in a Tox secret key used for encryption. + * @brief The number of bytes in a Tox secret key used for encryption. */ #define CRYPTO_SECRET_KEY_SIZE 32 /** - * The number of bytes in a shared key computed from public and secret keys. + * @brief The number of bytes in a shared key computed from public and secret keys. */ #define CRYPTO_SHARED_KEY_SIZE 32 /** - * The number of bytes in a symmetric key. + * @brief The number of bytes in a symmetric key. */ #define CRYPTO_SYMMETRIC_KEY_SIZE CRYPTO_SHARED_KEY_SIZE /** - * The number of bytes needed for the MAC (message authentication code) in an + * @brief The number of bytes needed for the MAC (message authentication code) in an * encrypted message. */ #define CRYPTO_MAC_SIZE 16 /** - * The number of bytes in a nonce used for encryption/decryption. + * @brief The number of bytes in a nonce used for encryption/decryption. */ #define CRYPTO_NONCE_SIZE 24 /** - * The number of bytes in a SHA256 hash. + * @brief The number of bytes in a SHA256 hash. */ #define CRYPTO_SHA256_SIZE 32 /** - * The number of bytes in a SHA512 hash. + * @brief The number of bytes in a SHA512 hash. */ #define CRYPTO_SHA512_SIZE 64 /** - * A `bzero`-like function which won't be optimised away by the compiler. Some - * compilers will inline `bzero` or `memset` if they can prove that there will - * be no reads to the written data. Use this function if you want to be sure the - * memory is indeed zeroed. + * @brief A `bzero`-like function which won't be optimised away by the compiler. + * + * Some compilers will inline `bzero` or `memset` if they can prove that there + * will be no reads to the written data. Use this function if you want to be + * sure the memory is indeed zeroed. */ void crypto_memzero(void *data, size_t length); /** - * Compute a SHA256 hash (32 bytes). + * @brief Compute a SHA256 hash (32 bytes). */ void crypto_sha256(uint8_t *hash, const uint8_t *data, size_t length); /** - * Compute a SHA512 hash (64 bytes). + * @brief Compute a SHA512 hash (64 bytes). */ void crypto_sha512(uint8_t *hash, const uint8_t *data, size_t length); /** - * Compare 2 public keys of length CRYPTO_PUBLIC_KEY_SIZE, not vulnerable to + * @brief Compare 2 public keys of length @ref CRYPTO_PUBLIC_KEY_SIZE, not vulnerable to * timing attacks. * - * @return 0 if both mem locations of length are equal, -1 if they are not. + * @retval 0 if both mem locations of length are equal + * @retval -1 if they are not */ int32_t public_key_cmp(const uint8_t *pk1, const uint8_t *pk2); /** - * Compare 2 SHA512 checksums of length CRYPTO_SHA512_SIZE, not vulnerable to + * @brief Compare 2 SHA512 checksums of length CRYPTO_SHA512_SIZE, not vulnerable to * timing attacks. * * @return 0 if both mem locations of length are equal, -1 if they are not. @@ -93,27 +95,27 @@ int32_t public_key_cmp(const uint8_t *pk1, const uint8_t *pk2); int32_t crypto_sha512_cmp(const uint8_t *cksum1, const uint8_t *cksum2); /** - * Return a random 8 bit integer. + * @brief Return a random 8 bit integer. */ uint8_t random_u08(void); /** - * Return a random 16 bit integer. + * @brief Return a random 16 bit integer. */ uint16_t random_u16(void); /** - * Return a random 32 bit integer. + * @brief Return a random 32 bit integer. */ uint32_t random_u32(void); /** - * Return a random 64 bit integer. + * @brief Return a random 64 bit integer. */ uint64_t random_u64(void); /** - * Return a random 32 bit integer between 0 and upper_bound (excluded). + * @brief Return a random 32 bit integer between 0 and upper_bound (excluded). * * On libsodium builds this function guarantees a uniform distribution of possible outputs. * On vanilla NACL builds this function is equivalent to `random() % upper_bound`. @@ -121,68 +123,78 @@ uint64_t random_u64(void); uint32_t random_range_u32(uint32_t upper_bound); /** - * Fill the given nonce with random bytes. + * @brief Fill the given nonce with random bytes. */ void random_nonce(uint8_t *nonce); /** - * Fill an array of bytes with random values. + * @brief Fill an array of bytes with random values. */ void random_bytes(uint8_t *bytes, size_t length); /** - * Check if a Tox public key CRYPTO_PUBLIC_KEY_SIZE is valid or not. This - * should only be used for input validation. + * @brief Check if a Tox public key CRYPTO_PUBLIC_KEY_SIZE is valid or not. + * + * This should only be used for input validation. * * @return false if it isn't, true if it is. */ bool public_key_valid(const uint8_t *public_key); /** - * Generate a new random keypair. Every call to this function is likely to - * generate a different keypair. + * @brief Generate a new random keypair. + * + * Every call to this function is likely to generate a different keypair. */ int32_t crypto_new_keypair(uint8_t *public_key, uint8_t *secret_key); /** - * Derive the public key from a given secret key. + * @brief Derive the public key from a given secret key. */ void crypto_derive_public_key(uint8_t *public_key, const uint8_t *secret_key); /** - * Encrypt plain text of the given length to encrypted of length + - * CRYPTO_MAC_SIZE using the public key (CRYPTO_PUBLIC_KEY_SIZE bytes) of the - * receiver and the secret key of the sender and a CRYPTO_NONCE_SIZE byte - * nonce. + * @brief Encrypt message to send from secret key to public key. * - * @return -1 if there was a problem, length of encrypted data if everything - * was fine. + * Encrypt plain text of the given length to encrypted of + * `length + CRYPTO_MAC_SIZE` using the public key (@ref CRYPTO_PUBLIC_KEY_SIZE + * bytes) of the receiver and the secret key of the sender and a + * @ref CRYPTO_NONCE_SIZE byte nonce. + * + * @retval -1 if there was a problem. + * @retval >=0 length of encrypted data if everything was fine. */ int32_t encrypt_data(const uint8_t *public_key, const uint8_t *secret_key, const uint8_t *nonce, const uint8_t *plain, size_t length, uint8_t *encrypted); /** - * Decrypt encrypted text of the given length to plain text of the given length - * - CRYPTO_MAC_SIZE using the public key (CRYPTO_PUBLIC_KEY_SIZE bytes) of - * the sender, the secret key of the receiver and a CRYPTO_NONCE_SIZE byte - * nonce. + * @brief Decrypt message from public key to secret key. * - * @return -1 if there was a problem (decryption failed), length of plain text - * data if everything was fine. + * Decrypt encrypted text of the given @p length to plain text of the given + * `length - CRYPTO_MAC_SIZE` using the public key (@ref CRYPTO_PUBLIC_KEY_SIZE + * bytes) of the sender, the secret key of the receiver and a + * @ref CRYPTO_NONCE_SIZE byte nonce. + * + * @retval -1 if there was a problem (decryption failed). + * @retval >=0 length of plain text data if everything was fine. */ int32_t decrypt_data(const uint8_t *public_key, const uint8_t *secret_key, const uint8_t *nonce, const uint8_t *encrypted, size_t length, uint8_t *plain); /** - * Fast encrypt/decrypt operations. Use if this is not a one-time communication. - * encrypt_precompute does the shared-key generation once so it does not have - * to be performed on every encrypt/decrypt. + * @brief Fast encrypt/decrypt operations. + * + * Use if this is not a one-time communication. @ref encrypt_precompute does the + * shared-key generation once so it does not have to be performed on every + * encrypt/decrypt. */ int32_t encrypt_precompute(const uint8_t *public_key, const uint8_t *secret_key, uint8_t *shared_key); /** - * Encrypts plain of length length to encrypted of length + CRYPTO_MAC_SIZE - * using a shared key CRYPTO_SYMMETRIC_KEY_SIZE big and a CRYPTO_NONCE_SIZE + * @brief Encrypt message with precomputed shared key. + * + * Encrypts plain of length length to encrypted of length + @ref CRYPTO_MAC_SIZE + * using a shared key @ref CRYPTO_SYMMETRIC_KEY_SIZE big and a @ref CRYPTO_NONCE_SIZE * byte nonce. * * @return -1 if there was a problem, length of encrypted data if everything @@ -192,9 +204,11 @@ int32_t encrypt_data_symmetric(const uint8_t *shared_key, const uint8_t *nonce, uint8_t *encrypted); /** + * @brief Decrypt message with precomputed shared key. + * * Decrypts encrypted of length length to plain of length length - - * CRYPTO_MAC_SIZE using a shared key CRYPTO_SHARED_KEY_SIZE big and a - * CRYPTO_NONCE_SIZE byte nonce. + * @ref CRYPTO_MAC_SIZE using a shared key @ref CRYPTO_SHARED_KEY_SIZE big and a + * @ref CRYPTO_NONCE_SIZE byte nonce. * * @return -1 if there was a problem (decryption failed), length of plain data * if everything was fine. @@ -203,39 +217,43 @@ int32_t decrypt_data_symmetric(const uint8_t *shared_key, const uint8_t *nonce, uint8_t *plain); /** - * Increment the given nonce by 1 in big endian (rightmost byte incremented + * @brief Increment the given nonce by 1 in big endian (rightmost byte incremented * first). */ void increment_nonce(uint8_t *nonce); /** - * Increment the given nonce by a given number. The number should be in host - * byte order. + * @brief Increment the given nonce by a given number. + * + * The number should be in host byte order. */ void increment_nonce_number(uint8_t *nonce, uint32_t increment); /** - * Fill a key CRYPTO_SYMMETRIC_KEY_SIZE big with random bytes. + * @brief Fill a key @ref CRYPTO_SYMMETRIC_KEY_SIZE big with random bytes. */ void new_symmetric_key(uint8_t *key); /** - * Locks `length` bytes of memory pointed to by `data`. This will attempt to prevent - * the specified memory region from being swapped to disk. + * @brief Locks `length` bytes of memory pointed to by `data`. * - * Returns true on success. + * This will attempt to prevent the specified memory region from being swapped + * to disk. + * + * @return true on success. */ bool crypto_memlock(void *data, size_t length); /** - * Unlocks `length` bytes of memory pointed to by `data`. This allows the specified - * memory region to be swapped to disk. + * @brief Unlocks `length` bytes of memory pointed to by `data`. + * + * This allows the specified memory region to be swapped to disk. * * This function call has the side effect of zeroing the specified memory region * whether or not it succeeds. Therefore it should only be used once the memory * is no longer in use. * - * Returns true on success. + * @return true on success. */ bool crypto_memunlock(void *data, size_t length); diff --git a/toxcore/ping_array.h b/toxcore/ping_array.h index 3519dde6..98dceaba 100644 --- a/toxcore/ping_array.h +++ b/toxcore/ping_array.h @@ -3,8 +3,8 @@ * Copyright © 2013 Tox project. */ -/** - * Implementation of an efficient array to store that we pinged something. +/** @file + * @brief Implementation of an efficient array to store that we pinged something. */ #ifndef C_TOXCORE_TOXCORE_PING_ARRAY_H #define C_TOXCORE_TOXCORE_PING_ARRAY_H @@ -21,7 +21,7 @@ extern "C" { typedef struct Ping_Array Ping_Array; /** - * Initialize a Ping_Array. + * @brief Initialize a Ping_Array. * * @param size represents the total size of the array and should be a power of 2. * @param timeout represents the maximum timeout in seconds for the entry. @@ -31,12 +31,12 @@ typedef struct Ping_Array Ping_Array; struct Ping_Array *ping_array_new(uint32_t size, uint32_t timeout); /** - * Free all the allocated memory in a Ping_Array. + * @brief Free all the allocated memory in a @ref Ping_Array. */ void ping_array_kill(struct Ping_Array *array); /** - * Add a data with length to the Ping_Array list and return a ping_id. + * @brief Add a data with length to the @ref Ping_Array list and return a ping_id. * * @return ping_id on success, 0 on failure. */ @@ -44,7 +44,7 @@ uint64_t ping_array_add(struct Ping_Array *array, const struct Mono_Time *mono_t uint32_t length); /** - * Check if ping_id is valid and not timed out. + * @brief Check if @p ping_id is valid and not timed out. * * On success, copies the data into data of length, * diff --git a/toxcore/tox.h b/toxcore/tox.h index a4c9bac9..966ac647 100644 --- a/toxcore/tox.h +++ b/toxcore/tox.h @@ -3,8 +3,7 @@ * Copyright © 2013 Tox project. */ -/** - * @file tox.h +/** @file * @brief Public core API for Tox clients. * * Every function that can fail takes a function-specific error code pointer @@ -3231,7 +3230,7 @@ uint16_t tox_self_get_tcp_port(const Tox *tox, Tox_Err_Get_Port *error); #endif //!TOKSTYLE- -#ifdef DOXYGEN_IGNORE +#ifndef DOXYGEN_IGNORE typedef Tox_Err_Options_New TOX_ERR_OPTIONS_NEW; typedef Tox_Err_New TOX_ERR_NEW;