Related to ticket #485: huge changeset to update STUN relating to managing authentication. See the ticket for the details

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

3 files changed, 178 insertions, 46 deletions

diff --git a/pjnath/include/pjnath/stun_auth.h b/pjnath/include/pjnath/stun_auth.h
index 840e473d..249b0622 100644
--- a/pjnath/include/pjnath/stun_auth.h
+++ b/pjnath/include/pjnath/stun_auth.h
@@ -39,6 +39,29 @@ PJ_BEGIN_DECL
  */
 
 /**
+ * Type of authentication.
+ */
+typedef enum pj_stun_auth_type
+{ 
+    /**
+     * No authentication.
+     */
+    PJ_STUN_AUTH_NONE = 0,
+
+    /**
+     * Authentication using short term credential.
+     */
+    PJ_STUN_AUTH_SHORT_TERM = 1,
+
+    /**
+     * Authentication using long term credential.
+     */
+    PJ_STUN_AUTH_LONG_TERM = 2
+
+} pj_stun_auth_type;
+
+
+/**
  * Type of authentication data in the credential.
  */
 typedef enum pj_stun_auth_cred_type
@@ -62,6 +85,26 @@ typedef enum pj_stun_auth_cred_type
 
 
 /**
+ * Type of encoding applied to the password stored in the credential.
+ */
+typedef enum pj_stun_passwd_type
+{
+    /**
+     * Plain text password.
+     */
+    PJ_STUN_PASSWD_PLAIN    = 0,
+
+    /**
+     * Hashed password, valid for long term credential only. The hash value
+     * of the password is calculated as MD5(USERNAME ":" REALM ":" PASSWD)
+     * with all quotes removed from the username and realm values.
+     */
+    PJ_STUN_PASSWD_HASHED = 1
+
+} pj_stun_passwd_type;
+
+
+/**
  * This structure contains the descriptions needed to perform server side
  * authentication. Depending on the \a type set in the structure, application
  * may specify a static username/password combination, or to have callbacks
@@ -89,31 +132,29 @@ typedef struct pj_stun_auth_cred
 	    /** 
 	     * If not-empty, it indicates that this is a long term credential.
 	     */
-	    pj_str_t	  realm;
+	    pj_str_t		realm;
 
 	    /** 
 	     * The username of the credential.
 	     */
-	    pj_str_t	  username;
+	    pj_str_t		username;
 
 	    /**
 	     * Data type to indicate the type of password in the \a data field.
-	     * Value zero indicates that the data contains a plaintext
-	     * password.
 	     */
-	    int		  data_type;
+	    pj_stun_passwd_type	data_type;
 
 	    /** 
 	     * The data, which depends depends on the value of \a data_type
 	     * field. When \a data_type is zero, this field will contain the
 	     * plaintext password.
 	     */
-	    pj_str_t	  data;
+	    pj_str_t		data;
 
 	    /** 
 	     * Optional NONCE.
 	     */
-	    pj_str_t	  nonce;
+	    pj_str_t		nonce;
 
 	} static_cred;
 
@@ -156,7 +197,7 @@ typedef struct pj_stun_auth_cred
 				    pj_str_t *nonce);
 
 	    /**
-	     * Get the credential to be put in outgoing message.
+	     * Get the credential to be put in outgoing request.
 	     *
 	     * @param msg	The outgoing message where the credential is
 	     *			to be applied.
@@ -186,7 +227,7 @@ typedef struct pj_stun_auth_cred
 				    pj_str_t *realm,
 				    pj_str_t *username,
 				    pj_str_t *nonce,
-				    int *data_type,
+				    pj_stun_passwd_type *data_type,
 				    pj_str_t *data);
 
 	    /**
@@ -217,7 +258,7 @@ typedef struct pj_stun_auth_cred
 				        const pj_str_t *realm,
 				        const pj_str_t *username,
 					pj_pool_t *pool,
-					int *data_type,
+					pj_stun_passwd_type *data_type,
 					pj_str_t *data);
 
 	    /**
@@ -250,6 +291,40 @@ typedef struct pj_stun_auth_cred
 
 
 /**
+ * This structure contains the credential information that is found and
+ * used to authenticate incoming requests. Application may use this
+ * information when generating authentication for the outgoing response.
+ */
+typedef struct pj_stun_req_cred_info
+{
+    /**
+     * The REALM value found in the incoming request. If short term 
+     * credential is used, the value will be empty.
+     */
+    pj_str_t	realm;
+
+    /**
+     * The USERNAME value found in the incoming request.
+     */
+    pj_str_t	username;
+
+    /**
+     * Optional NONCE.
+     */
+    pj_str_t	nonce;
+
+    /**
+     * Authentication key that was used to authenticate the incoming 
+     * request. This key is created with #pj_stun_create_key(), and
+     * it can be used to encode the credential of the outgoing
+     * response.
+     */
+    pj_str_t	auth_key;
+
+} pj_stun_req_cred_info;
+
+
+/**
  * Duplicate authentication credential.
  *
  * @param pool		Pool to be used to allocate memory.
@@ -260,6 +335,40 @@ PJ_DECL(void) pj_stun_auth_cred_dup(pj_pool_t *pool,
 				      pj_stun_auth_cred *dst,
 				      const pj_stun_auth_cred *src);
 
+/**
+ * Duplicate request credential.
+ *
+ * @param pool		Pool to be used to allocate memory.
+ * @param dst		Destination credential.
+ * @param src		Source credential.
+ */
+PJ_DECL(void) pj_stun_req_cred_info_dup(pj_pool_t *pool,
+					pj_stun_req_cred_info *dst,
+					const pj_stun_req_cred_info *src);
+
+
+/**
+ * Create authentication key to be used for encoding the message with
+ * MESSAGE-INTEGRITY. If short term credential is used (i.e. the realm
+ * argument is NULL or empty), the key will be copied from the password.
+ * If long term credential is used, the key will be calculated from the
+ * MD5 hash of the realm, username, and password.
+ *
+ * @param pool		Pool to allocate memory for the key.
+ * @param key		String to receive the key.
+ * @param realm		The realm of the credential, if long term credential
+ *			is to be used. If short term credential is wanted,
+ *			application can put NULL or empty string here.
+ * @param username	The username.
+ * @param data_type	Password encoding.
+ * @param data		The password.
+ */
+PJ_DECL(void) pj_stun_create_key(pj_pool_t *pool,
+				 pj_str_t *key,
+				 const pj_str_t *realm,
+				 const pj_str_t *username,
+				 pj_stun_passwd_type data_type,
+				 const pj_str_t *data);
 
 /**
  * Verify credential in the STUN request. Note that before calling this
@@ -277,9 +386,9 @@ PJ_DECL(void) pj_stun_auth_cred_dup(pj_pool_t *pool,
  *			the message.
  * @param pool		If response is to be created, then memory will
  *			be allocated from this pool.
- * @param auth_key	Optional pointer to receive authentication key to
- *			calculate MESSAGE-INTEGRITY of the response, if
- *			the response needs to be authenticated.
+ * @param info		Optional pointer to receive authentication information
+ *			found in the request and the credential that is used
+ *			to authenticate the request.
  * @param p_response	Optional pointer to receive the response message
  *			then the credential in the request fails to
  *			authenticate.
@@ -294,7 +403,7 @@ PJ_DECL(pj_status_t) pj_stun_authenticate_request(const pj_uint8_t *pkt,
 					          const pj_stun_msg *msg,
 					          pj_stun_auth_cred *cred,
 					          pj_pool_t *pool,
-						  pj_str_t *auth_key,
+						  pj_stun_req_cred_info *info,
 					          pj_stun_msg **p_response);
 
 
diff --git a/pjnath/include/pjnath/stun_msg.h b/pjnath/include/pjnath/stun_msg.h
index cde21fa9..31e40333 100644
--- a/pjnath/include/pjnath/stun_msg.h
+++ b/pjnath/include/pjnath/stun_msg.h
@@ -1225,6 +1225,17 @@ PJ_DECL(pj_status_t) pj_stun_msg_create(pj_pool_t *pool,
 					pj_stun_msg **p_msg);
 
 /**
+ * Clone a STUN message with all of its attributes.
+ *
+ * @param pool		Pool to allocate memory for the new message.
+ * @param msg		The message to be cloned.
+ *
+ * @return		The duplicate message.
+ */
+PJ_DECL(pj_stun_msg*) pj_stun_msg_clone(pj_pool_t *pool,
+					const pj_stun_msg *msg);
+
+/**
  * Create STUN response message. 
  *
  * @param pool		Pool to create the mesage.
@@ -1300,30 +1311,6 @@ PJ_DECL(pj_status_t) pj_stun_msg_encode(pj_stun_msg *msg,
 					const pj_str_t *key,
 				        unsigned *p_msg_len);
 
-
-/**
- * Create authentication key to be used for encoding the message with
- * MESSAGE-INTEGRITY. If short term credential is used (i.e. the realm
- * argument is NULL or empty), the key will be copied from the password.
- * If long term credential is used, the key will be calculated from the
- * MD5 hash of the realm, username, and password.
- *
- * @param pool		Pool to allocate memory for the key.
- * @param key		String to receive the key.
- * @param realm		The realm of the credential, if long term credential
- *			is to be used. If short term credential is wanted,
- *			application can put NULL or empty string here.
- * @param username	The username.
- * @param passwd	The clear text password.
- */
-PJ_DECL(void) pj_stun_create_key(pj_pool_t *pool,
-				 pj_str_t *key,
-				 const pj_str_t *realm,
-				 const pj_str_t *username,
-				 const pj_str_t *passwd);
-
-
-
 /**
  * Check that the PDU is potentially a valid STUN message. This function
  * is useful when application needs to multiplex STUN packets with other
@@ -1417,6 +1404,18 @@ PJ_DECL(pj_stun_attr_hdr*) pj_stun_msg_find_attr(const pj_stun_msg *msg,
 
 
 /**
+ * Clone a STUN attribute.
+ *
+ * @param pool		Pool to allocate memory.
+ * @param attr		Attribute to clone.
+ *
+ * @return		Duplicate attribute.
+ */
+PJ_DECL(pj_stun_attr_hdr*) pj_stun_attr_clone(pj_pool_t *pool,
+					      const pj_stun_attr_hdr *attr);
+
+
+/**
  * Create a generic STUN IP address attribute. The \a addr_len and
  * \a addr parameters specify whether the address is IPv4 or IPv4
  * address.
diff --git a/pjnath/include/pjnath/stun_session.h b/pjnath/include/pjnath/stun_session.h
index b28763ac..187064ed 100644
--- a/pjnath/include/pjnath/stun_session.h
+++ b/pjnath/include/pjnath/stun_session.h
@@ -46,6 +46,9 @@ PJ_BEGIN_DECL
 /** Forward declaration for pj_stun_tx_data */
 typedef struct pj_stun_tx_data pj_stun_tx_data;
 
+/** Forward declaration for pj_stun_rx_data */
+typedef struct pj_stun_rx_data pj_stun_rx_data;
+
 /** Forward declaration for pj_stun_session */
 typedef struct pj_stun_session pj_stun_session;
 
@@ -85,7 +88,7 @@ typedef struct pj_stun_session_cb
      * @param sess	    The STUN session.
      * @param pkt	    Pointer to the original STUN packet.
      * @param pkt_len	    Length of the STUN packet.
-     * @param msg	    The parsed STUN request.
+     * @param rdata	    Data containing incoming request message.
      * @param src_addr	    Source address of the packet.
      * @param src_addr_len  Length of the source address.
      *
@@ -96,7 +99,7 @@ typedef struct pj_stun_session_cb
     pj_status_t (*on_rx_request)(pj_stun_session *sess,
 				 const pj_uint8_t *pkt,
 				 unsigned pkt_len,
-				 const pj_stun_msg *msg,
+				 const pj_stun_rx_data *rdata,
 				 const pj_sockaddr_t *src_addr,
 				 unsigned src_addr_len);
 
@@ -144,6 +147,25 @@ typedef struct pj_stun_session_cb
 
 
 /**
+ * This structure describes incoming request message.
+ */
+struct pj_stun_rx_data
+{
+    /**
+     * The parsed request message.
+     */
+    pj_stun_msg		    *msg;
+
+    /**
+     * Credential information that is found and used to authenticate 
+     * incoming request. Application may use this information when 
+     * generating  authentication for the outgoing response.
+     */
+    pj_stun_req_cred_info   info;
+};
+
+
+/**
  * This structure describe the outgoing STUN transmit data to carry the
  * message to be sent.
  */
@@ -161,7 +183,7 @@ struct pj_stun_tx_data
     pj_uint32_t		 msg_magic;	/**< Message magic.		    */
     pj_uint8_t		 msg_key[12];	/**< Message/transaction key.	    */
 
-    pj_str_t		 auth_key;	/**< Auth key.			    */
+    pj_stun_req_cred_info auth_info;	/**< Credential info		    */
 
     void		*pkt;		/**< The STUN packet.		    */
     unsigned		 max_len;	/**< Length of packet buffer.	    */
@@ -259,13 +281,15 @@ PJ_DECL(pj_status_t) pj_stun_session_set_server_name(pj_stun_session *sess,
  * again with NULL as the argument.
  *
  * @param sess	    The STUN session instance.
+ * @param auth_type Type of authentication.
  * @param cred	    The credential to be used by this session. If NULL
  *		    is specified, authentication will be disabled.
  *
  * @return	    PJ_SUCCESS on success, or the appropriate error code.
  */
-PJ_DECL(void) pj_stun_session_set_credential(pj_stun_session *sess,
-					     const pj_stun_auth_cred *cred);
+PJ_DECL(pj_status_t) pj_stun_session_set_credential(pj_stun_session *sess,
+						pj_stun_auth_type auth_type,
+						const pj_stun_auth_cred *cred);
 
 /**
  * Create a STUN request message. After the message has been successfully
@@ -328,7 +352,7 @@ PJ_DECL(pj_status_t) pj_stun_session_create_ind(pj_stun_session *sess,
  * @return	    PJ_SUCCESS on success, or the appropriate error code.
  */
 PJ_DECL(pj_status_t) pj_stun_session_create_res(pj_stun_session *sess,
-						const pj_stun_msg *req,
+						const pj_stun_rx_data *rdata,
 						unsigned err_code,
 						const pj_str_t *err_msg,
 						pj_stun_tx_data **p_tdata);
@@ -362,7 +386,7 @@ PJ_DECL(pj_status_t) pj_stun_session_send_msg(pj_stun_session *sess,
  * Create and send STUN response message.
  *
  * @param sess	    The STUN session instance.
- * @param req	    The STUN request message to be responded.
+ * @param rdata	    The STUN request message to be responded.
  * @param err_code  Error code to be set in the response, if error response
  *		    is to be created, according to pj_stun_status enumeration.
  *		    This argument MUST be zero if successful response is
@@ -382,7 +406,7 @@ PJ_DECL(pj_status_t) pj_stun_session_send_msg(pj_stun_session *sess,
  * @return	    PJ_SUCCESS on success, or the appropriate error code.
  */
 PJ_DECL(pj_status_t) pj_stun_session_respond(pj_stun_session *sess, 
-					     const pj_stun_msg *req,
+					     const pj_stun_rx_data *rdata,
 					     unsigned code, 
 					     const char *err_msg,
 					     pj_bool_t cache,