Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Refactored Doxygen for tls_multi functions

  • Loading branch information...
commit be3d6f97f7596c91fae5e656854dbfed6de80ec6 1 parent 360ff29
andj authored June 30, 2011

Showing 2 changed files with 98 additions and 68 deletions. Show diff stats Hide diff stats

  1. 54  ssl.c
  2. 112  ssl.h
54  ssl.c
@@ -2074,27 +2074,6 @@ lame_duck_must_die (const struct tls_session* session, interval_t *wakeup)
2074 2074
     return false;
2075 2075
 }
2076 2076
 
2077  
-
2078  
-/** @addtogroup control_processor
2079  
- *  @{ */
2080  
-
2081  
-/** @name Functions for initialization and cleanup of tls_multi structures
2082  
- *  @{ */
2083  
-
2084  
-/**
2085  
- * Allocate and initialize a \c tls_multi structure.
2086  
- * @ingroup control_processor
2087  
- * 
2088  
- * This function allocates a new \c tls_multi structure, and performs some
2089  
- * amount of initialization.  Afterwards, the \c tls_multi_init_finalize()
2090  
- * function must be called to finalize the structure's initialization
2091  
- * process.
2092  
- * 
2093  
- * @param tls_options  - The configuration options to be used for this VPN
2094  
- *                       tunnel.
2095  
- * 
2096  
- * @return A newly allocated and initialized \c tls_multi structure.
2097  
- */
2098 2077
 struct tls_multi *
2099 2078
 tls_multi_init (struct tls_options *tls_options)
2100 2079
 {
@@ -2117,21 +2096,6 @@ tls_multi_init (struct tls_options *tls_options)
2117 2096
   return ret;
2118 2097
 }
2119 2098
 
2120  
-
2121  
-/**
2122  
- * Finalize initialization of a \c tls_multi structure.
2123  
- * @ingroup control_processor
2124  
- * 
2125  
- * This function initializes the \c TM_ACTIVE \c tls_session, and in
2126  
- * server mode also the \c TM_UNTRUSTED \c tls_session, associated with
2127  
- * this \c tls_multi structure.  It also configures the control channel's
2128  
- * \c frame structure based on the data channel's \c frame given in
2129  
- * argument \a frame.
2130  
- * 
2131  
- * @param multi        - The \c tls_multi structure of which to finalize
2132  
- *                       initialization.
2133  
- * @param frame        - The data channel's \c frame structure.
2134  
- */
2135 2099
 void
2136 2100
 tls_multi_init_finalize (struct tls_multi* multi, const struct frame* frame)
2137 2101
 {
@@ -2192,18 +2156,8 @@ tls_multi_init_set_options (struct tls_multi* multi,
2192 2156
 #endif
2193 2157
 }
2194 2158
 
2195  
-
2196  
-/**
2197  
- * Cleanup a \c tls_multi structure and free associated memory
2198  
- * allocations.
2199  
- * @ingroup control_processor
2200  
- * 
2201  
- * This function cleans up a \c tls_multi structure.  This includes
2202  
- * cleaning up all associated \c tls_session structures.
2203  
- * 
2204  
- * @param multi        - The \c tls_multi structure to clean up in free.
2205  
- * @param clear        - Whether the memory allocated for the \a multi
2206  
- *                       object should be overwritten with 0s.
  2159
+/*
  2160
+ * Cleanup a tls_multi structure and free associated memory allocations.
2207 2161
  */
2208 2162
 void
2209 2163
 tls_multi_free (struct tls_multi *multi, bool clear)
@@ -2235,10 +2189,6 @@ tls_multi_free (struct tls_multi *multi, bool clear)
2235 2189
   free(multi);
2236 2190
 }
2237 2191
 
2238  
-/** @} name Functions for initialization and cleanup of tls_multi structures */
2239  
-
2240  
-/** @} addtogroup control_processor */
2241  
-
2242 2192
 
2243 2193
 /*
2244 2194
  * Move a packet authentication HMAC + related fields to or from the front
112  ssl.h
@@ -177,8 +177,11 @@
177 177
 #define TLS_MULTI_HORIZON 2     /* call tls_multi_process frequently for n seconds after
178 178
 				   every packet sent/received action */
179 179
 
180  
-/* The SSL/TLS worker thread will wait at most this many seconds for the interprocess
181  
-   communication pipe to the main thread to be ready to accept writes. */
  180
+/*
  181
+ * The SSL/TLS worker thread will wait at most this many seconds for the
  182
+ * interprocess communication pipe to the main thread to be ready to accept
  183
+ * writes.
  184
+ */
182 185
 #define TLS_MULTI_THREAD_SEND_TIMEOUT 5
183 186
 
184 187
 /* Interval that tls_multi_process should call tls_authentication_status */
@@ -229,15 +232,6 @@ struct cert_hash {
229 232
 struct cert_hash_set {
230 233
   struct cert_hash *ch[MAX_CERT_DEPTH];
231 234
 };
232  
-/*
233  
- * Prepare the SSL library for use
234  
- */
235  
-void init_ssl_lib (void);
236  
-
237  
-/*
238  
- * Free any internal state that the SSL library might have
239  
- */
240  
-void free_ssl_lib (void);
241 235
 
242 236
 #ifdef ENABLE_X509_TRACK
243 237
 
@@ -362,6 +356,8 @@ struct tls_session
362 356
  */
363 357
 #define KEY_SCAN_SIZE 3
364 358
 
  359
+/** @name Functions for initialization and cleanup of tls_multi structures
  360
+ *  @{ */
365 361
 
366 362
 /**
367 363
  * Security parameter state for a single VPN tunnel.
@@ -450,7 +446,14 @@ struct tls_auth_standalone
450 446
   struct frame frame;
451 447
 };
452 448
 
  449
+/*
  450
+ * Prepare the SSL library for use
  451
+ */
453 452
 void init_ssl_lib (void);
  453
+
  454
+/*
  455
+ * Free any internal state that the SSL library might have
  456
+ */
454 457
 void free_ssl_lib (void);
455 458
 
456 459
 /**
@@ -459,32 +462,100 @@ void free_ssl_lib (void);
459 462
  */
460 463
 void init_ssl (const struct options *options, struct tls_root_ctx *ctx);
461 464
 
  465
+/** @addtogroup control_processor
  466
+ *  @{ */
  467
+
  468
+/** @name Functions for initialization and cleanup of tls_multi structures
  469
+ *  @{ */
  470
+
  471
+/**
  472
+ * Allocate and initialize a \c tls_multi structure.
  473
+ * @ingroup control_processor
  474
+ *
  475
+ * This function allocates a new \c tls_multi structure, and performs some
  476
+ * amount of initialization.  Afterwards, the \c tls_multi_init_finalize()
  477
+ * function must be called to finalize the structure's initialization
  478
+ * process.
  479
+ *
  480
+ * @param tls_options  - The configuration options to be used for this VPN
  481
+ *                       tunnel.
  482
+ *
  483
+ * @return A newly allocated and initialized \c tls_multi structure.
  484
+ */
462 485
 struct tls_multi *tls_multi_init (struct tls_options *tls_options);
463 486
 
  487
+/**
  488
+ * Finalize initialization of a \c tls_multi structure.
  489
+ * @ingroup control_processor
  490
+ *
  491
+ * This function initializes the \c TM_ACTIVE \c tls_session, and in
  492
+ * server mode also the \c TM_UNTRUSTED \c tls_session, associated with
  493
+ * this \c tls_multi structure.  It also configures the control channel's
  494
+ * \c frame structure based on the data channel's \c frame given in
  495
+ * argument \a frame.
  496
+ *
  497
+ * @param multi        - The \c tls_multi structure of which to finalize
  498
+ *                       initialization.
  499
+ * @param frame        - The data channel's \c frame structure.
  500
+ */
  501
+void tls_multi_init_finalize(struct tls_multi *multi,
  502
+			     const struct frame *frame);
  503
+
  504
+/*
  505
+ * Initialize a standalone tls-auth verification object.
  506
+ */
464 507
 struct tls_auth_standalone *tls_auth_standalone_init (struct tls_options *tls_options,
465 508
 						      struct gc_arena *gc);
466 509
 
  510
+/*
  511
+ * Finalize a standalone tls-auth verification object.
  512
+ */
467 513
 void tls_auth_standalone_finalize (struct tls_auth_standalone *tas,
468 514
 				   const struct frame *frame);
469 515
 
470  
-void tls_multi_init_finalize(struct tls_multi *multi,
471  
-			     const struct frame *frame);
472  
-
  516
+/*
  517
+ * Set local and remote option compatibility strings.
  518
+ * Used to verify compatibility of local and remote option
  519
+ * sets.
  520
+ */
473 521
 void tls_multi_init_set_options(struct tls_multi* multi,
474 522
 				const char *local,
475 523
 				const char *remote);
476 524
 
  525
+/**
  526
+ * Cleanup a \c tls_multi structure and free associated memory
  527
+ * allocations.
  528
+ * @ingroup control_processor
  529
+ *
  530
+ * This function cleans up a \c tls_multi structure.  This includes
  531
+ * cleaning up all associated \c tls_session structures.
  532
+ *
  533
+ * @param multi        - The \c tls_multi structure to clean up in free.
  534
+ * @param clear        - Whether the memory allocated for the \a multi
  535
+ *                       object should be overwritten with 0s.
  536
+ */
  537
+void tls_multi_free (struct tls_multi *multi, bool clear);
  538
+
  539
+/** @} name Functions for initialization and cleanup of tls_multi structures */
  540
+
  541
+/** @} addtogroup control_processor */
  542
+
477 543
 #define TLSMP_INACTIVE 0
478 544
 #define TLSMP_ACTIVE   1
479 545
 #define TLSMP_KILL     2
  546
+
  547
+/*
  548
+ * Called by the top-level event loop.
  549
+ *
  550
+ * Basically decides if we should call tls_process for
  551
+ * the active or untrusted sessions.
  552
+ */
480 553
 int tls_multi_process (struct tls_multi *multi,
481 554
 		       struct buffer *to_link,
482 555
 		       struct link_socket_actual **to_link_addr,
483 556
 		       struct link_socket_info *to_link_socket_info,
484 557
 		       interval_t *wakeup);
485 558
 
486  
-void tls_multi_free (struct tls_multi *multi, bool clear);
487  
-
488 559
 
489 560
 /**************************************************************************/
490 561
 /**
@@ -634,12 +705,21 @@ void tls_set_verify_command (const char *cmd);
634 705
 void tls_set_crl_verify (const char *crl);
635 706
 void tls_set_verify_x509name (const char *x509name);
636 707
 
  708
+/*
  709
+ * Reserve any extra space required on frames.
  710
+ */
637 711
 void tls_adjust_frame_parameters(struct frame *frame);
638 712
 
  713
+/*
  714
+ * Send a payload over the TLS control channel
  715
+ */
639 716
 bool tls_send_payload (struct tls_multi *multi,
640 717
 		       const uint8_t *data,
641 718
 		       int size);
642 719
 
  720
+/*
  721
+ * Receive a payload through the TLS control channel
  722
+ */
643 723
 bool tls_rec_payload (struct tls_multi *multi,
644 724
 		      struct buffer *buf);
645 725
 

1 note on commit be3d6f9

Please sign in to comment.
Something went wrong with that request. Please try again.