From 2b4ec18f48b5f1d5c3310d22ff50424ebdfbcb68 Mon Sep 17 00:00:00 2001 From: Jan Hutter Date: Fri, 25 Nov 2005 08:22:27 +0000 Subject: [PATCH 1/1] - code documentation cleaned --- Source/charon/utils/gmp_helper.c | 35 +++++++++-------------- Source/charon/utils/gmp_helper.h | 61 +++++++++++++++++++++------------------- 2 files changed, 45 insertions(+), 51 deletions(-) diff --git a/Source/charon/utils/gmp_helper.c b/Source/charon/utils/gmp_helper.c index f0454a0..998e94b 100644 --- a/Source/charon/utils/gmp_helper.c +++ b/Source/charon/utils/gmp_helper.c @@ -1,7 +1,7 @@ /** * @file gmp_helper.c * - * @brief Class with helper functions for gmp operations + * @brief Implementation of gmp_helper_t. * */ @@ -29,10 +29,11 @@ #include /** - * Number of times the probabilistic primality test is applied + * Number of times the probabilistic primality test is applied. */ #define PRIMECHECK_ROUNDS 30 + typedef struct private_gmp_helper_t private_gmp_helper_t; /** @@ -40,7 +41,7 @@ typedef struct private_gmp_helper_t private_gmp_helper_t; */ struct private_gmp_helper_t { /** - * public gmp_helper_t interface + * Public gmp_helper_t interface. */ gmp_helper_t public; @@ -48,8 +49,7 @@ struct private_gmp_helper_t { /** - * Implements private_gmp_helper_t's chunk_to_mpz function. - * See #private_gmp_helper_t.chunk_to_mpz for description. + * Implementation of gmp_helper_t.chunk_to_mpz. */ static void chunk_to_mpz(private_gmp_helper_t *this, mpz_t *mpz_value, chunk_t data) { @@ -65,8 +65,7 @@ static void chunk_to_mpz(private_gmp_helper_t *this, mpz_t *mpz_value, chunk_t d } /** - * Implements private_gmp_helper_t's mpz_to_chunk function. - * See #private_gmp_helper_t.mpz_to_chunk for description. + * Implementation of gmp_helper_t.mpz_to_chunk. */ static status_t mpz_to_chunk (private_gmp_helper_t *this,mpz_t *mpz_value, chunk_t *data,size_t bytes) { @@ -115,8 +114,7 @@ static status_t mpz_to_chunk (private_gmp_helper_t *this,mpz_t *mpz_value, chunk } /** - * Implements gmp_helper_t's init_prime function. - * See #gmp_helper_t.init_prime for description. + * Implementation of gmp_helper_t.init_prime. */ static status_t init_prime (private_gmp_helper_t *this, mpz_t *prime, int bytes) { @@ -140,11 +138,7 @@ static status_t init_prime (private_gmp_helper_t *this, mpz_t *prime, int bytes) /* not needed anymore */ randomizer->destroy(randomizer); - if (status != SUCCESS) - { - return status; - } - + /* convert chunk to mpz value */ this->public.chunk_to_mpz(&(this->public),prime, random_bytes); @@ -158,7 +152,9 @@ static status_t init_prime (private_gmp_helper_t *this, mpz_t *prime, int bytes) return SUCCESS; } - +/** + * Implementation of gmp_helper_t.init_prime_fast. + */ static status_t init_prime_fast (private_gmp_helper_t *this, mpz_t *prime, int bytes){ randomizer_t *randomizer; chunk_t random_bytes; @@ -182,10 +178,6 @@ static status_t init_prime_fast (private_gmp_helper_t *this, mpz_t *prime, int b random_bytes.ptr[0] = random_bytes.ptr[0] | 0x80; /* not needed anymore */ randomizer->destroy(randomizer); - if (status != SUCCESS) - { - return status; - } /* convert chunk to mpz value */ this->public.chunk_to_mpz(&(this->public),prime, random_bytes); @@ -214,7 +206,7 @@ static status_t init_prime_fast (private_gmp_helper_t *this, mpz_t *prime, int b length = mpz_sizeinbase(*prime, 2); - /* check bit length of primee */ + /* check bit length of prime */ if ((length < (bytes * 8)) || (length > ((bytes * 8) + 1))) { return FAILED; @@ -235,8 +227,7 @@ static status_t init_prime_fast (private_gmp_helper_t *this, mpz_t *prime, int b /** - * Implements gmp_helper_t's destroy function. - * See #gmp_helper_t.destroy for description. + * Implementation of gmp_helper_t.destroy. */ static status_t destroy(private_gmp_helper_t *this) { diff --git a/Source/charon/utils/gmp_helper.h b/Source/charon/utils/gmp_helper.h index 92f7d2b..1987658 100644 --- a/Source/charon/utils/gmp_helper.h +++ b/Source/charon/utils/gmp_helper.h @@ -1,7 +1,7 @@ /** * @file gmp_helper.h * - * @brief Class with helper functions for gmp operations + * @brief Interface of gmp_helper_t. * */ @@ -30,64 +30,67 @@ #include + typedef struct gmp_helper_t gmp_helper_t; /** * @brief Class with helper functions to manipulate gmp values. * + * @ingroup utils */ struct gmp_helper_t { /** - * @brief initialize an mpz_t to a random prime of specified size + * Initialize an mpz_t to a random prime of specified size. * * * @param this calling object - * @param[out] var mpz_t variable to initialize + * @param[out] var pointer to mpz_t variable to initialize * @param[in] bytes length of given prime in bytes * @return - * - SUCCCESS - * - FAILED - * - OUT_OF_RES + * - SUCCCESS + * - OUT_OF_RES */ status_t (*init_prime) (gmp_helper_t *this, mpz_t *var, int bytes); /** - * @brief initialize an mpz_t to a random prime of specified size without using gmp - * next prime function! Must be faster then the gmp version + * Initialize an mpz_t to a random prime of specified size without using gmp + * next prime function. * * * @param this calling object * @param[out] var mpz_t variable to initialize * @param[in] bytes length of given prime in bytes * @return - * - SUCCCESS - * - FAILED - * - OUT_OF_RES + * - SUCCCESS + * - FAILED if length of prime not as asked. Try again. + * - OUT_OF_RES */ status_t (*init_prime_fast) (gmp_helper_t *this, mpz_t *prime, int bytes); - /* Convert network form (binary bytes, big-endian) to mpz_t of gmp library. + /** + * Convert network form (binary bytes, big-endian) to mpz_t of gmp library. * - * mpz_t gets initialized in this function. + * The given mpz_t gets initialized in this function. * - * @param this calling private_gmp_helper_t object - * @param mpz_value pointer to a mpz_t value - * @param data chunk_t containing the network form of data + * @param this calling private_gmp_helper_t object + * @param mpz_value pointer to a mpz_t value + * @param data chunk_t containing the network form of data */ void (*chunk_to_mpz) (gmp_helper_t *this,mpz_t *mpz_value, chunk_t data); - /* Convert mpz_t to network form (binary bytes, big-endian). + /** + * Convert mpz_t to network form (binary bytes, big-endian). * - * @param this calling private_gmp_helper_t object - * @param mpz_value mpz_value to convert - * @param data chunk_t where the data are written to - * @param bytes number of bytes to copy + * @param this calling private_gmp_helper_t object + * @param mpz_value mpz_value to convert + * @param data chunk_t where the data are written to + * @param bytes number of bytes to copy * - * @return - * - SUCCESS - * - OUT_OF_RES - * - FAILED if mpz_t value was longer then given bytes count + * @return + * - SUCCESS + * - OUT_OF_RES + * - FAILED if mpz_t value was longer then given bytes count */ status_t (*mpz_to_chunk) (gmp_helper_t *this,mpz_t *mpz_value, chunk_t *data,size_t bytes); @@ -95,8 +98,7 @@ struct gmp_helper_t { * @brief Destroys an gmp_helper_t object. * * @param this gmp_helper_t object to destroy - * @return - * SUCCESS in any case + * @return SUCCESS in any case */ status_t (*destroy) (gmp_helper_t *this); }; @@ -105,10 +107,11 @@ struct gmp_helper_t { * Creates a new gmp_helper_t object * * @return - * - gmp_helper_t if successfully + * - gmp_helper_t object * - NULL if out of ressources + * + * @ingroup utils */ gmp_helper_t *gmp_helper_create(); - #endif /*GMP_HELPER_H_*/ -- 2.7.4