Merge pull request #70 from RetroShare/master

update to master

libretroshare/src/libretroshare.pro

@@ -12,10 +12,6 @@ DESTDIR = lib
 
 !include("use_libretroshare.pri"):error("Including")
 
-# the dht stunner is used to obtain RS external ip addr. when it is natted
-# this system is unreliable and rs supports a newer and better one (asking connected peers)
-# CONFIG += useDhtStunner
-
 # treat warnings as error for better removing
 #QMAKE_CFLAGS += -Werror
 #QMAKE_CXXFLAGS += -Werror

libretroshare/src/pqi/p3netmgr.cc

@@ -711,47 +711,6 @@ void p3NetMgrIMPL::netExtCheck()
 			}
 		}
 
-#ifdef ALLOW_DHT_STUNNER
-        // (cyril) I disabled this because it's pretty dangerous. The DHT can report a wrong address quite easily
-        // if the other DHT peers are not collaborating.
-        
-		/* Next ask the DhtStunner */
-		{
-#if defined(NETMGR_DEBUG_TICK) || defined(NETMGR_DEBUG_RESET)
-			std::cerr << "p3NetMgrIMPL::netExtCheck() Ext Not Ok, Checking DhtStunner" << std::endl;
-#endif
-			uint8_t isstable = 0;
-			struct sockaddr_storage tmpaddr;
-			sockaddr_storage_clear(tmpaddr);
-
-			if (mDhtStunner)
-			{
-				/* input network bits */
-				if (mDhtStunner->getExternalAddr(tmpaddr, isstable))
-				{
-					if((rsBanList == NULL) || rsBanList->isAddressAccepted(tmpaddr,RSBANLIST_CHECKING_FLAGS_BLACKLIST))
-					{
-						// must be stable???
-						isStable = (isstable == 1);
-						//mNetFlags.mExtAddr = tmpaddr;
-						mNetFlags.mExtAddrOk = true;
-						mNetFlags.mExtAddrStableOk = isStable;
-
-						address_votes[tmpaddr].n++ ;
-#ifdef	NETMGR_DEBUG_STATEBOX
-						std::cerr << "p3NetMgrIMPL::netExtCheck() From DhtStunner: ";
-						std::cerr << sockaddr_storage_tostring(tmpaddr);
-						std::cerr << " Stable: " << (uint32_t) isstable;
-						std::cerr << std::endl;
-#endif
-					}
-					else
-						std::cerr << "(SS) DHTStunner returned wrong own IP " << sockaddr_storage_iptostring(tmpaddr) << " (banned). Rejecting." << std::endl;
-				}
-			}
-		}
-#endif
-
 		/* ask ExtAddrFinder */
 		{
 			/* ExtAddrFinder */
@@ -829,6 +788,49 @@ void p3NetMgrIMPL::netExtCheck()
 #endif
 		}
 
+#ifdef ALLOW_DHT_STUNNER
+		// (cyril) I disabled this because it's pretty dangerous. The DHT can report a wrong address quite easily
+		// if the other DHT peers are not collaborating.
+		// (sehraf) For the record: The udp stunner uses multiple (as for now: two) peers to ensure that the IP recieved is the correct one, see UdpStunner::locked_checkExternalAddress()
+		// Nevertheless this stays a more risky method to determine the external ip address.
+
+		/* lastly ask the DhtStunner as fallback */
+		if (address_votes.empty()) {
+#if defined(NETMGR_DEBUG_TICK) || defined(NETMGR_DEBUG_RESET)
+			std::cerr << "p3NetMgrIMPL::netExtCheck() Ext Not Ok, Checking DhtStunner" << std::endl;
+#endif
+			uint8_t isstable = 0;
+			struct sockaddr_storage tmpaddr;
+			sockaddr_storage_clear(tmpaddr);
+
+			if (mDhtStunner)
+			{
+				/* input network bits */
+				if (mDhtStunner->getExternalAddr(tmpaddr, isstable))
+				{
+					if((rsBanList == NULL) || rsBanList->isAddressAccepted(tmpaddr,RSBANLIST_CHECKING_FLAGS_BLACKLIST))
+					{
+						// must be stable???
+						isStable = (isstable == 1);
+						//mNetFlags.mExtAddr = tmpaddr;
+						mNetFlags.mExtAddrOk = true;
+						mNetFlags.mExtAddrStableOk = isStable;
+
+						address_votes[tmpaddr].n++ ;
+#ifdef	NETMGR_DEBUG_STATEBOX
+						std::cerr << "p3NetMgrIMPL::netExtCheck() From DhtStunner: ";
+						std::cerr << sockaddr_storage_tostring(tmpaddr);
+						std::cerr << " Stable: " << (uint32_t) isstable;
+						std::cerr << std::endl;
+#endif
+					}
+					else
+						std::cerr << "(SS) DHTStunner returned wrong own IP " << sockaddr_storage_iptostring(tmpaddr) << " (banned). Rejecting." << std::endl;
+				}
+			}
+		}
+#endif
+
 		/* any other sources ??? */
 
 		/* finalise address */

libretroshare/src/retroshare/rsposted.h

@@ -3,7 +3,8 @@
  *                                                                             *
  * libretroshare: retroshare core library                                      *
  *                                                                             *
- * Copyright 2008-2012 by Robert Fernie, Christopher Evi-Parker                *
+ * Copyright (C) 2008-2012  Robert Fernie, Christopher Evi-Parker              *
+ * Copyright (C) 2020  Gioacchino Mazzurco <gio@eigenlab.org>                  *
  *                                                                             *
  * This program is free software: you can redistribute it and/or modify        *
  * it under the terms of the GNU Lesser General Public License as              *
@@ -19,8 +20,7 @@
  * along with this program. If not, see <https://www.gnu.org/licenses/>.       *
  *                                                                             *
  *******************************************************************************/
-#ifndef RETROSHARE_GXS_RSPOSTED_GUI_INTERFACE_H
+#pragma once
-#define RETROSHARE_GXS_RSPOSTED_GUI_INTERFACE_H
 
 #include <inttypes.h>
 #include <string>
@@ -32,20 +32,62 @@
 #include "retroshare/rsgxscommon.h"
 #include "serialiser/rsserializable.h"
 
-/* The Main Interface Class - for information about your Posted */
 class RsPosted;
-extern RsPosted *rsPosted;
 
-class RsPostedPost;
+/**
-class RsPostedGroup
+ * Pointer to global instance of RsGxsChannels service implementation
+ * @jsonapi{development}
+ */
+extern RsPosted* rsPosted;
+
+struct RsPostedGroup
 {
-	public:
-	RsPostedGroup() { return; }
-
 	RsGroupMetaData mMeta;
 	std::string mDescription;
 	RsGxsImage mGroupImage;
+};
 
+struct RsPostedPost
+{
+	RsPostedPost(): mHaveVoted(false), mUpVotes(0), mDownVotes(0), mComments(0),
+	    mHotScore(0), mTopScore(0), mNewScore(0) {}
+
+	bool calculateScores(rstime_t ref_time);
+
+	RsMsgMetaData mMeta;
+	std::string mLink;
+	std::string mNotes;
+
+	bool     mHaveVoted;
+
+	// Calculated.
+	uint32_t mUpVotes;
+	uint32_t mDownVotes;
+	uint32_t mComments;
+
+
+	// and Calculated Scores:???
+	double  mHotScore;
+	double  mTopScore;
+	double  mNewScore;
+
+	RsGxsImage mImage;
+
+	/// @see RsSerializable
+	/*virtual void serial_process( RsGenericSerializer::SerializeJob j,
+								 RsGenericSerializer::SerializeContext& ctx )
+	{
+		RS_SERIAL_PROCESS(mImage);
+		RS_SERIAL_PROCESS(mMeta);
+		RS_SERIAL_PROCESS(mLink);
+		RS_SERIAL_PROCESS(mHaveVoted);
+		RS_SERIAL_PROCESS(mUpVotes);
+		RS_SERIAL_PROCESS(mDownVotes);
+		RS_SERIAL_PROCESS(mComments);
+		RS_SERIAL_PROCESS(mHotScore);
+		RS_SERIAL_PROCESS(mTopScore);
+		RS_SERIAL_PROCESS(mNewScore);
+	}*/
 };
 
 
@@ -65,9 +107,6 @@ class RsPostedGroup
 #define RSPOSTED_VIEWMODE_COMMENTS	4
 
 
-std::ostream &operator<<(std::ostream &out, const RsPostedGroup &group);
-std::ostream &operator<<(std::ostream &out, const RsPostedPost &post);
-
 enum class RsPostedEventCode: uint8_t
 {
 	UNKNOWN                  = 0x00,
@@ -98,25 +137,41 @@ struct RsGxsPostedEvent: RsEvent
 		RS_SERIAL_PROCESS(mPostedGroupId);
 		RS_SERIAL_PROCESS(mPostedMsgId);
 	}
+
+	~RsGxsPostedEvent() override;
 };
 
 class RsPosted : public RsGxsIfaceHelper, public RsGxsCommentService
 {
-	    public:
+public:
-
-	enum RankType {TopRankType, HotRankType, NewRankType };
-
-	//static const uint32_t FLAG_MSGTYPE_POST;
-	//static const uint32_t FLAG_MSGTYPE_MASK;
-
 	explicit RsPosted(RsGxsIface& gxs) : RsGxsIfaceHelper(gxs) {}
-	virtual ~RsPosted() {}
 
-	    /* Specific Service Data */
+	virtual bool getBoardsInfo(
-virtual bool getGroupData(const uint32_t &token, std::vector<RsPostedGroup> &groups) = 0;
+	        const std::list<RsGxsGroupId>& boardsIds,
-virtual bool getPostData(const uint32_t &token, std::vector<RsPostedPost> &posts, std::vector<RsGxsComment> &cmts) = 0;
+	        std::vector<RsPostedGroup>& boardsInfo ) = 0;
-virtual bool getPostData(const uint32_t &token, std::vector<RsPostedPost> &posts) = 0;
+
-//Not currently used
+	virtual bool getBoardContent(
+	        const RsGxsGroupId& boardId,
+	        const std::set<RsGxsMessageId>& contentsIds,
+	        std::vector<RsPostedPost>& posts,
+	        std::vector<RsGxsComment>& comments ) = 0;
+
+	enum RS_DEPRECATED RankType {TopRankType, HotRankType, NewRankType };
+
+	RS_DEPRECATED_FOR(getBoardsInfo)
+	virtual bool getGroupData( const uint32_t& token,
+	                           std::vector<RsPostedGroup> &groups ) = 0;
+
+	RS_DEPRECATED_FOR(getBoardsContent)
+	virtual bool getPostData(
+	        const uint32_t& token, std::vector<RsPostedPost>& posts,
+	        std::vector<RsGxsComment>& cmts) = 0;
+
+	RS_DEPRECATED_FOR(getBoardsContent)
+	virtual bool getPostData(
+	        const uint32_t& token, std::vector<RsPostedPost>& posts) = 0;
+
+	//Not currently used
 //virtual bool getRelatedPosts(const uint32_t &token, std::vector<RsPostedPost> &posts) = 0;
 
 	    /* From RsGxsCommentService */
@@ -134,62 +189,6 @@ virtual bool createPost(uint32_t &token, RsPostedPost &post) = 0;
 virtual bool updateGroup(uint32_t &token, RsPostedGroup &group) = 0;
 
     virtual bool groupShareKeys(const RsGxsGroupId& group,const std::set<RsPeerId>& peers) = 0 ;
+
+	virtual ~RsPosted();
 };
-
-
-class RsPostedPost
-{
-	public:
-	RsPostedPost()
-	{
-		//mMeta.mMsgFlags = RsPosted::FLAG_MSGTYPE_POST;
-		mUpVotes = 0;
-		mDownVotes = 0;
-		mComments = 0;
-		mHaveVoted = false;
-
-        mHotScore = 0;
-        mTopScore = 0;
-        mNewScore = 0;
-	}
-
-	bool calculateScores(rstime_t ref_time);
-
-	RsMsgMetaData mMeta;
-	std::string mLink;
-	std::string mNotes;
-
-	bool     mHaveVoted;
-
-	// Calculated.
-	uint32_t mUpVotes;
-	uint32_t mDownVotes;
-	uint32_t mComments;
-
-
-	// and Calculated Scores:???
-	double  mHotScore;
-	double  mTopScore;
-	double  mNewScore;
-	
-	RsGxsImage mImage;
-
-	/// @see RsSerializable
-	/*virtual void serial_process( RsGenericSerializer::SerializeJob j,
-	                             RsGenericSerializer::SerializeContext& ctx )
-	{
-		RS_SERIAL_PROCESS(mImage);
-		RS_SERIAL_PROCESS(mMeta);
-		RS_SERIAL_PROCESS(mLink);
-		RS_SERIAL_PROCESS(mHaveVoted);
-		RS_SERIAL_PROCESS(mUpVotes);
-		RS_SERIAL_PROCESS(mDownVotes);
-		RS_SERIAL_PROCESS(mComments);
-		RS_SERIAL_PROCESS(mHotScore);
-		RS_SERIAL_PROCESS(mTopScore);
-		RS_SERIAL_PROCESS(mNewScore);
-	}*/
-};
-
-
-#endif // RETROSHARE_GXS_RSPOSTED_GUI_INTERFACE_H

libretroshare/src/services/p3posted.cc

@@ -30,7 +30,7 @@
  * #define POSTED_DEBUG 1
  ****/
 
-RsPosted *rsPosted = NULL;
+/*extern*/ RsPosted* rsPosted = nullptr;
 
 /********************************************************************************/
 /******************* Startup / Tick    ******************************************/
@@ -300,4 +300,35 @@ bool p3Posted::createPost(uint32_t &token, RsPostedPost &msg)
 	return true;
 }
 
-/********************************************************************************************/
+bool p3Posted::getBoardsInfo(
+        const std::list<RsGxsGroupId>& boardsIds,
+        std::vector<RsPostedGroup>& channelsInfo )
+{
+	uint32_t token;
+	RsTokReqOptions opts;
+	opts.mReqType = GXS_REQUEST_TYPE_GROUP_DATA;
+	if( !requestGroupInfo(token, opts, boardsIds)
+	        || waitToken(token) != RsTokenService::COMPLETE ) return false;
+	return getGroupData(token, channelsInfo) && !channelsInfo.empty();
+}
+
+bool p3Posted::getBoardContent( const RsGxsGroupId& channelId,
+                       const std::set<RsGxsMessageId>& contentsIds,
+                       std::vector<RsPostedPost>& posts,
+                       std::vector<RsGxsComment>& comments )
+{
+	uint32_t token;
+	RsTokReqOptions opts;
+	opts.mReqType = GXS_REQUEST_TYPE_MSG_DATA;
+
+	GxsMsgReq msgIds;
+	msgIds[channelId] = contentsIds;
+
+	if( !requestMsgInfo(token, opts, msgIds) ||
+	        waitToken(token) != RsTokenService::COMPLETE ) return false;
+
+	return getPostData(token, posts, comments);
+}
+
+RsPosted::~RsPosted() = default;
+RsGxsPostedEvent::~RsGxsPostedEvent() = default;

libretroshare/src/services/p3posted.h

@@ -39,12 +39,12 @@
 
 class p3Posted: public p3PostBase, public RsPosted
 {
-	public:
+public:
 
 	p3Posted(RsGeneralDataService* gds, RsNetworkExchangeService* nes, RsGixs* gixs);
-virtual RsServiceInfo getServiceInfo();
+	virtual RsServiceInfo getServiceInfo();
 
-	protected:
+protected:
 
 virtual void notifyChanges(std::vector<RsGxsNotify*>& changes)
 {
@@ -58,8 +58,17 @@ virtual void receiveHelperChanges(std::vector<RsGxsNotify*>& changes)
 	return RsGxsIfaceHelper::receiveChanges(changes);
 }
 
-	// Posted Specific DataTypes.
+	bool getBoardsInfo(
-virtual bool getGroupData(const uint32_t &token, std::vector<RsPostedGroup> &groups);
+	        const std::list<RsGxsGroupId>& boardsIds,
+	        std::vector<RsPostedGroup>& channelsInfo ) override;
+
+	bool getBoardContent(
+	            const RsGxsGroupId& boardId,
+	            const std::set<RsGxsMessageId>& contentsIds,
+	            std::vector<RsPostedPost>& posts,
+	            std::vector<RsGxsComment>& comments ) override;
+
+	virtual bool getGroupData(const uint32_t &token, std::vector<RsPostedGroup> &groups);
 virtual bool getPostData(const uint32_t &token, std::vector<RsPostedPost> &posts, std::vector<RsGxsComment> &cmts);
 virtual bool getPostData(const uint32_t &token, std::vector<RsPostedPost> &posts) {	std::vector<RsGxsComment> cmts; return getPostData( token, posts, cmts);}
 //Not currently used

libretroshare/src/tcponudp/udpstunner.cc

@@ -164,12 +164,12 @@ int	UdpStunner::grabExclusiveMode(std::string holder)  /* returns seconds since
 		commsage = 1;
 	}
 #ifdef DEBUG_UDP_STUNNER_FILTER
-#endif
 	std::cerr << "UdpStunner::grabExclusiveMode() SUCCESS. last comms: " << commsage;
 	std::cerr << " ago";
 	std::cerr << std::endl;
 	std::cerr << "UdpStunner::grabExclusiveMode() Exclusive held by: " << mExclusiveHolder;
 	std::cerr << std::endl;
+#endif
 
 	return commsage;
 }
@@ -181,13 +181,12 @@ int	UdpStunner::releaseExclusiveMode(std::string holder, bool forceStun)
 	if (!mExclusiveMode)
 	{
 #ifdef DEBUG_UDP_STUNNER_FILTER
-#endif
 		std::cerr << "UdpStunner::cancelExclusiveMode() ERROR, not in exclusive Mode";
 		std::cerr << std::endl;
+#endif
 		return 0;
 	}
 
-	rstime_t now = time(NULL);
 	mExclusiveMode = false;
 	if (forceStun)
 	{
@@ -217,10 +216,11 @@ int	UdpStunner::releaseExclusiveMode(std::string holder, bool forceStun)
 	}
 
 #ifdef DEBUG_UDP_STUNNER_FILTER
-#endif
+	rstime_t now = time(nullptr);
 	std::cerr << "UdpStunner::cancelExclusiveMode() Canceled. Was in ExclusiveMode for: " << now - mExclusiveModeTS;
 	std::cerr << " secs";
 	std::cerr << std::endl;
+#endif
 
 	return 1;
 }
@@ -326,7 +326,7 @@ bool UdpStunner::locked_handleStunPkt(void *data, int size, struct sockaddr_in &
 #endif
 		/* generate a response */
 		int len;
-		void *pkt = UdpStun_generate_stun_reply(&from, &len);
+		void *pkt = UdpStun_generate_stun_reply(&from, &len, data);
 		if (!pkt)
 			return false;
 
@@ -485,7 +485,7 @@ bool    UdpStun_response(void *stun_pkt, int size, struct sockaddr_in &addr)
 		return false;
 	}
 
-	if (htons(((uint16_t *) stun_pkt)[0]) != 0x0101)
+	if (htons(((uint16_t *) stun_pkt)[0]) != UdpStunner::STUN_BINDING_RESPONSE)
 	{
 		/* not a response */
 		return false;
@@ -517,33 +517,38 @@ bool UdpStun_generate_stun_pkt(void *stun_pkt, int *len)
 	}
 
 	/* just the header */
-	((uint16_t *) stun_pkt)[0] = (uint16_t) htons(0x0001);
+	((uint16_t *) stun_pkt)[0] = (uint16_t) htons(UdpStunner::STUN_BINDING_REQUEST);
 	((uint16_t *) stun_pkt)[1] = (uint16_t) htons(20); /* only header */
-	/* transaction id - should be random */
+	/* RFC 3489
-	((uint32_t *) stun_pkt)[1] = (uint32_t) htonl(0x0020); 
+	 *	The transaction ID is used to correlate requests and responses.
-	((uint32_t *) stun_pkt)[2] = (uint32_t) htonl(0x0121); 
+	 *
-	((uint32_t *) stun_pkt)[3] = (uint32_t) htonl(0x0111); 
+	 * RFC 5389 introduces a mmgic cokie at the location where preciously the transaction ID was located:
-	((uint32_t *) stun_pkt)[4] = (uint32_t) htonl(0x1010); 
+	 *	In RFC 3489, this field was part of
+	 *	the transaction ID; placing the magic cookie in this location allows
+	 *	a server to detect if the client will understand certain attributes
+	 *	that were added in this revised specification.
+	 */
+	RsRandom::random_bytes(&((uint8_t *) stun_pkt)[4], 4 * sizeof (uint32_t));
 	*len = 20;
 	return true;
 }
 
 
-void *UdpStun_generate_stun_reply(struct sockaddr_in *stun_addr, int *len)
+void *UdpStun_generate_stun_reply(struct sockaddr_in *stun_addr, int *len, const void *transId)
 {
 	/* just the header */
 	void *stun_pkt = rs_malloc(28);
     
-    	if(!stun_pkt)
+	if(!stun_pkt)
-            return NULL ;
+		return nullptr ;
         
-	((uint16_t *) stun_pkt)[0] = (uint16_t) htons(0x0101);
+	((uint16_t *) stun_pkt)[0] = (uint16_t) htons(UdpStunner::STUN_BINDING_RESPONSE);
 	((uint16_t *) stun_pkt)[1] = (uint16_t) htons(28); /* only header + 8 byte addr */
-	/* transaction id - should be random */
+	/* RFC 3489
-	((uint32_t *) stun_pkt)[1] = (uint32_t) htonl(0x0f20); 
+	 *	The Binding Response MUST contain the same transaction ID contained in the Binding Request.
-	((uint32_t *) stun_pkt)[2] = (uint32_t) htonl(0x0f21); 
+	 */
-	((uint32_t *) stun_pkt)[3] = (uint32_t) htonl(0x0f11); 
+	memcpy(&((uint32_t *) stun_pkt)[1], &((uint32_t *) transId)[1], 4 * sizeof (uint32_t));
-	((uint32_t *) stun_pkt)[4] = (uint32_t) htonl(0x1010); 
+
 	/* now add address
 	 *  0  1    2  3
 	 * <INET>  <port>
@@ -586,20 +591,20 @@ bool UdpStun_isStunPacket(void *data, int size)
 		return false;
 	}
 
-	if ((size == 20) && (0x0001 == ntohs(((uint16_t *) data)[0])))
+	if ((size == 20) && (UdpStunner::STUN_BINDING_REQUEST == ntohs(((uint16_t *) data)[0])))
 	{
 #ifdef DEBUG_UDP_STUNNER_FILTER
-		std::cerr << "UdpStunner::isStunPacket() (size=20 & data[0]=0x0001) -> true";
+		std::cerr << "UdpStunner::isStunPacket() (size=20 & data[0]=STUN_BINDING_REQUEST) -> true";
 		std::cerr << std::endl;
 #endif
 		/* request */
 		return true;
 	}
 
-	if ((size == 28) && (0x0101 == ntohs(((uint16_t *) data)[0])))
+	if ((size == 28) && (UdpStunner::STUN_BINDING_RESPONSE == ntohs(((uint16_t *) data)[0])))
 	{
 #ifdef DEBUG_UDP_STUNNER_FILTER
-		std::cerr << "UdpStunner::isStunPacket() (size=28 & data[0]=0x0101) -> true";
+		std::cerr << "UdpStunner::isStunPacket() (size=28 & data[0]=STUN_BINDING_RESPONSE) -> true";
 		std::cerr << std::endl;
 #endif
 		/* response */
@@ -947,15 +952,15 @@ bool    UdpStunner::locked_recvdStun(const struct sockaddr_in &remote, const str
 	if (remote.sin_addr.s_addr == extaddr.sin_addr.s_addr)
 	{
 #ifdef DEBUG_UDP_STUNNER
-#endif
 		std::cerr << "UdpStunner::locked_recvdStun() WARNING, BAD PEER: ";
 		std::cerr << "Stun Peer Returned its own address: " << rs_inet_ntoa(remote.sin_addr);
 		std::cerr << std::endl;
+#endif
 		return false;
 	}
 #endif
 
-	bool found = true;
+	bool found = false;
 	std::list<TouStunPeer>::iterator it;
 	for(it = mStunList.begin(); it != mStunList.end(); ++it)
 	{

libretroshare/src/tcponudp/udpstunner.h

@@ -30,10 +30,10 @@
 #include "util/rsthreads.h"
 #include <string>
 
-/* UdpStun.
+/**
+ * @brief The TouStunPeer class
  * Stuns peers to determine external addresses.
  */
-
 class TouStunPeer
 {
 	public:
@@ -53,10 +53,17 @@ class TouStunPeer
 		return; 
 	}
 	
+	/// id for identification
 	std::string id;
-	struct sockaddr_in remote, eaddr;
+	/// Remote address of the peer.
+	struct sockaddr_in remote;
+	/// Our external IP address as reported by the peer.
+	struct sockaddr_in eaddr;
+	/// true when a response was received in the past
 	bool response;
+	/// used to rate limit STUN requests
 	rstime_t lastsend;
+	/// fail counter for dead/bad peer detection (0 = good)
 	uint32_t failCount;
 };
 
@@ -65,6 +72,13 @@ class TouStunPeer
  * #define UDPSTUN_ALLOW_LOCALNET	1	
  */
 
+/**
+ * @brief The UdpStunner class
+ * The UDP stunner implements the STUN protocol to determin the NAT type (behind that RS is usually running).
+ * It maintains a list of DHT peers that are regulary contacted.
+ *
+ * The actual NAT type determination logic is located in void pqiNetStateBox::determineNetworkState()
+ */
 class UdpStunner: public UdpSubReceiver
 {
 	public:
@@ -102,6 +116,12 @@ virtual int status(std::ostream &out);
 	/* monitoring / updates */
 	int tick();
 
+	/*
+	 * based on RFC 3489
+	 */
+	static constexpr uint16_t STUN_BINDING_REQUEST  = 0x0001;
+	static constexpr uint16_t STUN_BINDING_RESPONSE = 0x0101;
+
 	private:
 
 bool  	checkStunDesired();
@@ -123,7 +143,7 @@ bool    locked_checkExternalAddress();
 
 	struct sockaddr_in eaddr; /* external addr */
 
-        bool eaddrKnown;
+	bool eaddrKnown;
 	bool eaddrStable; /* if true then usable. if false -> Symmettric NAT */
 	rstime_t eaddrTime;
 
@@ -143,13 +163,19 @@ bool    locked_checkExternalAddress();
 
 #endif
 
+	/// The UDP stunner will only (actively) contact it's peers when mPassiveStunMode is false. (has priority over mForceRestun
 	bool mPassiveStunMode;
-        uint32_t mTargetStunPeriod;
+	/// Time between STUNs
+	uint32_t mTargetStunPeriod;
+	/// Rate that determines how often STUN attempts are successfull
 	double mSuccessRate;
 
+	/// Some variables used for tracking who and when exclusive mode is enabled
 	bool mExclusiveMode; /* when this is switched on, the stunner stays silent (and extAddr is maintained) */
 	rstime_t mExclusiveModeTS;
 	std::string mExclusiveHolder;
+
+	/// force a STUN immediately
 	bool mForceRestun;
 
 };
@@ -158,7 +184,14 @@ bool    locked_checkExternalAddress();
 
 bool	UdpStun_isStunPacket(void *data, int size);
 bool    UdpStun_response(void *stun_pkt, int size, struct sockaddr_in &addr);
-void   *UdpStun_generate_stun_reply(struct sockaddr_in *stun_addr, int *len);
+/**
+ * @brief UdpStun_generate_stun_reply Generates a STUN reply package.
+ * @param stun_addr The address to set in the response field.
+ * @param len Lenght of the generated package (always 28).
+ * @param transId The transaction ID of the request package.
+ * @return Pointer to the generated reply package.
+ */
+void   *UdpStun_generate_stun_reply(struct sockaddr_in *stun_addr, int *len, const void* transId);
 bool    UdpStun_generate_stun_pkt(void *stun_pkt, int *len);
 
 #endif

retroshare.pri

@@ -111,6 +111,19 @@ no_direct_chat:CONFIG -= direct_chat
 CONFIG *= bitdht
 no_bitdht:CONFIG -= bitdht
 
+# The DHT stunner is used to determine the NAT type using other RS DHT peers and the STUN (Session Traversal Utilities for NAT) protocol.
+# To disable DHT stunner append the following assignation to qmake command line
+# "CONFIG+=no_use_dht_stunner"
+CONFIG *= use_dht_stunner
+no_use_dht_stunner:CONFIG -= use_dht_stunner
+
+# The DHT stunner can be used to figure out our external IP. As this purely relying on random DHT peers that answer our request, it can easily be abused.
+# Therefore, it is turned off by default.
+# To enable external ip determination (additionally) based on the dht stunner append the following assignation to qmake
+# command line "CONFIG+=use_dht_stunner_ext_ip"
+CONFIG *= no_use_dht_stunner_ext_ip
+use_dht_stunner_ext_ip:CONFIG -= no_use_dht_stunner_ext_ip
+
 # To select your MacOsX version append the following assignation to qmake
 # command line "CONFIG+=rs_macos10.11" where 10.11 depends your version
 macx:CONFIG *= rs_macos10.11
@@ -492,6 +505,14 @@ rs_gxs_trans {
 
 bitdht {
     DEFINES *= RS_USE_BITDHT
+
+    use_dht_stunner {
+        CONFIG *= useDhtStunner
+
+        use_dht_stunner_ext_ip {
+            DEFINES *= ALLOW_DHT_STUNNER
+        }
+    }
 }
 
 direct_chat {