Ticket #780: Update TURN from draft 09 to draft 13:

 - new rules for permissions:
    - permission must be created and refreshed explicitly with CreatePermission
    - transmitting data does not refresh permission
 - attributes changed/added: XOR-PEER-ADDRESS, XOR-RELAYED-ADDRESS, EVEN-PORT, DONT-FRAGMENT
 - attribute(s) removed: REQUESTED-PROPS
 - new status codes: 401 (Forbidden), 507 (Insufficient Capacity)
 - removed status codes: 443 (Invalid IP address), 444 (Invalid Port), 508 (Insufficient Port Capacity)



git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@2589 74dad513-b988-da41-8d7b-12977e46ad98

5 files changed, 143 insertions, 80 deletions

diff --git a/pjnath/include/pjnath/stun_msg.h b/pjnath/include/pjnath/stun_msg.h
index 5a7237f3..25082626 100644
--- a/pjnath/include/pjnath/stun_msg.h
+++ b/pjnath/include/pjnath/stun_msg.h
@@ -83,6 +83,11 @@ enum pj_stun_method_e
     PJ_STUN_DATA_METHOD			    = 7,
 
     /**
+     * STUN/TURN CreatePermission method as defined by draft-ietf-behave-turn
+     */
+    PJ_STUN_CREATE_PERM_METHOD		    = 8,
+
+    /**
      * STUN/TURN ChannelBind as defined by draft-ietf-behave-turn
      */
     PJ_STUN_CHANNEL_BIND_METHOD		    = 9,
@@ -254,6 +259,22 @@ typedef enum pj_stun_msg_type
 
 
     /**
+     * TURN CreatePermission request
+     */
+    PJ_STUN_CREATE_PERM_REQUEST		    = 0x0008,
+
+    /**
+     * TURN CreatePermission successful response.
+     */
+    PJ_STUN_CREATE_PERM_RESPONSE	    = 0x0108,
+
+    /**
+     * TURN CreatePermission failure response
+     */
+    PJ_STUN_CREATE_PERM_ERROR_RESPONSE	    = 0x0118,
+
+
+    /**
      * STUN/TURN ChannelBind Request
      */
     PJ_STUN_CHANNEL_BIND_REQUEST	    = 0x0009,
@@ -292,14 +313,15 @@ typedef enum pj_stun_attr_type
     PJ_STUN_ATTR_LIFETIME	    = 0x000D,/**< TURN LIFETIME attr.	    */
     PJ_STUN_ATTR_MAGIC_COOKIE	    = 0x000F,/**< MAGIC-COOKIE attr (deprec)*/
     PJ_STUN_ATTR_BANDWIDTH	    = 0x0010,/**< TURN BANDWIDTH (deprec)   */
-    PJ_STUN_ATTR_PEER_ADDR	    = 0x0012,/**< TURN PEER-ADDRESS attr.   */
+    PJ_STUN_ATTR_XOR_PEER_ADDR	    = 0x0012,/**< TURN XOR-PEER-ADDRESS	    */
     PJ_STUN_ATTR_DATA		    = 0x0013,/**< DATA attribute.	    */
     PJ_STUN_ATTR_REALM		    = 0x0014,/**< REALM attribute.	    */
     PJ_STUN_ATTR_NONCE		    = 0x0015,/**< NONCE attribute.	    */
-    PJ_STUN_ATTR_RELAYED_ADDR	    = 0x0016,/**< RELAYED-ADDRESS attribute.*/
+    PJ_STUN_ATTR_XOR_RELAYED_ADDR   = 0x0016,/**< TURN XOR-RELAYED-ADDRESS  */
     PJ_STUN_ATTR_REQ_ADDR_TYPE	    = 0x0017,/**< REQUESTED-ADDRESS-TYPE    */
-    PJ_STUN_ATTR_REQ_PROPS	    = 0x0018,/**< REQUESTED-PROPS	    */
-    PJ_STUN_ATTR_REQ_TRANSPORT	    = 0x0019,/**< REQUESTED-TRANSPORT	    */
+    PJ_STUN_ATTR_EVEN_PORT	    = 0x0018,/**< TURN EVEN-PORT	    */
+    PJ_STUN_ATTR_REQ_TRANSPORT	    = 0x0019,/**< TURN REQUESTED-TRANSPORT  */
+    PJ_STUN_ATTR_DONT_FRAGMENT	    = 0x001A,/**< TURN DONT-FRAGMENT	    */
     PJ_STUN_ATTR_XOR_MAPPED_ADDR    = 0x0020,/**< XOR-MAPPED-ADDRESS	    */
     PJ_STUN_ATTR_TIMER_VAL	    = 0x0021,/**< TIMER-VAL attribute.	    */
     PJ_STUN_ATTR_RESERVATION_TOKEN  = 0x0022,/**< TURN RESERVATION-TOKEN    */
@@ -332,6 +354,7 @@ typedef enum pj_stun_status
     PJ_STUN_SC_TRY_ALTERNATE		= 300,  /**< Try Alternate	    */
     PJ_STUN_SC_BAD_REQUEST		= 400,  /**< Bad Request	    */
     PJ_STUN_SC_UNAUTHORIZED	        = 401,  /**< Unauthorized	    */
+    PJ_STUN_SC_FORBIDDEN		= 403,	/**< Forbidden (TURN)	    */
     PJ_STUN_SC_UNKNOWN_ATTRIBUTE        = 420,  /**< Unknown Attribute	    */
 #if 0
     /* These were obsolete in recent rfc3489bis */
@@ -349,8 +372,6 @@ typedef enum pj_stun_status
     PJ_STUN_SC_WRONG_CREDENTIALS	= 441,	/**< TURN Wrong Credentials */
     PJ_STUN_SC_UNSUPP_TRANSPORT_PROTO   = 442,  /**< Unsupported Transport or
 						     Protocol (TURN) */
-    PJ_STUN_SC_INVALID_IP_ADDR		= 443,  /**< Invalid IP Address(TURN)*/
-    PJ_STUN_SC_INVALID_PORT	        = 444,  /**< Invalid Port (TURN)    */
     PJ_STUN_SC_OPER_TCP_ONLY		= 445,  /**< Operation for TCP Only */
     PJ_STUN_SC_CONNECTION_FAILURE       = 446,  /**< Connection Failure	    */
     PJ_STUN_SC_CONNECTION_TIMEOUT       = 447,  /**< Connection Timeout	    */
@@ -358,9 +379,7 @@ typedef enum pj_stun_status
 						     (TURN) */
     PJ_STUN_SC_ROLE_CONFLICT		= 487,  /**< Role Conflict	    */
     PJ_STUN_SC_SERVER_ERROR	        = 500,  /**< Server Error	    */
-    PJ_STUN_SC_INSUFFICIENT_CAPACITY    = 507,  /**< Insufficient Capacity 
-						     (TURN) */
-    PJ_STUN_SC_INSUFFICIENT_PORT_CAPACITY=508,  /**< Insufficient Port Capacity 
+    PJ_STUN_SC_INSUFFICIENT_CAPACITY	= 508,  /**< Insufficient Capacity 
 						     (TURN) */
     PJ_STUN_SC_GLOBAL_FAILURE	        = 600   /**< Global Failure	    */
 } pj_stun_status;
@@ -912,12 +931,12 @@ typedef struct pj_stun_uint_attr pj_stun_bandwidth_attr;
 
 
 /**
- * This describes the STUN PEER-ADDRESS attribute.
- * The PEER-ADDRESS specifies the address and port of the peer as seen
+ * This describes the STUN XOR-PEER-ADDRESS attribute.
+ * The XOR-PEER-ADDRESS specifies the address and port of the peer as seen
  * from the TURN server.  It is encoded in the same way as XOR-MAPPED-
  * ADDRESS. 
  */
-typedef struct pj_stun_sockaddr_attr pj_stun_peer_addr_attr;
+typedef struct pj_stun_sockaddr_attr pj_stun_xor_peer_addr_attr;
 
 
 /**
@@ -931,12 +950,12 @@ typedef struct pj_stun_binary_attr pj_stun_data_attr;
 
 
 /**
- * This describes the STUN RELAYED-ADDRESS attribute.
- * The RELAYED-ADDRESS is present in Allocate responses.  It specifies the
+ * This describes the STUN XOR-RELAYED-ADDRESS attribute. The 
+ * XOR-RELAYED-ADDRESS is present in Allocate responses.  It specifies the
  * address and port that the server allocated to the client.  It is
  * encoded in the same way as XOR-MAPPED-ADDRESS.
  */
-typedef struct pj_stun_sockaddr_attr pj_stun_relayed_addr_attr;
+typedef struct pj_stun_sockaddr_attr pj_stun_xor_relayed_addr_attr;
 
 
 /**
@@ -955,71 +974,37 @@ typedef struct pj_stun_sockaddr_attr pj_stun_relayed_addr_attr;
 
  \endverbatim
  */
-typedef struct pj_stun_uint_attr pj_stun_req_addr_type;
-
-/**
- * This describes the TURN REQUESTED-PROPS attribute, encoded as
- * STUN 32bit integer attribute. Few macros are provided to manipulate
- * the values in this attribute: #PJ_STUN_GET_PROP_TYPE(), and
- * #PJ_STUN_SET_PROP_TYPE().
- * 
- * This attribute allows the client to request that the allocation have
- * certain properties, and by the server to indicate which properties
- * are supported.  The attribute is 32 bits long.  Its format is:
-
- \verbatim
-
-      0                   1                   2                   3
-      0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
-     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-     |   Prop-type   |                  Reserved = 0                 |
-     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+typedef struct pj_stun_uint_attr pj_stun_req_addr_type_attr;
 
- \endverbatim
 
- * The field labeled "Prop-type" is an 8-bit field specifying the
- * desired property.  The rest of the attribute is RFFU (Reserved For
- * Future Use) and MUST be set to 0 on transmission and ignored on
- * reception.
+/**
+ * This describes the TURN REQUESTED-TRANSPORT attribute, encoded in
+ * STUN generic integer attribute.
  *
- * The "Prop-type" field is formatted as follows:
-
- \verbatim
+ * This attribute allows the client to request that the port in the
+ * relayed-transport-address be even, and (optionally) that the server
+ * reserve the next-higher port number.  The attribute is 8 bits long.
+ * Its format is:
 
-      0 1 2 3 4 5 6 7 
+\verbatim
+      0
+      0 1 2 3 4 5 6 7
      +-+-+-+-+-+-+-+-+
-     |E|R|P|         |
+     |R|    RFFU     |
      +-+-+-+-+-+-+-+-+
 
- \endverbatim
-
-   The bits in "Prop-type" are:
-
-   E: If 1, the port number for the relayed-transport-address must be
-      even.  If 0, the port number can be even or odd.
-
-   R: If 1, the server must reserve the next highest port for a
-      subsequent allocation.  If 0, no such reservation is requested.
-      If the client sets the R bit to 1, it MUST also set the E bit to 1
-      (however, the E bit may be 1 when the R bit is 0).
-
-   P: If 1, the allocation must be a Preserving allocation.  If 0, the
-      allocation can be either Preserving or Non-Preserving.
-
- */
-typedef struct pj_stun_uint_attr pj_stun_req_props_attr;
-
-/**
- * Get the 8bit Prop-type value from a 32bit integral value of TURN 
- * TURN REQUESTED-PROPS attribute.
- */
-#define PJ_STUN_GET_PROP_TYPE(u32)	(u32 >> 24)
+\endverbatim
 
-/**
- * Convert 8bit Prop-type value to a 32bit integral value of TURN 
- * REQUESTED-PROPS attribute.
+ * The attribute contains a single 1-bit flag:
+ * 
+ * R: If 1, the server is requested to reserve the next higher port
+ *    number (on the same IP address) for a subsequent allocation.  If
+ *    0, no such reservation is requested.
+ * 
+ * The other 7 bits of the attribute must be set to zero on transmission
+ * and ignored on reception.
  */
-#define PJ_STUN_SET_PROP_TYPE(PropType)	(PropType << 24)
+typedef struct pj_stun_uint_attr pj_stun_even_port_attr;
 
 
 /**
@@ -1064,6 +1049,16 @@ typedef struct pj_stun_uint_attr pj_stun_req_transport_attr;
 #define PJ_STUN_SET_RT_PROTO(proto)   (((pj_uint32_t)(proto)) << 24)
 
 
+/**
+ * This describes the TURN DONT-FRAGMENT attribute.
+ *
+ * This attribute is used by the client to request that the server set
+ * the DF (Don't Fragment) bit in the IP header when relaying the
+ * application data onward to the peer.  This attribute has no value
+ * part and thus the attribute length field is 0.
+ */
+typedef struct pj_stun_empty_attr pj_stun_use_candidate_attr;
+
 
 /**
  * This describes the TURN RESERVATION-TOKEN attribute.
diff --git a/pjnath/include/pjnath/stun_session.h b/pjnath/include/pjnath/stun_session.h
index 518e4ad3..714cbf9e 100644
--- a/pjnath/include/pjnath/stun_session.h
+++ b/pjnath/include/pjnath/stun_session.h
@@ -327,15 +327,17 @@ PJ_DECL(pj_status_t) pj_stun_session_set_lock(pj_stun_session *sess,
 					      pj_bool_t auto_del);
 
 /**
- * Set server name to be included in all response.
+ * Set SOFTWARE name to be included in all requests and responses.
  *
  * @param sess	    The STUN session instance.
- * @param srv_name  Server name string.
+ * @param sw	    Software name string. If this argument is NULL or
+ *		    empty, the session will not include SOFTWARE attribute
+ *		    in STUN requests and responses.
  *
- * @return	    The user data associated with this STUN session.
+ * @return	    PJ_SUCCESS on success, or the appropriate error code.
  */
-PJ_DECL(pj_status_t) pj_stun_session_set_server_name(pj_stun_session *sess,
-						     const pj_str_t *srv_name);
+PJ_DECL(pj_status_t) pj_stun_session_set_software_name(pj_stun_session *sess,
+						       const pj_str_t *sw);
 
 /**
  * Set credential to be used by this session. Once credential is set, all
diff --git a/pjnath/include/pjnath/turn_session.h b/pjnath/include/pjnath/turn_session.h
index f028fd8e..88cf1bfe 100644
--- a/pjnath/include/pjnath/turn_session.h
+++ b/pjnath/include/pjnath/turn_session.h
@@ -437,6 +437,21 @@ PJ_DECL(void) pj_turn_session_set_log(pj_turn_session *sess,
 
 
 /**
+ * Configure the SOFTWARE name to be sent in all STUN requests by the
+ * TURN session.
+ *
+ * @param sess	    The TURN client session.
+ * @param sw	    Software name string. If this argument is NULL or
+ *		    empty, the session will not include SOFTWARE attribute
+ *		    in STUN requests and responses.
+ *
+ * @return	    PJ_SUCCESS on success, or the appropriate error code.
+ */
+PJ_DECL(pj_status_t) pj_turn_session_set_software_name(pj_turn_session *sess,
+						       const pj_str_t *sw);
+
+
+/**
  * Set the server or domain name of the server. Before the application
  * can send Allocate request (with pj_turn_session_alloc()), it must first
  * resolve the server address(es) using this function. This function will
@@ -519,6 +534,30 @@ PJ_DECL(pj_status_t) pj_turn_session_alloc(pj_turn_session *sess,
 
 
 /**
+ * Create or renew permission in the TURN server for the specified peer IP
+ * addresses. Application must install permission for a particular (peer)
+ * IP address before it sends any data to that IP address, or otherwise
+ * the TURN server will drop the data.
+ *
+ * @param sess		The TURN client session.
+ * @param addr_cnt	Number of IP addresses.
+ * @param addr		Array of peer IP addresses. Only the address family
+ *			and IP address portion of the socket address matter.
+ * @param options	Specify 1 to let the TURN client session automatically
+ *			renew the permission later when they are about to
+ *			expire.
+ *
+ * @return		PJ_SUCCESS if the operation has been successfully
+ *			issued, or the appropriate error code. Note that
+ *			the operation itself will complete asynchronously.
+ */
+PJ_DECL(pj_status_t) pj_turn_session_set_perm(pj_turn_session *sess,
+					      unsigned addr_cnt,
+					      const pj_sockaddr addr[],
+					      unsigned options);
+
+
+/**
  * Send a data to the specified peer address via the TURN relay. This 
  * function will encapsulate the data as STUN Send Indication or TURN
  * ChannelData packet and send the message to the TURN server. The TURN
diff --git a/pjnath/include/pjnath/turn_sock.h b/pjnath/include/pjnath/turn_sock.h
index e2e0c040..e0931ab9 100644
--- a/pjnath/include/pjnath/turn_sock.h
+++ b/pjnath/include/pjnath/turn_sock.h
@@ -248,6 +248,29 @@ PJ_DECL(pj_status_t) pj_turn_sock_alloc(pj_turn_sock *turn_sock,
 				        const pj_turn_alloc_param *param);
 
 /**
+ * Create or renew permission in the TURN server for the specified peer IP
+ * addresses. Application must install permission for a particular (peer)
+ * IP address before it sends any data to that IP address, or otherwise
+ * the TURN server will drop the data.
+ *
+ * @param turn_sock	The TURN transport instance.
+ * @param addr_cnt	Number of IP addresses.
+ * @param addr		Array of peer IP addresses. Only the address family
+ *			and IP address portion of the socket address matter.
+ * @param options	Specify 1 to let the TURN client session automatically
+ *			renew the permission later when they are about to
+ *			expire.
+ *
+ * @return		PJ_SUCCESS if the operation has been successfully
+ *			issued, or the appropriate error code. Note that
+ *			the operation itself will complete asynchronously.
+ */
+PJ_DECL(pj_status_t) pj_turn_sock_set_perm(pj_turn_sock *turn_sock,
+					   unsigned addr_cnt,
+					   const pj_sockaddr addr[],
+					   unsigned options);
+
+/**
  * Send a data to the specified peer address via the TURN relay. This 
  * function will encapsulate the data as STUN Send Indication or TURN
  * ChannelData packet and send the message to the TURN server. The TURN
diff --git a/pjnath/include/pjnath/types.h b/pjnath/include/pjnath/types.h
index a7d66070..0f857d00 100644
--- a/pjnath/include/pjnath/types.h
+++ b/pjnath/include/pjnath/types.h
@@ -107,11 +107,15 @@ This version of PJNATH implements the following STUN RFC:
 Traversal Using Relays around NAT (TURN) allows the host to control the
 operation of the relay and to exchange packets with its peers using the relay.
 
-This version of PJNATH implements both TCP and UDP client transport and it
-complies with the following TURN draft:
- - <A HREF="http://www.ietf.org/internet-drafts/draft-ietf-behave-turn-09.txt">
-   <B>draft-ietf-behave-turn-09</B></A>: Obtaining Relay Addresses 
+Features:
+ - <A HREF="http://www.ietf.org/internet-drafts/draft-ietf-behave-turn-13.txt">
+   <B>draft-ietf-behave-turn-13</B></A>: Obtaining Relay Addresses 
    from Simple Traversal Underneath NAT (STUN)
+ - DNS SRV resolution
+ - Fallback to DNS A resolution if SRV record is not found
+ - UDP and TCP connection to TURN server
+ - automatic management of allocation refresh
+
 
 
 \subsection comp_ice ICE