Helper.hxx

Go to the documentation of this file.

#if !defined(RESIP_HELPER_HXX)
#define RESIP_HELPER_HXX 
 
#include <time.h>
#include <vector>
 
#include "resip/stack/NonceHelper.hxx"
#include "resip/stack/Symbols.hxx"
#include "resip/stack/Uri.hxx"
#include "resip/stack/MethodTypes.hxx"
#include "rutil/BaseException.hxx"
#include "rutil/Data.hxx"
#include "rutil/DigestStream.hxx"
#include "resip/stack/Contents.hxx"
#include "resip/stack/SecurityAttributes.hxx"
#include "resip/stack/SdpContents.hxx"
 
namespace resip
{
 
class SipMessage;
class NameAddr;
class SecurityAttributes;
class Security;
 
 
class Helper
{
   public:
 
      const static int tagSize;
 
      template<typename T>
      static T aBitSmallerThan(T secs)
      {
         return resipMax(T(0), resipMin(T(secs-5), T(9*secs/10)));
      }
 
      static void integer2hex(char* _d, unsigned int _s, bool _l = true);
 
      static unsigned int hex2integer(const char* _s);
 
      static int jitterValue(int input, int lowerPercentage, int upperPercentage, int minimum=0);
 
 
 
      static SipMessage* makeRequest(const NameAddr& target, const NameAddr& from, const NameAddr& contact, MethodTypes method);
 
      static SipMessage* makeRequest(const NameAddr& target, const NameAddr& from, MethodTypes method);
 
      static SipMessage* makeRegister(const NameAddr& to, const NameAddr& from);
 
      static SipMessage* makeRegister(const NameAddr& to, const NameAddr& from, const NameAddr& contact);
 
      static SipMessage* makeRegister(const NameAddr& to, const Data& transport);
 
      static SipMessage* makeRegister(const NameAddr& to, const Data& transport, const NameAddr& contact);
 
      static SipMessage* makeInvite(const NameAddr& target, const NameAddr& from);
      
      static SipMessage* makeInvite(const NameAddr& target, const NameAddr& from, const NameAddr& contact);
 
      static SipMessage* makeCancel(const SipMessage& request);
 
      static SipMessage* makeFailureAck(const SipMessage& request, const SipMessage& response);
 
      static SipMessage* makePublish(const NameAddr& target, const NameAddr& from);
 
      static SipMessage* makePublish(const NameAddr& target, const NameAddr& from, const NameAddr& contact);
 
      static SipMessage* makeMessage(const NameAddr& target, const NameAddr& from);
 
      static SipMessage* makeMessage(const NameAddr& target, const NameAddr& from, const NameAddr& contact);
 
      static SipMessage* makeSubscribe(const NameAddr& target, const NameAddr& from);
 
      static SipMessage* makeSubscribe(const NameAddr& target, const NameAddr& from, const NameAddr& contact);
 
      static void makeResponse(SipMessage& response, 
                               const SipMessage& request, 
                               int responseCode, 
                               const Data& reason = Data::Empty,
                               const Data& hostname = Data::Empty,
                               const Data& warning=Data::Empty);
 
      static void makeResponse(SipMessage& response, 
                               const SipMessage& request, 
                               int responseCode, 
                               const NameAddr& myContact, 
                               const Data& reason = Data::Empty,
                               const Data& hostname = Data::Empty,
                               const Data& warning=Data::Empty);
 
      static SipMessage* makeResponse(const SipMessage& request,
                                      int responseCode,
                                      const Data& reason = Data::Empty, 
                                      const Data& hostname = Data::Empty,
                                      const Data& warning=Data::Empty);
 
      static SipMessage* makeResponse(const SipMessage& request, 
                                      int responseCode, 
                                      const NameAddr& myContact, 
                                      const Data& reason = Data::Empty,
                                      const Data& hostname = Data::Empty,
                                      const Data& warning=Data::Empty);
 
      static void makeRawResponse(Data& rawBuffer,
                                    const SipMessage& request, 
                                    int responseCode,
                                    const Data& additionalHeaders=Data::Empty,
                                    const Data& body=Data::Empty);
 
      static SipMessage* make405(const SipMessage& request,
                                 const int* allowedMethods = 0,
                                 int nMethods = -1);
 
      static void getResponseCodeReason(int responseCode, Data& reason);
 
      static Data computeUniqueBranch();
 
      static Data computeCallId();
      static Data computeTag(int numBytes);
 
 
      
      static void setNonceHelper(NonceHelper* nonceHelper);
      static NonceHelper* getNonceHelper();
      static Data makeNonce(const SipMessage& request, const Data& timestamp);
 
      // returns true if the digest scheme is supported, and sets digestType
      static bool isDigestAlgorithmSupported(const Auth& auth, DigestType& digestType);
      static bool isDigestAlgorithmSupported(const Data& algorithmName, DigestType& digestType);
 
      // Create a custom A1 string (applicable for password storage, that supports multiple digest algorithms)
      // Format: [<algorithm_name>]<hex_encoded_A1_hash>[<algorithm2_name>]<hex_encoded_A1_hash2>....
      // Example: [MD5]5f4dcc3b5aa765d61d8327deb882cf99[SHA-256]6bb4837eb74329105ee4568dda7dc67ed2ca2ad9e59fcbfbcde5e7f8c1b6d9d1
      // For backward compatibility, if no algorithm name is found, MD5 is assumed.
      static Data createResipA1HashString(const Data& username,
                                          const Data& realm,
                                          const Data& password);
      // Extract the algorithm specific A1 hash from a custom resip A1 hash string. Returns empty string if hash 
      // algorithm not found in string.
      static Data extractA1FromResipA1HashString(const Data& resipA1HashString, DigestType digestType);
      static bool isDigestTypeSupportedInResipA1HashString(const Data& resipA1HashString, DigestType digestType);
 
      enum AuthResult { Failed = 1, Authenticated, Expired, BadlyFormed };
      static AuthResult authenticateRequest(const SipMessage& request,
                                            const Data& realm,
                                            const Data& password,
                                            int expiresDelta = 0);
 
      static AuthResult authenticateRequestWithA1(const SipMessage& request, 
                                                  const Data& realm,
                                                  const Data& resipPasswordHashA1,
                                                  int expiresDelta = 0);
 
      static AuthResult authenticateRequest(const SipMessage& request, 
                                            const Data& realm,
                                            const Data& passwordOrResipPasswordHashA1,
                                            int expiresDelta,
                                            bool isPasswordHashResipA1);
 
      // Only looks a Proxy-Authorization or Authorization header based on proxyAuthorization flag
      // Returns username in std::pair second if authentication is successful
      static std::pair<AuthResult, Data> advancedAuthenticateRequest(const SipMessage& request,
                                                                     const Data& realm,
                                                                     const Data& resipPasswordHashA1,
                                                                     int expiresDelta = 0,
                                                                     bool proxyAuthorization = true);
 
      // create a 407 response with Proxy-Authenticate header filled in
      static SipMessage* makeProxyChallenge(const SipMessage& request, 
                                            const Data& realm,
                                            bool useAuth = true,
                                            bool stale = false,
                                            const std::vector<DigestType>& digestTypes = std::vector<DigestType>());
 
      // create a 401 response with WWW-Authenticate header filled in
      static SipMessage* makeWWWChallenge(const SipMessage& request, 
                                          const Data& realm,
                                          bool useAuth = true,
                                          bool stale = false,
                                          const std::vector<DigestType>& digestTypes = std::vector<DigestType>());
 
      // create a 401 or 407 response with Proxy-Authenticate or Authenticate header 
      // filled in
      static SipMessage* makeChallenge(const SipMessage& request, 
                                       const Data& realm,
                                       bool useAuth = true,
                                       bool stale = false,
                                       bool proxy = false,
                                       const std::vector<DigestType>& digestTypes = std::vector<DigestType>());
 
      // add an additional Proxy-Authenticate or WWW-Authenticate header to an existing response
      static void addChallenge(SipMessage& response,
                               const SipMessage& request,
                               const Data& realm,
                               bool useAuth = true,
                               bool stale = false,
                               bool proxy = false,
                               DigestType digestType = MD5);
 
      static Data qopOption(const Auth& challenge);
      static void updateNonceCount(unsigned int& nonceCount, Data& nonceCountString);
 
      //Used by clients to determine if they can respond to a given challenge
      static bool algorithmAndQopSupported(const Auth& challenge);
      static bool algorithmAndQopSupported(const Auth& challenge, DigestType& digestType);
 
      // adds authorization headers in reponse to the 401 or 407
      static SipMessage& addAuthorization(SipMessage& request,
                                          const SipMessage& challenge,
                                          const Data& username,
                                          const Data& password,
                                          const Data& cnonce,
                                          unsigned int& nonceCount);
 
      static Auth makeChallengeResponseAuth(const SipMessage& request,
                                            const Data& username,
                                            const Data& password,
                                            const Auth& challenge,
                                            const Data& cnonce,
                                            unsigned int& nonceCount,
                                            Data& nonceCountString);
 
      static void makeChallengeResponseAuth(const SipMessage& request,
                                            const Data& username,
                                            const Data& password,
                                            const Auth& challenge,
                                            const Data& cnonce,
                                            const Data& authQop,
                                            const Data& nonceCountString,
                                            Auth& auth);
 
      static Auth makeChallengeResponseAuthWithA1(const SipMessage& request,
                                                  const Data& username,
                                                  const Data& resipPasswordHashA1,
                                                  const Auth& challenge,
                                                  const Data& cnonce,
                                                  unsigned int& nonceCount,
                                                  Data& nonceCountString);
 
      static void makeChallengeResponseAuthWithA1(const SipMessage& request,
                                                  const Data& username,
                                                  const Data& resipPasswordHashA1,
                                                  const Auth& challenge,
                                                  const Data& cnonce,
                                                  const Data& authQop,
                                                  const Data& nonceCountString,
                                                  Auth& auth);
 
      // Backwards compatiblity (legacy API)
      static Data makeResponseMD5WithA1(const Data& a1,
                                        const Data& method, const Data& digestUri, const Data& nonce,
                                        const Data& qop = Data::Empty, const Data& cnonce = Data::Empty, 
                                        const Data& cnonceCount = Data::Empty, const Contents *entityBody = 0)
      {
         return makeResponseDigestWithA1(a1, method, digestUri, nonce, qop, cnonce, cnonceCount, entityBody, MD5);
      }
 
      static Data makeResponseDigestWithA1(const Data& a1,
                                           const Data& method, const Data& digestUri, const Data& nonce,
                                           const Data& qop = Data::Empty, const Data& cnonce = Data::Empty,
                                           const Data& cnonceCount = Data::Empty, const Contents* entityBody = 0,
                                           DigestType digestType = MD5);
 
      // Backwards compatiblity (legacy API)
      static Data makeResponseMD5(const Data& username, const Data& password, const Data& realm, 
                                  const Data& method, const Data& digestUri, const Data& nonce,
                                  const Data& qop = Data::Empty, const Data& cnonce = Data::Empty, 
                                  const Data& cnonceCount = Data::Empty, const Contents *entityBody = 0)
      {
         return makeResponseDigest(username, password, realm, method, digestUri, nonce, qop, cnonce, cnonceCount, entityBody, MD5);
      }
 
      static Data makeResponseDigest(const Data& username, const Data& password, const Data& realm, 
                                     const Data& method, const Data& digestUri, const Data& nonce,
                                     const Data& qop = Data::Empty, const Data& cnonce = Data::Empty, 
                                     const Data& cnonceCount = Data::Empty, const Contents *entityBody = 0,
                                     DigestType digestType = MD5);
 
 
 
      static Uri makeUri(const Data& aor, const Data& scheme=Symbols::DefaultSipScheme);
 
      static void processStrictRoute(SipMessage& request);
 
      // return the port that the response should be sent to using rules from 
      // RFC 3261 - 18.2.2
      static int getPortForReply(SipMessage& request);
 
      static void massageRoute(const SipMessage& request, NameAddr& route);
 
      static Uri fromAor(const Data& aor, const Data& scheme=Symbols::DefaultSipScheme);
 
      // Do basic checks to validate a received message off the wire
      // If the basic check fails, and reason is non-null, reason will be set
      // to the reason the check failed. This function does not take ownership
      // of reason.
      static bool validateMessage(const SipMessage& message,resip::Data* reason=0);
 
      // GRUU support -- reversibly and opaquely combine instance id and aor
      static Data gruuUserPart(const Data& instanceId,
                               const Data& aor,
                               const Data& key);
 
      // GRUU support -- extract instance id and aor from user portion
      static std::pair<Data,Data> fromGruuUserPart(const Data& gruuUserPart,
                                                   const Data& key);
 
      struct ContentsSecAttrs
      {
            ContentsSecAttrs() = default;
            ContentsSecAttrs(std::unique_ptr<Contents> contents,
                             std::unique_ptr<SecurityAttributes> attributes);
            ContentsSecAttrs(const ContentsSecAttrs&) = delete;
            ContentsSecAttrs(ContentsSecAttrs&&) = default;
            ~ContentsSecAttrs() = default;
 
            ContentsSecAttrs& operator=(const ContentsSecAttrs&) = delete;
            ContentsSecAttrs& operator=(ContentsSecAttrs&&) = default;
 
            mutable std::unique_ptr<Contents> mContents;
            mutable std::unique_ptr<SecurityAttributes> mAttributes;
      };
 
      static ContentsSecAttrs extractFromPkcs7(const SipMessage& message, Security& security);
 
      
      enum FailureMessageEffect{ DialogTermination, TransactionTermination, UsageTermination, 
                                 RetryAfter, OptionalRetryAfter, ApplicationDependant };
      
      static FailureMessageEffect determineFailureMessageEffect(const SipMessage& response,
          const std::set<int>* additionalTransactionTerminatingResponses = NULL);
 
      static SdpContents* getSdpRecurse(Contents* tree);
 
      // Just simply walk the contents tree and return acopy of the first SdpContents in
      // the tree.
      static std::unique_ptr<SdpContents> getSdp(Contents* tree);
 
      static bool isClientBehindNAT(const SipMessage& request, bool privateToPublicOnly=true);
 
      static Tuple getClientPublicAddress(const SipMessage& request);
 
   private:
      class NonceHelperPtr
      {
         public:
            NonceHelperPtr() : mNonceHelper(0) {}
            ~NonceHelperPtr() { delete mNonceHelper; }
            NonceHelper *mNonceHelper;
      };
      static NonceHelperPtr mNonceHelperPtr;
};
 
}
 
#endif
 
/* ====================================================================
 * The Vovida Software License, Version 1.0 
 * 
 * Copyright (c) 2026 SIP Spectrum, Inc. https://www.sipspectrum.com
 * Copyright (c) 2000 Vovida Networks, Inc.  All rights reserved.
 * 
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 * 
 * 3. The names "VOCAL", "Vovida Open Communication Application Library",
 *    and "Vovida Open Communication Application Library (VOCAL)" must
 *    not be used to endorse or promote products derived from this
 *    software without prior written permission. For written
 *    permission, please contact vocal@vovida.org.
 *
 * 4. Products derived from this software may not be called "VOCAL", nor
 *    may "VOCAL" appear in their name, without prior written
 *    permission of Vovida Networks, Inc.
 * 
 * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND
 * NON-INFRINGEMENT ARE DISCLAIMED.  IN NO EVENT SHALL VOVIDA
 * NETWORKS, INC. OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT DAMAGES
 * IN EXCESS OF $1,000, NOR FOR ANY INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
 * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
 * USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
 * DAMAGE.
 * 
 * ====================================================================
 * 
 * This software consists of voluntary contributions made by Vovida
 * Networks, Inc. and many individuals on behalf of Vovida Networks,
 * Inc.  For more information on Vovida Networks, Inc., please see
 * <http://www.vovida.org/>.
 *
 */