The WebSocket Protocol defined by RFC 6455 enables two-way communication between a client running untrusted code in a controlled environment, such as web browsers, to a remote host that has opted-in to communications from that code. The internet draft
draft-ietf-sipcore-sip-websocket-08 [SIP-WEBSOCKET-DRAFT] defines a new WebSocket sub-protocol for transporting SIP messages between a WebSocket client and server.
A SIP servlet containers support incoming WebSocket connections from WebSocket clients that contain “sip” as one of the sub-protocols during handshake. Once the handshake negotiation has been completed, the WebSocket connection established can be used for the transport of SIP requests and responses. The WebSocket messages transmitted over this connection MUST conform to the negotiated WebSocket sub-protocol. The SIP Servlet Container follow the procedures specified in RFC 3261 and SIP-WEBSOCKET-DRAFT for implementing the SIP Websocket Transport.
Support for use of WebSocket transports by a SIP container is optional. Containers with this capability must include the string "draft-ietf-sipcore-sip-websocket" in the list of supported rfcs available to applications via the ServletContext. see3.3 Extensions Supported.
13.1 WebSocket Transport
SIP-WEBSOCKET-DRAFT updates RFC 3261 to introduce WebSocket as another reliable protocol apart from the ones already defined. SIP Servlet container is required to support the procedures specified in section 5 of the SIP-WEBSOCKET-DRAFT, whereever it is applicable
to to the SIP WebSocket Server. The procedures specific to SIP WebSocket client is not applicable to this version of SIP Servlet specification.
Notes: A future version of this specification might define APIs to support SIP WebSocket
Client.
13.2 Converged Applications
13.2.1 SipWebSocketContext
Each SIP WebSocket connection established to a SIP Servlet Container has an associated SipWebsocketContext. A SIP Servlet application may access the SipWebsocketContext, if the WebSocket connection is established by an http request on a path beginning with the context root of the same Converged application. A SipWebSocketContext may be retrieved by a SIP Servlet using SipServletMessage.getLocalSipWebsocketContext()
13.2.2 Accessing WebSocket URL
The URL on which the SIP servlet container received the SIP Message can be accessed by SIP Servlets using SipWebSocketContext.getURL() method. The returned URL contains a protocol, server name, port number, server path, and include query string parameters.
13.2.3 Relationship with HttpSession
It is often useful for developers who embed SIP WebSocket Server endpoints into a larger web application to be able to share information on a per client basis between the web resources (JSPs, JSFs, Servlets for example) and the web socket endpoints servicing that client. Because handshake for establishing web sockets are initiated with an http request, there is an association between the HttpSession under which a client is operating and any web sockets that are established within that HttpSession.
The HttpSession on which the original handshake for the websocket happened can be accessed by SIP Servlets using getInitiatingWebSession method in the SipWebSocketContext. Note that the getInitiatingWebSession will return null, if the HTTP session has been invalidated.
An alternate way EG is considering is to enhance the current ConvergedHttpSession mechanism to support such implicit protocol association usecases in a transport independent way, without SIP/WebSocket transport specific apis. Feedback from community will be taken into account before taking a final decision.
C o n v e r g e d A p p l i c a t i o n s
13.2.4 Creating an Initial Request
When SIP servlet application need to create an initial request, application need to specify which WebSocket connection should be used for sending the SIP message. SIP-WEBSOCKET-DRAFT has suggested SIP Outbound Extension [RFC 5626] as a way to reach the client. Thus SIP servlet application can use SipSession.setFlow(Flow flow), Proxy.setFlow(Flow flow) or ProxyBranch.setFlow(Flow flow) methods to specify the Flow representing the SIP WebSocket Connection.
Applications that does not use SIP Outbound Extension may set a SipWebSocketContext instance in the SipSession, Proxy or ProxyBranch objects before sending the message, to indicate the Sip WebSocket connection to be used for sending the message. Following text describes the corresponding methods.
z SipSession.setSipWebSocketContext(SipWebSocketContext wscontext) z Proxy.setSipWebSocketContext(SipWebSocketContext wscontext) z ProxyBranch.setSipWebSocketContext(SipWebSocketContext wscontext)
13.2.5 Destroying the SipWebSocketContext
An application may initiate the closure of the SipWebSocketContext by executing close() method on the SipWebSocketContext.
The usecases for a close() method on SipWebSocketContext can also be applicable for other transports. Feedback from the community will be taken into account before deciding the way forward on allowing the application to close the Sip WebSocket connection since closing a connection could affect other applications as well.
13.2.6 SipWebSocketContextListener
An application may listen to the life cycle of SipWebSocketContext using an application listener that implements SipWebSocketContextListener. Following are the methods supported by the SipWebSocketListener.
z void onOpen(SipWebSocketContextEvent contextEvt) : This method is invoked after the WebSocket connection is opened.
z void onClose(SipWebSocketContextEvent contextEvt) : This method is invoked before the WebSocket connection is closed.
z void onError(SipWebSocketContextEvent contextEvt) : This method is invoked when an error occurs in the WebSocket connection.
13.3 Application Composition
When an initial request is received on WebSocket transport, just like any other SIP Servlet Request on other transports, the message will be passed to the application router to begin the application selection and composition process as specified in section 15 of this specification.
13.4 Authentication
A SIP Servlet container is required to support authentication prior to sending SIP requests as specified in section 7 of the SIP-WEBSOCKET-DRAFT. If the connection is already
authenticated (for example, by the web application that originally handles the context-root), then the principal established by that authentication process will also be made available to SIP Servlet application using SipServletMessage.getRemoteUser(),
SipServletMessage.getUserPrincipal() methods. Similarly,
SipServletMessage.isUserInRole would return true if the user in question has the relevant role defined in security-role element of the deployment descriptor of the SIP Servlet application.
A SIP Servlet application may further enforce authentication of SIP messages using the procedures explained in section 17.5 of this specification. Thus when an application is configured to use any of the three mechanisms (SIP digest, P-Asserted-Identity, Identity and Identity-Info headers) for authentication, any previous authentication of the WebSocket connection will be ignored by the container.