Changeset 14548b9 in mod_gnutls


Ignore:
Timestamp:
Dec 5, 2016, 4:02:30 PM (6 years ago)
Author:
Thomas Klute <thomas2.klute@…>
Branches:
asyncio, debian/master, debian/stretch-backports, main, master, proxy-ticket, upstream
Children:
104e881
Parents:
d4d066f
git-author:
Thomas Klute <thomas2.klute@…> (12/05/16 16:01:23)
git-committer:
Thomas Klute <thomas2.klute@…> (12/05/16 16:02:30)
Message:

Update comments in gnutls_cache.(c|h) to work with Doxygen

Location:
src
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • src/gnutls_cache.c

    rd4d066f r14548b9  
    1 /**
     1/*
    22 *  Copyright 2004-2005 Paul Querna
    33 *  Copyright 2008 Nikos Mavrogiannopoulos
    … …  
    1616 *  See the License for the specific language governing permissions and
    1717 *  limitations under the License.
    18  *
    1918 */
    2019
    21 /***
    22  * The signatures of the (dbm|mc)_cache_...() functions may be a bit
     20/**
     21 * @file gnutls_cache.c
     22 *
     23 * The signatures of the `(dbm|mc)_cache_...()` functions may be a bit
    2324 * confusing: "store" and "expire" take a server_rec, "fetch" an
    24  * mgs_handle_t, and "delete" the void* required for a
    25  * gnutls_db_remove_func. The first two have matching ..._session
     25 * mgs_handle_t, and "delete" the `void*` required for a
     26 * `gnutls_db_remove_func`. The first two have matching `..._session`
    2627 * functions to fit their respective GnuTLS session cache signatures.
    2728 *
    2829 * This is because "store", "expire" (dbm only), and "fetch" are also
    29  * needed for the OCSP cache. Their ..._session variants have been
     30 * needed for the OCSP cache. Their `..._session` variants have been
    3031 * created to take care of the session cache specific parts, mainly
    3132 * calculating the DB key from the session ID. They have to match the
    3233 * appropriate GnuTLS DB function signatures.
    3334 *
    34  * Additionally, there are the mc_cache_(store|fetch)_generic()
     35 * Additionally, there are the `mc_cache_(store|fetch)_generic()`
    3536 * functions. They exist because memcached requires string keys while
    3637 * DBM accepts binary keys, and provide wrappers to turn binary keys
    37  * into hex strings with a "mod_gnutls:" prefix.
     38 * into hex strings with a `mod_gnutls:` prefix.
    3839 *
    3940 * To update cached OCSP responses independent of client connections,
    … …  
    4142 * the other hand "fetch" does not need to do that, because cached
    4243 * OCSP responses will be retrieved for use in client connections.
    43  ***/
     44 */
    4445
    4546#include "gnutls_cache.h"
    … …  
    6465#endif
    6566
    66 /* default cache timeout */
     67/** Default session cache timeout */
    6768#define MGS_DEFAULT_CACHE_TIMEOUT 300
    6869
    69 /* it seems the default has some strange errors. Use SDBM
    70  */
     70/** Prefix for keys used with a memcached cache */
    7171#define MC_TAG "mod_gnutls:"
    72 /* two characters per byte, plus one more for '\0' */
     72/** Maximum length of the hex string representation of a GnuTLS
     73 * session ID: two characters per byte, plus one more for `\0` */
    7374#if GNUTLS_VERSION_NUMBER >= 0x030400
    7475#define GNUTLS_SESSION_ID_STRING_LEN ((GNUTLS_MAX_SESSION_ID_SIZE * 2) + 1)
    … …  
    8586#endif
    8687
    87 /* Name the Session ID as:
    88  * server:port.SessionID
    89  * to disallow resuming sessions on different servers
     88/**
     89 * Turn a GnuTLS session ID into the key format we use with DBM
     90 * caches. Name the Session ID as `server:port.SessionID` to disallow
     91 * resuming sessions on different servers.
     92 *
     93 * @return `0` on success, `-1` on failure
    9094 */
    9195static int mgs_session_id2dbm(conn_rec *c, unsigned char *id, int idlen,
    … …  
    106110}
    107111
    108 /* The OPENSSL_TIME_FORMAT macro and mgs_time2sz() serve to print time
    109  * in a format compatible with OpenSSL's ASN1_TIME_print()
     112/** The OPENSSL_TIME_FORMAT macro and mgs_time2sz() serve to print
     113 * time in a format compatible with OpenSSL's `ASN1_TIME_print()`
    110114 * function. */
    111 
    112115#define OPENSSL_TIME_FORMAT "%b %d %k:%M:%S %Y %Z"
    113116
    … …  
    128131#if HAVE_APR_MEMCACHE
    129132
    130 /* Name the Session ID as:
    131  * server:port.SessionID
    132  * to disallow resuming sessions on different servers
     133/**
     134 * Turn a GnuTLS session ID into the key format we use with memcached
     135 * caches. Name the Session ID as `server:port.SessionID` to disallow
     136 * resuming sessions on different servers.
     137 *
     138 * @return `0` on success, `-1` on failure
    133139 */
    134140static char *mgs_session_id2mc(conn_rec * c, unsigned char *id, int idlen)

  • src/gnutls_cache.h

    rd4d066f r14548b9  
    1 /**
     1/*
    22 *  Copyright 2004-2005 Paul Querna
    33 *  Copyright 2014 Nikos Mavrogiannopoulos
    … …  
    1515 *  See the License for the specific language governing permissions and
    1616 *  limitations under the License.
     17 */
     18
     19/**
     20 * @file
    1721 *
     22 * Generic object cache for mod_gnutls
    1823 */
    1924
    … …  
    2429#include <httpd.h>
    2530
     31/** Name of the mod_gnutls cache access mutex, for use with Apache's
     32 * `Mutex` directive */
    2633#define MGS_CACHE_MUTEX_NAME "gnutls-cache"
    2734
    2835/**
    29  * Init the Cache after Configuration is done
     36 * Initialize the internal cache configuration structure. This
     37 * function is called after the configuration file(s) have been
     38 * parsed.
    3039 */
    3140int mgs_cache_post_config(apr_pool_t *p, server_rec *s, mgs_srvconf_rec *sc);
    3241
    3342/**
    34  * Init the Cache inside each Process
     43 * (Re-)Initialize the cache in a child process after forking
    3544 */
    3645int mgs_cache_child_init(apr_pool_t *p, server_rec *s, mgs_srvconf_rec *sc);
    3746
    3847/**
    39  * Setup the Session Caching
     48 * Setup caching for the given TLS session
     49 *
     50 * @param ctxt mod_gnutls session context
     51 * @return 0
    4052 */
    4153int mgs_cache_session_init(mgs_handle_t *ctxt);
    … …  
    4456
    4557/**
    46  * Convert a time_t into a null terminated string in a format
    47  * compatible with OpenSSL's ASN1_TIME_print()
     58 * Convert a `time_t` into a null terminated string in a format
     59 * compatible with OpenSSL's `ASN1_TIME_print()`
    4860 *
    4961 * @param t time_t time
    5062 * @param str Location to store the time string
    51  * @param strsize The maximum length that can be stored in str
     63 * @param strsize The maximum length that can be stored in `str`
     64 * @return `str`
    5265 */
    5366char *mgs_time2sz(time_t t, char *str, int strsize);
    5467
    55 /*
    56  * Generic object cache functions, used for OCSP caching
     68/**
     69 * Generic store function for the mod_gnutls object cache
     70 *
     71 * @param s server associated with the cache entry
     72 * @param key key for the cache entry
     73 * @param data data to be cached
     74 * @param expiry expiration time
     75 * @return -1 on error, 0 on success
    5776 */
    5877typedef int (*cache_store_func)(server_rec *s, gnutls_datum_t key,
    5978                                gnutls_datum_t data, apr_time_t expiry);
     79/**
     80 * Generic fetch function for the mod_gnutls object cache
     81 *
     82 * @param ctxt mod_gnutls session context for the request
     83 * @param key key for the cache entry to be fetched
     84 * @return the requested cache entry, or `{NULL, 0}`
     85 */
    6086typedef gnutls_datum_t (*cache_fetch_func)(mgs_handle_t *ctxt,
    6187                                           gnutls_datum_t key);
     88/**
     89 * Internal cache configuration structure
     90 */
    6291struct mgs_cache {
     92    /** Store function for this cache */
    6393    cache_store_func store;
     94    /** Fetch function for this cache */
    6495    cache_fetch_func fetch;
    65     /* Mutex for cache access (used only if the cache type is not
     96    /** Mutex for cache access (used only if the cache type is not
    6697     * thread-safe) */
    6798    apr_global_mutex_t *mutex;
Note: See TracChangeset for help on using the changeset viewer.