NETCONF Working Group T. Iijima Internet-Draft Hitachi, Ltd. Intended status: Experimental H. Kimura Expires: September 6, 2012 Y. Atarashi H. Higuchi Alaxala Networks Corp. Mar 05, 2012 NETCONF over WebSocket draft-iijima-netconf-websocket-ps-02 Abstract This memo proposes a way of transporting NETCONF over WebSocket protocol. Web-based applications are increasing with the advancement of Web technologies and emergence of cloud computing. Management systems that support browser-based interface are getting common. It's natural to expect network devices to have browser-based managemaent interface. Currently, however, few network management protocols support the transportation over HTTP. Although NETCONF[RFC6241] was defined to be sent over SOAP/HTTPS[RFC4743], it can not realize notification mechanism[RFC5277] over SOAP/HTTPS since HTTP lacks bi-directional capabilty. But now, WebSocket protocol, the update of HTTP with bi-directional capability, is available[RFC6455]. This memo describes the way NETCONF is sent over WebSocket protocol. Status of this Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on September 6, 2012. Copyright Notice Copyright (c) 2012 IETF Trust and the persons identified as the Iijima, et al. Expires September 6, 2012 [Page 1] Internet-Draft NETCONF over WebSocket Mar 2012 document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Problem Statement . . . . . . . . . . . . . . . . . . . . . . 4 3. Use Case . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 4. Concerns about Using HTTP and WebSocket . . . . . . . . . . . 7 5. Handling of NETCONF username . . . . . . . . . . . . . . . . . 8 6. Transporting NETCONF Messages over WebSocket Protocol . . . . 9 6.1. Message Sequence . . . . . . . . . . . . . . . . . . . . . 9 6.2. WebSocket Message from NETCONF Client at WebSocket Handshake . . . . . . . . . . . . . . . . . . . . . . . . 11 6.3. WebSocket Message from NETCONF Server at WebSocket Handshake . . . . . . . . . . . . . . . . . . . . . . . . 12 6.4. NETCONF Message at NETCONF Client over WebSocket Connection . . . . . . . . . . . . . . . . . . . . . . . . 13 6.5. NETCONF Message at NETCONF Server over WebSocket Connection . . . . . . . . . . . . . . . . . . . . . . . . 14 7. Security Considerations . . . . . . . . . . . . . . . . . . . 16 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 18 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19 10.1. Normative References . . . . . . . . . . . . . . . . . . . 19 10.2. Informative References . . . . . . . . . . . . . . . . . . 19 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 21 Iijima, et al. Expires September 6, 2012 [Page 2] Internet-Draft NETCONF over WebSocket Mar 2012 1. Introduction Web-based applications are increasing in contrast with install-based applications due to the advancement of Web technologies and emergence of cloud computing. Management systems that support browser-based interface are getting common. It's natural to expect network devices to have browser-based management interface. Currently, however, few network management protocols support the transportation over HTTP. Although NETCONF[RFC6241] was defined to be sent over SOAP/ HTTPS[RFC4743], it can not realize notification mechanism[RFC5277] over SOAP/HTTPS since HTTP lacks bi-directional capabilty. But now, WebSocket protocol, the update of HTTP with bi-directional capability, is available[RFC6455]. This memo describes the way NETCONF is sent over WebSocket protocol. This memo does not intend to standardize WebSocket protocol as a mandatory transport mapping of NETCONF. NETCONF[RFC6241] specifies that it is mandatory to be sent over SSH. But RFC6241 also specifies in section 2 that "the NETCONF protocol can be layered on any transport protocol that provides the required set of functionality." According to the specification, those required set of functionality are "Connection-Oriented Operation" and "Authentication, Integrity, and Confidentiality." WebSocket protocol meets those requirements. It is 'connection-oriented.' And, as written in the section 10.5 of the WebSocket protocol specification[RFC6455], 'authentication' is ensured by mechanisms available to a generic HTTP server, such as cookies, HTTP Authentication, or TLS. Moreover, as written in the section 10.6 of the specification, 'integrity and confidentiality' are ensured by running WebSocket protocol over TLS. For these reasons, WebSocket protocol has a legitimacy to become one of the optional transport protocols of NETCONF. Iijima, et al. Expires September 6, 2012 [Page 3] Internet-Draft NETCONF over WebSocket Mar 2012 2. Problem Statement Figure 1 is an architecture of NETCONF extracted from [RFC6241]. As of now, there's few protocols that provide browser-based interface for NETCONF. Although SOAP/HTTP/TLS is defined to be one of the transport protocols for NETCONF, it falls short of realizing notification mechanis since HTTP lacks bi-directional capability. Although there are ways to outwardly provide HTTP with bi-directional capability, they have disadvantages. AJAX and Comet technologies are providing HTTP with bi-directinal capability by polling or keeping a long session at the application level. But, they tend to consume large amount of bandwidth and memories. Thus, they aren't suitable to be used in network devices due to resource constraints. Layer Example +-------------+ +-----------------+ +----------------+ (4) | Content | | Configuration | | Notification | | | | data | | data | +-------------+ +-----------------+ +----------------+ | | | +-------------+ +-----------------+ | (3) | Operations | | | | | | | | | +-------------+ +-----------------+ | | | | +-------------+ +-----------------+ +----------------+ (2) | Messages | | , | | | | | | | | | +-------------+ +-----------------+ +----------------+ | | | +-------------+ +-----------------------------------------+ (1) | Secure | | SSH, TLS, BEEP/TLS, SOAP/HTTP/TLS, ... | | Transport | | | +-------------+ +-----------------------------------------+ Figure 1: NETCONF Protocol Layers At present, however, WebSocket protocol is available. It is based on HTTP and has a bi-directional capability. Some implementations are available already. Jetty[Jetty], Kaazing[Kaazing] and so on are available as WebSocket servers. And, Chrome[Chrome] and FireFox[FireFox] are available as browsers that work as WebSocket clients. In addition, there are WebSocket client implementations. By using WebSocket protocol as an underlying protocol for NETCONF, it's possible to realize browser-based NETCONF client with event Iijima, et al. Expires September 6, 2012 [Page 4] Internet-Draft NETCONF over WebSocket Mar 2012 notification function. Iijima, et al. Expires September 6, 2012 [Page 5] Internet-Draft NETCONF over WebSocket Mar 2012 3. Use Case There are cases in which network management systems manage network devices by sending XML messages directly onto HTTP. If NETCONF and its data models, instead of proprietary XML, are used for this purpose, it's possible to manage various network devices in a same manner. Development of browser-based NETCONF client is easily possible because JavaScript-based WebSocket API[WebSocket API] is standardized and supported by current Web browsers. By writing an html file that uses WebSocket API to send and receive NETCONF messages, the html file works as a NETCONF client on Web browser. Browser-based network management systems don't require installation on computers. Therefore, those management systems can run without much care about platform on which they run. And, there is a case when people want to manage network devices from computers which they normally don't use. In such a case, browser-based management systems are effective since it doesn't require installlation. People can also manage network devices even from tablet computers. Furthermore, there are other APIs, which are also intended to be used by Web browsers for the purpose of controlling computer and storage resources. For example, DMTF (Distributed Management Task Force), has standarded REST-based CIMI(Cloud Infrastructure Management Interface)[DMTF]. REST-based API can be manipulated by JavaScript language. And, SNIA (Storage Networking Industry Association) has defined CDMI (Cloud Data Management Interface)[CDMI]. This can also be manipulated by JavaScript language. Having an option to control network devices through JavaScript-based WebSocket API will help developers to develop a NETCONF client in the same environment as other management systems that use Web-based APIs. Iijima, et al. Expires September 6, 2012 [Page 6] Internet-Draft NETCONF over WebSocket Mar 2012 4. Concerns about Using HTTP and WebSocket There are some drawbacks inherent in HTTP as mentioned in the section 2.4 of RFC 4743[RFC4743], which describes the way of using HTTP for transporting NETCONF/SOAP. But, for these drawbacks, the same section makes suggestions. Those suggestions are effective when WebSocket is used for transporting NETCONF. That is, intermediate proxies should not be used since it may close idle connections. And, the field of 'Cache-Control' and 'Pragma' in HTTP header, which is sent before WebSocket handshake, should be specified as 'no-cache.' And, WebSocket has several security concerns in common with HTTP. But, WebSocket incorporates its own security mechanisms such as origin header and masking, as stated in the Security Considerations section of [RFC6455]. In any case, use of TLS is necessary on top of those mechanisms for ensuring authentication and confidentiality. Iijima, et al. Expires September 6, 2012 [Page 7] Internet-Draft NETCONF over WebSocket Mar 2012 5. Handling of NETCONF username NETCONF[RFC6241] mandates underlying transport protocol to carry NETCONF username and to provide it to NETCONF server. For this porpose in the case of transporting NETCONF over WebSocket, this memo proposes the use of Cookie at the time of WebSocket opening handshake. How Cookie is used for NETCONF username is described in more detail in the following chapter. But, when Cookie is used for this purpose, cares need to be taken. Web browser has a characteristic to preserve Cookie value even after it stops working. Thus, if Cookie value isn't deleted explicitly, Cookie value used for NETCONF username might remain against operator's will. For this reason, it's recommended that NETCONF server, which is responsible for deploying an html file of NETCONF client, incorporates a mechanism in the html file that deletes Cookie value of NETCONF username after NETCONF username authentication is complete. Iijima, et al. Expires September 6, 2012 [Page 8] Internet-Draft NETCONF over WebSocket Mar 2012 6. Transporting NETCONF Messages over WebSocket Protocol This section specifies the way of transporting NETCONF messages between an NETCONF client and an NETCONF server when WebSocket protocol is used for underlying protocol for NETCONF. 6.1. Message Sequence Overall message sequence is depicted in Figure 2. This sequence is depicting the case in which NETCONF client runs on a Web-browser. But it must be noted that there is also a case in which NETCONF client runs as an install-based application. +---------------------------+ +-------------------------+ | Network Management System | | Network Device | | | | (192.168.1.1) | | +---------++-----------+ | |+-----------++---------+ | | | NETCONF || WebSocket | | || WebSocket || NETCONF | | | | Client || (HTTP) | | || (HTTP) || Server | | | | || Client | | || Server || | | | +---------++-----------+ | |+-----------++---------+ | +------|-----------|--------+ +------|-----------|------+ |Load *.html| | | |---------->| GET(HTTP) | | | |----------------->| | | | 200 OK(HTTP) | | | |<-----------------| | |<----------| | | .... |1. Set NETCONF username | | | on Cookie value | | |2. Call WebSocket() API | | |---------->| | | | |Connection: Upgrade | | |Set-Cookie: NETCONF_username="***" | / |----------------->| | | | | |Authentication | | | |---------->| | WebSocket | | OK | | opening | |<----------| | handshake |Connection: Upgrade | | | |<-----------------| | | | | ACK(TCP) | | | \ |----------------->| | |Invoke onopen = function() { }| | |<----------| | | | | | | Iijima, et al. Expires September 6, 2012 [Page 9] Internet-Draft NETCONF over WebSocket Mar 2012 |(NETCONF) | | |---------->| | | | |----------------->| | | | |---------->| | | | | | | |<----------| | |<-----------------| | |<----------| | | |(NETCONF)| | |---------->| | | | |----------------->| | | | |---------->| | | | | | | |<----------| | |<-----------------| | |<----------| | | .... | | (NETCONF)| | | |<----------| | |<-----------------| | |<----------| | | | | | | Figure 2: Message Sequence First of all, a browser loads an html file, which imports the code of NETCONF client that uses WebSocket API. The loaded html file works as an NETCONF client and asks an operator to type in NETCONF username. After obtaining NETCONF username, the NETCONF client sets the NETCONF username to Cookie value field in HTTP header, and it initiates WebSocket opening handshake. When NETCONF server receives a WebSocket connection request, it derives NETCONF username from the request and authenticates the client. When NETCONF client is authenticated, NETCONF server notify NETCONF client of the success of WebSocket handshake. After WebSocket connection is established, NETCONF client starts sending NETCONF messages over the connection. At first, NETCONF messages are exchanged between NETCONF client and server so that an NETCONF session is established and an NETCONF session ID is allocated by NETCONF server to the NETCONF client. After that, NETCONF messages are exchanged. After NETCONF message of request is approved by the NETCONF server, NETCONF messages are sent from NETCONF server. When WebSocket server shuts down, NETCONF session as well as WebSocket connection is killed. Since NETCONF notification Iijima, et al. Expires September 6, 2012 [Page 10] Internet-Draft NETCONF over WebSocket Mar 2012 subscription is associated with NETCONF session ID as written in section 3.5 of NETCONF notification mechanism[RFC5277], subscription status is lost when WebSocket server shuts down. Thus, it is necessary to redo WebSocket opening handshake, NETCONF session establishment, and NETCONF notification subscription when WebSocket server reboots. TCP port numbers of 80 and 443 can be used for transporting NETCONF messages over WebSocket and over WebSocket over TLS, respectively. These port numbers are automatically used if there's no indication of TCP port numbers at NETCONF client and server. But, any TCP port numbers other than above numbers can be used if there's indication of TCP port numbers at NETCONF client and server. 6.2. WebSocket Message from NETCONF Client at WebSocket Handshake WebSocket opening handshake is necessary for the establishment of an WebSocket connection. The WebSocket handshake is initiated by the NETCONF client. Figure 3 is an example of WebSocket message sent from the NETCONF client at the time of WebSocket handshake. C: GET /netconf HTTP/1.1 C: Host: 192.168.1.1 C: Upgrade: websocket C: Connection: Upgrade C: Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== C: Origin: http://192.168.1.1 C: Sec-WebSocket-Protocol: netconf C: Sec-WebSocket-Version: 13 C: Cookie: netconf_username=foo Figure 3: WebSocket Message from NETCONF Client Most of the fileds in Figure 3 are generated automatically by WebSocket client. For example, fields of 'Upgrade' and 'Connection' are specified by WebSocket client as 'websocket' and 'Upgrade' respectively, so that an HTTP server running in the NETCONF server understands that it needs to respond as an WebSocket server. The field that the NETCONF client needs to specify is that of 'Sec- WebSocket-Protocol,' so-called subprotocol field, and 'Set-Cookie' field. The NETCONF client has to specify 'Sec-WebSocket-Protocol' as 'netconf,' for example, so that the WebSocket server understands that it needs to hand over messages sent over this connection to the NETCONF server. And, the NETCONF client has to specify 'Set-Cookie' field as 'netconf_username=foo,' for example, so that the NETCONF server can authenticate NETCONF client. Iijima, et al. Expires September 6, 2012 [Page 11] Internet-Draft NETCONF over WebSocket Mar 2012 Aforementioned establishment of the WebSocket connection and specification of subprotocol is made by using WebSocket API in the html file of the NETCONF client as depicted in Figure 4. var wsURL = "ws://" + host; ws = new WebSocket(wsURL, "netconf"); Figure 4: WebSocket API in NETCONF Clients for Initiating Handshake And, setting of Cookie is made by using JavaScript API in the html file of the NETCONF client as depicted in Figure 5. If "foo" is typed in by operators of the NETCONF client, Cookie NAME of "netconf_username" and Cookie VALUE of "foo" need to be set. var userName; do{ userName = prompt("Please type in operator's name.") }while(!userName); $("#username").text(userName); document.cookie = "netconf_username=" + userName; Figure 5: JavaScript API in NETCONF Clients for Setting Cookie 6.3. WebSocket Message from NETCONF Server at WebSocket Handshake Figure 6 is an example of WebSocket message sent from an NETCONF server to an NETCONF client at the time of WebSocket handshake. S: HTTP/1.1 101 Switching Protocols S: Upgrade: websocket S: Connection: Upgrade S: Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= S: Sec-WebSocket-Protocol: netconf Figure 6: WebSocket Message from NETCONF Server Unlike the WebSocket client, there's no standardized WebSocket API for WebSocket server. Although the way of implementing WebSocket server is proprietary, there are some implementations as mentioned in section 2. Thus, it's possible to develop NETCONF server on top of those implementations by using their libraries. Iijima, et al. Expires September 6, 2012 [Page 12] Internet-Draft NETCONF over WebSocket Mar 2012 Most of the fields in Figure 6 are generated automatically by WebSocket server. For example, fields of 'Upgrade' and 'Connection' are specified by WebSocket server as 'websocket' and 'Upgrade' respectively, in order to let the NETCONF client know that an HTTP server in network device can run as WebSocket server. The field that the NETCONF server needs to specify is that of 'Sec-WebSocket- Protocol.' The NETCONF server has to specify its name of the subprotocol as 'netconf,' for example, in order to let the NETCONF client know that the WebSocket server in the network device accepts NETCONF messages. 6.4. NETCONF Message at NETCONF Client over WebSocket Connection After an WebSocket connection is established, an NETCONF client and an NETCONF server start exchanging NETCONF messages. Exchanges of messages between NETCONF client and NETCONF server begin, at first, to establish a NETCONF session. After the NETCONF session is established and a session ID is allocated to NETCONF client, messages like for NETCONF configurations and messages like for NETCONF notification should be sent from the NETCONF client to the NETCONF server. And, messages like should be sent from the NETCONF server to the NETCONF client asynchronously. During this data transfer period, both NETCONF configuration messages and NETCONF notification messages are encapsulated as a payload of WebSocket protocol according to the Data Framing specified in the section 5.2 of WebSocket protocol[RFC6455]. This encapsulation is made by WebSocket layer. Sending and receiving of NETCONF messages at NETCONF client is made by using WebSocket API as depicted in Figure 7. Iijima, et al. Expires September 6, 2012 [Page 13] Internet-Draft NETCONF over WebSocket Mar 2012 ws.onopen = function() { // WebSocket connection has established. // rpc message of can be sent here // by send() method. ws.send("message to send"); .... }; ws.onmessage = function (evt) { // NETCONF message has arrived. // NETCONF message can be parsed by DOM APIs. var received_msg = evt.data; var parser = new DOMParser(); var dom = parser.parseFromString(evt.data, "text/xml"); if(dom.documentElement.nodeName == "hello"){ // rpc reply message of has arrived. // Subsequent NETCONF message can be sent here // by send() method. ws.send("message to send"); ... } }; Figure 7: WebSocket API in NETCONF Client for Sending Messages As shown in Figure 7, NETCONF messages are sent from WebSocket API of "ws.send()." The NETCONF message to be sent through this API might be a hand-written text message typed into browser-based NMS. Or it might be created by JavaScript DOM API according to the data typed into browser-based NMS. Unlike the case of transporting NETCONF over SOAP/HTTPS, which creates parts, in the case of transporting NETCONF over WebSocket, parts as well as contents need to be created by NETCONF client. NETCONF messages are also received by WebSocket API of "ws.onmessage()." These messages are analyzed by JavaScript DOM API afterwards. 6.5. NETCONF Message at NETCONF Server over WebSocket Connection The way of sending and receiving NETCONF message at NETCONF server is proprietary. Unlike the WebSocket client, there's no standardized WebSocket API for WebSocket server. Although the way of implementing WebSocket server is proprietary, there are some implementations as mentioned in section 2. Thus, it's possible to develop NETCONF server on top of those implementations by using their libraries. By Iijima, et al. Expires September 6, 2012 [Page 14] Internet-Draft NETCONF over WebSocket Mar 2012 using send method of those libraries, it's possible to send NETCONF notification message asynchronously from NETCONF server to NETCONF clients. Iijima, et al. Expires September 6, 2012 [Page 15] Internet-Draft NETCONF over WebSocket Mar 2012 7. Security Considerations The security considerations of NETCONF protocol[RFC6241], NETCONF Notification mechanism[RFC5277], and WebSocket protocol[RFC6455] are applicable to this document. Implementers or users should take these considerations into account. It is necessary to use TLS (Transport Layer Security) in order to ensure Transport-level security, such as authentication of users and encryption of data transfer. That is, security has to be provided in the form of NETCONF over WebSocket over TLS (WSS). Iijima, et al. Expires September 6, 2012 [Page 16] Internet-Draft NETCONF over WebSocket Mar 2012 8. IANA Considerations As written in section 11.5 of WebSokcet protocol[RFC6455], NETCONF's Subprotocol Common Name, to be exchanged in 'Sec-WebSocket-Protocol' field at WebSocket opening handshake, coupled with Identifier and Definition are necessary to be registered with the WebSocket Subprotocol Name Registry. Iijima, et al. Expires September 6, 2012 [Page 17] Internet-Draft NETCONF over WebSocket Mar 2012 9. Acknowledgements This document was written using the xml2rfc tool described in RFC 2629 [RFC2629]. Iijima, et al. Expires September 6, 2012 [Page 18] Internet-Draft NETCONF over WebSocket Mar 2012 10. References 10.1. Normative References [RFC4743] Goddard, T., "Using NETCONF over the Simple Object Access Protocol (SOAP)", RFC 4743, December 2006. [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event Notifications", RFC 5277, July 2008. [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. Bierman, "Network Configuration Protocol (NETCONF)", RFC 6241, June 2011. [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", RFC 6455, December 2011. [WebSocket API] "The WebSocket API". 10.2. Informative References [CDMI] "SNIA's CDMI". [Chrome] "Chrome". [DMTF] "CLOUD | DMTF". [FireFox] "FireFox". [Jetty] "Jetty WebServer". [Kaazing] "Kaazing". Iijima, et al. Expires September 6, 2012 [Page 19] Internet-Draft NETCONF over WebSocket Mar 2012 [RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, June 1999. Iijima, et al. Expires September 6, 2012 [Page 20] Internet-Draft NETCONF over WebSocket Mar 2012 Authors' Addresses Tomoyuki Iijima Hitachi, Ltd. 292 Yoshida-cho, Totsuka-ku Yokohama, Kanagawa 244-0817 Japan Phone: +81-45-860-2156 Email: tomoyuki.iijima.fg@hitachi.com Hiroyasu Kimura Alaxala Networks Corp. Shin-Kawasaki Mitsui Bldg. 890 Saiwai-ku Kashimada Kawasaki, Kanagawa 212-0058 Japan Phone: +81-44-549-1735 Fax: +81-44-549-1272 Email: h-kimura@alaxala.com Yoshifumi Atarashi Alaxala Networks Corp. Shin-Kawasaki Mitsui Bldg. 890 Saiwai-ku Kashimada Kawasaki, Kanagawa 212-0058 Japan Phone: +81-44-549-1735 Fax: +81-44-549-1272 Email: atarashi@alaxala.net Hidemitsu Higuchi Alaxala Networks Corp. Shin-Kawasaki Mitsui Bldg. 890 Saiwai-ku Kashimada Kawasaki, Kanagawa 212-0058 Japan Phone: +81-44-549-1735 Fax: +81-44-549-1272 Email: hidemitsu.higuchi@alaxala.com Iijima, et al. Expires September 6, 2012 [Page 21]