From afdf6cd0b490878bd752997849b9124454cd1c8e Mon Sep 17 00:00:00 2001 From: roman Date: Tue, 14 May 2024 11:00:54 +0200 Subject: [PATCH] session wrapper REFACTOR add doxygen to static fns --- src/session_mbedtls.c | 75 +++++++++++++++++++++++++++++++++++++------ src/session_openssl.c | 19 +++++++++++ 2 files changed, 84 insertions(+), 10 deletions(-) diff --git a/src/session_mbedtls.c b/src/session_mbedtls.c index 1a53620b..9aba7c33 100644 --- a/src/session_mbedtls.c +++ b/src/session_mbedtls.c @@ -52,7 +52,14 @@ #include #include -/* some mbedTLS functions may return 'high' and some 'low' level errors, try to handle both cases this way */ +/** + * @brief Converts mbedTLS error codes to a string. + * + * Some mbedTLS functions may return 'high' and some 'low' level errors, try to handle both cases this way. + * + * @param[in] err MbedTLS error code. + * @return Error string. + */ static const char * nc_get_mbedtls_str_err(int err) { @@ -101,7 +108,13 @@ nc_server_tls_dn2str(const mbedtls_x509_name *dn) return str; } -/* creates a new rng context needed for PK operations and for ssl config */ +/** + * @brief Create a new random number generator context. + * + * @param[out] ctr_drbg Random bit generator context. + * @param[out] entropy Entropy context. + * @return 0 on success, 1 on failure. + */ static int nc_tls_rng_new(mbedtls_ctr_drbg_context **ctr_drbg, mbedtls_entropy_context **entropy) { @@ -138,6 +151,12 @@ nc_tls_rng_new(mbedtls_ctr_drbg_context **ctr_drbg, mbedtls_entropy_context **en return 1; } +/** + * @brief Destroy the random number generator context. + * + * @param[in] ctr_drbg Random bit generator context. + * @param[in] entropy Entropy context. + */ static void nc_tls_rng_destroy(mbedtls_ctr_drbg_context *ctr_drbg, mbedtls_entropy_context *entropy) { @@ -149,7 +168,12 @@ nc_tls_rng_destroy(mbedtls_ctr_drbg_context *ctr_drbg, mbedtls_entropy_context * } } -/* get verify err string, caller is responsible for freeing it, 256B should be more than enough */ +/** + * @brief Get a string representation of the verification error. + * + * @param[in] err Verification error code. + * @return String representation of the error. Caller is responsible for freeing it. + */ static char * nc_tls_get_verify_err_str(int err) { @@ -242,6 +266,11 @@ nc_tls_cert_destroy_wrap(void *cert) free(cert); } +/** + * @brief Create a new private key context. + * + * @return New private key context or NULL. + */ static void * nc_tls_pkey_new_wrap(void) { @@ -427,6 +456,12 @@ nc_server_tls_set_tls_versions_wrap(void *tls_cfg, unsigned int tls_versions) return 0; } +/** + * @brief Duplicates a certificate. + * + * @param[in] cert Certificate to duplicate. + * @return Duplicated certificate or NULL. + */ static mbedtls_x509_crt * nc_tls_cert_dup(const mbedtls_x509_crt *cert) { @@ -445,6 +480,15 @@ nc_tls_cert_dup(const mbedtls_x509_crt *cert) return new_cert; } +/** + * @brief Verify a certificate. + * + * @param[in] cb_data Callback data (session, opts, data for CTN). + * @param[in] cert Certificate to verify. + * @param[in] depth Certificate depth in the chain. + * @param[in,out] flags Verification flags. Used to propagate errors. + * @return 0 on success (verification result is based on the value of flags), non-zero on fatal-error. + */ static int nc_server_tls_verify_cb(void *cb_data, mbedtls_x509_crt *cert, int depth, uint32_t *flags) { @@ -734,6 +778,14 @@ nc_server_tls_sha512_wrap(void *cert, unsigned char *buf) return 0; } +/** + * @brief Callback for sending data. + * + * @param[in] ctx Socket. + * @param[in] buf Data to send. + * @param[in] len Length of the data. + * @return Number of bytes sent or negative value on error. + */ static int nc_server_tls_send(void *ctx, const unsigned char *buf, size_t len) { @@ -757,6 +809,14 @@ nc_server_tls_send(void *ctx, const unsigned char *buf, size_t len) return ret; } +/** + * @brief Callback for receiving data. + * + * @param[in] ctx Socket. + * @param[out] buf Buffer to store the received data. + * @param[in] len Length of the buffer. + * @return Number of bytes received or negative value on error. + */ static int nc_server_tls_recv(void *ctx, unsigned char *buf, size_t len) { @@ -1095,13 +1155,8 @@ nc_tls_is_der_subpubkey_wrap(unsigned char *der, long len) ret = mbedtls_pk_parse_subpubkey(&der, der + len, pkey); nc_tls_privkey_destroy_wrap(pkey); - if (!ret) { - /* success */ - return 1; - } else { - /* fail */ - return 0; - } + + return !ret; } int diff --git a/src/session_openssl.c b/src/session_openssl.c index 83a5b933..3fd88980 100644 --- a/src/session_openssl.c +++ b/src/session_openssl.c @@ -324,6 +324,13 @@ nc_server_tls_set_tls_versions_wrap(void *tls_cfg, unsigned int tls_versions) return 0; } +/** + * @brief Verify a certificate. + * + * @param[in] preverify_ok The result of the in-built verification. + * @param[in] x509_ctx Verification context. + * @return 1 on success, 0 on error. + */ static int nc_server_tls_verify_cb(int preverify_ok, X509_STORE_CTX *x509_ctx) { @@ -747,6 +754,13 @@ nc_tls_init_ctx_wrap(int UNUSED(sock), void *cert, void *pkey, void *cert_store, return 0; } +/** + * @brief Move CRLs from one store to another. + * + * @param[in] src Source store. + * @param[in] dst Destination store. + * @return 0 on success, 1 on error. + */ static int nc_tls_move_crls_to_store(const X509_STORE *src, X509_STORE *dst) { @@ -918,6 +932,11 @@ nc_base64_encode_wrap(const unsigned char *bin, size_t len, char **base64) return 0; } +/** + * @brief Get all OpenSSL error reasons. + * + * @return String with all OpenSSL error reasons or NULL. + */ static char * nc_tls_get_err_reasons(void) {