diff options
author | Benny Prijono <bennylp@teluu.com> | 2008-03-19 23:00:30 +0000 |
---|---|---|
committer | Benny Prijono <bennylp@teluu.com> | 2008-03-19 23:00:30 +0000 |
commit | 97dfbff2ebfae83b7cb10517247215d38e4a74fd (patch) | |
tree | 0edea19f19049829e444733eced5d892b5a95a84 /pjnath/include | |
parent | b15dff0bed0f34a3371bce1b17e5a13ade0fb194 (diff) |
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
Diffstat (limited to 'pjnath/include')
-rw-r--r-- | pjnath/include/pjnath/stun_auth.h | 137 | ||||
-rw-r--r-- | pjnath/include/pjnath/stun_msg.h | 47 | ||||
-rw-r--r-- | pjnath/include/pjnath/stun_session.h | 40 |
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, |