git.sip-router.org Git - sip-router/blob - src/modules/websocket/README

   1 WebSocket Module
   2
   3 Peter Dunkley
   4
   5    Crocodile RCS Ltd
   6
   7    Copyright © 2012-2013 Crocodile RCS Ltd
   8      __________________________________________________________________
   9
  10    Table of Contents
  11
  12    1. Admin Guide
  13
  14         1. Overview
  15         2. How it works
  16
  17               2.1. Initiating a connection
  18               2.2. SIP message routing
  19               2.3. MSRP message routing
  20
  21         3. Dependencies
  22
  23               3.1. Kamailio Modules
  24               3.2. External Libraries or Applications
  25
  26         4. Parameters
  27
  28               4.1. keepalive_mechanism (integer)
  29               4.2. keepalive_timeout (integer)
  30               4.3. keepalive_processes (integer)
  31               4.4. keepalive_interval (integer)
  32               4.5. ping_application_data (string)
  33               4.6. sub_protocols (integer)
  34               4.7. cors_mode (integer)
  35               4.8. verbose_list (int)
  36
  37         5. Functions
  38
  39               5.1. ws_handle_handshake()
  40               5.2. ws_close([status, reason[, connection_id]])
  41
  42         6. RPC Commands
  43
  44               6.1. ws.dump
  45               6.2. ws.close
  46               6.3. ws.ping
  47               6.4. ws.pong
  48               6.5. ws.disable
  49               6.6. ws.enable
  50
  51         7. Event routes
  52
  53               7.1. websocket:closed
  54
  55         8. Exported Pseudo Variables
  56
  57               8.1. $ws_conid
  58
  59    List of Examples
  60
  61    1.1. event_route[xhttp:request]
  62    1.2. WebSocket SIP Routing
  63    1.3. Set keepalive_mechanism parameter
  64    1.4. Set keepalive_timeout parameter
  65    1.5. Set keepalive_processes parameter
  66    1.6. Set keepalive_interval parameter
  67    1.7. Set ping_application_data parameter
  68    1.8. Set sub_protocols parameter
  69    1.9. Set cors_mode parameter
  70    1.10. Set verbose_list parameter
  71    1.11. ws_handle_handshake usage
  72    1.12. ws_close usage
  73    1.13. event_route[websocket:closed] usage
  74    1.14. $ws_conid usage
  75
  76 Chapter 1. Admin Guide
  77
  78    Table of Contents
  79
  80    1. Overview
  81    2. How it works
  82
  83         2.1. Initiating a connection
  84         2.2. SIP message routing
  85         2.3. MSRP message routing
  86
  87    3. Dependencies
  88
  89         3.1. Kamailio Modules
  90         3.2. External Libraries or Applications
  91
  92    4. Parameters
  93
  94         4.1. keepalive_mechanism (integer)
  95         4.2. keepalive_timeout (integer)
  96         4.3. keepalive_processes (integer)
  97         4.4. keepalive_interval (integer)
  98         4.5. ping_application_data (string)
  99         4.6. sub_protocols (integer)
 100         4.7. cors_mode (integer)
 101         4.8. verbose_list (int)
 102
 103    5. Functions
 104
 105         5.1. ws_handle_handshake()
 106         5.2. ws_close([status, reason[, connection_id]])
 107
 108    6. RPC Commands
 109
 110         6.1. ws.dump
 111         6.2. ws.close
 112         6.3. ws.ping
 113         6.4. ws.pong
 114         6.5. ws.disable
 115         6.6. ws.enable
 116
 117    7. Event routes
 118
 119         7.1. websocket:closed
 120
 121    8. Exported Pseudo Variables
 122
 123         8.1. $ws_conid
 124
 125 1. Overview
 126
 127    This module implements a WebSocket (RFC 6455) server and provides
 128    connection establishment (handshaking), management (including
 129    connection keep-alive), and framing for the SIP and MSRP WebSocket
 130    sub-protocols (RFC 7118 and RFC 7977).
 131
 132    The module supports WebSockets (ws) and secure WebSockets (wss)
 133    transports
 134
 135 2. How it works
 136
 137    2.1. Initiating a connection
 138    2.2. SIP message routing
 139    2.3. MSRP message routing
 140
 141 2.1. Initiating a connection
 142
 143    A WebSocket connection is initiated with an HTTP GET. The xhttp module
 144    is used to handle this GET and call the Section 5.1, “
 145    ws_handle_handshake() ” exported function.
 146
 147    event_route[xhttp:request] should perform some validation of the HTTP
 148    headers before calling Section 5.1, “ ws_handle_handshake() ”. The
 149    event_route can also be used to make sure the HTTP GET has the correct
 150    URI, perform HTTP authentication on the WebSocket connection, and check
 151    the Origin header (RFC 6454) to ensure a browser-based SIP UA or MSRP
 152    client has been downloaded from the correct location.
 153
 154    Example 1.1. event_route[xhttp:request]
 155 ...
 156 loadmodule "sl.so"
 157 loadmodule "xhttp.so"
 158 loadmodule "msrp.so"  # Only required if using MSRP over WebSockets
 159 loadmodule "websocket.so"
 160 ...
 161 event_route[xhttp:request] {
 162         set_reply_close();
 163         set_reply_no_connect();
 164
 165         if ($Rp != 80
 166 #!ifdef WITH_TLS
 167             && $Rp != 443
 168 #!endif
 169         ) {
 170
 171                 xlog("L_WARN", "HTTP request received on $Rp\n");
 172                 xhttp_reply("403", "Forbidden", "", "");
 173                 exit;
 174         }
 175
 176         xlog("L_DBG", "HTTP Request Received\n");
 177
 178         if ($hdr(Upgrade)=~"websocket"
 179                         && $hdr(Connection)=~"Upgrade"
 180                         && $rm=~"GET") {
 181
 182                 # Validate Host - make sure the client is using the correct
 183                 # alias for WebSockets
 184                 if ($hdr(Host) == $null || !is_myself("sip:" + $hdr(Host))) {
 185                         xlog("L_WARN", "Bad host $hdr(Host)\n");
 186                         xhttp_reply("403", "Forbidden", "", "");
 187                         exit;
 188                 }
 189
 190                 # Optional... validate Origin - make sure the client is from an
 191                 # authorised website.  For example,
 192                 #
 193                 # if ($hdr(Origin) != "http://communicator.MY_DOMAIN"
 194                 #     && $hdr(Origin) != "https://communicator.MY_DOMAIN") {
 195                 #       xlog("L_WARN", "Unauthorised client $hdr(Origin)\n");
 196                 #       xhttp_reply("403", "Forbidden", "", "");
 197                 #       exit;
 198                 # }
 199
 200                 # Optional... perform HTTP authentication
 201
 202                 # ws_handle_handshake() exits (no further configuration file
 203                 # processing of the request) when complete.
 204                 if (ws_handle_handshake())
 205                 {
 206                         # Optional... cache some information about the
 207                         # successful connection
 208                         exit;
 209                 }
 210         }
 211
 212         xhttp_reply("404", "Not found", "", "");
 213 }
 214 ...
 215
 216 2.2. SIP message routing
 217
 218    SIP over WebSockets uses invalid URIs in routing headers (Contact:,
 219    Record-Route:, and Via:) because a JavaScript stack running in a
 220    browser has no way to determine the local address from which the
 221    WebSocket connection is made. This means that the routing headers
 222    cannot be used for request or response routing in the normal manner.
 223
 224    RFC 7118 - The WebSocket Protocol as a Transport for the Session
 225    Initiation Protocol - states that SIP WebSocket Clients and the SIP
 226    registrar should implement SIP Outbound (RFC 5626) and Path header
 227    support (RFC 3327) to enable requests and responses to be correctly
 228    routed. Kamailio has a module called "Outbound" for this functionality.
 229
 230    The nathelper module functions (nat_uac_test(), fix_nated_register(),
 231    add_contact_alias(), and handle_ruri_alias()) and the Kamailio core
 232    force_rport() can be used to ensure correct routing of SIP WebSocket
 233    requests without using Outbound and Path.
 234
 235    Example 1.2. WebSocket SIP Routing
 236 ...
 237 loadmodule "sl.so"
 238 loadmodule "tm.so"
 239 ...
 240 loadmodule "websocket.so"
 241 ...
 242 request_route {
 243
 244         # per request initial checks
 245         route(REQINIT);
 246
 247         if (nat_uac_test(64)) {
 248                 # Do NAT traversal stuff for requests from a WebSocket
 249                 # connection - even if it is not behind a NAT!
 250                 # This won't be needed in the future if Kamailio and the
 251                 # WebSocket client support Outbound and Path.
 252                 force_rport();
 253                 if (is_method("REGISTER"))
 254                         fix_nated_register();
 255                 else {
 256                         if (!add_contact_alias()) {
 257                                 xlog("L_ERR", "Error aliasing contact <$ct>\n");
 258                                 sl_send_reply("400", "Bad Request");
 259                                 exit;
 260                         }
 261                 }
 262         }
 263
 264         if (!is_method("REGISTER"))
 265                 t_on_reply("WS_REPLY");
 266 ...
 267 # Handle requests within SIP dialogs
 268 route[WITHINDLG] {
 269         if (has_totag()) {
 270                 # sequential request withing a dialog should
 271                 # take the path determined by record-routing
 272                 if (loose_route()) {
 273                         if ($du == "") {
 274                                 if (!handle_ruri_alias()) {
 275                                         xlog("L_ERR", "Bad alias <$ru>\n");
 276                                         sl_send_reply("400", "Bad Request");
 277                                         exit;
 278                                 }
 279                         }
 280                         route(RELAY);
 281                 } else {
 282                         if ( is_method("ACK") ) {
 283 ...
 284 onreply_route[WS_REPLY] {
 285         if (nat_uac_test(64)) {
 286                 # Do NAT traversal stuff for replies to a WebSocket connection
 287                 # - even if it is not behind a NAT!
 288                 # This won't be needed in the future if Kamailio and the
 289                 # WebSocket client support Outbound and Path.
 290                 add_contact_alias();
 291         }
 292 }
 293 ...
 294
 295 2.3. MSRP message routing
 296
 297    MSRP over WebSocket clients create invalid local URIs for use in Path
 298    headers (From-Path: and To-Path:) because a JavaScript stack running in
 299    a browser has no way to determine the local address from which the
 300    WebSocket connection is made. This is OK because MSRP over WebSocket
 301    clients MUST use an MSRP relay and it is the MSRP relay's
 302    responsibility to select the correct connection to the client based on
 303    the MSRP URIs that it has created (and maintains a mapping for).
 304
 305 3. Dependencies
 306
 307    3.1. Kamailio Modules
 308    3.2. External Libraries or Applications
 309
 310 3.1. Kamailio Modules
 311
 312    The following module must be loaded before this module:
 313      * sl.
 314      * tm.
 315
 316    The following modules are required to make proper use of this module:
 317      * nathelper or outbound.
 318      * xhttp.
 319
 320    The following module is required to use the secure WebSocket (wss)
 321    scheme:
 322      * tls.
 323
 324    The following module is required to support MSRP over WebSockets:
 325      * msrp.
 326
 327 3.2. External Libraries or Applications
 328
 329    The following libraries must be installed before running Kamailio with
 330    this module loaded:
 331      * OpenSSL.
 332      * GNU libunistring.
 333
 334 4. Parameters
 335
 336    4.1. keepalive_mechanism (integer)
 337    4.2. keepalive_timeout (integer)
 338    4.3. keepalive_processes (integer)
 339    4.4. keepalive_interval (integer)
 340    4.5. ping_application_data (string)
 341    4.6. sub_protocols (integer)
 342    4.7. cors_mode (integer)
 343    4.8. verbose_list (int)
 344
 345 4.1. keepalive_mechanism (integer)
 346
 347    The keep-alive mechanism to use for WebSocket connections.
 348
 349 Note
 350
 351    If nathelper is only being used for WebSocket connections then
 352    nathelper NAT pinging is not required. If nathelper is used for
 353    WebSocket connections and TCP/TLS aliasing/NAT-traversal then WebSocket
 354    keep-alives are not required.
 355
 356      * 0 - no WebSocket keep-alives
 357      * 1 - Ping WebSocket keep-alives
 358      * 2 - Pong WebSocket keep-alives
 359
 360    Default value is 1.
 361
 362    Example 1.3. Set keepalive_mechanism parameter
 363 ...
 364 modparam("websocket", "keepalive_mechanism", 0)
 365 ...
 366
 367 4.2. keepalive_timeout (integer)
 368
 369    The time (in seconds) after which to send a keep-alive on idle
 370    WebSocket connections.
 371
 372    Default value is 180.
 373
 374    Example 1.4. Set keepalive_timeout parameter
 375 ...
 376 modparam("websocket", "keepalive_timeout", 30)
 377 ...
 378
 379 4.3. keepalive_processes (integer)
 380
 381    The number of processes to start to perform WebSocket connection
 382    keep-alives.
 383
 384    Default value is 1.
 385
 386    Example 1.5. Set keepalive_processes parameter
 387 ...
 388 modparam("websocket", "keepalive_processes", 2)
 389 ...
 390
 391 4.4. keepalive_interval (integer)
 392
 393    The number of seconds between each keep-alive process run
 394
 395    Default value is 1.
 396
 397    Example 1.6. Set keepalive_interval parameter
 398 ...
 399 modparam("websocket", "keepalive_interval", 2)
 400 ...
 401
 402 4.5. ping_application_data (string)
 403
 404    The application data to use in keep-alive Ping and Pong frames.
 405
 406    Default value is Kamailio Server: header content
 407
 408    Example 1.7. Set ping_application_data parameter
 409 ...
 410 modparam("websocket", "ping_application_data", "WebSockets rock")
 411 ...
 412
 413 4.6. sub_protocols (integer)
 414
 415    A bitmap that allows you to control the sub-protocols supported by the
 416    WebSocket server.
 417      * 1 - sip (RFC 7118)
 418      * 2 - msrp (RFC 7977) - msrp.so must be loaded before websocket.so
 419
 420    Default value is 1 when msrp.so is not loaded 3 when msrp.so is loaded.
 421
 422    Example 1.8. Set sub_protocols parameter
 423 ...
 424 modparam("websocket", "sub_protocols", 2)
 425 ...
 426
 427 4.7. cors_mode (integer)
 428
 429    This parameter lets you set the "Cross-origin resource sharing"
 430    behaviour of the WebSocket server.
 431      * 0 - Do not add an "Access-Control-Allow-Origin:" header to the
 432        response accepting the WebSocket handshake.
 433      * 1 - Add a "Access-Control-Allow-Origin: *" header to the response
 434        accepting the WebSocket handshake.
 435      * 2 - Add a "Access-Control-Allow-Origin:" header containing the same
 436        body as the "Origin:" header from the request to the response
 437        accepting the WebSocket handshake. If there is no "Origin:" header
 438        in the request no header will be added to the response.
 439
 440    Default value is 0.
 441
 442    Example 1.9. Set cors_mode parameter
 443 ...
 444 modparam("websocket", "cors_mode", 2)
 445 ...
 446
 447 4.8. verbose_list (int)
 448
 449    Allows to enable/disable the printing of debug messages when getting
 450    the list of websocket connections. If enabled, it prints debug messages
 451    every second for ping operations.
 452
 453    Default value is 0 (disabled).
 454
 455    Example 1.10. Set verbose_list parameter
 456 ...
 457 modparam("websocket", "verbose_list", 1)
 458 ...
 459
 460 5. Functions
 461
 462    5.1. ws_handle_handshake()
 463    5.2. ws_close([status, reason[, connection_id]])
 464
 465 5.1.  ws_handle_handshake()
 466
 467    This function checks an HTTP GET request for the required headers and
 468    values, and (if successful) upgrades the connection from HTTP to
 469    WebSocket.
 470
 471    This function can be used from ANY_ROUTE (but will only work in
 472    event_route[xhttp:request]).
 473
 474 Note
 475
 476    This function returns 0, stopping all further processing of the
 477    request, when there is a problem.
 478
 479    Example 1.11. ws_handle_handshake usage
 480 ...
 481 ws_handle_handshake();
 482 ...
 483
 484 5.2.  ws_close([status, reason[, connection_id]])
 485
 486    This function closes a WebSocket connection.
 487
 488    The function returns -1 if there is an error and 1 if it succeeds.
 489
 490    The meaning of the parameters is as follows:
 491      * status - an integer indicating the reason for closure.
 492      * reason - a string describing the reason for closure.
 493      * connection_id - the connection to close. If not specified the
 494        connection the current message arrived on will be closed.
 495
 496 Note
 497
 498    status and reason values SHOULD correspond to the definitions in
 499    section 7.4 of RFC 6455. If these parameters are not used the defaults
 500    of "1000" and "Normal closure" will be used.
 501
 502    This function can be used from ANY_ROUTE.
 503
 504    Example 1.12. ws_close usage
 505 ...
 506 ws_close(4000, "Because I say so");
 507 ...
 508
 509 6. RPC Commands
 510
 511    6.1. ws.dump
 512    6.2. ws.close
 513    6.3. ws.ping
 514    6.4. ws.pong
 515    6.5. ws.disable
 516    6.6. ws.enable
 517
 518 6.1. ws.dump
 519
 520    Provides the details of the first 50 WebSocket connections.
 521
 522    Name: ws.dump
 523
 524    Parameters:
 525      * order (optional) - “id_hash”, “used_desc”, or “used_asc”.
 526
 527 Note
 528
 529    If no parameter is provided id_hash order is used.
 530
 531    RPC Command Usage:
 532 ...
 533 kamcmd ws.dump used_asc
 534 ...
 535
 536 6.2. ws.close
 537
 538    Starts the close handshake for the specified WebSocket connection.
 539
 540    Name: ws.close
 541
 542    Parameters:
 543      * id - WebSocket connection ID.
 544
 545    RPC Command Usage:
 546 ...
 547 kamcmd ws.close: 1
 548 ...
 549
 550 6.3. ws.ping
 551
 552    Sends a Ping frame on the specified WebSocket connection.
 553
 554    Name: ws.ping
 555
 556    Parameters:
 557      * id - WebSocket connection ID.
 558
 559    RPC Command Usage:
 560 ...
 561 kamcmd ws.ping 1
 562 ...
 563
 564 6.4. ws.pong
 565
 566    Sends a Pong frame on the specified WebSocket connection.
 567
 568    Name: ws.pong
 569
 570    Parameters:
 571      * id - WebSocket connection ID.
 572
 573    RPC Command Usage:
 574 ...
 575 kamcmd ws.pong 1
 576 ...
 577
 578 6.5. ws.disable
 579
 580    Disables WebSockets preventing new connections from being established.
 581
 582    Name: ws.disable
 583
 584    Parameters: none
 585
 586    RPC Command Usage:
 587 ...
 588 kamcmd ws.disable
 589 ...
 590
 591 6.6. ws.enable
 592
 593    Enables WebSockets allowing new connections to be established.
 594
 595 Note
 596
 597    WebSockets are enabled at start-up.
 598
 599    Name: ws.enable
 600
 601    Parameters: none
 602
 603    RPC Command Format:
 604 ...
 605 kamcmd ws.enable
 606 ...
 607
 608 7. Event routes
 609
 610    7.1. websocket:closed
 611
 612 7.1.  websocket:closed
 613
 614    When defined, the module calls event_route[websocket:closed] when a
 615    connection closes. The connection may be identified using the the $si
 616    and $sp pseudo-variables.
 617
 618    Example 1.13. event_route[websocket:closed] usage
 619 ...
 620 event_route[websocket:closed] {
 621         xlog("L_INFO", "WebSocket connection from $si:$sp has closed\n");
 622 }
 623 ...
 624
 625 8. Exported Pseudo Variables
 626
 627    8.1. $ws_conid
 628
 629 8.1. $ws_conid
 630
 631    Connection id of closed websocket connection. Can only be used in
 632    websocket:closed event route.
 633
 634    Example 1.14. $ws_conid usage
 635 ...
 636 event_route[websocket:closed] {
 637         xlog("L_INFO", "WebSocket connection with id $ws_conid has closed\n");
 638 }
 639 ...