Changeset 1877 for pjproject/trunk/pjnath/include/pjnath/stun_auth.h

Timestamp:

Mar 19, 2008 11:00:30 PM (16 years ago)

Author:

bennylp

Message:

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

File:

• pjproject/trunk/pjnath/include/pjnath/stun_auth.h (modified) (11 diffs)

pjproject/trunk/pjnath/include/pjnath/stun_auth.h

@@ -40 +40 @@
 
 /**
+ * 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.
  */
@@ -60 +83 @@
 
 } 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;
 
 
@@ -90 +133 @@
              * 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;
 
             /** 
@@ -109 +150 @@
              * plaintext password.
              */
-            pj_str_t      data;
+            pj_str_t            data;
 
             /** 
              * Optional NONCE.
              */
-            pj_str_t      nonce;
+            pj_str_t            nonce;
 
         } static_cred;
@@ -157 +198 @@
 
             /**
-             * 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
@@ -187 +228 @@
                                     pj_str_t *username,
                                     pj_str_t *nonce,
-                                    int *data_type,
+                                    pj_stun_passwd_type *data_type,
                                     pj_str_t *data);
 
@@ -218 +259 @@
                                         const pj_str_t *username,
                                         pj_pool_t *pool,
-                                        int *data_type,
+                                        pj_stun_passwd_type *data_type,
                                         pj_str_t *data);
 
@@ -251 +292 @@
 
 /**
+ * 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.
  *
@@ -261 +336 @@
                                       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);
 
 /**
@@ -278 +387 @@
  * @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
@@ -295 +404 @@
                                                   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);