path: root/wiki/engineering/protocols/SIP.org

# -*- mode: org; -*-

#+TITLE: SIP
#+SUBTITLE: The Session Initiation Protocol.
#+AUTHOR: Marius Peter
#+DATE: <2022-07-12 Tue>
#+OPTIONS: toc:2

#+DESCRIPTION: The Session Initiation Protocol.


#+begin_abstract
SIP is a communication protocol used for VOIP.
#+end_abstract


* Introduction

- ``Session Information Protocol''
- Layer 7 (Application Layer) protocol
  - Based on HTTP (request/response architecture for service delivery)
- VOIP, IM, video calling...
- Invite other participants into existing session
- RFC 3261

What SIP does /not/ do: provide the media services.


* Establishing and terminating multimedia sessions

- User location :: What end system will be used to communicate?
  
- User availability :: Is the called party willing to engage in
  communication?
  
- User capabilities :: What media and media parameters will be used?
  
- Session setup :: How are session parameters established between
  calling/called parties? (``Ringing'')
  
- Session management :: How are sessions transferred and terminated?
  How are session parameters modified?  How are services invoked?


* User Agents
# Section 2

SIP endpoints are called User Agents. At the very least, two types of
UAs needed to setup a call: User-Agent Client and User-Agent Servers.


** UAC

#+BEGIN_QUOTE
A user agent client is a logical entity that creates a new request,
and then uses the client transaction state machinery to send it. The
role of UAC lasts only for the duration of the transaction. In other
words, if a piece of software initiates a request, it acts as a UAC
for the duration of the transaction.  If it receives a request later,
it assumes the role of a UAS for the processing of that transaction.

From RFC 3261
#+END_QUOTE


** UAS

#+BEGIN_QUOTE
A user agent server is a logical entity that generates a response to a
SIP request. The response accepts, rejects or redirects the request.
This role lasts only for the duration of the transaction. In other
words, if a piece of software responds to a request, it acts as a UAS
for the duration of the transaction. If it generates a request later,
it assumes the role of a UAC for the processing of that transaction.

From RFC 3261
#+END_QUOTE


** B2BUA

#+BEGIN_QUOTE
A back-to-back user agent is a logical entity that receives a request
and processes it as a UAS. In order to determine how the request
should be answered, it acts as a UAC and generates requests. Unlike a
proxy server, it maintains dialog state and must participate in all
requests sent on the dialogs it has established. Since it is the
concatenation of a UAC and a UAS, no explicit definitions are needed
for its behavior.

From RFC 3261
#+END_QUOTE


** Proxy Server

#+BEGIN_QUOTE
A proxy server is an intermediary entity that acts as both a server
and a client for the purpose of making requests on behalf of other
clients. A proxy server primarily serves the role of routing, which
means its job is to ensure that a request is sent to another entity
``closer'' to the targeted user. Proxies are also useful for enforcing
policy (for example, making sure that a user is allowed to make a
call). A proxy interprets and, if necessary, rewrites specific parts
of a request message before forwarding it.

From RFC 3261
#+END_QUOTE

A proxy does not need to be involved for requests after a dialog has
been created.


* SIP messages
# Section 3

A SIP message is either a request or a response. When a UAC sends a
request to a UAS, the UAS replies with a response, to inform the UAC
that the request was received.


** Message structure

: Start line (request line for request/status line for response)
: Message headers
: Empty line
: Message body


** SIP request methods

- =REGISTER= :: Register contact information
- =INVITE= :: Setting up a session
- =ACK= :: Acknowledge
- =CANCEL= :: Cancel session before other party answers
- =BYE= :: Hang up (tear down) the session
- =OPTIONS= :: Query UAS to determine capabilities, can be used as a
  ``ping'' method

RFC 3261 defines six types of REQUEST methods, other RFCs define
additional methods.


** SIP response codes

- Status line for responses consists of a response code and a /reason
  phrase/.
- The reason phrase has a default value, which can be overridden.
- Generated by UAS to inform UAC on transaction state.
- Responses usually have no body, but always have an empty line
  following the headers.
- SIP response codes are consistent with HTTP, the reverse is not
  true.


*** =1XX= provisional response

- Provisional: UAS is performing some additional actions.
- Sent when UAS expects >200 ms delay to obtain final response.
- Not transmitted reliably.
- Never requires UAC to send ACK.
- May contain message bodies.
- Stops retransmission of an =INVITE= by UAC.


- =100 TRYING= :: Request has been received by the next-hop server,
  some unspecified action (e.g. database query) is being
  performed. =100 TRYING= is never forwarded upstream by a stateful
  proxy.

- =180 RINGING= :: UAS has received the =INVITE= request, the UAC
  should initiate local ringback while further call processing takes
  place.

- =181 CALL IS BEING FORWARDED= :: A UAS may use this status code to
  indicate that the call is being forwarded to a different set of
  destinations.

- =182 QUEUED= :: Called party is temporarily unavailable, but UAS has
  decided to queue the call rather than reject it.  When callee
  becomes available, it will return appropriate final status response.
  Reason phrase may give further details about call status, e.g. ``5
  calls queued, expected waiting time is 15 minutes''.  UAS may issue
  many =182 QUEUED= responses to update caller about queued call
  status.

- =183 SESSION IN PROGRESS= :: Convey information about call
  progress. Typically used for ``early media session'', implying that
  audio or video is being sent before call is answered.


*** =200 OK=

- Only one =2XX= response.
- Implies request was successful.
- When callee picks up the phone, the phone sends a =200 OK= response.


*** =3XX= redirections

- =300 MULTIPLE CHOICES= :: Address in the request resolves to more
  than one choice, each with a specific location. UA can select
  preferred communication endpoint and redirect communication to that
  location. Response body may contain a list of resource
  characteristics and locations.

- =301 MOVED PERMANENTLY= :: User cannot be found at the address in
  the request URI, requesting client should retry at new address given
  by the =CONTACT= header. Requesting client should update any local
  directories, address books, and user location caches with this new
  value, and redirect future requests to this new address.

- =302 MOVED TEMPORARILY= :: Requesting client should retry at the new
  address. Duration of validity of the new address can be specified in
  the =EXPIRES= header. If no explicit expiration time, address is
  only valid once, and must not be cached for future transactions.

- =380 ALTERNATIVE SERVICE= :: Call was unsuccessful, but alternative
  services are available. These alternative services are described in
  the response body.


*** =4XX= request failures

- Definite failure responses
- UAC should not retry submitting the same request.
- However, same request with a different UAS might be successful.


- =400 BAD REQUEST= :: UAS cannot understand the request due to
  malformed syntax. Reason phrase should identify the syntax error so
  UAC can fix it. Associated with /fuzzing/, i.e. purposefully sending
  malformed data to the UAS for a DoS attack or to compromise a
  security weakness.

- =401 UNAUTHORIZED= and =407 PROXY REQUIRES AUTHENTICATION= :: UAS
  wants UAC to authenticate. Usually seen when UAC is attempting to
  =REGISTER=, can also be seen for other methods.

- =403 FORBIDDEN= :: Many systems issue this response if UAC sends an
  =INVITE=, but is not registered.

- =404 NOT FOUND= :: Request was received by UAS, but user does not
  exist at the specified domain. Can also be sent if domain does not
  match.  Expected if you call the wrong number.

- =405 METHOD NOT ALLOWED= :: Request method is understood, but not
  allowed for the address specified in the URI. Response must include
  an =ALLOW= header that contains a list of allowed methods for the
  address.

- =406 NOT ACCEPTABLE= :: The UAS cannot generate a response with a
  content type that satisfies the =ACCEPT= header in the request.

- =408 REQUEST TIMEOUT= :: The UAS cannot produce a response within a
  suitable amount of time. UAC may repeat the request at any later
  time.

- =410 GONE= :: The requested resource is no longer available, and no
  forwarding address is known. This condition is expected to be
  permanent. If UAS does not/cannot know whether the condition is
  permanent, =404 NOT FOUND= should be used instead.

- =413 REQUEST ENTITY TOO LARGE= :: Request body is larger than the
  UAS is willing or able to process. UAS may close the connection. If
  condition is temporary, UAS should include a =RETRY-AFTER= header to
  indicate the delay after which the UAC can try again.

- =414 REQUEST URI TOO LONG= :: Request URI is longer than the UAS is
  willing to interpret.

- =415 UNSUPPORTED MEDIA TYPE= Request body :: format is unsupported
  by UAS for the specified method. UAS must return a list of
  acceptable formats using the =ACCEPT=, =ACCEPT-ENCODING=, or
  =ACCEPT-LANGUAGE= headers depending on the specific problem.

- =416 UNSUPPORTED URI SCHEME= :: The request URI scheme is unknown to
  the server.

- =420 BAD EXTENSION= :: The UAS did not understand a protocol
  extension specified in the =PROXY-REQUIRE= or =REQUIRE= header
  fields. UAS must return a list of unsupported extensions in an
  =UNSUPPORTED= header.

- =421 EXTENSION REQUIRED= :: UAS needs a particular extension to
  process the request which is not listed in the =SUPPORTED=
  header. Response must contain a =REQUIRE= header listing the
  required extensions. UAS should only return this response if no
  service whatsoever can be provided to the UAC.

- =423 INTERVAL TOO BRIEF= :: Expiration time of the resource to be
  refreshed is too short.

- =480 TEMPORARY UNAVAILABLE= :: UAS was contacted successfully, but
  callee is unavailable, e.g. not logged in, ``do not disturb''
  feature activated.  Response may include better time to call in the
  =RETRY-AFTER= header. User might be available elsewhere. Reason
  phrase should include more precise reason why callee is unavailable,
  and should be settable by the UA. =486 BUSY HERE= may be used for
  more details on why the call failed.

- =481 TRANSACTION DOES NOT EXIST= :: UAS received a request that does
  not match any existing transaction.

- =482 LOOP DETECTED= :: Observed frequently with packet loss,
  i.e. the same request is sent again, without packet sequence number
  being incremented.

- =483 TOO MANY HOPS= :: UAS has received a request in which
  =MAX-FORWARDS= header is equal to zero.

- =484 ADDRESS INCOMPLETE= :: Request URI is incomplete. Additional
  reason should be provided in reason phrase.

- =486 BUSY HERE= :: Callee's end system contacted successfully, but
  callee is unavailable at this end system. Response may include a
  better time to call in the =RETRY-AFTER= header. Callee might be
  available elsewhere, e.g. via a voicemail system.

- =487 REQUEST TERMINATED= :: Request terminated by a =BYE= or
  =CANCEL= request.
  
- =488 NOT ACCEPTABLE HERE= :: Request is not acceptable for the
  specific resource identified in the request URI. Request may succeed
  somewhere else.  Description of media capabilities may be included
  in response body.

- =491 REQUEST PENDING= :: UAS received the request but had a pending
  request in the same dialog. This is a ``glare condition''.


*** =5XX= server failures

The UAS has experienced an error.


- =501 NOT IMPLEMENTED= :: UAS does not support the functionality
  required to fulfill the request. If UAS recognizes the request
  method, but it is not allowed or supported, use =405 METHOD NOT
  ALLOWED= instead.

- =502 BAD GATEWAY= :: The UAS, whilst acting as a gateway or proxy,
  received an invalid response from the downstream server it accessed
  when attempting to fulfill the request.

- =503 SERVER NOT AVAILABLE= :: UAS is temporarily unable to fulfill
  the request due to temporary overload or server maintenance. UAS may
  include a =RETRY-AFTER= header; if it does not, UAC must act as if
  it has received a =500 SERVER INTERNAL ERROR= response.  UAC should
  attempt to forward the request to an alternate server.  UAS may
  refuse the connection or drop the request instead of responding with
  =503 SERVER NOT AVAILABLE=.

- =504 SERVER TIMEOUT= :: UAS did not receive a response from an
  external server in time. =408 REQUEST TIMEOUT= should be used if
  there was no response within the time period specified in the
  =EXPIRES= header from the upstream server.

- =505 VERSION NOT SUPPORTED= :: The UAS does not or refuses to
  support the SIP protocol version used in the request.

- =513 MESSAGE TOO LARGE= :: Message length exceeds UAS capabilities.


*** =6XX= global failures

These responses indicate that the UAS has information about a
particular user (not just the instance specified in request URI).

- =600 BUSY EVERYWHERE= :: Callee's end system was contacted
  successfully, but callee does not wish to take the call at this
  time. Response may indicate a better call back time in the
  =RETRY-AFTER= header. This response is returned if client know that
  callee is not available anywhere else (otherwise return =486 BUSY
  HERE=).

- =603 DECLINE= :: Callee's end system was contacted successfully, but
  callee explicitly does not wish to or cannot participate.  Response
  may indicate a better call back time in the =RETRY-AFTER=
  header. This response is returned if client know that callee is not
  available anywhere else (otherwise return =486 BUSY HERE=).

- =604 DOES NOT EXIST ANYWHERE= :: Server is certain that the resource
  pointed to in request URI does not exist anywhere.

- =605 NOT ACCEPTABLE= :: The UAS was contacted successfully, but
  cannot properly support the described session. Response may contain
  a list of reasons in a =WARNING= header. This response is only
  returned if UAS knows that no other endpoint will answer the
  request.


** SIP URI structure

: sip:user:password@host:port:parameters
or
: sip:user@host:port;parameters

| =sip=  | =bob= | =example.com= | =5060= | =;user=phone= |
| scheme | user  | host          | port   | parameters    |

- SIP addresses are based on the same URI structure used in e-mail
  (RFC 2396).
- =sip= scheme is used for unsecured communication, =sips= is used
  alongside TLS.
- While permitted, the RFC recommends against including the password
  in the URI.
- No limit to parameter amount; however, they must each only appear
  once.
- Common parameters: =transport=, =maddr=, =ttl=, =user=, =method=,
  =lr=.
  - =transport=: either TCP or UDP.
  - =maddr= (mandatory address): defines server to be contacted for
    this user. Overrides =host=.
  - =ttl= (time to live): for a UDP multicast packet. Must only be
    used if =maddr= is a multicast address.
  - =lr= (loose route): indicates that the device responsible for the
    resource implements the routing methods.


** SIP headers

- SIP headers are named attributes that provide additional information
  about the message.
- Who is calling? What new requests are allowed in the call? Many
  other details too.


*** Mandatory headers

- =REQUEST-URI= ::
- =TO= :: Logical recipient of the request. It can optionally include
  a display name.
- =FROM= :: Logical identity of the request initiator. Used by SIP
  elements to determine call processing rules. A tag is appended to
  establish a dialog.
- =CSEQ= :: Sequence number + method.
- =CALL-ID= :: Unique identifier to group a series of messages. Must
  be the same for all requests within dialog. Recommended that the UAC
  generate a globally unique =CALL-ID=.
- =MAX-FORWARDS= :: Used to prevent loops. Default value should be 70.
- =VIA= :: Used for routing responses and identifying the transport
  protocol used. Must contain a unique branch parameter. RFC
  3261-compliant branch parameters must begin with =z9hG4bK= (magic
  cookie).


- =CONTACT= :: Contains a URI used to contact UA for subsequent
  requests.
- =ALERT-INFO= :: In an =INVITE= request, specify an alternative
  ringtone to the UAS. In a =180 RINGING= response, specify an
  alternative ringback tone to the UAC. Can also be used for ``auto
  answering'' calls by certain endpoints.
- =ALLOW= :: Specify the type of methods supported by the UA
  generating the message.
- =AUTHORIZATION= :: Contains UA auth credentials.
- =CALL-INFO= :: Contains additional information about request
  originator or responder.
- =CONTENT-DISPOSITION= :: Describes how the body should be
  interpreted by UAC/UAS.
- =CONTENT-LENGTH= :: Size of the message body, not including CRLF
  separating header from body.
- =CONTENT-TYPE= :: Type of media sent in body.
- =MIN-EXPIRES= :: Minimum refresh interval of soft-state elements
  managed by the UA.
- =RECORD-ROUTE= :: Inserted by a proxy in a request to force future
  requests to route through the proxy.
- =REQUIRE= :: Used by a UAC to inform a UAS about options that are
  expected to be supported by the UAS.
- =ROUTE= :: Force the routing of a request through the listed set of
  proxies.
- =SUPPORTED= :: List all extensions supported by the UAC/UAS.
- =USER-AGENT= :: Information about the UA, e.g. manufacturer name,
  SIP UA version.
- =WWW-AUTHENTICATE= :: Authentication challenge.


- Compact headers act the same as regular headers; they are just
  presented differently (single letter instead of full words).


** Session Description Protocol

- RFC 4566.
- When used with SIP, provides a standard representation of how
  information should be transported.
- Contains:
  - Session name and purpose
  - Time(s) the session is active
  - Media type used by the session
  - Information about how to receive media
- Normally presents enough information for UAs to join a session.


** SIP and user mobility

- A proxy receives an =INVITE= from a UAC, and proceeds with /Parallel
  Call Forking/: it relays the =INVITE= to all devices the callee is
  susceptible to pick up the call from. Contrast this with /Sequential
  Call Forking/.
- Each proxy that forks a request adds its own branch ID.


* SIP authentication
# Section 4

- SIP provides the same stateless, challenge-based authentication as
  used in HTTP.
- After authentication is performed, the challenger should determine
  if user is authorized to make the request.
- When a UAS requires authentication, it will return a =401
  UNAUTHORIZED= response.
- When a proxy requires authentication, it will return a =407 PROXY
  REQUIRES AUTHENTICATION= response.
- Basic authentication is not used. SIP uses Digest Authentication.
- A =401= or =407= response is sent with a =WWW-AUTHENTICATE= header
  containing the challenge information.
- The challenged UAC sends a response within the =AUTHENTICATION=
  header, consisting of:
  - Hash_1 = hash of =username:realm:password=
  - Hash_2 = hash of =method:domain-in-401-response=
  - Hash_3 = hash of =hash1:nonce:hash2=
  - If Quality Of Protection is required, Hash_3 = hash of
    =hash1:nonce:nc:cnonce:qop:h2=


* SIP routing and responses
# Section 5

- A SIP transaction consists in a single request, zero or more
  provisional responses, and a final response (plus an =ACK= if
  transaction is not =INVITE=).
- A dialog is a P2P relationship between two UAs that persists for
  some amount of time, following a successful =INVITE= transaction.
- The dialog is responsible for facilitating the sequence of messages
  and proper routing of requests between two UAs.
- A dialog is identified at each UA by a dialog ID, consisting in the
  call ID header value, a local tag, and a remote tag.
- The dialog ID is not the same for the UAC and the UAS.
- If either UAC or UAS initiates an =INVITE= within a dialog, this is
  called a =RE-INVITE=.


** SIP call routing

- Proxy may operate in stateless or stateful manner.
- A stateless proxy chooses the routing based on the request. After
  forwarding, it forgets any information about the request.
- A stateful proxy remembers transaction state of each request and
  uses this information when processing additional associated
  messages.


** COMMENT SIP trapezoid model

This name results from the shape observed when plotting a typical SIP
message flow on a sequence diagram.

* COMMENT SIP registration
# Section 6


* Media and RTP
# Section 7

- RTP is defined in RFC 3550. It is used to send media or audio
  between devices.
- Mainly two aspects:
  - Real Time Protocol: used to carry data with real time properties.
  - Real Time Control Protocol: used to monitor the quality of the
    session and convey information.
- RTP payload types used in a call can be found in the SDP.
- Mixers combine media from multiple sources and place them in a new
  RTP packet.
- Translators are able to modify the encoding, yet keep the same SSRC.