tls: fix all doxygen errors, extend existing documentation in touched files

modules/tls/tls_cfg.c

@@ -17,7 +17,7 @@
 /**
  * SIP-router TLS support :: tls runtime configuration
  * @file tls_cfg.c
- * @ingroup: @tls
+ * @ingroup tls
  * Module: @ref tls
  */
 

modules/tls/tls_ct_q.h

@@ -1,6 +1,4 @@
 /* 
- * $Id$
- * 
  * Copyright (C) 2010 iptelorg GmbH
  *
  * Permission to use, copy, modify, and distribute this software for any
@@ -15,13 +13,16 @@
  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
-/** tls clear text queue (wrappers over sbufq).
+
+/**
+ * TLS clear text queue (wrappers over sbufq)
  * (e.g. queue clear text when SSL_write() cannot write it immediately due to
- *  re-keying).
- * @file modules/tls/tls_ct_q.c
- * @ingroup: tls
+ * re-keying).
+ * @file
+ * @ingroup tls
  * Module: @ref tls
  */
+
 /*
  * History:
  * --------
@@ -41,8 +42,9 @@ typedef struct sbuffer_queue tls_ct_q;
 #define tls_ct_q_non_empty(bq) ((bq) && (bq)->first!=0)
 
 
-/** adds/appends data to a tls clear text buffer queue.
- * WARNING: it does no attempt to synchronize access/lock. If needed it should
+/**
+ * @brief Adds/appends data to a tls clear text buffer queue
+ * @warning it does no attempt to synchronize access/lock. If needed it should
  * be called under lock.
  * @param **ct_q - double pointer to the buffer queue
  * @param data
@@ -70,9 +72,11 @@ error:
 
 
 
-/** destroy a buffer queue.
- * Everything is destroyed (shm_free()'d), included the queue head.
- * WARNING: it does no attempt to synchronize access/lock. If needed it should
+/**
+ * @brief Destroy a buffer queue
+ * 
+ * Everything is destroyed from a buffer queue (shm_free()'d), included the queue head.
+ * @warning it does no attempt to synchronize access/lock. If needed it should
  * be called under lock.
  * @param **ct_q - double pointer to the queue
  * @return - number of bytes that used to be queued (>=0).
@@ -92,12 +96,14 @@ inline static unsigned int tls_ct_q_destroy(tls_ct_q** ct_q)
 
 
 
-/** tries to flush the tls clear text queue.
+/**
+ * @brief Tries to flush the tls clear text queue
+ * 
  * Tries to flush as much as possible from the given queue, using the 
  * given callback.
- * WARNING: it does no attempt to synchronize access/lock. If needed it should
+ * @warning it does no attempt to synchronize access/lock. If needed it should
  * be called under lock.
- * @param q - buffer queue
+ * @param tc_q - buffer queue
  * @param *flags - set to:
  *                   F_BUFQ_EMPTY if the queued is completely flushed
  *                   F_BUFQ_FLUSH_ERR if the flush_f callback returned error.

modules/tls/tls_ct_wrq.c

@@ -1,6 +1,4 @@
 /* 
- * $Id$
- * 
  * Copyright (C) 2010 iptelorg GmbH
  *
  * Permission to use, copy, modify, and distribute this software for any
@@ -15,13 +13,16 @@
  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
-/** tls clear text write queue.
+
+/**
+ * tls clear text write queue.
  * (queue clear text when SSL_write() cannot write it immediately due to
- *  re-keying).
- * @file modules/tls/tls_ct_wrq.c
- * @ingroup: tls
+ * re-keying).
+ * @file
+ * @ingroup tls
  * Module: @ref tls
  */
+
 /*
  * History:
  * --------
@@ -43,7 +44,8 @@ atomic_t* tls_total_ct_wq; /* total clear text bytes queued for a future
 
 
 
-/** init clear text write queues support.
+/**
+ * @brief Init clear text write queues support
  * @return 0 on success, < 0 on error.
  */
 int tls_ct_wq_init()
@@ -57,7 +59,9 @@ int tls_ct_wq_init()
 
 
 
-/** destroy clear text write queues support. */
+/**
+ * @brief Destroy clear text write queues support
+ */
 void tls_ct_wq_destroy()
 {
 	if (tls_total_ct_wq) {
@@ -68,7 +72,10 @@ void tls_ct_wq_destroy()
 
 
 
-/** total number of wr. queued bytes in all the SSL connections. */
+/**
+ * @brief Total number of written queued bytes in all the SSL connections
+ * @return total number of written queued bytes in all SSL connections
+ */
 unsigned int tls_ct_wq_total_bytes()
 {
 	return (unsigned)atomic_get(tls_total_ct_wq);
@@ -76,13 +83,16 @@ unsigned int tls_ct_wq_total_bytes()
 
 
 
-/** callback for tls_ct_q_flush().
+/**
+ * @brief Callback for tls_ct_q_flush()
  *
- * @param *ssl - ssl context.
- * @param *err - error reason (set on exit).
+ * @param tcp_c TCP connection containing the SSL context
+ * @param error error reason (set on exit)
+ * @param buf buffer
+ * @param size buffer size
  * @return >0 on success (bytes written), <=0 on ssl error (should be
- *  handled outside).
- * WARNING: the ssl context must have the wbio and rbio previously set!
+ * handled outside)
+ * @warning the SSL context must have the wbio and rbio previously set!
  */
 static int ssl_flush(void* tcp_c, void* error, const void* buf, unsigned size)
 {
@@ -120,14 +130,15 @@ static int ssl_flush(void* tcp_c, void* error, const void* buf, unsigned size)
 
 
 
-
-/** wrapper over tls_ct_q_flush().
- * Besides doing a tls_ct_q_add it also keeps track of queue size and
- * total queued bytes.
- * @param ssl - ssl context
- * @param **ct_q - double pointer to clear text queue.
- * @param *flags - filled, @see tls_ct_q_add() for more details.
- * @param ssl_err - set to the ssl err (SSL_ERROR_NONE on full success).
+/**
+ * @brief Wrapper over tls_ct_q_flush()
+ * 
+ * Wrapper over tls_ct_q_flush(), besides doing a tls_ct_q_add it
+ * also keeps track of queue size and total queued bytes.
+ * @param c TCP connection
+ * @param ct_q clear text queue
+ * @param flags filled, @see tls_ct_q_add() for more details.
+ * @param ssl_err set to the SSL err (SSL_ERROR_NONE on full success).
  * @return -1 on internal error, or the number of bytes flushed on success
  *         (>=0).
  */
@@ -147,9 +158,15 @@ int tls_ct_wq_flush(struct tcp_connection* c, tls_ct_q** ct_q,
 
 
 
-/** wrapper over tls_ct_q_add().
- * Besides doing a tls_ct_q_add it also keeps track of queue size and
- * total queued bytes. If the maximum queue size is exceeded => error.
+/**
+ * @brief Wrapper over tls_ct_q_add()
+ * 
+ * Wrapper over tls_ct_q_add(), besides doing a tls_ct_q_add it
+ * also keeps track of queue size and total queued bytes.
+ * If the maximum queue size is exceeded => error.
+ * @param ct_q clear text queue
+ * @param data data
+ * @param size data size
  * @return 0 on success, < 0 on error (-1 memory allocation, -2 queue size
  *         too big).
  */
@@ -172,10 +189,12 @@ int tls_ct_wq_add(tls_ct_q** ct_q, const void* data, unsigned int size)
 
 
 
-/** wrapper over tls_ct_q_destroy().
- * Besides doing a tls_ct_q_destroy it also keeps track of the total queued
- * bytes.
- * @return - number of bytes that used to be queued (>=0),
+/**
+ * @brief Wrapper over tls_ct_q_destroy()
+ * Wrapper over tls_ct_q_destroy(), besides doing a tls_ct_q_destroy it
+ * also keeps track of the total queued bytes.
+ * @param ct_q clear text queue
+ * @return number of bytes that used to be queued (>=0),
  */
 unsigned int tls_ct_wq_free(tls_ct_q** ct_q)
 {

modules/tls/tls_ct_wrq.h

@@ -1,6 +1,4 @@
 /* 
- * $Id$
- * 
  * Copyright (C) 2010 iptelorg GmbH
  *
  * Permission to use, copy, modify, and distribute this software for any
@@ -16,10 +14,13 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 
-/** .
+/**
+ * tls clear text write queue.
+ * (queue clear text when SSL_write() cannot write it immediately due to
+ * re-keying).
  * @file
- * @ingroup: 
- * Module: 
+ * @ingroup tls
+ * Module: @ref tls
  */
 
 /*
@@ -37,17 +38,63 @@
 
 
 
+/**
+ * @brief Init clear text write queues support
+ * @return 0 on success, < 0 on error.
+ */
 int tls_ct_wq_init();
+
+/**
+ * @brief Destroy clear text write queues support
+ */
 void tls_ct_wq_destroy();
+
+
+/**
+ * @brief Total number of written queued bytes in all the SSL connections
+ * @return total number of written queued bytes in all SSL connections
+ */
 unsigned int tls_ct_wq_total_bytes();
 
 #define tls_ct_wq_empty(tc_q) (*(tc_q)==0 || (*(tc_q))->first==0)
 #define tls_ct_wq_non_empty(bq) (*(tc_q) && (*(tc_q))->first!=0)
 
-
+/**
+ * @brief Wrapper over tls_ct_q_flush()
+ * 
+ * Wrapper over tls_ct_q_flush(), besides doing a tls_ct_q_add it
+ * also keeps track of queue size and total queued bytes.
+ * @param c TCP connection
+ * @param ct_q clear text queue
+ * @param flags filled, @see tls_ct_q_add() for more details.
+ * @param ssl_err set to the SSL err (SSL_ERROR_NONE on full success).
+ * @return -1 on internal error, or the number of bytes flushed on success
+ *         (>=0).
+ */
 int tls_ct_wq_flush(struct tcp_connection* c, tls_ct_q** tc_q,
 					int* flags, int* ssl_err);
+
+/**
+ * @brief Wrapper over tls_ct_q_add()
+ * 
+ * Wrapper over tls_ct_q_add(), besides doing a tls_ct_q_add it
+ * also keeps track of queue size and total queued bytes.
+ * If the maximum queue size is exceeded => error.
+ * @param ct_q clear text queue
+ * @param data data
+ * @param size data size
+ * @return 0 on success, < 0 on error (-1 memory allocation, -2 queue size
+ *         too big).
+ */
 int tls_ct_wq_add(tls_ct_q** ct_q, const void* data, unsigned int size);
+
+/**
+ * @brief Wrapper over tls_ct_q_destroy()
+ * Wrapper over tls_ct_q_destroy(), besides doing a tls_ct_q_destroy it
+ * also keeps track of the total queued bytes.
+ * @param ct_q clear text queue
+ * @return number of bytes that used to be queued (>=0),
+ */
 unsigned int tls_ct_wq_free(tls_ct_q** ct_q);
 
 #endif /*__tls_ct_wrq_h*/

modules/tls/tls_domain.c

@@ -41,8 +41,14 @@
 #include "tls_cfg.h"
 
 
-/*
- * create a new domain 
+/**
+ * @brief Create a new TLS domain structure
+ * 
+ * Create a new domain structure in new allocated shared memory.
+ * @param type domain Type
+ * @param ip domain IP
+ * @param port domain port
+ * @return new domain
  */
 tls_domain_t* tls_new_domain(int type, struct ip_addr *ip, unsigned short port)
 {
@@ -69,8 +75,9 @@ tls_domain_t* tls_new_domain(int type, struct ip_addr *ip, unsigned short port)
 }
 
 
-/*
- * Free all memory used by configuration domain
+/**
+ * @brief Free all memory used by TLS configuration domain
+ * @param d freed domain
  */
 void tls_free_domain(tls_domain_t* d)
 {
@@ -95,8 +102,9 @@ void tls_free_domain(tls_domain_t* d)
 }
 
 
-/*
- * clean up 
+/**
+ * @brief Free TLS configuration structure
+ * @param cfg freed configuration
  */
 void tls_free_cfg(tls_domains_cfg_t* cfg)
 {
@@ -116,7 +124,9 @@ void tls_free_cfg(tls_domains_cfg_t* cfg)
 }
 
 
-
+/**
+ * @brief Destroy all TLS configuration data
+ */
 void tls_destroy_cfg(void)
 {
 	tls_domains_cfg_t* ptr;
@@ -141,8 +151,10 @@ void tls_destroy_cfg(void)
 
 
 
-/*
- * Print TLS domain identifier
+/**
+ * @brief Generate TLS domain identifier
+ * @param d printed domain
+ * @return printed domain, with zero termination
  */
 char* tls_domain_str(tls_domain_t* d)
 {
@@ -164,9 +176,14 @@ char* tls_domain_str(tls_domain_t* d)
 }
 
 
-/*
- * Initialize parameters that have not been configured from
- * parent domain (usually one of default domains
+/**
+ * @brief Initialize TLS domain parameters that have not been configured yet
+ * 
+ * Initialize TLS domain parameters that have not been configured from
+ * parent domain (usually one of default domains)
+ * @param d initialized domain
+ * @param parent parent domain
+ * @return 0 on success, -1 on error
  */
 static int fill_missing(tls_domain_t* d, tls_domain_t* parent)
 {
@@ -228,18 +245,23 @@ static int fill_missing(tls_domain_t* d, tls_domain_t* parent)
 }
 
 
-/* called for ctx, with 2 args.
- * should return 0 on succes, <0 on critical error.
+/** 
+ * @brief Called for ctx, with 2 args
+ * @param ctx SSL context
+ * @param larg ?
+ * @param parg ?
+ * @return return 0 on succes, <0 on critical error
  */
 typedef int (*per_ctx_cbk_f)(SSL_CTX* ctx, long larg, void* parg);
 
 
-/** execute callback on all the CTX'es on a domain.
- * @param d - domain
- * @param f - callback function
- * @param l - parameter passed to the callback
- * @param p - parameter passed to the callback
- * @return 0 on success, <0 on error.
+/**
+ * @brief Execute callback on all the CTX'es on a domain
+ * @param d domain
+ * @param ctx_cbk callback function
+ * @param l1 parameter passed to the callback
+ * @param p2 parameter passed to the callback
+ * @return 0 on success, <0 on error
  */
 static int tls_domain_foreach_CTX(tls_domain_t* d, per_ctx_cbk_f ctx_cbk,
 									long l1, void* p2)
@@ -256,12 +278,13 @@ static int tls_domain_foreach_CTX(tls_domain_t* d, per_ctx_cbk_f ctx_cbk,
 }
 
 
-/** execute callback on all the CTX'es on in a domain list.
- * @param d - domain
- * @param f - callback function
- * @param l - parameter passed to the callback
- * @param p - parameter passed to the callback
- * @return 0 on success, <0 on error.
+/**
+ * @brief Execute callback on all the CTX'es on in a domain list
+ * @param d domain
+ * @param ctx_cbk callback function
+ * @param l1 parameter passed to the callback
+ * @param p2 parameter passed to the callback
+ * @return 0 on success, <0 on error
  */
 static int tls_foreach_CTX_in_domain_lst(tls_domain_t* d,
 										per_ctx_cbk_f ctx_cbk,
@@ -275,12 +298,13 @@ static int tls_foreach_CTX_in_domain_lst(tls_domain_t* d,
 }
 
 
-/** execute callback on all the CTX'es in all the srv domains in a tls cfg.
- * @param cfg - tls cfg.
- * @param f - callback function
- * @param l - parameter passed to the callback
- * @param p - parameter passed to the callback
- * @return 0 on success, <0 on error.
+/**
+ * @brief Execute callback on all the CTX'es in all the srv domains in a tls cfg
+ * @param cfg tls cfg.
+ * @param ctx_cbk callback function
+ * @param l1 parameter passed to the callback
+ * @param p2 parameter passed to the callback
+ * @return 0 on success, <0 on error
  */
 static int tls_foreach_CTX_in_srv_domains(tls_domains_cfg_t* cfg,
 											per_ctx_cbk_f ctx_cbk,
@@ -296,11 +320,12 @@ static int tls_foreach_CTX_in_srv_domains(tls_domains_cfg_t* cfg,
 }
 
 
-/** execute callback on all the CTX'es in all the client domains in a tls cfg.
- * @param cfg - tls cfg.
- * @param f - callback function
- * @param l - parameter passed to the callback
- * @param p - parameter passed to the callback
+/**
+ * @brief Execute callback on all the CTX'es in all the client domains in a tls cfg
+ * @param cfg tls cfg.
+ * @param ctx_cbk callback function
+ * @param l1 parameter passed to the callback
+ * @param p2 parameter passed to the callback
  * @return 0 on success, <0 on error.
  */
 static int tls_foreach_CTX_in_cli_domains(tls_domains_cfg_t* cfg,
@@ -317,12 +342,13 @@ static int tls_foreach_CTX_in_cli_domains(tls_domains_cfg_t* cfg,
 }
 
 
-/** execute callback on all the CTX'es in all the domains in a tls cfg.
- * @param cfg - tls cfg
- * @param f - callback function
- * @param l - parameter passed to the callback
- * @param p - parameter passed to the callback
- * @return 0 on success, <0 on error.
+/**
+ * @brief Execute callback on all the CTX'es in all the domains in a tls cfg
+ * @param cfg tls cfg
+ * @param ctx_cbk callback function
+ * @param l1 parameter passed to the callback
+ * @param p2 parameter passed to the callback
+ * @return 0 on success, <0 on error
  */
 static int tls_foreach_CTX_in_cfg(tls_domains_cfg_t* cfg,
 										per_ctx_cbk_f ctx_cbk,
@@ -340,15 +366,17 @@ static int tls_foreach_CTX_in_cfg(tls_domains_cfg_t* cfg,
 
 
 
-/** fix pathnames.
- * To be used when loading the domain key, cert, ca list a.s.o.
+/**
+ * @brief Fix pathnames when loading domain keys or other list
+ * 
+ * Fix pathnames, to be used when loading the domain key, cert, ca list a.s.o.
  * It will replace path with a fixed shm allocated version. Assumes path->s
  * was shm allocated.
- * @param path - path to be fixed. If it starts with '.' or '/' is left alone
- *               (forced "relative" or "absolute" path). Otherwise the path
- *               is considered to be relative to the main config file directory
- *               (e.g. for /etc/ser/ser.cfg => /etc/ser/\<path\>).
- * @return  0 on success, -1 on error.
+ * @param path path to be fixed. If it starts with '.' or '/' is left alone
+ * (forced "relative" or "absolute" path). Otherwise the path is considered 
+ * to be relative to the main config file directory
+ * (e.g. for /etc/ser/ser.cfg => /etc/ser/\<path\>).
+ * @return  0 on success, -1 on error
  */
 int fix_shm_pathname(str* path)
 {
@@ -370,8 +398,10 @@ int fix_shm_pathname(str* path)
 
 
 
-/* 
- * Load certificate from file 
+/**
+ * @brief Load certificate from file
+ * @param d domain
+ * @return 0 if not configured or on success, -1 on error
  */
 static int load_cert(tls_domain_t* d)
 {
@@ -398,8 +428,10 @@ static int load_cert(tls_domain_t* d)
 }
 
 
-/* 
- * Load CA list from file 
+/**
+ * @brief Load CA list from file
+ * @param d domain
+ * @return 0 if not configured or on success, -1 on error
  */
 static int load_ca_list(tls_domain_t* d)
 {
@@ -432,8 +464,10 @@ static int load_ca_list(tls_domain_t* d)
 }
 
 
-/*
- * Load CRL from file
+/**
+ * @brief Load CRL from file
+ * @param d domain
+ * @return 0 if not configured or on success, -1 on error
  */
 static int load_crl(tls_domain_t* d)
 {
@@ -470,8 +504,10 @@ static int load_crl(tls_domain_t* d)
 #define C_NO_KRB5_SUFFIX ":!KRB5"
 #define C_NO_KRB5_SUFFIX_LEN (sizeof(C_NO_KRB5_SUFFIX)-1)
 
-/* 
- * Configure cipher list 
+/**
+ * @brief Configure cipher list
+ * @param d domain
+ * @return 0 on success, -1 on error
  */
 static int set_cipher_list(tls_domain_t* d)
 {
@@ -513,8 +549,10 @@ static int set_cipher_list(tls_domain_t* d)
 }
 
 
-/* 
- * Enable/disable certificate verification 
+/**
+ * @brief Enable/disable TLS certificate verification
+ * @param d domain
+ * @return 0
  */
 static int set_verification(tls_domain_t* d)
 {
@@ -557,8 +595,10 @@ static int set_verification(tls_domain_t* d)
 }
 
 
-/* 
- * Configure generic SSL parameters 
+/**
+ * @brief Configure generic SSL parameters 
+ * @param d domain
+ * @return 0
  */
 static int set_ssl_options(tls_domain_t* d)
 {
@@ -604,8 +644,10 @@ static int set_ssl_options(tls_domain_t* d)
 }
 
 
-/* 
- * Configure session cache parameters 
+/**
+ * @brief Configure TLS session cache parameters 
+ * @param d domain
+ * @return 0
  */
 static int set_session_cache(tls_domain_t* d)
 {
@@ -632,10 +674,12 @@ static int set_session_cache(tls_domain_t* d)
 
 
 
-/** tls SSL_CTX_set_mode and SSL_CTX_clear_mode wrapper.
- *  @param mode - SSL_MODE_*.
- *  @param clear - if set to !=0 will do a clear, else (==0) a set.
- *  @return - 0 (always succeeds).
+/**
+ * @brief TLS SSL_CTX_set_mode and SSL_CTX_clear_mode wrapper
+ * @param ctx SSL context
+ * @param mode SSL_MODE_*
+ * @param clear if set to !=0 will do a clear, else (==0) a set
+ * @return 0 (always succeeds)
  */
 int tls_ssl_ctx_mode(SSL_CTX* ctx, long mode, void* clear)
 {
@@ -653,9 +697,12 @@ int tls_ssl_ctx_mode(SSL_CTX* ctx, long mode, void* clear)
 
 
 
-/** tls set ctx->free_list_max_len.
- *  @param val - value (<0 ignored).
- *  @return - 0 (always succeeds).
+/**
+ * @brief TLS set ctx->free_list_max_len
+ * @param ctx TLS context
+ * @param val value (<0 ignored)
+ * @param unused unused
+ * @return 0 (always succeeds)
  */
 int tls_ssl_ctx_set_freelist(SSL_CTX* ctx, long val, void* unused)
 {
@@ -671,9 +718,12 @@ int tls_ssl_ctx_set_freelist(SSL_CTX* ctx, long val, void* unused)
 	return 0;
 }
 
-/** tls SSL_CTX_set_max_send_fragment wrapper.
- *  @param val - value (<0 ignored). Should be between 512 and 16k.
- *  @return  0 on success, < 0 on failure (invalid value)
+/**
+ * @brief TLS SSL_CTX_set_max_send_fragment wrapper
+ * @param ctx TLS context
+ * @param val value (<0 ignored). Should be between 512 and 16k
+ * @param unused unused
+ * @return 0 on success, < 0 on failure (invalid value)
  */
 int tls_ssl_ctx_set_max_send_fragment(SSL_CTX* ctx, long val, void* unused)
 {
@@ -688,9 +738,12 @@ int tls_ssl_ctx_set_max_send_fragment(SSL_CTX* ctx, long val, void* unused)
 
 
 
-/** tls SSL_CTX_set_read_ahead wrapper.
- *  @param val - value (<0 ignored, 0 or >0).
- *  @return  0 (always success).
+/**
+ * @brief TLS SSL_CTX_set_read_ahead wrapper
+ * @param ctx TLS context
+ * @param val value (<0 ignored, 0 or >0)
+ * @param unused unused
+ * @return 0 (always success).
  */
 int tls_ssl_ctx_set_read_ahead(SSL_CTX* ctx, long val, void* unused)
 {
@@ -699,9 +752,10 @@ int tls_ssl_ctx_set_read_ahead(SSL_CTX* ctx, long val, void* unused)
 	return 0;
 }
 
-/*
- * Initialize all domain attributes from default domains
- * if necessary
+/**
+ * @brief Initialize all domain attributes from default domains if necessary
+ * @param d initialized TLS domain
+ * @param def default TLS domains
  */
 static int fix_domain(tls_domain_t* d, tls_domain_t* def)
 {
@@ -736,6 +790,14 @@ static int fix_domain(tls_domain_t* d, tls_domain_t* def)
 }
 
 
+/**
+ * @brief Password callback, ask for private key password on CLI
+ * @param buf buffer
+ * @param size buffer size
+ * @param rwflag not used
+ * @param filename filename
+ * @return length of password on success, 0 on error
+ */
 static int passwd_cb(char *buf, int size, int rwflag, void *filename)
 {
 #if OPENSSL_VERSION_NUMBER >= 0x00907000L	
@@ -770,8 +832,10 @@ static int passwd_cb(char *buf, int size, int rwflag, void *filename)
 
 
 #define NUM_RETRIES 3
-/*
- * load a private key from a file 
+/**
+ * @brief Load a private key from a file 
+ * @param d TLS domain
+ * @return 0 on success, -1 on error
  */
 static int load_private_key(tls_domain_t* d)
 {
@@ -824,9 +888,15 @@ static int load_private_key(tls_domain_t* d)
 }
 
 
-/*
- * Initialize attributes of all domains from default domains
- * if necessary
+/**
+ * @brief Initialize attributes of all domains from default domains if necessary
+ *
+ * Initialize attributes of all domains from default domains if necessary,
+ * fill in missing parameters.
+ * @param cfg initialized domain
+ * @param srv_defaults server defaults
+ * @param cli_defaults command line interface defaults
+ * @return 0 on success, -1 on error
  */
 int tls_fix_domains_cfg(tls_domains_cfg_t* cfg, tls_domain_t* srv_defaults,
 				tls_domain_t* cli_defaults)
@@ -958,8 +1028,11 @@ int tls_fix_domains_cfg(tls_domains_cfg_t* cfg, tls_domain_t* srv_defaults,
 }
 
 
-/*
- * Create new configuration structure
+/**
+ * @brief Create new configuration structure
+ * 
+ * Create new configuration structure in new allocated shared memory
+ * @return configuration structure or zero on error
  */
 tls_domains_cfg_t* tls_new_cfg(void)
 {
@@ -975,8 +1048,13 @@ tls_domains_cfg_t* tls_new_cfg(void)
 }
 
 
-/*
- * Lookup TLS configuration based on type, ip, and port
+/**
+ * @brief Lookup TLS configuration based on type, ip, and port
+ * @param cfg configuration set
+ * @param type type of configuration
+ * @param ip IP for configuration
+ * @param port port for configuration
+ * @return found configuration or default, if not found
  */
 tls_domain_t* tls_lookup_cfg(tls_domains_cfg_t* cfg, int type,
 								struct ip_addr* ip, unsigned short port)
@@ -1003,8 +1081,11 @@ tls_domain_t* tls_lookup_cfg(tls_domains_cfg_t* cfg, int type,
 }
 
 
-/*
- * Check whether configuration domain exists
+/**
+ * @brief Check whether configuration domain exists
+ * @param cfg configuration set
+ * @param d checked domain
+ * @return 1 if domain exists, 0 if its not exists
  */
 static int domain_exists(tls_domains_cfg_t* cfg, tls_domain_t* d)
 {
@@ -1028,8 +1109,11 @@ static int domain_exists(tls_domains_cfg_t* cfg, tls_domain_t* d)
 }
 
 
-/*
- * Add a domain to the configuration set
+/**
+ * @brief Add a domain to the configuration set
+ * @param cfg configuration set
+ * @param d TLS domain
+ * @return 1 if domain already exists, 0 after addition, -1 on error
  */
 int tls_add_domain(tls_domains_cfg_t* cfg, tls_domain_t* d)
 {

modules/tls/tls_domain.h

@@ -1,8 +1,4 @@
 /*
- * $Id$
- *
- * TLS module - virtual configuration domain support
- * 
  * Copyright (C) 2001-2003 FhG FOKUS
  * Copyright (C) 2005,2006 iptelorg GmbH
  *
@@ -18,8 +14,10 @@
  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
-/** SIP-router TLS support :: virtual configuration domain support.
- * @file tls_domain.h
+
+/**
+ * SIP-router TLS support :: virtual domain configuration support
+ * @file
  * @ingroup tls
  * Module: @ref tls
  */
@@ -33,7 +31,7 @@
 #include <openssl/ssl.h>
 
 
-/*
+/**
  * Available TLS methods
  */
 enum tls_method {
@@ -54,17 +52,17 @@ enum tls_method {
 };
 
 
-/*
+/**
  * TLS configuration domain type
  */
 enum tls_domain_type {
-	TLS_DOMAIN_DEF = (1 << 0), /* Default domain */
-	TLS_DOMAIN_SRV = (1 << 1), /* Server domain */
-	TLS_DOMAIN_CLI = (1 << 2)  /* Client domain */
+	TLS_DOMAIN_DEF = (1 << 0), /**< Default domain */
+	TLS_DOMAIN_SRV = (1 << 1), /**< Server domain */
+	TLS_DOMAIN_CLI = (1 << 2)  /**< Client domain */
 };
 
 
-/*
+/**
  * separate configuration per ip:port
  */
 typedef struct tls_domain {
@@ -85,72 +83,101 @@ typedef struct tls_domain {
 } tls_domain_t;
 
 
-/*
+/**
  * TLS configuration structures
  */
 typedef struct tls_domains_cfg {
-	tls_domain_t* srv_default; /* Default server domain */
-	tls_domain_t* cli_default; /* Default client domain */
-	tls_domain_t* srv_list;    /* Server domain list */
-	tls_domain_t* cli_list;    /* Client domain list */
-	struct tls_domains_cfg* next; /* Next element in the garbage list */
-	int ref_count;             /* How many connections use this configuration */
+	tls_domain_t* srv_default; /**< Default server domain */
+	tls_domain_t* cli_default; /**< Default client domain */
+	tls_domain_t* srv_list;    /**< Server domain list */
+	tls_domain_t* cli_list;    /**< Client domain list */
+	struct tls_domains_cfg* next; /**< Next element in the garbage list */
+	int ref_count;             /**< How many connections use this configuration */
 } tls_domains_cfg_t;
 
 
-/*
- * create a new domain 
+/**
+ * @brief Create a new TLS domain structure
+ * 
+ * Create a new domain structure in new allocated shared memory.
+ * @param type domain Type
+ * @param ip domain IP
+ * @param port domain port
+ * @return new domain
  */
 tls_domain_t *tls_new_domain(int type, struct ip_addr *ip, 
 			     unsigned short port);
 
 
-/*
- * Free all memory used for configuration domain
+/**
+ * @brief Free all memory used by TLS configuration domain
+ * @param d freed domain
  */
 void tls_free_domain(tls_domain_t* d);
 
 
-/*
- * Generate tls domain string identifier
+/**
+ * @brief Generate TLS domain identifier
+ * @param d printed domain
+ * @return printed domain, with zero termination
  */
 char* tls_domain_str(tls_domain_t* d);
 
 
 
-/*
- * Create new instance of TLS configuration data
+/**
+ * @brief Create new TLS configuration structure
+ * 
+ * Create new configuration structure in new allocated shared memory.
+ * @return configuration structure or zero on error
  */
 tls_domains_cfg_t* tls_new_cfg(void);
 
 
-/*
- * Add a new configuration domain
+/**
+ * @brief Add a domain to the configuration set
+ * @param cfg configuration set
+ * @param d TLS domain
+ * @return 1 if domain already exists, 0 after addition, -1 on error
  */
 int tls_add_domain(tls_domains_cfg_t* cfg, tls_domain_t* d);
 
 
-/*
- * Fill in missing parameters
+/**
+ * @brief Initialize attributes of all domains from default domains if necessary
+ * 
+ * Initialize attributes of all domains from default domains if necessary,
+ * fill in missing parameters.
+ * @param cfg initialized domain
+ * @param srv_defaults server defaults
+ * @param cli_defaults command line interface defaults
+ * @return 0 on success, -1 on error
  */
 int tls_fix_domains_cfg(tls_domains_cfg_t* cfg, tls_domain_t* srv_defaults,
 				tls_domain_t* cli_defaults);
 
 
-/*
- * Lookup TLS configuration
+/**
+ * @brief Lookup TLS configuration based on type, ip, and port
+ * @param cfg configuration set
+ * @param type type of configuration
+ * @param ip IP for configuration
+ * @param port port for configuration
+ * @return found configuration or default, if not found
  */
 tls_domain_t* tls_lookup_cfg(tls_domains_cfg_t* cfg, int type,
 								struct ip_addr* ip, unsigned short port);
 
 
-/*
- * Free TLS configuration data
+/**
+ * @brief Free TLS configuration structure
+ * @param cfg freed configuration
  */
 void tls_free_cfg(tls_domains_cfg_t* cfg);
 
-/*
- * Destroy all the config data
+
+/**
+ * @brief Destroy all TLS configuration data
  */
 void tls_destroy_cfg(void);