[tor-commits] [tor/master] Add missing documentation for counter-mode checks

[nickm at torproject.org]

commit dca3c9fff87227b8119afe804ce0ae8ed840b1f8
Author: Nick Mathewson <nickm at torproject.org>
Date:   Tue Jan 10 11:13:45 2012 -0500

    Add missing documentation for counter-mode checks
---
 src/common/aes.c |   17 ++++++++++++-----
 1 files changed, 12 insertions(+), 5 deletions(-)

diff --git a/src/common/aes.c b/src/common/aes.c
index 3c315dc..da7220f 100644
--- a/src/common/aes.c
+++ b/src/common/aes.c
@@ -47,8 +47,8 @@
  * OpenSSL pre-1.0 (by about 10%!).  But OpenSSL 1.0.0 added a counter mode
  * implementation faster than the one here (by about 7%).  So we pick which
  * one to used based on the Openssl version above.  (OpenSSL 1.0.0a fixed a
- * critical bug in that counter mode implementation, so we actually require
- * that one.)
+ * critical bug in that counter mode implementation, so we need to test to
+ * make sure that we have a fixed version.)
  */
 
 /*======================================================================*/
@@ -90,12 +90,13 @@ struct aes_cnt_cipher {
   uint8_t using_evp;
 };
 
-/** True if we should prefer the EVP implementation for AES, either because
+/** True iff we should prefer the EVP implementation for AES, either because
  * we're testing it or because we have hardware acceleration configured */
 static int should_use_EVP = 0;
 
 #ifdef CAN_USE_OPENSSL_CTR
-/**DOCDOC*/
+/** True iff we have tested the counter-mode implementation and found that it
+ * doesn't have the counter-mode bug from OpenSSL 1.0.0. */
 static int should_use_openssl_CTR = 0;
 #endif
 
@@ -129,7 +130,13 @@ evaluate_evp_for_aes(int force_val)
   return 0;
 }
 
-/**DOCDOC*/
+/** Test the OpenSSL counter mode implementation to see whether it has the
+ * counter-mode bug from OpenSSL 1.0.0. If the implementation works, then
+ * we will use it for future encryption/decryption operations.
+ *
+ * We can't just look at the OpenSSL version, since some distributions update
+ * their OpenSSL packages without changing the version number.
+ **/
 int
 evaluate_ctr_for_aes(void)
 {