\section{Usage of HTTP Authentication}
\label{sec:security:auth}

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~\ref{sec:security:auth:framework}), 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 {\MUSTNOT} accept
credentials using the ``Basic'' authorization scheme, and servers also
{\MUSTNOT} challenge with ``Basic''.  This is a change from RFC~2543.


\subsection{Framework}
\label{sec:security:auth:framework}

The framework for SIP authentication closely parallels that of HTTP 
(RFC~2617~\citenorm{rfc2617}).  In particular, the BNF for \header{auth-scheme},
\header{auth-param}, \header{challenge}, \header{realm},
\header{realm-value}, and \header{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
{\MUSTNOT}, and instead {\MAY} use the 407 (Proxy Authentication
Required) response.  The requirements for inclusion of the
\header{Proxy-Authenticate}, \header{Proxy-Authorization},
\header{WWW-Authenticate}, and \header{Authorization} in the various
messages are identical to those described in RFC~2617~\citenorm{rfc2617}.


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 \header{Request-URI} and the realm together
defined the protection domain.
 
\motivation{This previous definition of protection domain caused some amount
of confusion since the \header{Request-URI} sent by the UAC and the
\header{Request-URI} received by the challenging server might be
different, and indeed the final form of the \header{Request-URI} might
not be known to the UAC. Also, the previous definition depended on the
presence of a SIP URI in the \header{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:

\begin{itemize}
\item 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~\citenorm{rfc2617}.

\item Realm strings {\SHOULD} present a human-readable identifier that
can be rendered to a user.
\end{itemize}

For example:

\begin{verbatim}
   INVITE sip:bob@biloxi.com SIP/2.0
   Authorization: Digest realm="biloxi.com", <...>
\end{verbatim}


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 \header{Authorization} and
\header{Proxy-Authorization} header field values that appeared in the {\INVITE} to
which the {\ACK} corresponds.
Servers {\MUSTNOT} attempt to challenge an {\ACK}.

Although the {\CANCEL} method does take a response (a 2xx), servers
{\MUSTNOT} 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~\ref{sec:security:transport}, is in place).

When a UAC receives a challenge, it {\SHOULD} render to the user
the contents of the ``\header{realm}'' parameter in the challenge (which
appears in either a \header{WWW-Authenticate} header field or
\header{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 {\MUSTNOT}
re-attempt requests with the credentials that have just been rejected
\begin{changebar}
(though the request may be are retried if the nonce was stale).
\end{changebar}


\subsection{User-to-User Authentication}
\label{sec:security:auth:u2u}

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 \header{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. 

\begin{changebar}
The \header{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.  See [H14.47] for a
definition of the syntax.
\end{changebar}

An example of the \header{WWW-Authenticate} header field in a 401
challenge is:


\begin{verbatim}
         WWW-Authenticate: Digest
                 realm="biloxi.com",
                 qop="auth,auth-int",
                 nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093",
                 opaque="5ccc069c403ebaf9f0171e9517f40e41"
\end{verbatim}


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
\header{To} header field and ``\header{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 \header{Authorization} header field with the
request.  The \header{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 \header{Authorization} header field is:

\begin{changebar}
\begin{verbatim}
   Authorization: Digest username="bob",
           realm="biloxi.com",
           nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093",
           uri="sip:bob@biloxi.com",
           qop=auth,
           nc=00000001,
           cnonce="0a4f113b",
           response="6629fae49393a05397450978507c4ef1",
           opaque="5ccc069c403ebaf9f0171e9517f40e41"

\end{verbatim}
\end{changebar}


When a UAC resubmits a request with its credentials after receiving a
401 (Unauthorized) or 407 (Proxy Authentication Required) response, it
{\MUST} increment the \header{CSeq} header field value as it would normally
when sending an updated request.

\subsection{Proxy-to-User Authentication}
\label{sec:security:auth:p2u}

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 \header{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 \header{Proxy-Authenticate} header field value applicable to the proxy for 
the requested resource.

The use of \header{Proxy-Authentication} and
\header{Proxy-Authorization} parallel that described 
in~\citenorm{rfc2617}, with one difference.  Proxies {\MUSTNOT}
add values to the \header{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 \header{Proxy-Authorization} header field value containing
credentials for the realm of the proxy that has asked for
authentication.

\motivation{If a proxy were to resubmit a request adding a 
\header{Proxy-Authorization} header field value, it would need to increment
the \header{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 \header{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 ``\header{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 \header{Proxy-Authenticate} header field value in a 401/407
response to a request with a particular \header{Call-ID}, it should
incorporate credentials for that realm in all subsequent requests that
contain the same \header{Call-ID}.  These credentials {\MUSTNOT} 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 \header{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
\header{Proxy-Authorization} header field value with the request.  The
\header{Proxy-Authorization} request-header field allows the client to
identify itself (or its user) to a proxy that requires authentication. 
The \header{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 \header{Proxy-Authorization} header field value applies only to the proxy 
whose realm is identified in the ``\header{realm}'' parameter  
(this proxy may previously have demanded authentication using the 
\header{Proxy-Authenticate} field). When multiple proxies are used in a 
chain, a \header{Proxy-Authorization} header field value {\MUSTNOT} be 
consumed by any proxy whose realm does not match the ``\header{realm}'' 
parameter specified in that value.

Note that if an authentication scheme that does not support realms is used in 
the \header{Proxy-Authorization} header field, 
a proxy server {\MUST} attempt to parse all \header{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 \header{Proxy-Authorization} header field. 


If a request is forked (as described in 
Section~\ref{sec:proxy-response-processing}), 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 \header{WWW-Authenticate} and 
\header{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.

\motivation{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, then 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 \header{Authorization} value for each
\header{WWW-Authenticate} value and a \header{Proxy-Authorization} value for each
\header{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 ``\header{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. 
\begin{changebar}
When it retries a request, a UAC {\MAY} therefore supply multiple
credentials in \header{Authorization} or \header{Proxy-Authorization}
header fields with the same ``\header{realm}'' parameter
value. The same credentials {\SHOULD} be used for the same realm.
\end{changebar}


See [H14.34] for a definition of the syntax of 
\header{Proxy-Authentication} and \header{Proxy-Authorization}.

\subsection{The Digest Authentication Scheme}
\label{sec:security:auth: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~\citenorm{rfc2617}.  

Since RFC~2543 is based on HTTP Digest as defined in
RFC~2069~\citenonnorm{rfc2069}, 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 {\MUSTNOT} accept or request Basic
authentication.  


The rules for Digest authentication follow those defined
in~\citenorm{rfc2617}, with ``HTTP/1.1'' replaced by ``SIP/2.0'' in
addition to the following differences:

\begin{enumerate}
\item The URI included in the challenge has the following BNF:
\begin{syntax}
URI & = & SIP-URI $/$ SIPS-URI
\end{syntax}

\item The BNF in RFC~2617 has an error in that the 'uri' parameter of
the \header{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. 

\item The BNF for \header{digest-uri-value} is:
\begin{syntax}
digest-uri-value & = & Request-URI ; \textrm{as defined in 
Section~\ref{sec:abnf}}
\end{syntax}

\item The example procedure for choosing a nonce based on \header{Etag}
does not work for SIP. 

\item The text in RFC~2617~\citenorm{rfc2617} regarding cache operation 
does not apply to SIP.

\begin{changebar}
\item RFC~2617~\citenorm{rfc2617} requires that a server check that the URI
in the request line and the URI included in the \header{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 \header{Request-URI} 
in the \header{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. 
\end{changebar}

\item 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:

\begin{syntax}
H(entity-body) = MD5("") = "d41d8cd98f00b204e9800998ecf8427e"
\end{syntax}

\item RFC~2617 notes that a cnonce value {\MUSTNOT} be sent in an
\header{Authorization} (and by extension \header{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
\header{WWW-Authenticate} and \header{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. 

\end{enumerate}

RFC~2543 did not allow usage of the \header{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~\citenorm{rfc2617} 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.

