Skip to content

Latest commit

 

History

History
139 lines (123 loc) · 6.28 KB

README.md

File metadata and controls

139 lines (123 loc) · 6.28 KB
Raw

sbc-inbound Build Status

This application provides a part of the SBC (Session Border Controller) functionality of jambonz platform. It handles incoming INVITE requests from carrier sip trunks or from sip devices and webrtc applications. SIP INVITEs from known carriers are allowed in, while INVITEs from sip devices are challenged to authenticate. SIP traffic that is allowed in is sent on to a jambonz application server in a private subnet.

Configuration

Configuration is provided via environment variables:

variable meaning required?
DRACHTIO_HOST ip address of drachtio server (typically '127.0.0.1') yes
DRACHTIO_PORT listening port of drachtio server for control connections (typically 9022) yes
DRACHTIO_SECRET shared secret yes
HTTP_PORT http listen port no
JAMBONES_LOGLEVEL log level for application, 'info' or 'debug' no
JAMBONES_MYSQL_HOST mysql host yes
JAMBONES_MYSQL_PORT mysql port no
JAMBONES_MYSQL_USER mysql username yes
JAMBONES_MYSQL_PASSWORD mysql password yes
JAMBONES_MYSQL_DATABASE mysql data yes
JAMBONES_MYSQL_CONNECTION_LIMIT mysql connection limit no
DTMF_LISTEN_PORT DTMF listening port no
JAMBONES_NG_PROTOCOL rtpengine NG protocol no
RTPENGINE_PORT rtpengine port no
JAMBONES_CLUSTER_ID cluster id no
JAMBONES_NETWORK_CIDR CIDR of private network that feature server is running in (e.g. '172.31.0.0/16') yes
JAMBONES_REDIS_HOST redis host yes
JAMBONES_REDIS_PORT redis port no
JAMBONES_RTPENGINES commas-separated list of ip:ng-port for rtpengines (e.g. '172.31.32.10:22222') no
JAMBONES_TIME_SERIES_HOST influxdb host yes
JAMBONES_TIME_SERIES_PORT influxdb port no
JAMBONES_RECORD_ALL_CALLS enable auto record calls, 'yes' or 'no' no
K8S service running as kubernetes service no
K8S_RTPENGINE_SERVICE_NAME rtpengine service name(required for K8S) no
K8S_FEATURE_SERVER_SERVICE_NAME feature server service name(required for K8S) no
JWT_SECRET secret for signing JWT token yes
ENCRYPTION_SECRET secret for credential encryption(JWT_SECRET is deprecated) yes
drachtio server location
{
  "drachtio": {
    "port": 3001,
    "secret": "cymru"
  },

the drachtio object specifies the port to listen on for tcp connections from drachtio servers as well as the shared secret that is used to authenticate to the server.

Note: either inbound or outbound connections may be used, depending on the configuration supplied. In production, it is the intent to use outbound connections for easier centralization and clustering of application logic, while inbound connections are used for the automated test suite.

rtpengine location
  "rtpengine": {
    "host": "127.0.0.1",
    "port": 22222
  },

the rtpengine object specifies the location of the rtpengine, which will typically be running on the same server as drachtio.

application log level
  "logging": {
    "level": "info"
  }
application server location

The sip trunk routing to internal application servers are specified as an array of IP addresses.

  "trunks": {
    "appserver": ["sip:10.10.120.1"]
  }
transcoding options

The transcoding options for rtpengine are found in the configuration file, however these should not need to be modified.

  "transcoding": {
  "rtpCharacteristics" : {
      "transport protocol": "RTP/AVP",
      "DTLS": "off",
      "SDES": "off",
      "ICE": "remove",
      "rtcp-mux": ["demux"]
  },
  "srtpCharacteristics": {
      "transport-protocol": "UDP/TLS/RTP/SAVPF",
      "ICE": "force",
      "SDES": "off",
      "flags": ["generate mid", "SDES-no"],
      "rtcp-mux": ["require"]
  } 
}

Authentication

Authenticating users is the responsibility of the client by exposing an http callback. A POST request will be sent to the configured callback (i.e. the value in the accounts.registration_hook column in the associated sip realm value in the REGISTER request). The body of the POST will be a json payload including the following information:

{
	"method": "REGISTER",
	"expires": 3600,
	"scheme": "digest",
	"username": "john",
	"realm": "jambonz.org",
	"nonce": "157590482938000",
	"uri": "sip:172.37.0.10:5060",
	"response": "be641cf7951ff23ab04c57907d59f37d",
	"qop": "auth",
	"nc": "00000001",
	"cnonce": "6b8b4567",
	"algorithm": "MD5"
}

It is the responsibility of the customer-side logic to retrieve the associated password for the given username and to then authenticate the request by calculating a response hash value (per the algorithm described in RFC 2617) and comparing it to the response property in the http body.

For example code showing how to calculate the response hash given the above inputs, see here.

For a simple, full-fledged example server doing the same, see here.

The customer server SHOULD return a 200 OK response to the http request in all cases with a json body indicating whether the request was successfully authenticated.

The body MUST include a status field with a value of either ok or fail, indicating whether the request was authenticated or not.

{"status": "ok"}

Additionally, in the case of failure, the body MAY include a msg field with a human-readable description of why the authentication failed.

{"status": "fail", "msg": "invalid username"}

Forwarding behavior

This application acts as a back-to-back user agent and media proxy. When sending INVITEs on to the jambonz application servers, it adds the following headers onto the INVITE:

  • X-Forwarded-For: the IP address of the client that sent the INVITE
  • X-Forwarded-Carrier: the name of the inbound carrier, if applicable

Running the test suite

To run the included test suite, you will need to have a mysql server installed on your laptop/server. You will need to set the MYSQL_ROOT_PASSWORD env variable to the mysql root password before running the tests. The test suite creates a database named 'jambones_test' in your mysql server to run the tests against, and removes it when done.

MYSQL_ROOT_PASSWORD=foobar npm test