From 80a7c5fe311c13c34411440a98d6d0398c7d3fe6 Mon Sep 17 00:00:00 2001
From: Matthias Wachs <wachs@net.in.tum.de>
Date: Thu, 28 Mar 2013 13:26:19 +0000
Subject: [PATCH] docu

---
 .../gnunet-service-transport_blacklist.c      | 34 +++++++++++++++++--
 src/transport/test_transport_blacklisting.c   | 10 +++---
 2 files changed, 37 insertions(+), 7 deletions(-)

diff --git a/src/transport/gnunet-service-transport_blacklist.c b/src/transport/gnunet-service-transport_blacklist.c
index b1a0047f7..8599f6f24 100644
--- a/src/transport/gnunet-service-transport_blacklist.c
+++ b/src/transport/gnunet-service-transport_blacklist.c
@@ -21,7 +21,38 @@
 /**
  * @file transport/gnunet-service-transport_blacklist.c
  * @brief blacklisting implementation
- * @author Christian Grothoff
+ * @author Christian Grothoff, Matthias Wachs
+ * @details This is the blacklisting component of transport service. With
+ * blacklisting it is possible to deny connections to specific peers of
+ * to use a specific plugin to a specific peer. Peers can be blacklisted using
+ * the configuration or a blacklist client can be asked.
+ *
+ * To blacklist peers using the configuration you have to add a section to your
+ * configuration containing the peer id of the peer to blacklist and the plugin
+ * if required.
+ *
+ * Example:
+ * To blacklist connections to P565... on peer AG2P... using tcp add:
+ * [transport-blacklist-AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520]
+ * P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G = tcp
+ *
+ * To blacklist connections to P565... on peer AG2P... using all plugins add:
+ * [transport-blacklist-AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520]
+ * P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G =
+ *
+ * You can also add a blacklist client usign the blacklist api. On a blacklist
+ * check, blacklisting first checks internally if the peer is blacklisted and
+ * if not, it asks the blacklisting clients. Clients are asked if it is OK to
+ * connect to a peer ID, the plugin is omitted.
+ *
+ * On blacklist check for (peer, plugin)
+ * - Do we have a local blacklist entry for this peer and this plugin?
+ *   - YES: disallow connection
+ * - Do we have a local blacklist entry for this peer and all plugins?
+ *   - YES: disallow connection
+ * - Does one of the clients disallow?
+ *   - YES: disallow connection
+ *
  */
 #include "platform.h"
 #include "gnunet-service-transport.h"
@@ -29,7 +60,6 @@
 #include "gnunet-service-transport_neighbours.h"
 #include "transport.h"
 
-
 /**
  * Size of the blacklist hash map.
  */
diff --git a/src/transport/test_transport_blacklisting.c b/src/transport/test_transport_blacklisting.c
index b75da26d1..f0f5a2b63 100644
--- a/src/transport/test_transport_blacklisting.c
+++ b/src/transport/test_transport_blacklisting.c
@@ -158,7 +158,7 @@ testing_connect_cb (struct PeerContext *p1, struct PeerContext *p2, void *cls)
 static void
 connect_timeout (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc)
 {
-  GNUNET_log (GNUNET_ERROR_TYPE_ERROR, "Peers not connected, next stage\n");
+  GNUNET_log (GNUNET_ERROR_TYPE_INFO, "Peers not connected, next stage\n");
 	timeout_task = GNUNET_SCHEDULER_NO_TASK;
   stage_task = GNUNET_SCHEDULER_add_now (&run_stage, NULL);
 }
@@ -178,7 +178,7 @@ start_cb (struct PeerContext *p, void *cls)
 
   char *sender_c = GNUNET_strdup (GNUNET_i2s (&p1->id));
 
-  GNUNET_log (GNUNET_ERROR_TYPE_ERROR,
+  GNUNET_log (GNUNET_ERROR_TYPE_DEBUG,
               "Test tries to connect peer %u (`%s') -> peer %u (`%s')\n",
               p1->no, sender_c, p2->no, GNUNET_i2s (&p2->id));
   GNUNET_free (sender_c);
@@ -195,7 +195,7 @@ run_stage (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc)
 	if (GNUNET_SCHEDULER_NO_TASK != die_task)
 		GNUNET_SCHEDULER_cancel (die_task);
   die_task = GNUNET_SCHEDULER_add_delayed (TIMEOUT, &end_badly, NULL);
-  GNUNET_log (GNUNET_ERROR_TYPE_ERROR, "Running stage %u\n", stage);
+  GNUNET_log (GNUNET_ERROR_TYPE_INFO, "Running stage %u\n", stage);
 
 	if (0 == stage)
 	{
@@ -282,7 +282,7 @@ run_stage (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc)
     p2 = NULL;
   }
 
-  GNUNET_log (GNUNET_ERROR_TYPE_ERROR, "Done in stage %u: Peers %s and %s!\n", stage,
+  GNUNET_log (GNUNET_ERROR_TYPE_INFO, "Done in stage %u: Peers %s and %s!\n", stage,
   		(GNUNET_NO == started) ? "NOT STARTED" : "STARTED",
   		(GNUNET_YES == connected) ? "CONNECTED" : "NOT CONNECTED");
 
@@ -315,7 +315,7 @@ run (void *cls, char *const *args, const char *cfgfile,
 {
   connected = GNUNET_NO;
   stage = 0;
-  GNUNET_log (GNUNET_ERROR_TYPE_ERROR, "Running test `%s'!\n", test_name);
+  GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, "Running test `%s'!\n", test_name);
   stage_task = GNUNET_SCHEDULER_add_now (&run_stage, NULL);
 }
 
-- 
2.25.1