[tor-commits] [tor/release-0.2.9] Improve comments in check_private_dir and onion poisoning

[nickm at torproject.org]

commit 2f48693663c3703e1015fd438fc585cd2857ba71
Author: teor <teor2345 at gmail.com>
Date:   Wed Nov 2 14:11:26 2016 +1100

    Improve comments in check_private_dir and onion poisoning
    
    Comment changes only
---
 src/common/util.c    | 12 +++++++-----
 src/or/rendservice.c |  8 ++++++--
 2 files changed, 13 insertions(+), 7 deletions(-)

diff --git a/src/common/util.c b/src/common/util.c
index 9162967..a7bce2e 100644
--- a/src/common/util.c
+++ b/src/common/util.c
@@ -2191,11 +2191,13 @@ file_status(const char *fname)
   }
 }
 
-/** Check whether <b>dirname</b> exists and is private.  If yes return 0.  If
- * it does not exist, and <b>check</b>&CPD_CREATE is set, try to create it
- * and return 0 on success. If it does not exist, and
- * <b>check</b>&CPD_CHECK, and we think we can create it, return 0.  Else
- * return -1.  If CPD_GROUP_OK is set, then it's okay if the directory
+/** Check whether <b>dirname</b> exists and is private.  If yes return 0.
+ * If <b>dirname</b> does not exist:
+ *  - if <b>check</b>&CPD_CREATE, try to create it and return 0 on success.
+ *  - if <b>check</b>&CPD_CHECK, and we think we can create it, return 0.
+ *  - if <b>check</b>&CPD_CHECK is false, and the directory exists, return 0.
+ *  - otherwise, return -1.
+ * If CPD_GROUP_OK is set, then it's okay if the directory
  * is group-readable, but in all cases we create the directory mode 0700.
  * If CPD_GROUP_READ is set, existing directory behaves as CPD_GROUP_OK and
  * if the directory is created it will use mode 0750 with group read
diff --git a/src/or/rendservice.c b/src/or/rendservice.c
index 6743d82..7dbcf71 100644
--- a/src/or/rendservice.c
+++ b/src/or/rendservice.c
@@ -998,7 +998,9 @@ service_is_single_onion_poisoned(const rend_service_t *service)
   fstatus = file_status(poison_fname);
   tor_free(poison_fname);
 
-  /* If this fname is occupied, the hidden service has been poisoned. */
+  /* If this fname is occupied, the hidden service has been poisoned.
+   * fstatus can be FN_ERROR if the service directory does not exist, in that
+   * case, there is obviously no private key. */
   if (fstatus == FN_FILE || fstatus == FN_EMPTY) {
     return 1;
   }
@@ -1014,7 +1016,9 @@ rend_service_private_key_exists(const rend_service_t *service)
   char *private_key_path = rend_service_path(service, private_key_fname);
   const file_status_t private_key_status = file_status(private_key_path);
   tor_free(private_key_path);
-  /* Only non-empty regular private key files could have been used before. */
+  /* Only non-empty regular private key files could have been used before.
+   * fstatus can be FN_ERROR if the service directory does not exist, in that
+   * case, there is obviously no private key. */
   return private_key_status == FN_FILE;
 }