(no commit message)

[oweals/gnunet.git] / src / transport / plugin_transport.h

diff --git a/src/transport/plugin_transport.h b/src/transport/plugin_transport.h
index 2b7017036798773ada9e9062e380305cdb33092e..d3dc52f3249954e885c81ccbe94117ac830091d6 100644 (file)
--- a/src/transport/plugin_transport.h
+++ b/src/transport/plugin_transport.h
@@ -4,7 +4,7 @@
 
      GNUnet is free software; you can redistribute it and/or modify
      it under the terms of the GNU General Public License as published
-     by the Free Software Foundation; either version 2, or (at your
+     by the Free Software Foundation; either version 3, or (at your
      option) any later version.
 
      GNUnet is distributed in the hope that it will be useful, but
@@ -47,6 +47,24 @@
  */
 struct Session;
 
+/**
+ * Every 'struct Session' must begin with this header.
+ */
+struct SessionHeader
+{
+
+  /**
+   * Cached signature for PONG generation for the session.  Do not use
+   * in the plugin!
+   */
+  struct GNUNET_CRYPTO_RsaSignature pong_signature;
+
+  /**
+   * Expiration time for signature.  Do not use in the plugin!
+   */
+  struct GNUNET_TIME_Absolute pong_sig_expires;
+  
+};
 
 /**
  * Function that will be called whenever the plugin internally
@@ -74,8 +92,14 @@ typedef void (*GNUNET_TRANSPORT_SessionEnd) (void *cls,
  * @param message the message, NULL if we only care about
  *                learning about the delay until we should receive again -- FIXME!
  * @param distance in overlay hops; use 1 unless DV (or 0 if message == NULL)
- * @param session identifier used for this session (can be NULL)
- * @param sender_address binary address of the sender (if observed)
+ * @param session identifier used for this session (NULL for plugins
+ *                that do not offer bi-directional communication to the sender
+ *                using the same "connection")
+ * @param sender_address binary address of the sender (if we established the
+ *                connection or are otherwise sure of it; should be NULL
+ *                for inbound TCP/UDP connections since it it not clear
+ *                that we could establish ourselves a connection to that
+ *                IP address and get the same system)
  * @param sender_address_len number of bytes in sender_address
  * @return how long the plugin should wait until receiving more data
  *         (plugins that do not support this, can ignore the return value)
@@ -90,7 +114,7 @@ typedef struct GNUNET_TIME_Relative (*GNUNET_TRANSPORT_PluginReceiveCallback) (v
                                                                               uint32_t distance,
                                                                               struct Session *session,
                                                                               const char *sender_address,
-                                                                              size_t sender_address_len);
+                                                                              uint16_t sender_address_len);
 
 
 /**
@@ -107,7 +131,7 @@ typedef struct GNUNET_TIME_Relative (*GNUNET_TRANSPORT_PluginReceiveCallback) (v
 typedef void (*GNUNET_TRANSPORT_AddressNotification) (void *cls,
                                                       const char *name,
                                                       const void *addr,
-                                                      size_t addrlen,
+                                                      uint16_t addrlen,
                                                       struct
                                                       GNUNET_TIME_Relative
                                                       expires);
@@ -335,16 +359,35 @@ typedef void
  * plugin.  Check that this could be a valid address.  This function
  * is not expected to 'validate' the address in the sense of trying to
  * connect to it but simply to see if the binary format is technically
- * legal for establishing a connection.
+ * legal for establishing a connection to this peer (and make sure that
+ * the address really corresponds to our network connection/settings
+ * and not some potential man-in-the-middle).
  *
- * @param addr pointer to the address, may be modified (slightly)
+ * @param addr pointer to the address
  * @param addrlen length of addr
  * @return GNUNET_OK if this is a plausible address for this peer
  *         and transport, GNUNET_SYSERR if not
  */
 typedef int
-  (*GNUNET_TRANSPORT_CheckAddress) (void *cls,
-                                   void *addr, size_t addrlen);
+(*GNUNET_TRANSPORT_CheckAddress) (void *cls,
+                                 const void *addr, size_t addrlen);
+
+
+/**
+ * Function called for a quick conversion of the binary address to
+ * a numeric address.  Note that the caller must not free the 
+ * address and that the next call to this function is allowed
+ * to override the address again.
+ *
+ * @param cls closure
+ * @param addr binary address
+ * @param addr_len length of the address
+ * @return string representing the same address 
+ */
+typedef const char* (*GNUNET_TRANSPORT_AddressToString) (void *cls,
+                                                        const void *addr,
+                                                        size_t addrlen);
+
 
 /**
  * Each plugin is required to return a pointer to a struct of this
@@ -385,11 +428,21 @@ struct GNUNET_TRANSPORT_PluginFunctions
 
   /**
    * Function that will be called to check if a binary address
-   * for this plugin is well-formed.  If clearly needed, patch
-   * up information such as port numbers.
+   * for this plugin is well-formed and corresponds to an
+   * address for THIS peer (as per our configuration).  Naturally,
+   * if absolutely necessary, plugins can be a bit conservative in
+   * their answer, but in general plugins should make sure that the
+   * address does not redirect traffic to a 3rd party that might
+   * try to man-in-the-middle our traffic.
    */
   GNUNET_TRANSPORT_CheckAddress check_address;
 
+  /**
+   * Function that will be called to convert a binary address
+   * to a string (numeric conversion only).
+   */
+  GNUNET_TRANSPORT_AddressToString address_to_string;
+
 };