Add full support for SHA-256 and SHA-512-256 digest algorithms

There are no breaking changes for this work however several structures
were extended with new fields.  See below.

In order to use the new algorithms, you MUST set the new
pjsip_cred_info.ext.algorithm_type field to the appropriate value
when the credential data type is PJSIP_CRED_DATA_DIGEST and when
acting as a server, you must also use pjsip_auth_srv_challenge2()
to send challenges so you can specify algorithms other than MD5.

Summary of changes:

* Added enum pjsip_auth_algorithm_type which list all digest algorithms
supported.

* Added struct pjsip_auth_algorithm which defines parameters for each
algorithm including its IANA name, OpenSSL name, digest length and
digest string representation length.

* Added pjsip_auth_algorithm_type to the pjsip_cred_info structure
so the digest algorithm can be specified when the cred data type
is PJSIP_CRED_DATA_DIGEST.

* Added pjsip_auth_algorithm_type to the pjsip_cached_auth_hdr
structure so we can match on specific algorithm.

* Added functions pjsip_auth_get_algorithm_by_type(),
pjsip_auth_get_algorithm_by_iana_name(), and
pjsip_auth_is_digest_algorithm_supported() to find and search
for supported algorithms.

* Added pjsip_authorization_hdr to the pjsip_auth_lookup_cred_param
structure so we can look up credentiials by specific algorithm.

* Added the pjsip_auth_srv_challenge2() function that takes
a pjsip_auth_algorithm_type so users can create challenges with
specific algorithms instead of defaulting to MD5.

* pjsip_auth_create_digest() was heavily refactored to use the
new algorithm_type contained in pjsip_cred_info to determine the
algorithm to use when creating the digest.  The function is now
generic and can use any supported algorithm.  If OpenSSL isn't
available, it will fall back to the internal MD5 implementation.

* pjsip_auth_create_digestSHA256() is now marked as deprecated and
simply calls the new function with PJSIP_AUTH_ALGORITHM_SHA256.

* sip_auth_client.c and sip_auth_server.c were refactored to support
multiple digest algorithms.

* sip_auth_client was updated to allow the AKEv2-MD5 algorithm
to pass through to the callback specified in pjsip_cred_info.

* A bug was fixed with the PJSIP_AUTH_ALLOW_MULTIPLE_AUTH_HEADER
option where the default setting of 0 prevented sip_auth_client
from responding to WWW/Proxy-Authenticate headers from different
realms.  The RFCs state that this behavior should be allowed.
The comment for this option in sip_config.h was also updated to
indicate that setting this option to 1 is probably not a good idea
for security reasons.

Resolves: #4119

Author: gtjoseph

pjlib/src/pj/ssl_sock_ossl.c

@@ -713,6 +713,7 @@ static pj_status_t init_openssl(void)
 #if OPENSSL_VERSION_NUMBER < 0x009080ffL
     /* This is now synonym of SSL_library_init() */
     OpenSSL_add_all_algorithms();
+    OpenSSL_add_all_digests();
 #endif
 
     /* Init available ciphers */

pjsip/include/pjsip/sip_auth.h

@@ -42,12 +42,54 @@ PJ_BEGIN_DECL
  * @{
  */
 
-/** Length of digest MD5 string. */
+/**
+ * Length of digest MD5 string.
+ * \deprecated Use pjsip_auth_algorithm.digest_str_length instead.
+ */
 #define PJSIP_MD5STRLEN         32
 
-/** Length of digest SHA256 string. */
+/**
+ * Length of digest SHA256 string.
+ * \deprecated Use pjsip_auth_algorithm.digest_str_length instead.
+ */
 #define PJSIP_SHA256STRLEN      64
 
+/**
+ * The largest supported algorithm's digest length
+ */
+#define PJSIP_AUTH_MAX_DIGEST_BUFFER_LENGTH      64
+
+/**
+ * Digest Algorithm Types.
+ * \warning These entries must remain in order with
+ * no gaps and with _NOT_SET = 0 and _COUNT as the last entry.
+ *
+ */
+typedef enum pjsip_auth_algorithm_type
+{
+    PJSIP_AUTH_ALGORITHM_NOT_SET = 0,
+    PJSIP_AUTH_ALGORITHM_MD5,
+    PJSIP_AUTH_ALGORITHM_SHA256,
+    PJSIP_AUTH_ALGORITHM_SHA512_256,
+    PJSIP_AUTH_ALGORITHM_AKAV1_MD5,
+    PJSIP_AUTH_ALGORITHM_AKAV2_MD5,
+    PJSIP_AUTH_ALGORITHM_COUNT,
+} pjsip_auth_algorithm_type;
+
+
+typedef struct pjsip_auth_algorithm
+{
+    pjsip_auth_algorithm_type algorithm_type; /**< Digest algorithm type */
+    pj_str_t iana_name;                       /**< IANA/RFC name used in
+                                                   SIP headers           */
+    const char *openssl_name;                 /**< The name used by
+                                                   EVP_get_digestbyname()*/
+    unsigned digest_length;                   /**< Length of the raw digest
+                                                   in bytes */
+    unsigned digest_str_length;               /**< Length of the HEX
+                                                   representation        */
+} pjsip_auth_algorithm;
+
 
 /** Type of data in the credential information in #pjsip_cred_info. */
 typedef enum pjsip_cred_data_type
@@ -59,6 +101,13 @@ typedef enum pjsip_cred_data_type
 
 } pjsip_cred_data_type;
 
+#define PJSIP_CRED_DATA_PASSWD_MASK         0x000F
+#define PJSIP_CRED_DATA_EXT_MASK            0x00F0
+
+#define PJSIP_CRED_DATA_IS_AKA(cred) (((cred)->data_type & PJSIP_CRED_DATA_EXT_MASK) == PJSIP_CRED_DATA_EXT_AKA)
+#define PJSIP_CRED_DATA_IS_PASSWD(cred) (((cred)->data_type & PJSIP_CRED_DATA_PASSWD_MASK) == PJSIP_CRED_DATA_PLAIN_PASSWD)
+#define PJSIP_CRED_DATA_IS_DIGEST(cred) (((cred)->data_type & PJSIP_CRED_DATA_PASSWD_MASK) == PJSIP_CRED_DATA_DIGEST)
+
 /** Authentication's quality of protection (qop) type. */
 typedef enum pjsip_auth_qop_type
 {
@@ -102,11 +151,14 @@ typedef pj_status_t (*pjsip_cred_cb)(pj_pool_t *pool,
 /** 
  * This structure describes credential information. 
  * A credential information is a static, persistent information that identifies
- * username and password required to authorize to a specific realm.
+ * credentials required to authorize to a specific realm.
  *
  * Note that since PJSIP 0.7.0.1, it is possible to make a credential that is
  * valid for any realms, by setting the realm to star/wildcard character,
  * i.e. realm = pj_str("*");.
+ *
+ * You should always fill this structure with zeros using PJ_POOL_ZALLOC_T()
+ * or pj_bzero() before setting any fields.
  */
 struct pjsip_cred_info
 {
@@ -115,9 +167,15 @@ struct pjsip_cred_info
                                      challenges.                            */
     pj_str_t    scheme;         /**< Scheme (e.g. "digest").                */
     pj_str_t    username;       /**< User name.                             */
-    int         data_type;      /**< Type of data (0 for plaintext passwd). */
+    int         data_type;      /**< Type of data \ref pjsip_cred_data_type */
     pj_str_t    data;           /**< The data, which can be a plaintext 
                                      password or a hashed digest.           */
+    /**
+     * If the data_type is PJSIP_CRED_DATA_DIGEST and the digest algorithm
+     * used is not MD5 (the default), then this field MUST be set to the
+     * appropriate digest algorithm type.
+     */
+    pjsip_auth_algorithm_type algorithm_type;/**< Digest algorithm type */
 
     /** Extended data */
     union {
@@ -182,7 +240,8 @@ typedef struct pjsip_cached_auth
     pjsip_cached_auth_hdr        cached_hdr;/**< List of cached header for
                                                  each method.               */
 #endif
-
+    pjsip_auth_algorithm_type    challenge_algorithm_type; /**< Challenge
+                                                                algorithm   */
 } pjsip_cached_auth;
 
 
@@ -208,6 +267,44 @@ typedef struct pjsip_auth_clt_pref
 } pjsip_auth_clt_pref;
 
 
+/**
+ * Get a pjsip_auth_algorithm structure by type.
+ *
+ * @param algorithm_type  The algorithm type
+ *
+ * @return                A pointer to a pjsip_auth_algorithm structure
+ *                        or NULL if not found.
+ */
+PJ_DECL(const pjsip_auth_algorithm *) pjsip_auth_get_algorithm_by_type(
+    pjsip_auth_algorithm_type algorithm_type);
+
+
+/**
+ * Get a pjsip_auth_algorithm by IANA name.
+ *
+ * @param iana_name  The IANA name (MD5, SHA-256, SHA-512-256)
+ *
+ * @return                A pointer to a pjsip_auth_algorithm structure
+ *                        or NULL if not found.
+ */
+PJ_DECL(const pjsip_auth_algorithm *) pjsip_auth_get_algorithm_by_iana_name(
+    const pj_str_t *iana_name);
+
+
+/**
+ * Check if a digest algorithm is supported.
+ * Algorithms that require support from OpenSSL will be checked
+ * to determine if they can actually be used.
+ *
+ * @param algorithm_type  The algorithm type
+ *
+ * @return                PJ_TRUE if the algorithm is supported,
+ *                        PJ_FALSE otherwise.
+ */
+PJ_DECL(pj_bool_t) pjsip_auth_is_algorithm_supported(
+    pjsip_auth_algorithm_type algorithm_type);
+
+
 /**
  * Duplicate a client authentication preference setting.
  *
@@ -287,6 +384,7 @@ typedef struct pjsip_auth_lookup_cred_param
     pj_str_t realm;         /**< Realm to find the account.             */
     pj_str_t acc_name;      /**< Account name to look for.              */
     pjsip_rx_data *rdata;   /**< Incoming request to be authenticated.  */
+    pjsip_authorization_hdr *auth_hdr; /**< Authorization header to be authenticated. */
 
 } pjsip_auth_lookup_cred_param;
 
@@ -549,7 +647,8 @@ PJ_DECL(pj_status_t) pjsip_auth_srv_verify( pjsip_auth_srv *auth_srv,
  * Add authentication challenge headers to the outgoing response in tdata. 
  * Application may specify its customized nonce and opaque for the challenge, 
  * or can leave the value to NULL to make the function fills them in with 
- * random characters.
+ * random characters.  The digest algorithm defaults to MD5.  If you need
+ * to specify a different algorithm, use \ref pjsip_auth_srv_challenge2.
  *
  * @param auth_srv      The server authentication structure.
  * @param qop           Optional qop value.
@@ -569,9 +668,43 @@ PJ_DECL(pj_status_t) pjsip_auth_srv_challenge( pjsip_auth_srv *auth_srv,
                                                pjsip_tx_data *tdata);
 
 /**
- * Helper function to create MD5 digest out of the specified 
+ * Add authentication challenge headers to the outgoing response in tdata.
+ * Application may specify its customized nonce and opaque for the challenge,
+ * or can leave the value to NULL to make the function fills them in with
+ * random characters.
+ * Application must specify the algorithm to use.
+ *
+ * @param auth_srv      The server authentication structure.
+ * @param qop           Optional qop value.
+ * @param nonce         Optional nonce value.
+ * @param opaque        Optional opaque value.
+ * @param stale         Stale indication.
+ * @param tdata         The outgoing response message. The response must have
+ *                      401 or 407 response code.
+ * @param algorithm_type One of the \ref pjsip_auth_algorithm_type values.
+ *
+ * @return              PJ_SUCCESS on success.
+ */
+PJ_DECL(pj_status_t) pjsip_auth_srv_challenge2(pjsip_auth_srv *auth_srv,
+                                               const pj_str_t *qop,
+                                               const pj_str_t *nonce,
+                                               const pj_str_t *opaque,
+                                               pj_bool_t stale,
+                                               pjsip_tx_data *tdata,
+                                               const pjsip_auth_algorithm_type algorithm_type);
+
+/**
+ * Helper function to create a digest out of the specified
  * parameters.
  *
+ * \warning Because of ambiguities in the API, this function
+ * should only be used for backward compatibility with the
+ * MD5 digest algorithm. New code should use
+ * \ref pjsip_auth_create_digest2
+ *
+ * cred_info->data_type must be PJSIP_CRED_DATA_PLAIN_PASSWORD
+ * or PJSIP_CRED_DATA_DIGEST.
+ *
  * @param result        String to store the response digest. This string
  *                      must have been preallocated by caller with the 
  *                      buffer at least PJSIP_MD5STRLEN (32 bytes) in size.
@@ -599,6 +732,9 @@ PJ_DECL(pj_status_t) pjsip_auth_create_digest(pj_str_t *result,
 /**
  * Helper function to create SHA-256 digest out of the specified 
  * parameters.
+ * \deprecated Use \ref pjsip_auth_create_digest2 with
+ * algorithm_type = PJSIP_AUTH_ALGORITHM_SHA256.
+ *
  *
  * @param result        String to store the response digest. This string
  *                      must have been preallocated by caller with the 
@@ -614,7 +750,7 @@ PJ_DECL(pj_status_t) pjsip_auth_create_digest(pj_str_t *result,
  *
  * @return              PJ_SUCCESS on success. 
  */
-PJ_DEF(pj_status_t) pjsip_auth_create_digestSHA256(pj_str_t* result,
+PJ_DECL(pj_status_t) pjsip_auth_create_digestSHA256(pj_str_t* result,
                                             const pj_str_t* nonce,
                                             const pj_str_t* nc,
                                             const pj_str_t* cnonce,
@@ -624,6 +760,56 @@ PJ_DEF(pj_status_t) pjsip_auth_create_digestSHA256(pj_str_t* result,
                                             const pjsip_cred_info* cred_info,
                                             const pj_str_t* method);
 
+/**
+ * Helper function to create a digest out of the specified
+ * parameters.
+ *
+ * cred_info->data_type must be PJSIP_CRED_DATA_PLAIN_PASSWORD
+ * or PJSIP_CRED_DATA_DIGEST.
+ *
+ * If cred_info->data_type is PJSIP_CRED_DATA_PLAIN_PASSWORD,
+ * cred_info->username + ":" + realm + ":" + cred_info->data
+ * will be hashed using the algorithm_type specified by the last
+ * parameter passed to this function to create the "ha1" hash.
+ *
+ * If cred_info->data_type is PJSIP_CRED_DATA_DIGEST,
+ * cred_info->data must contain the value of
+ * username + ":" + realm + ":" + password pre-hashed
+ * with the algorithm specifed by cred_info->algorithm_type
+ * and will be used as the "ha1" hash directly.  In this case
+ * cred_info->algorithm_type MUST match the algorithm_type
+ * passed as the last parameter to this function.
+ *
+ * \note If left unset (0), cred_info->algorithm_type will
+ * default to PJSIP_AUTH_ALGORITHM_MD5.
+ *
+ * @param result         String to store the response digest. This string
+ *                       must have been preallocated by the caller with the
+ *                       buffer at least as large as the digest_str_length
+ *                       member of the appropriate pjsip_auth_algorithm.
+ * @param nonce          Optional nonce.
+ * @param nc             Nonce count.
+ * @param cnonce         Optional cnonce.
+ * @param qop            Optional qop.
+ * @param uri            URI.
+ * @param realm          Realm.
+ * @param cred_info      Credential info.
+ * @param method         SIP method.
+ * @param algorithm_type The hash algorithm to use.
+ *
+ * @return              PJ_SUCCESS on success.
+ */
+PJ_DECL(pj_status_t) pjsip_auth_create_digest2(pj_str_t *result,
+                                 const pj_str_t *nonce,
+                                 const pj_str_t *nc,
+                                 const pj_str_t *cnonce,
+                                 const pj_str_t *qop,
+                                 const pj_str_t *uri,
+                                 const pj_str_t *realm,
+                                 const pjsip_cred_info *cred_info,
+                                 const pj_str_t *method,
+                                 const pjsip_auth_algorithm_type algorithm_type);
+
 /**
  * @}
  */

pjsip/include/pjsip/sip_config.h

@@ -1345,10 +1345,25 @@ PJ_INLINE(pjsip_cfg_t*) pjsip_cfg(void)
 #endif
 
 /**
- * Allow client to send multiple Authorization header when receiving multiple 
- * WWW-Authenticate header fields. If this is disabled, the stack will send
- * Authorization header field containing credentials that match the
- * topmost header field.
+ * RFC-7616 and RFC-8760 state that for each realm a UAS requires authentication
+ * for it can send a WWW/Proxy-Authenticate header for each digest algorithm it
+ * supports and for each realm, they must be added in most-preferred to least-
+ * preferred order.  The RFCs also state that the UAS MUST NOT send multiple
+ * WWW/Proxy-Authenticate headers with the same realm and algorithm.
+ *
+ * The RFCs also state that the UAC SHOULD respond to the topmost header
+ * for each realm containing a digest algorithm it supports.  Neither RFC
+ * however, states whether the UAC should send multiple Authorization headers
+ * for the same realm if it can support multiple digest algorithms.  Common
+ * sense dicates though that the UAC should NOT send additional Authorization
+ * headers for the same realm once it's already sent a more preferred one.
+ * The reasoning is simple...  If a UAS sends two WWW-Authenticate headers,
+ * the first for SHA-256 and the second for MD5, a UAC responding to both
+ * completely defeats the purpose of the UAS sending the more secure SHA-256.
+ *
+ * Having said that, if there is some corner case where continuing to send
+ * additional Authorization headers for the same realm is necessary, then
+ * this define can be set to 1 to allow it.
  *
  * Default is 0
  */

pjsip/src/pjsip/sip_auth_aka.c

@@ -147,9 +147,10 @@ PJ_DEF(pj_status_t) pjsip_auth_create_aka_response(
         aka_cred.data.ptr = (char*)res;
         aka_cred.data.slen = PJSIP_AKA_RESLEN;
 
-        status = pjsip_auth_create_digest(&auth->response, &chal->nonce, 
+        status = pjsip_auth_create_digest2(&auth->response, &chal->nonce,
                                  &auth->nc, &auth->cnonce, &auth->qop, 
-                                 &auth->uri, &chal->realm, &aka_cred, method);  
+                                 &auth->uri, &chal->realm, &aka_cred, method,
+                                 PJSIP_AUTH_ALGORITHM_MD5);
 
     } else if (aka_version == 2) {
 
@@ -186,9 +187,10 @@ PJ_DEF(pj_status_t) pjsip_auth_create_aka_response(
                          aka_cred.data.ptr, &len);
         aka_cred.data.slen = hmac64_len;
 
-        status = pjsip_auth_create_digest(&auth->response, &chal->nonce, 
+        status = pjsip_auth_create_digest2(&auth->response, &chal->nonce,
                                  &auth->nc, &auth->cnonce, &auth->qop, 
-                                 &auth->uri, &chal->realm, &aka_cred, method);
+                                 &auth->uri, &chal->realm, &aka_cred, method,
+                                 PJSIP_AUTH_ALGORITHM_MD5);
 
     } else {
         pj_assert(!"Bug!");