Section 22 Usage of HTTP Authentication

SIP provides a stateless, challenge-based mechanism for
   authentication that is based on authentication in HTTP.  Any time
   that a proxy server or UA receives a request (with the exceptions
   given in Section 22.1), it MAY challenge the initiator of the request
   to provide assurance of its identity.  Once the originator has been
   identified, the recipient of the request SHOULD ascertain whether or
   not this user is authorized to make the request in question.  No
   authorization systems are recommended or discussed in this document.
   The "Digest" authentication mechanism described in this section
   provides message authentication and replay protection only, without
   message integrity or confidentiality.  Protective measures above and
   beyond those provided by Digest need to be taken to prevent active
   attackers from modifying SIP requests and responses.
   Note that due to its weak security, the usage of "Basic"
   authentication has been deprecated.  Servers MUST NOT accept
   credentials using the "Basic" authorization scheme, and servers also
   MUST NOT challenge with "Basic".  This is a change from RFC 2543.
22.1 Framework
   The framework for SIP authentication closely parallels that of HTTP
   (RFC 2617 [17]).  In particular, the BNF for auth-scheme, auth-param,
   challenge, realm, realm-value, and credentials is identical (although
   the usage of "Basic" as a scheme is not permitted).  In SIP, a UAS
   uses the 401 (Unauthorized) response to challenge the identity of a
   UAC.  Additionally, registrars and redirect servers MAY make use of
   401 (Unauthorized) responses for authentication, but proxies MUST
   NOT, and instead MAY use the 407 (Proxy Authentication Required)
   response.  The requirements for inclusion of the Proxy-Authenticate,
   Proxy-Authorization, WWW-Authenticate, and Authorization in the
   various messages are identical to those described in RFC 2617 [17].
   Since SIP does not have the concept of a canonical root URL, the
   notion of protection spaces is interpreted differently in SIP.  The
   realm string alone defines the protection domain.  This is a change
   from RFC 2543, in which the Request-URI and the realm together
   defined the protection domain.
      This previous definition of protection domain caused some amount
      of confusion since the Request-URI sent by the UAC and the
      Request-URI received by the challenging server might be different,
      and indeed the final form of the Request-URI might not be known to
      the UAC.  Also, the previous definition depended on the presence
      of a SIP URI in the Request-URI and seemed to rule out alternative
      URI schemes (for example, the tel URL).
   Operators of user agents or proxy servers that will authenticate
   received requests MUST adhere to the following guidelines for
   creation of a realm string for their server:
      o  Realm strings MUST be globally unique.  It is RECOMMENDED that
         a realm string contain a hostname or domain name, following the
         recommendation in Section 3.2.1 of RFC 2617 [17].
      o  Realm strings SHOULD present a human-readable identifier that
         can be rendered to a user.
   For example:
      INVITE sip:bob@biloxi.com SIP/2.0
      Authorization: Digest realm="biloxi.com", <...>
   Generally, SIP authentication is meaningful for a specific realm, a
   protection domain.  Thus, for Digest authentication, each such
   protection domain has its own set of usernames and passwords.  If a
   server does not require authentication for a particular request, it
   MAY accept a default username, "anonymous", which has no password
   (password of "").  Similarly, UACs representing many users, such as
   PSTN gateways, MAY have their own device-specific username and
   password, rather than accounts for particular users, for their realm.
   While a server can legitimately challenge most SIP requests, there
   are two requests defined by this document that require special
   handling for authentication: ACK and CANCEL.
   Under an authentication scheme that uses responses to carry values
   used to compute nonces (such as Digest), some problems come up for
   any requests that take no response, including ACK.  For this reason,
   any credentials in the INVITE that were accepted by a server MUST be
   accepted by that server for the ACK.  UACs creating an ACK message
   will duplicate all of the Authorization and Proxy-Authorization
   header field values that appeared in the INVITE to which the ACK
   corresponds.  Servers MUST NOT attempt to challenge an ACK.
   Although the CANCEL method does take a response (a 2xx), servers MUST
   NOT attempt to challenge CANCEL requests since these requests cannot
   be resubmitted.  Generally, a CANCEL request SHOULD be accepted by a
   server if it comes from the same hop that sent the request being
   canceled (provided that some sort of transport or network layer
   security association, as described in Section 26.2.1, is in place).
   When a UAC receives a challenge, it SHOULD render to the user the
   contents of the "realm" parameter in the challenge (which appears in
   either a WWW-Authenticate header field or Proxy-Authenticate header
   field) if the UAC device does not already know of a credential for
   the realm in question.  A service provider that pre-configures UAs
   with credentials for its realm should be aware that users will not
   have the opportunity to present their own credentials for this realm
   when challenged at a pre-configured device.
   Finally, note that even if a UAC can locate credentials that are
   associated with the proper realm, the potential exists that these
   credentials may no longer be valid or that the challenging server
   will not accept these credentials for whatever reason (especially
   when "anonymous" with no password is submitted).  In this instance a
   server may repeat its challenge, or it may respond with a 403
   Forbidden.  A UAC MUST NOT re-attempt requests with the credentials
   that have just been rejected (though the request may be retried if
   the nonce was stale).
22.2 User-to-User Authentication
   When a UAS receives a request from a UAC, the UAS MAY authenticate
   the originator before the request is processed.  If no credentials
   (in the Authorization header field) are provided in the request, the
   UAS can challenge the originator to provide credentials by rejecting
   the request with a 401 (Unauthorized) status code.
   The WWW-Authenticate response-header field MUST be included in 401
   (Unauthorized) response messages.  The field value consists of at
   least one challenge that indicates the authentication scheme(s) and
   parameters applicable to the realm.
   An example of the WWW-Authenticate header field in a 401 challenge
   is:
      WWW-Authenticate: Digest
              realm="biloxi.com",
              qop="auth,auth-int",
              nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093",
              opaque="5ccc069c403ebaf9f0171e9517f40e41"
   When the originating UAC receives the 401 (Unauthorized), it SHOULD,
   if it is able, re-originate the request with the proper credentials.
   The UAC may require input from the originating user before
   proceeding.  Once authentication credentials have been supplied
   (either directly by the user, or discovered in an internal keyring),
   UAs SHOULD cache the credentials for a given value of the To header
   field and "realm" and attempt to re-use these values on the next
   request for that destination.  UAs MAY cache credentials in any way
   they would like.
   If no credentials for a realm can be located, UACs MAY attempt to
   retry the request with a username of "anonymous" and no password (a
   password of "").
   Once credentials have been located, any UA that wishes to
   authenticate itself with a UAS or registrar -- usually, but not
   necessarily, after receiving a 401 (Unauthorized) response -- MAY do
   so by including an Authorization header field with the request.  The
   Authorization field value consists of credentials containing the
   authentication information of the UA for the realm of the resource
   being requested as well as parameters required in support of
   authentication and replay protection.
   An example of the Authorization header field is:
      Authorization: Digest username="bob",
              realm="biloxi.com",
              nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093",
              uri="sip:bob@biloxi.com",
              qop=auth,
              nc=00000001,
              cnonce="0a4f113b",
              response="6629fae49393a05397450978507c4ef1",
              opaque="5ccc069c403ebaf9f0171e9517f40e41"
   When a UAC resubmits a request with its credentials after receiving a
   401 (Unauthorized) or 407 (Proxy Authentication Required) response,
   it MUST increment the CSeq header field value as it would normally
   when sending an updated request.
22.3 Proxy-to-User Authentication
   Similarly, when a UAC sends a request to a proxy server, the proxy
   server MAY authenticate the originator before the request is
   processed.  If no credentials (in the Proxy-Authorization header
   field) are provided in the request, the proxy can challenge the
   originator to provide credentials by rejecting the request with a 407
   (Proxy Authentication Required) status code.  The proxy MUST populate
   the 407 (Proxy Authentication Required) message with a Proxy-
   Authenticate header field value applicable to the proxy for the
   requested resource.
   The use of Proxy-Authenticate and Proxy-Authorization parallel that
   described in [17], with one difference.  Proxies MUST NOT add values
   to the Proxy-Authorization header field.  All 407 (Proxy
   Authentication Required) responses MUST be forwarded upstream toward
   the UAC following the procedures for any other response.  It is the
   UAC's responsibility to add the Proxy-Authorization header field
   value containing credentials for the realm of the proxy that has
   asked for authentication.
      If a proxy were to resubmit a request adding a Proxy-Authorization
      header field value, it would need to increment the CSeq in the new
      request.  However, this would cause the UAC that submitted the
      original request to discard a response from the UAS, as the CSeq
      value would be different.
   When the originating UAC receives the 407 (Proxy Authentication
   Required) it SHOULD, if it is able, re-originate the request with the
   proper credentials.  It should follow the same procedures for the
   display of the "realm" parameter that are given above for responding
   to 401.
   If no credentials for a realm can be located, UACs MAY attempt to
   retry the request with a username of "anonymous" and no password (a
   password of "").
   The UAC SHOULD also cache the credentials used in the re-originated
   request.
   The following rule is RECOMMENDED for proxy credential caching:
   If a UA receives a Proxy-Authenticate header field value in a 401/407
   response to a request with a particular Call-ID, it should
   incorporate credentials for that realm in all subsequent requests
   that contain the same Call-ID.  These credentials MUST NOT be cached
   across dialogs; however, if a UA is configured with the realm of its
   local outbound proxy, when one exists, then the UA MAY cache
   credentials for that realm across dialogs.  Note that this does mean
   a future request in a dialog could contain credentials that are not
   needed by any proxy along the Route header path.
   Any UA that wishes to authenticate itself to a proxy server --
   usually, but not necessarily, after receiving a 407 (Proxy
   Authentication Required) response -- MAY do so by including a Proxy-
   Authorization header field value with the request.  The Proxy-
   Authorization request-header field allows the client to identify
   itself (or its user) to a proxy that requires authentication.  The
   Proxy-Authorization header field value consists of credentials
   containing the authentication information of the UA for the proxy
   and/or realm of the resource being requested.
   A Proxy-Authorization header field value applies only to the proxy
   whose realm is identified in the "realm" parameter (this proxy may
   previously have demanded authentication using the Proxy-Authenticate
   field).  When multiple proxies are used in a chain, a Proxy-
   Authorization header field value MUST NOT be consumed by any proxy
   whose realm does not match the "realm" parameter specified in that
   value.
   Note that if an authentication scheme that does not support realms is
   used in the Proxy-Authorization header field, a proxy server MUST
   attempt to parse all Proxy-Authorization header field values to
   determine whether one of them has what the proxy server considers to
   be valid credentials.  Because this is potentially very time-
   consuming in large networks, proxy servers SHOULD use an
   authentication scheme that supports realms in the Proxy-Authorization
   header field.
   If a request is forked (as described in Section 16.7), various proxy
   servers and/or UAs may wish to challenge the UAC.  In this case, the
   forking proxy server is responsible for aggregating these challenges
   into a single response.  Each WWW-Authenticate and Proxy-Authenticate
   value received in responses to the forked request MUST be placed into
   the single response that is sent by the forking proxy to the UA; the
   ordering of these header field values is not significant.
      When a proxy server issues a challenge in response to a request,
      it will not proxy the request until the UAC has retried the
      request with valid credentials.  A forking proxy may forward a
      request simultaneously to multiple proxy servers that require
      authentication, each of which in turn will not forward the request
      until the originating UAC has authenticated itself in their
      respective realm.  If the UAC does not provide credentials for
      each challenge, the proxy servers that issued the challenges will
      not forward requests to the UA where the destination user might be
      located, and therefore, the virtues of forking are largely lost.
   When resubmitting its request in response to a 401 (Unauthorized) or
   407 (Proxy Authentication Required) that contains multiple
   challenges, a UAC MAY include an Authorization value for each WWW-
   Authenticate value and a Proxy-Authorization value for each Proxy-
   Authenticate value for which the UAC wishes to supply a credential.
   As noted above, multiple credentials in a request SHOULD be
   differentiated by the "realm" parameter.
   It is possible for multiple challenges associated with the same realm
   to appear in the same 401 (Unauthorized) or 407 (Proxy Authentication
   Required).  This can occur, for example, when multiple proxies within
   the same administrative domain, which use a common realm, are reached
   by a forking request.  When it retries a request, a UAC MAY therefore
   supply multiple credentials in Authorization or Proxy-Authorization
   header fields with the same "realm" parameter value.  The same
   credentials SHOULD be used for the same realm.
22.4 The Digest Authentication Scheme
   This section describes the modifications and clarifications required
   to apply the HTTP Digest authentication scheme to SIP.  The SIP
   scheme usage is almost completely identical to that for HTTP [17].
   Since RFC 2543 is based on HTTP Digest as defined in RFC 2069 [39],
   SIP servers supporting RFC 2617 MUST ensure they are backwards
   compatible with RFC 2069.  Procedures for this backwards
   compatibility are specified in RFC 2617.  Note, however, that SIP
   servers MUST NOT accept or request Basic authentication.
   The rules for Digest authentication follow those defined in [17],
   with "HTTP/1.1" replaced by "SIP/2.0" in addition to the following
   differences:
      1.  The URI included in the challenge has the following BNF:
          URI  =  SIP-URI / SIPS-URI
      2.  The BNF in RFC 2617 has an error in that the 'uri' parameter
          of the Authorization header field for HTTP Digest
          authentication is not enclosed in quotation marks.  (The
          example in Section 3.5 of RFC 2617 is correct.)  For SIP, the
          'uri' MUST be enclosed in quotation marks.
      3.  The BNF for digest-uri-value is:
          digest-uri-value  =  Request-URI ; as defined in Section 25
      4.  The example procedure for choosing a nonce based on Etag does
          not work for SIP.
      5.  The text in RFC 2617 [17] regarding cache operation does not
          apply to SIP.
      6.  RFC 2617 [17] requires that a server check that the URI in the
          request line and the URI included in the Authorization header
          field point to the same resource.  In a SIP context, these two
          URIs may refer to different users, due to forwarding at some
          proxy.  Therefore, in SIP, a server MAY check that the
          Request-URI in the Authorization header field value
          corresponds to a user for whom the server is willing to accept
          forwarded or direct requests, but it is not necessarily a
          failure if the two fields are not equivalent.
      7.  As a clarification to the calculation of the A2 value for
          message integrity assurance in the Digest authentication
          scheme, implementers should assume, when the entity-body is
          empty (that is, when SIP messages have no body) that the hash
          of the entity-body resolves to the MD5 hash of an empty
          string, or:
             H(entity-body) = MD5("") =
          "d41d8cd98f00b204e9800998ecf8427e"
      8.  RFC 2617 notes that a cnonce value MUST NOT be sent in an
          Authorization (and by extension Proxy-Authorization) header
          field if no qop directive has been sent.  Therefore, any
          algorithms that have a dependency on the cnonce (including
          "MD5-Sess") require that the qop directive be sent.  Use of
          the "qop" parameter is optional in RFC 2617 for the purposes
          of backwards compatibility with RFC 2069; since RFC 2543 was
          based on RFC 2069, the "qop" parameter must unfortunately
          remain optional for clients and servers to receive.  However,
          servers MUST always send a "qop" parameter in WWW-Authenticate
          and Proxy-Authenticate header field values.  If a client
          receives a "qop" parameter in a challenge header field, it
          MUST send the "qop" parameter in any resulting authorization
          header field.
   RFC 2543 did not allow usage of the Authentication-Info header field
   (it effectively used RFC 2069).  However, we now allow usage of this
   header field, since it provides integrity checks over the bodies and
   provides mutual authentication.  RFC 2617 [17] defines mechanisms for
   backwards compatibility using the qop attribute in the request.
   These mechanisms MUST be used by a server to determine if the client
   supports the new mechanisms in RFC 2617 that were not specified in
   RFC 2069.