[tor-commits] [tor/master] hs_cache.[ch]: repair doxygen comments.

commit 17b88241dbdca1b2d2ef71e5d9bd0cba5ada3d10 Author: Nick Mathewson nickm@torproject.org Date: Wed Oct 16 11:57:44 2019 -0400

hs_cache.[ch]: repair doxygen comments. --- src/feature/hs/hs_cache.c | 88 +++++++++++++++++++++++------------------------ src/feature/hs/hs_cache.h | 32 ++++++++--------- 2 files changed, 60 insertions(+), 60 deletions(-)

diff --git a/src/feature/hs/hs_cache.c b/src/feature/hs/hs_cache.c index 9817113b2..b223325ac 100644 --- a/src/feature/hs/hs_cache.c +++ b/src/feature/hs/hs_cache.c @@ -29,10 +29,10 @@ static int cached_client_descriptor_has_expired(time_t now,

/********************** Directory HS cache ******************/

-/* Directory descriptor cache. Map indexed by blinded key. */ +/** Directory descriptor cache. Map indexed by blinded key. */ static digest256map_t *hs_cache_v3_dir;

-/* Remove a given descriptor from our cache. */ +/** Remove a given descriptor from our cache. */ static void remove_v3_desc_as_dir(const hs_cache_dir_descriptor_t *desc) { @@ -40,7 +40,7 @@ remove_v3_desc_as_dir(const hs_cache_dir_descriptor_t *desc) digest256map_remove(hs_cache_v3_dir, desc->key); }

-/* Store a given descriptor in our cache. */ +/** Store a given descriptor in our cache. */ static void store_v3_desc_as_dir(hs_cache_dir_descriptor_t *desc) { @@ -48,7 +48,7 @@ store_v3_desc_as_dir(hs_cache_dir_descriptor_t *desc) digest256map_set(hs_cache_v3_dir, desc->key, desc); }

-/* Query our cache and return the entry or NULL if not found. */ +/** Query our cache and return the entry or NULL if not found. */ static hs_cache_dir_descriptor_t * lookup_v3_desc_as_dir(const uint8_t *key) { @@ -59,7 +59,7 @@ lookup_v3_desc_as_dir(const uint8_t *key) #define cache_dir_desc_free(val) \ FREE_AND_NULL(hs_cache_dir_descriptor_t, cache_dir_desc_free_, (val))

-/* Free a directory descriptor object. */ +/** Free a directory descriptor object. */ static void cache_dir_desc_free_(hs_cache_dir_descriptor_t *desc) { @@ -71,7 +71,7 @@ cache_dir_desc_free_(hs_cache_dir_descriptor_t *desc) tor_free(desc); }

-/* Helper function: Use by the free all function using the digest256map +/** Helper function: Use by the free all function using the digest256map * interface to cache entries. */ static void cache_dir_desc_free_void(void *ptr) @@ -79,7 +79,7 @@ cache_dir_desc_free_void(void *ptr) cache_dir_desc_free_(ptr); }

-/* Create a new directory cache descriptor object from a encoded descriptor. +/** Create a new directory cache descriptor object from a encoded descriptor. * On success, return the heap-allocated cache object, otherwise return NULL if * we can't decode the descriptor. */ static hs_cache_dir_descriptor_t * @@ -109,7 +109,7 @@ cache_dir_desc_new(const char *desc) return NULL; }

-/* Return the size of a cache entry in bytes. */ +/** Return the size of a cache entry in bytes. */ static size_t cache_get_dir_entry_size(const hs_cache_dir_descriptor_t *entry) { @@ -117,7 +117,7 @@ cache_get_dir_entry_size(const hs_cache_dir_descriptor_t *entry) + strlen(entry->encoded_desc)); }

-/* Try to store a valid version 3 descriptor in the directory cache. Return 0 +/** Try to store a valid version 3 descriptor in the directory cache. Return 0 * on success else a negative value is returned indicating that we have a * newer version in our cache. On error, caller is responsible to free the * given descriptor desc. */ @@ -167,7 +167,7 @@ cache_store_v3_as_dir(hs_cache_dir_descriptor_t *desc) return -1; }

-/* Using the query which is the base64 encoded blinded key of a version 3 +/** Using the query which is the base64 encoded blinded key of a version 3 * descriptor, lookup in our directory cache the entry. If found, 1 is * returned and desc_out is populated with a newly allocated string being the * encoded descriptor. If not found, 0 is returned and desc_out is untouched. @@ -202,7 +202,7 @@ cache_lookup_v3_as_dir(const char *query, const char **desc_out) return -1; }

-/* Clean the v3 cache by removing any entry that has expired using the +/** Clean the v3 cache by removing any entry that has expired using the * <b>global_cutoff</b> value. If <b>global_cutoff</b> is 0, the cleaning * process will use the lifetime found in the plaintext data section. Return * the number of bytes cleaned. */ @@ -252,7 +252,7 @@ cache_clean_v3_as_dir(time_t now, time_t global_cutoff) return bytes_removed; }

-/* Given an encoded descriptor, store it in the directory cache depending on +/** Given an encoded descriptor, store it in the directory cache depending on * which version it is. Return a negative value on error. On success, 0 is * returned. */ int @@ -287,7 +287,7 @@ hs_cache_store_as_dir(const char *desc) return -1; }

-/* Using the query, lookup in our directory cache the entry. If found, 1 is +/** Using the query, lookup in our directory cache the entry. If found, 1 is * returned and desc_out is populated with a newly allocated string being * the encoded descriptor. If not found, 0 is returned and desc_out is * untouched. On error, a negative value is returned and desc_out is @@ -312,7 +312,7 @@ hs_cache_lookup_as_dir(uint32_t version, const char *query, return found; }

-/* Clean all directory caches using the current time now. */ +/** Clean all directory caches using the current time now. */ void hs_cache_clean_as_dir(time_t now) { @@ -329,15 +329,15 @@ hs_cache_clean_as_dir(time_t now)

/********************** Client-side HS cache ******************/

-/* Client-side HS descriptor cache. Map indexed by service identity key. */ +/** Client-side HS descriptor cache. Map indexed by service identity key. */ static digest256map_t *hs_cache_v3_client;

-/* Client-side introduction point state cache. Map indexed by service public +/** Client-side introduction point state cache. Map indexed by service public * identity key (onion address). It contains hs_cache_client_intro_state_t * objects all related to a specific service. */ static digest256map_t *hs_cache_client_intro_state;

-/* Return the size of a client cache entry in bytes. */ +/** Return the size of a client cache entry in bytes. */ static size_t cache_get_client_entry_size(const hs_cache_client_descriptor_t *entry) { @@ -345,7 +345,7 @@ cache_get_client_entry_size(const hs_cache_client_descriptor_t *entry) strlen(entry->encoded_desc) + hs_desc_obj_size(entry->desc); }

-/* Remove a given descriptor from our cache. */ +/** Remove a given descriptor from our cache. */ static void remove_v3_desc_as_client(const hs_cache_client_descriptor_t *desc) { @@ -355,7 +355,7 @@ remove_v3_desc_as_client(const hs_cache_client_descriptor_t *desc) rend_cache_decrement_allocation(cache_get_client_entry_size(desc)); }

-/* Store a given descriptor in our cache. */ +/** Store a given descriptor in our cache. */ static void store_v3_desc_as_client(hs_cache_client_descriptor_t *desc) { @@ -365,7 +365,7 @@ store_v3_desc_as_client(hs_cache_client_descriptor_t *desc) rend_cache_increment_allocation(cache_get_client_entry_size(desc)); }

-/* Query our cache and return the entry or NULL if not found or if expired. */ +/** Query our cache and return the entry or NULL if not found or if expired. */ STATIC hs_cache_client_descriptor_t * lookup_v3_desc_as_client(const uint8_t *key) { @@ -388,7 +388,7 @@ lookup_v3_desc_as_client(const uint8_t *key) return cached_desc; }

-/* Parse the encoded descriptor in <b>desc_str</b> using +/** Parse the encoded descriptor in <b>desc_str</b> using * <b>service_identity_pk<b> to decrypt it first. * * If everything goes well, allocate and return a new @@ -448,7 +448,7 @@ cache_client_desc_free_void(void *ptr) cache_client_desc_free(desc); }

-/* Return a newly allocated and initialized hs_cache_intro_state_t object. */ +/** Return a newly allocated and initialized hs_cache_intro_state_t object. */ static hs_cache_intro_state_t * cache_intro_state_new(void) { @@ -460,21 +460,21 @@ cache_intro_state_new(void) #define cache_intro_state_free(val) \ FREE_AND_NULL(hs_cache_intro_state_t, cache_intro_state_free_, (val))

-/* Free an hs_cache_intro_state_t object. */ +/** Free an hs_cache_intro_state_t object. */ static void cache_intro_state_free_(hs_cache_intro_state_t *state) { tor_free(state); }

-/* Helper function: used by the free all function. */ +/** Helper function: used by the free all function. */ static void cache_intro_state_free_void(void *state) { cache_intro_state_free_(state); }

-/* Return a newly allocated and initialized hs_cache_client_intro_state_t +/** Return a newly allocated and initialized hs_cache_client_intro_state_t * object. */ static hs_cache_client_intro_state_t * cache_client_intro_state_new(void) @@ -488,7 +488,7 @@ cache_client_intro_state_new(void) FREE_AND_NULL(hs_cache_client_intro_state_t, \ cache_client_intro_state_free_, (val))

-/* Free a cache_client_intro_state object. */ +/** Free a cache_client_intro_state object. */ static void cache_client_intro_state_free_(hs_cache_client_intro_state_t *cache) { @@ -499,14 +499,14 @@ cache_client_intro_state_free_(hs_cache_client_intro_state_t *cache) tor_free(cache); }

-/* Helper function: used by the free all function. */ +/** Helper function: used by the free all function. */ static void cache_client_intro_state_free_void(void *entry) { cache_client_intro_state_free_(entry); }

-/* For the given service identity key service_pk and an introduction +/** For the given service identity key service_pk and an introduction * authentication key auth_key, lookup the intro state object. Return 1 if * found and put it in entry if not NULL. Return 0 if not found and entry is * untouched. */ @@ -541,7 +541,7 @@ cache_client_intro_state_lookup(const ed25519_public_key_t *service_pk, return 0; }

-/* Note the given failure in state. */ +/** Note the given failure in state. */ static void cache_client_intro_state_note(hs_cache_intro_state_t *state, rend_intro_point_failure_t failure) @@ -563,7 +563,7 @@ cache_client_intro_state_note(hs_cache_intro_state_t *state, } }

-/* For the given service identity key service_pk and an introduction +/** For the given service identity key service_pk and an introduction * authentication key auth_key, add an entry in the client intro state cache * If no entry exists for the service, it will create one. If state is non * NULL, it will point to the new intro state entry. */ @@ -597,7 +597,7 @@ cache_client_intro_state_add(const ed25519_public_key_t *service_pk, } }

-/* Remove every intro point state entry from cache that has been created +/** Remove every intro point state entry from cache that has been created * before or at the cutoff. */ static void cache_client_intro_state_clean(time_t cutoff, @@ -614,7 +614,7 @@ cache_client_intro_state_clean(time_t cutoff, } DIGEST256MAP_FOREACH_END; }

-/* Return true iff no intro points are in this cache. */ +/** Return true iff no intro points are in this cache. */ static int cache_client_intro_state_is_empty(const hs_cache_client_intro_state_t *cache) { @@ -664,7 +664,7 @@ cache_store_as_client(hs_cache_client_descriptor_t *client_desc) return 0; }

-/* Return true iff the cached client descriptor at <b>cached_desc</b has +/** Return true iff the cached client descriptor at <b>cached_desc</b has * expired. */ static int cached_client_descriptor_has_expired(time_t now, @@ -687,7 +687,7 @@ cached_client_descriptor_has_expired(time_t now, return 0; }

-/* clean the client cache using now as the current time. Return the total size +/** clean the client cache using now as the current time. Return the total size * of removed bytes from the cache. */ static size_t cache_clean_v3_as_client(time_t now) @@ -800,7 +800,7 @@ hs_cache_store_as_client(const char *desc_str, return -1; }

-/* Clean all client caches using the current time now. */ +/** Clean all client caches using the current time now. */ void hs_cache_clean_as_client(time_t now) { @@ -811,7 +811,7 @@ hs_cache_clean_as_client(time_t now) cache_clean_v3_as_client(now); }

-/* Purge the client descriptor cache. */ +/** Purge the client descriptor cache. */ void hs_cache_purge_as_client(void) { @@ -828,7 +828,7 @@ hs_cache_purge_as_client(void) log_info(LD_REND, "Hidden service client descriptor cache purged."); }

-/* For a given service identity public key and an introduction authentication +/** For a given service identity public key and an introduction authentication * key, note the given failure in the client intro state cache. */ void hs_cache_client_intro_state_note(const ed25519_public_key_t *service_pk, @@ -850,7 +850,7 @@ hs_cache_client_intro_state_note(const ed25519_public_key_t *service_pk, cache_client_intro_state_note(entry, failure); }

-/* For a given service identity public key and an introduction authentication +/** For a given service identity public key and an introduction authentication * key, return true iff it is present in the failure cache. */ const hs_cache_intro_state_t * hs_cache_client_intro_state_find(const ed25519_public_key_t *service_pk, @@ -861,7 +861,7 @@ hs_cache_client_intro_state_find(const ed25519_public_key_t *service_pk, return state; }

-/* Cleanup the client introduction state cache. */ +/** Cleanup the client introduction state cache. */ void hs_cache_client_intro_state_clean(time_t now) { @@ -881,7 +881,7 @@ hs_cache_client_intro_state_clean(time_t now) } DIGEST256MAP_FOREACH_END; }

-/* Purge the client introduction state cache. */ +/** Purge the client introduction state cache. */ void hs_cache_client_intro_state_purge(void) { @@ -897,7 +897,7 @@ hs_cache_client_intro_state_purge(void)

/**************** Generics *********************************/

-/* Do a round of OOM cleanup on all directory caches. Return the amount of +/** Do a round of OOM cleanup on all directory caches. Return the amount of * removed bytes. It is possible that the returned value is lower than * min_remove_bytes if the caches get emptied out so the caller should be * aware of this. */ @@ -951,7 +951,7 @@ hs_cache_handle_oom(time_t now, size_t min_remove_bytes) return bytes_removed; }

-/* Return the maximum size of a v3 HS descriptor. */ +/** Return the maximum size of a v3 HS descriptor. */ unsigned int hs_cache_get_max_descriptor_size(void) { @@ -960,7 +960,7 @@ hs_cache_get_max_descriptor_size(void) HS_DESC_MAX_LEN, 1, INT32_MAX); }

-/* Initialize the hidden service cache subsystem. */ +/** Initialize the hidden service cache subsystem. */ void hs_cache_init(void) { @@ -975,7 +975,7 @@ hs_cache_init(void) hs_cache_client_intro_state = digest256map_new(); }

-/* Cleanup the hidden service cache subsystem. */ +/** Cleanup the hidden service cache subsystem. */ void hs_cache_free_all(void) { diff --git a/src/feature/hs/hs_cache.h b/src/feature/hs/hs_cache.h index 079d31d43..5df7e54fc 100644 --- a/src/feature/hs/hs_cache.h +++ b/src/feature/hs/hs_cache.h @@ -18,47 +18,47 @@

struct ed25519_public_key_t;

-/* This is the maximum time an introduction point state object can stay in the +/** This is the maximum time an introduction point state object can stay in the * client cache in seconds (2 mins or 120 seconds). */ #define HS_CACHE_CLIENT_INTRO_STATE_MAX_AGE (2 * 60)

-/* Introduction point state. */ +/** Introduction point state. */ typedef struct hs_cache_intro_state_t { - /* When this entry was created and put in the cache. */ + /** When this entry was created and put in the cache. */ time_t created_ts;

- /* Did it suffered a generic error? */ + /** Did it suffered a generic error? */ unsigned int error : 1;

- /* Did it timed out? */ + /** Did it timed out? */ unsigned int timed_out : 1;

- /* How many times we tried to reached it and it was unreachable. */ + /** How many times we tried to reached it and it was unreachable. */ uint32_t unreachable_count; } hs_cache_intro_state_t;

typedef struct hs_cache_client_intro_state_t { - /* Contains hs_cache_intro_state_t object indexed by introduction point + /** Contains hs_cache_intro_state_t object indexed by introduction point * authentication key. */ digest256map_t *intro_points; } hs_cache_client_intro_state_t;

-/* Descriptor representation on the directory side which is a subset of +/** Descriptor representation on the directory side which is a subset of * information that the HSDir can decode and serve it. */ typedef struct hs_cache_dir_descriptor_t { - /* This object is indexed using the blinded pubkey located in the plaintext + /** This object is indexed using the blinded pubkey located in the plaintext * data which is populated only once the descriptor has been successfully * decoded and validated. This simply points to that pubkey. */ const uint8_t *key;

- /* When does this entry has been created. Used to expire entries. */ + /** When does this entry has been created. Used to expire entries. */ time_t created_ts;

- /* Descriptor plaintext information. Obviously, we can't decrypt the + /** Descriptor plaintext information. Obviously, we can't decrypt the * encrypted part of the descriptor. */ hs_desc_plaintext_data_t *plaintext_data;

- /* Encoded descriptor which is basically in text form. It's a NUL terminated + /** Encoded descriptor which is basically in text form. It's a NUL terminated * string thus safe to strlen(). */ char *encoded_desc; } hs_cache_dir_descriptor_t; @@ -104,19 +104,19 @@ void hs_cache_client_intro_state_purge(void);

/** Represents a locally cached HS descriptor on a hidden service client. */ typedef struct hs_cache_client_descriptor_t { - /* This object is indexed using the service identity public key */ + /** This object is indexed using the service identity public key */ struct ed25519_public_key_t key;

- /* When will this entry expire? We expire cached client descriptors in the + /** When will this entry expire? We expire cached client descriptors in the * start of the next time period, since that's when clients need to start * using the next blinded key of the service. */ time_t expiration_ts;

- /* The cached descriptor, this object is the owner. It can't be NULL. A + /** The cached descriptor, this object is the owner. It can't be NULL. A * cache object without a valid descriptor is not possible. */ hs_descriptor_t *desc;

- /* Encoded descriptor in string form. Can't be NULL. */ + /** Encoded descriptor in string form. Can't be NULL. */ char *encoded_desc; } hs_cache_client_descriptor_t;