draft-ietf-netconf-soap-02.txt   draft-ietf-netconf-soap-03.txt 
Network Working Group T. Goddard Network Working Group T. Goddard
Internet-Draft ICEsoft Technologies Inc. Internet-Draft ICEsoft Technologies Inc.
Expires: December 3, 2004 June 4, 2004 Expires: March 8, 2005 September 7, 2004
NETCONF Over SOAP Using the Network Configuration Protocol (NETCONF) Over the Simple
draft-ietf-netconf-soap-02 Object Access Protocol (SOAP)
draft-ietf-netconf-soap-03
Status of this Memo Status of this Memo
This document is an Internet-Draft and is in full conformance with This document is an Internet-Draft and is subject to all provisions
all provisions of Section 10 of RFC2026. of section 3 of RFC 3667. By submitting this Internet-Draft, each
author represents that any applicable patent or other IPR claims of
which he or she is aware have been or will be disclosed, and any of
which he or she become aware will be disclosed, in accordance with
RFC 3668.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that other Task Force (IETF), its areas, and its working groups. Note that
groups may also distribute working documents as Internet-Drafts. other groups may also distribute working documents as
Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at http:// The list of current Internet-Drafts can be accessed at
www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on December 3, 2004. This Internet-Draft will expire on March 8, 2005.
Copyright Notice Copyright Notice
Copyright (C) The Internet Society (2004). All Rights Reserved. Copyright (C) The Internet Society (2004).
Abstract Abstract
The device management protocol NETCONF is applicable to a wide range The Network Configuration Protocol (NETCONF) is applicable to a wide
of devices in a variety of environments. The emergence of Web range of devices in a variety of environments. The emergence of Web
Services gives one such environment, and is presently characterized Services gives one such environment, and is presently characterized
by the use of SOAP over HTTP. NETCONF finds many benefits in this by the use of the Simple Object Access Protocol (SOAP). NETCONF
environment: from the re-use of existing standards, to ease of finds many benefits in this environment: from the re-use of existing
software development, to integration with deployed systems. Herein, standards, to ease of software development, to integration with
we describe a SOAP over HTTP binding that, when used with persistent deployed systems. Herein, we describe SOAP over HTTP and SOAP over
HTTP connections, yields an application protocol sufficient for BEEP bindings that yield application protocols sufficient for
NETCONF. NETCONF.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. SOAP Background for NETCONF . . . . . . . . . . . . . . . . 4 2. SOAP Background for NETCONF . . . . . . . . . . . . . . . . . 4
2.1 Use and Storage of WSDL and XSD . . . . . . . . . . . . . . 4 2.1 Use and Storage of WSDL and XSD . . . . . . . . . . . . . 4
2.2 SOAP over HTTP . . . . . . . . . . . . . . . . . . . . . . . 5 2.2 SOAP over HTTP . . . . . . . . . . . . . . . . . . . . . . 5
2.3 HTTP Drawbacks . . . . . . . . . . . . . . . . . . . . . . . 5 2.3 HTTP Drawbacks . . . . . . . . . . . . . . . . . . . . . . 5
2.4 BCP56: On the Use of HTTP as a Substrate . . . . . . . . . . 6 2.4 BCP56: On the Use of HTTP as a Substrate . . . . . . . . . 6
2.5 Important HTTP 1.1 Features . . . . . . . . . . . . . . . . 6 2.5 Important HTTP 1.1 Features . . . . . . . . . . . . . . . 6
2.6 SOAP Implementation Considerations . . . . . . . . . . . . . 7 2.6 SOAP Over BEEP . . . . . . . . . . . . . . . . . . . . . . 7
2.6.1 SOAP Feature Exploitation . . . . . . . . . . . . . . . . . 7 2.7 SOAP Implementation Considerations . . . . . . . . . . . . 7
2.6.2 SOAP Headers . . . . . . . . . . . . . . . . . . . . . . . . 7 2.7.1 SOAP Feature Exploitation . . . . . . . . . . . . . . 7
2.6.3 SOAP Faults . . . . . . . . . . . . . . . . . . . . . . . . 8 2.7.2 SOAP Headers . . . . . . . . . . . . . . . . . . . . . 8
3. A SOAP Web Service for NETCONF . . . . . . . . . . . . . . . 9 2.7.3 SOAP Faults . . . . . . . . . . . . . . . . . . . . . 8
3.1 Fundamental Use Case . . . . . . . . . . . . . . . . . . . . 9 3. A SOAP Service for NETCONF . . . . . . . . . . . . . . . . . . 10
3.2 NETCONF Sessions . . . . . . . . . . . . . . . . . . . . . . 9 3.1 Fundamental Use Case . . . . . . . . . . . . . . . . . . . 10
3.3 Capabilities Exchange . . . . . . . . . . . . . . . . . . . 9 3.2 NETCONF Session Establishment . . . . . . . . . . . . . . 10
3.4 A NETCONF/SOAP example . . . . . . . . . . . . . . . . . . . 10 3.3 NETCONF Capabilities Exchange . . . . . . . . . . . . . . 10
4. Security Considerations . . . . . . . . . . . . . . . . . . 12 3.4 NETCONF Session Usage . . . . . . . . . . . . . . . . . . 10
4.1 Integrity, Privacy, and Authentication . . . . . . . . . . . 12 3.5 NETCONF Session Teardown . . . . . . . . . . . . . . . . . 11
4.2 Vulnerabilities . . . . . . . . . . . . . . . . . . . . . . 12 3.6 A NETCONF Over SOAP example . . . . . . . . . . . . . . . 11
4.3 Environmental Specifics . . . . . . . . . . . . . . . . . . 13 4. Security Considerations . . . . . . . . . . . . . . . . . . . 13
Normative References . . . . . . . . . . . . . . . . . . . . 14 4.1 Integrity, Privacy, and Authentication . . . . . . . . . . 13
Informative References . . . . . . . . . . . . . . . . . . . 16 4.2 Vulnerabilities . . . . . . . . . . . . . . . . . . . . . 13
Author's Address . . . . . . . . . . . . . . . . . . . . . . 16 4.3 Environmental Specifics . . . . . . . . . . . . . . . . . 14
A. WSDL Definitions . . . . . . . . . . . . . . . . . . . . . . 17 5. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15
A.1 NETCONF SOAP Binding . . . . . . . . . . . . . . . . . . . . 17 5.1 Normative References . . . . . . . . . . . . . . . . . . . . 15
A.2 Sample Service Definition . . . . . . . . . . . . . . . . . 18 5.2 Informative References . . . . . . . . . . . . . . . . . . . 16
Intellectual Property and Copyright Statements . . . . . . . 19 Author's Address . . . . . . . . . . . . . . . . . . . . . . . 16
A. WSDL Definitions . . . . . . . . . . . . . . . . . . . . . . . 17
A.1 NETCONF SOAP Binding . . . . . . . . . . . . . . . . . . . 17
A.2 Sample Service Definition . . . . . . . . . . . . . . . . 18
Intellectual Property and Copyright Statements . . . . . . . . 19
1. Introduction 1. Introduction
Given the use of XML [2] and the remote procedure call Given the use of XML [2] and the remote procedure call
characteristics, it is natural to consider a binding of the NETCONF characteristics, it is natural to consider a binding of the NETCONF
[1] operations to a SOAP [3] application protocol. This document [1] operations to a SOAP [3] application protocol. This document
proposes a binding of this form. proposes a binding of this form.
In general, SOAP over HTTP is a natural application protocol for In general, SOAP is a natural application protocol for NETCONF,
NETCONF, essentially because of the remote procedure call character essentially because of the remote procedure call character of both.
of both, but care must be taken in some cases as HTTP is inherently However, care must be taken with SOAP over HTTP as it is inherently
synchronous and client-driven. synchronous and client-driven. SOAP over BEEP [15] is technically
superior, but is not as widely adopted.
Four basic topics are presented: SOAP specifics of interest to Four basic topics are presented: SOAP specifics of interest to
NETCONF, specifics on implementing NETCONF as a SOAP-based web NETCONF, specifics on implementing NETCONF as a SOAP-based web
service, security considerations, and an appendix with functional service, security considerations, and an appendix with functional
WSDL. In some sense, the most important part of the document is the WSDL. In some sense, the most important part of the document is the
brief WSDL document presented in the Appendix. With the right tools, brief WSDL document presented in the Appendix. With the right tools,
the WSDL combined with the base NETCONF XML Schemas provide machine the WSDL combined with the base NETCONF XML Schemas provide machine
readable descriptions sufficient for the development of software readable descriptions sufficient for the development of software
applications using NETCONF. applications using NETCONF.
skipping to change at page 4, line 26 skipping to change at page 4, line 26
The "header" contains meta-information relating to the message, and The "header" contains meta-information relating to the message, and
can be used to indicate such things as store-and-forward behaviour or can be used to indicate such things as store-and-forward behaviour or
transactional characteristics. In addition, SOAP specifies an transactional characteristics. In addition, SOAP specifies an
optional encoding for the "body" of the message. However, this optional encoding for the "body" of the message. However, this
encoding is not applicable to NETCONF as one of the goals is to have encoding is not applicable to NETCONF as one of the goals is to have
highly readable XML, and SOAP-encoding is optimized instead for ease highly readable XML, and SOAP-encoding is optimized instead for ease
of automated deserialization. These benefits of the SOAP message of automated deserialization. These benefits of the SOAP message
structure are simple, but worthwhile due to the fact that they are structure are simple, but worthwhile due to the fact that they are
already standardized. already standardized.
It is the practical reasons that truly make SOAP over HTTP an It is the practical reasons that truly make SOAP an interesting
interesting choice for device management. It is not difficult to choice for device management. It is not difficult to invent a
invent a mechanism for exchanging XML messages over TCP, but what is mechanism for exchanging XML messages over TCP, but what is difficult
difficult is getting that mechanism supported in a wide variety of is getting that mechanism supported in a wide variety of tools and
tools and operating systems and having that mechanism understood by a operating systems and having that mechanism understood by a great
great many developers. SOAP over HTTP (with WSDL) is seeing good many developers. SOAP over HTTP (with WSDL) is seeing good success
success at this, and this means that a device management protocol at this, and this means that a device management protocol making use
making use of these technologies has advantages in being implemented of these technologies has advantages in being implemented and
and adopted. Admittedly, there are interoperability problems with adopted. Admittedly, there are interoperability problems with SOAP
SOAP and WSDL, but such problems have wide attention and can be and WSDL, but such problems have wide attention and can be expected
expected to be resolved. to be resolved.
2.1 Use and Storage of WSDL and XSD 2.1 Use and Storage of WSDL and XSD
One of the advantages of using machine readable formats such as Web One of the advantages of using machine readable formats such as Web
Services Description Language (WSDL) [4] and XML Schemas [5] is that Services Description Language (WSDL) [4] and XML Schemas [5] is that
they can be used automatically in the software development process. they can be used automatically in the software development process.
With appropriate tools, WSDL and XSD can be used to generate classes With appropriate tools, WSDL and XSD can be used to generate classes
that act as remote interfaces or application specific data that act as remote interfaces or application specific data
structures. Other uses, such as document generation and service structures. Other uses, such as document generation and service
location, are also common. A great innovation found with many location, are also common. A great innovation found with many
skipping to change at page 5, line 18 skipping to change at page 5, line 18
over time and all are accessible to automated software tools that over time and all are accessible to automated software tools that
ensure adherence to the standards. Thus, it will gradually become as ensure adherence to the standards. Thus, it will gradually become as
important for iana.org to host documents like important for iana.org to host documents like
http://iana.org/ietf/netconf/base_1.0.xsd http://iana.org/ietf/netconf/base_1.0.xsd
as the IETF now hosts documents such as as the IETF now hosts documents such as
http://www.ietf.org/rfc/rfc2616.txt http://www.ietf.org/rfc/rfc2616.txt
Note that WSDL declarations for SOAP over BEEP bindings are not yet
standardized.
2.2 SOAP over HTTP 2.2 SOAP over HTTP
While it is true that SOAP focuses on messages and can be bound to While it is true that SOAP focuses on messages and can be bound to
different underlying protocols such as HTTP, SMTP, or BEEP, most different underlying protocols such as HTTP, SMTP, or BEEP, most
existing SOAP implementations support only HTTP or HTTP/TLS. For existing SOAP implementations support only HTTP or HTTP/TLS.
this discussion we will assume SOAP over HTTP or HTTP/TLS unless
otherwise specified. (This also includes applications of IPSec to
SOAP over HTTP.)
Note that there are a number of advantages to considering SOAP over There are a number of advantages to considering SOAP over protocols
protocols other than HTTP, as HTTP assigns the very distinct client other than HTTP, as HTTP assigns the very distinct client and server
and server roles by connection initiation. This would cause roles by connection initiation. This causes difficulties in
difficulties in supporting asynchronous notification and could be supporting asynchronous notification and can be relieved in many ways
relieved in many ways by replacing HTTP with BEEP. by replacing HTTP with BEEP.
2.3 HTTP Drawbacks 2.3 HTTP Drawbacks
HTTP is not the ideal transport for messaging, but it is adequate for HTTP is not the ideal transport for messaging, but it is adequate for
the most basic interpretation of "remote procedure call". HTTP is the most basic interpretation of "remote procedure call". HTTP is
based on a communication pattern whereby the client (which initiates based on a communication pattern whereby the client (which initiates
the TCP connection) makes a "request" to the server. The server the TCP connection) makes a "request" to the server. The server
returns a "response" and this process is continued (possibly over a returns a "response" and this process is continued (possibly over a
persistent connection, as described below). This matches the basic persistent connection, as described below). This matches the basic
idea of a remote procedure call where the caller invokes a procedure idea of a remote procedure call where the caller invokes a procedure
on a remote server and waits for the return value. on a remote server and waits for the return value.
Potential criticisms of HTTP could include the following: Potential criticisms of HTTP could include the following:
o server-initiated data flow is awkward to provide
o server-initiated data flow is awkward
o headers are verbose and text-based o headers are verbose and text-based
o idle connections may be closed by intermediate proxies o idle connections may be closed by intermediate proxies
o data encapsulation must adhere to MIME o data encapsulation must adhere to MIME
o bulk transfer relies on stream-based ordering o bulk transfer relies on stream-based ordering
In many ways these criticisms are directed at particular compromises In many ways these criticisms are directed at particular compromises
in the design of HTTP. As such, they are important to consider, but in the design of HTTP. As such, they are important to consider, but
it is not clear that they result in fatal drawbacks for a device it is not clear that they result in fatal drawbacks for a device
management protocol. management protocol.
2.4 BCP56: On the Use of HTTP as a Substrate 2.4 BCP56: On the Use of HTTP as a Substrate
Best Current Practice 56 [9] presents a number of important Best Current Practice 56 [9] presents a number of important
skipping to change at page 6, line 18 skipping to change at page 6, line 13
In many ways these criticisms are directed at particular compromises In many ways these criticisms are directed at particular compromises
in the design of HTTP. As such, they are important to consider, but in the design of HTTP. As such, they are important to consider, but
it is not clear that they result in fatal drawbacks for a device it is not clear that they result in fatal drawbacks for a device
management protocol. management protocol.
2.4 BCP56: On the Use of HTTP as a Substrate 2.4 BCP56: On the Use of HTTP as a Substrate
Best Current Practice 56 [9] presents a number of important Best Current Practice 56 [9] presents a number of important
considerations on the use of HTTP in application protocols. In considerations on the use of HTTP in application protocols. In
particular, it raises the following concerns: particular, it raises the following concerns:
o HTTP may be more complex than is necessary for the application o HTTP may be more complex than is necessary for the application
o The use of HTTP may mask the application from some firewalls o The use of HTTP may mask the application from some firewalls
o A substantially new service should not re-use port 80 as assigned o A substantially new service should not re-use port 80 as assigned
to HTTP to HTTP
o HTTP caching may mask connection state
Fundamentally, these concerns lie directly with SOAP over HTTP, Fundamentally, these concerns lie directly with SOAP over HTTP,
rather than the application of SOAP over HTTP to NETCONF. As BCP 56 rather than the application of SOAP over HTTP to NETCONF. As BCP 56
indicates, it is debatable whether HTTP is an appropriate protocol indicates, it is debatable whether HTTP is an appropriate protocol
for SOAP at all, and it is likely that BEEP would be a superior for SOAP at all, and it is likely that BEEP would be a superior
protocol for most SOAP applications. Unfortunately, SOAP over HTTP is protocol for most SOAP applications. Unfortunately, SOAP over HTTP
in common use and must be supported if the practical benefits of SOAP is in common use and must be supported if the practical benefits of
are to be realized. SOAP are to be realized. Note that the verbose nature of SOAP
actually makes it more readily processed by firewalls, albeit
firewalls designed to process SOAP messages.
It is possible, however, to respond to the concern on the re-use of It is very important that HTTP caches are not inserted between
port 80. A NETCONF SOAP service can be offered on any desired port, NETCONF managers and agents as NETCONF session state is tied to the
and it is recommended that a new standard port for SOAP over HTTP, or state of the underlying transport connection. Three defensive
a new standard port for NETCONF over SOAP (over HTTP) be defined. actions can be taken:
o Prohibit caching through the use of HTTP headers Cache-Control and
Pragma: no-cache
o Ensure that HTTP proxies are not deployed within the management
network
o Use HTTPS
It is also possible to respond to the concern on the re-use of port
80. A NETCONF SOAP service can be offered on any desired port, and
it is recommended that a new standard port for SOAP over HTTP, or a
new standard port for NETCONF over SOAP (over HTTP) be defined.
2.5 Important HTTP 1.1 Features 2.5 Important HTTP 1.1 Features
HTTP 1.1 [8] includes two important features that provide for HTTP 1.1 [8] includes two important features that provide for
relatively efficient transport of SOAP messages. These features are relatively efficient transport of SOAP messages. These features are
"persistent connections" and "chunked transfer-coding". "persistent connections" and "chunked transfer-coding".
Persistent connections allow a single TCP connection to be used Persistent connections allow a single TCP connection to be used
across multiple HTTP requests. This permits multiple SOAP request/ across multiple HTTP requests. This permits multiple SOAP request/
response message pairs to be exchanged without the overhead of response message pairs to be exchanged without the overhead of
skipping to change at page 7, line 25 skipping to change at page 7, line 30
connections are clearly important for performance reasons, and are connections are clearly important for performance reasons, and are
particularly important when it is the persistence of authenticated particularly important when it is the persistence of authenticated
connections that is at stake. When one considers that messages of connections that is at stake. When one considers that messages of
dynamic length are the rule rather than the exception for SOAP dynamic length are the rule rather than the exception for SOAP
messages, it is also clear that Chunking is very useful. In some messages, it is also clear that Chunking is very useful. In some
cases it is possible to buffer a SOAP response and determine its cases it is possible to buffer a SOAP response and determine its
length before sending, but the storage requirements for this are length before sending, but the storage requirements for this are
prohibitive for many devices. Together, these two features provide a prohibitive for many devices. Together, these two features provide a
good foundation for device management using SOAP over HTTP. good foundation for device management using SOAP over HTTP.
2.6 SOAP Implementation Considerations 2.6 SOAP Over BEEP
Although not widely adopted by the Web Services community, BEEP is an
excellent substrate for SOAP [16]. In particular, it provides for
request/response message exchanges initiated by either BEEP peer and
allows the number of response messages to be arbitrary (including
zero). The BEEP profile for SOAP simply makes use of a single BEEP
channel for exchanging SOAP messages and benefits from BEEP's
inherent strengths for message exchange over a single transport
connection.
2.7 SOAP Implementation Considerations
It is not the goal of this document to cover the SOAP [3] It is not the goal of this document to cover the SOAP [3]
specification in detail. Instead, we provide a few comments that may specification in detail. Instead, we provide a few comments that may
be of interest to an implementor of NETCONF over SOAP. be of interest to an implementor of NETCONF over SOAP.
2.6.1 SOAP Feature Exploitation 2.7.1 SOAP Feature Exploitation
NETCONF over SOAP does not make extensive use of SOAP features. For NETCONF over SOAP does not make extensive use of SOAP features. For
instance, NETCONF operations are not broken into SOAP message parts, instance, NETCONF operations are not broken into SOAP message parts,
and the SOAP header is not used to convey <rpc> metadata. This is a and the SOAP header is not used to convey <rpc> metadata. This is a
deliberate design decision as it allows the implementor to easily deliberate design decision as it allows the implementor to easily
provide NETCONF over multiple substrates while handling the messages provide NETCONF over multiple substrates while handling the messages
over those different substrates in a common way. over those different substrates in a common way.
2.6.2 SOAP Headers 2.7.2 SOAP Headers
Implementors of NETCONF over SOAP should be aware of the following Implementors of NETCONF over SOAP should be aware of the following
characteristic of SOAP headers: a SOAP header may have the attribute characteristic of SOAP headers: a SOAP header may have the attribute
"mustUnderstand" and, if so, the recipient must either process the "mustUnderstand" and, if so, the recipient must either process the
header block or not process the SOAP message at all, and instead header block or not process the SOAP message at all, and instead
generate a fault. A "mustUnderstand" header must not be silently generate a fault. A "mustUnderstand" header must not be silently
discarded. discarded.
In general, however, SOAP headers are intended for In general, however, SOAP headers are intended for
application-specific uses. The NETCONF SOAP binding does not make application-specific uses. The NETCONF SOAP binding does not make
use of SOAP headers. use of SOAP headers.
2.6.3 SOAP Faults 2.7.3 SOAP Faults
A SOAP Fault is returned in the event of a NETCONF <rpc-error>. It A SOAP Fault is returned in the event of a NETCONF <rpc-error>. It
is constructed essentially as a wrapper for the <rpc-error>, but is constructed essentially as a wrapper for the <rpc-error>, but
allow SOAP processors to propagate the <rpc-error> to application allow SOAP processors to propagate the <rpc-error> to application
code using a language-appropriate exception mechanism. code using a language-appropriate exception mechanism.
A SOAP Fault is constructed from an <rpc-error> as follows: the SOAP A SOAP Fault is constructed from an <rpc-error> as follows: the SOAP
Fault faultcode is "Client" in the SOAP envelope namespace, the SOAP Fault faultcode is "Client" in the SOAP envelope namespace, the SOAP
Fault faultstring is the contents of the NETCONF <rpc-error> "tag", Fault faultstring is the contents of the NETCONF <rpc-error> "tag",
and the SOAP Fault detail is the original <rpc-error> structure. and the SOAP Fault detail is the original <rpc-error> structure.
skipping to change at page 9, line 5 skipping to change at page 10, line 5
<severity>error</severity> <severity>error</severity>
<statement>mtu 21050;</statement> <statement>mtu 21050;</statement>
<message>MTU 21050 on Ethernet/1 is <message>MTU 21050 on Ethernet/1 is
outside range 256..9192</message> outside range 256..9192</message>
</rpc-error> </rpc-error>
</detail> </detail>
</soapenv:Fault> </soapenv:Fault>
</soapenv:Body> </soapenv:Body>
</soapenv:Envelope> </soapenv:Envelope>
3. A SOAP Web Service for NETCONF 3. A SOAP Service for NETCONF
3.1 Fundamental Use Case 3.1 Fundamental Use Case
The fundamental use case for NETCONF over SOAP (NETCONF/SOAP) over The fundamental use case for NETCONF over SOAP is that of a
HTTP is that of a management console ("manager" role) managing one or management console ("manager" role) managing one or more devices
more devices running NETCONF agents ("agent" role). The manager running NETCONF agents ("agent" role). The manager initiates an HTTP
initiates an HTTP connection to an agent and drives the NETCONF or BEEP connection to an agent and drives the NETCONF session via a
session via a sequence of SOAP messages over HTTP requests. When the sequence of SOAP messages. When the manager closes the connection,
manager closes the HTTP connection, the NETCONF session is also the NETCONF session is also closed.
closed.
3.2 NETCONF Sessions 3.2 NETCONF Session Establishment
A NETCONF over SOAP session is established by the initial message
exchange on the underlying substrate. For HTTP, a NETCONF session is
established once a SOAP message is POSTed to the NETCONF web
application URI. For BEEP, a NETCONF session is established once the
BEEP profile for SOAP handshake establishes the SOAP channel.
3.3 NETCONF Capabilities Exchange
Capabilities exchange, if defined through a NETCONF RPC operation,
can easily be accommodated in the SOAP binding.
3.4 NETCONF Session Usage
NETCONF sessions are persistent for both performance and semantic NETCONF sessions are persistent for both performance and semantic
reasons. NETCONF session state contains the following: reasons. NETCONF session state contains the following:
1. Authentication Information 1. Authentication Information
2. Capability Information 2. Capability Information
3. Locks 3. Locks
4. Pending Operations 4. Pending Operations
5. Operation Sequence Numbers 5. Operation Sequence Numbers
Authentication must be maintained throughout a session due to the Authentication must be maintained throughout a session due to the
fact that it is expensive to establish. Capability Information is fact that it is expensive to establish. Capability Information is
maintained so that appropriate operations can be applied during a maintained so that appropriate operations can be applied during a
session. Locks are released upon termination of a session as this session. Locks are released upon termination of a session as this
makes the protocol more robust. Pending operations come and go from makes the protocol more robust. Pending operations come and go from
existence during the normal course of RPC operations. Operation existence during the normal course of RPC operations. Operation
sequence numbers provide the small but necessary state information to sequence numbers provide the small but necessary state information to
refer to operations during the session. refer to operations during the session.
skipping to change at page 9, line 41 skipping to change at page 10, line 48
Authentication must be maintained throughout a session due to the Authentication must be maintained throughout a session due to the
fact that it is expensive to establish. Capability Information is fact that it is expensive to establish. Capability Information is
maintained so that appropriate operations can be applied during a maintained so that appropriate operations can be applied during a
session. Locks are released upon termination of a session as this session. Locks are released upon termination of a session as this
makes the protocol more robust. Pending operations come and go from makes the protocol more robust. Pending operations come and go from
existence during the normal course of RPC operations. Operation existence during the normal course of RPC operations. Operation
sequence numbers provide the small but necessary state information to sequence numbers provide the small but necessary state information to
refer to operations during the session. refer to operations during the session.
In the case of SOAP over HTTP, a NETCONF "session" is supported by an In the case of SOAP over HTTP, a NETCONF session is supported by an
HTTP connection with an authenticated user. To support automated HTTP connection with an authenticated user. For SOAP over BEEP, a
cleanup, a NETCONF over SOAP session is closed when the HTTP NETCONF session is supported by a BEEP channel operating according to
connection is closed. the BEEP profile for SOAP [16].
3.3 Capabilities Exchange 3.5 NETCONF Session Teardown
Capabilities exchange, if defined through a NETCONF RPC operation, To allow automated cleanup, NETCONF over SOAP session teardown takes
can easily be accommodated in the SOAP binding. place when the underlying connection (in the case of HTTP) or channel
(in the case of BEEP) is closed. Note that the root cause of such
teardown may be the closure of the TCP connection under either HTTP
or BEEP as the case may be. NETCONF managers and agents must be
capable of programatically closing the transport connections
associated with NETCONF sessions; thus, the HTTP or BEEP substrate
implementation must expose this appropriately.
3.4 A NETCONF/SOAP example 3.6 A NETCONF Over SOAP example
Since the proposed WSDL (in Appendix A.1) uses document/literal Since the proposed WSDL (in Appendix A.1) uses document/literal
encoding, the use of a SOAP header and body has little impact on the encoding, the use of a SOAP header and body has little impact on the
representation of a NETCONF operation. This example shows HTTP/1.0 representation of a NETCONF operation. This example shows HTTP/1.0
for simplicity. for simplicity. Examples for HTTP/1.1 and BEEP would be similar.
POST /netconf HTTP/1.0 POST /netconf HTTP/1.0
Content-Type: text/xml; charset=utf-8 Content-Type: text/xml; charset=utf-8
Accept: application/soap+xml, text/* Accept: application/soap+xml, text/*
Cache-Control: no-cache Cache-Control: no-cache
Pragma: no-cache Pragma: no-cache
Content-Length: 470 Content-Length: 470
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope <soapenv:Envelope
skipping to change at page 12, line 33 skipping to change at page 13, line 33
protocols, such as HTTP, care should be taken to prevent execution of protocols, such as HTTP, care should be taken to prevent execution of
the NETCONF program when strong user authentication or data privacy the NETCONF program when strong user authentication or data privacy
is not available. is not available.
4.1 Integrity, Privacy, and Authentication 4.1 Integrity, Privacy, and Authentication
The NETCONF SOAP binding relies on an underlying secure transport for The NETCONF SOAP binding relies on an underlying secure transport for
integrity and privacy. Such transports are expected to include TLS integrity and privacy. Such transports are expected to include TLS
[12] and IPSec. There are a number of options for authentication [12] and IPSec. There are a number of options for authentication
(some of which are deployment-specific): (some of which are deployment-specific):
o within the transport (such as with TLS client certificates) o within the transport (such as with TLS client certificates)
o within HTTP (such as Digest Access Authentication [10]) o within HTTP (such as Digest Access Authentication [10])
o within SOAP (such as a digital signature in the header [18])
o within SOAP (such as a digital signature in the header [16]) HTTP, BEEP, and SOAP level authentication can be integrated with
RADIUS [13] to support remote authentication databases.
HTTP and SOAP level authentication can be integrated with RADIUS [13]
to support remote authentication databases.
4.2 Vulnerabilities 4.2 Vulnerabilities
The above protocols may have various vulnerabilities, and these may The above protocols may have various vulnerabilities, and these may
be inherited by NETCONF/SOAP. be inherited by NETCONF over SOAP.
NETCONF itself may have vulnerabilities due to the fact that an NETCONF itself may have vulnerabilities due to the fact that an
authorization model is not currently specified. authorization model is not currently specified.
It is important that device capabilities and authorization remain It is important that device capabilities and authorization remain
constant for the duration of any outstanding NETCONF session. In the constant for the duration of any outstanding NETCONF session. In the
case of NETCONF, it is important to consider that device management case of NETCONF, it is important to consider that device management
may be taking place over multiple substrates (in addition to SOAP) may be taking place over multiple substrates (in addition to SOAP)
and it is important that the different substrates have a common and it is important that the different substrates have a common
authentication model. authentication model.
4.3 Environmental Specifics 4.3 Environmental Specifics
Some deployments of NETCONF/SOAP may choose to use HTTP without Some deployments of NETCONF over SOAP may choose to use transports
encryption. This presents vulnerabilities but may be selected for without encryption. This presents vulnerabilities but may be
deployments involving closed networks or debugging scenarios. selected for deployments involving closed networks or debugging
scenarios.
A device managed by NETCONF may interact (over protocols other than A device managed by NETCONF may interact (over protocols other than
NETCONF) with devices managed by other protocols, all of differing NETCONF) with devices managed by other protocols, all of differing
security. Each point of entry brings with it a potential security. Each point of entry brings with it a potential
vulnerability. vulnerability.
Normative References 5. References
[1] Enns, R., "XMLCONF Configuration Protocol", 5.1 Normative References
draft-enns-xmlconf-spec-03 (work in progress), Feb 2003,
[1] Enns, R., "NETCONF Configuration Protocol",
draft-ietf-netconf-prot-03 (work in progress), June 2004,
<http://www.ietf.org/internet-drafts/ <http://www.ietf.org/internet-drafts/
draft-enns-xmlconf-spec-03.txt>. draft-ietf-netconf-prot-03.txt>.
[2] Bray, T., Paoli, J., Sperberg-McQueen, C. and E. Maler, [2] Bray, T., Paoli, J., Sperberg-McQueen, C. and E. Maler,
"Extensible Markup Language (XML) 1.0 (Second Edition)", W3C "Extensible Markup Language (XML) 1.0 (Second Edition)", W3C
REC REC-xml-20001006, October 2000, <http://www.w3.org/TR/2000/ REC REC-xml-20001006, October 2000,
REC-xml-20001006>. <http://www.w3.org/TR/2000/REC-xml-20001006>.
[3] Box, D., Ehnebuske, D., Kakivaya, G., Layman, A., Mendelsohn, [3] Box, D., Ehnebuske, D., Kakivaya, G., Layman, A., Mendelsohn,
N., Nielsen, H., Thatte, S. and D. Winer, "Simple Object Access N., Nielsen, H., Thatte, S. and D. Winer, "Simple Object Access
Protocol (SOAP) 1.1", W3C Note NOTE-SOAP-20000508, May 2000, Protocol (SOAP) 1.1", W3C Note NOTE-SOAP-20000508, May 2000,
<http://www.w3.org/TR/2000/NOTE-SOAP-20000508>. <http://www.w3.org/TR/2000/NOTE-SOAP-20000508>.
[4] Christensen, E., Curbera, F., Meredith, G. and S. Weerawarana, [4] Christensen, E., Curbera, F., Meredith, G. and S. Weerawarana,
"Web Services Description Language (WSDL) 1.1", W3C Note "Web Services Description Language (WSDL) 1.1", W3C Note
NOTE-wsdl-20010315, March 2001, <http://www.w3.org/TR/2001/ NOTE-wsdl-20010315, March 2001,
NOTE-wsdl-20010315>. <http://www.w3.org/TR/2001/NOTE-wsdl-20010315>.
[5] Thompson, H., Beech, D., Maloney, M. and N. Mendelsohn, "XML [5] Thompson, H., Beech, D., Maloney, M. and N. Mendelsohn, "XML
Schema Part 1: Structures", W3C Recommendation Schema Part 1: Structures", W3C Recommendation
REC-xmlschema-1-20010502, May 2001, <http://www.w3.org/TR/2001/ REC-xmlschema-1-20010502, May 2001,
REC-xmlschema-1-20010502/>. <http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/>.
[6] Freed, N. and N. Borenstein, "Multipurpose Internet Mail [6] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part One: Format of Internet Message Bodies", Extensions (MIME) Part One: Format of Internet Message Bodies",
RFC 2045, November 1996, <http://www.ietf.org/rfc/rfc2045.txt>. RFC 2045, November 1996, <http://www.ietf.org/rfc/rfc2045.txt>.
[7] Freed, N. and N. Borenstein, "Multipurpose Internet Mail [7] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part Two: Media Types", RFC 2046, November Extensions (MIME) Part Two: Media Types", RFC 2046, November
1996, <http://www.ietf.org/rfc/rfc2046.txt>. 1996, <http://www.ietf.org/rfc/rfc2046.txt>.
[8] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., [8] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L.,
Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol -- Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol --
HTTP/1.1", RFC 2616, June 1999, <http://www.ietf.org/rfc/ HTTP/1.1", RFC 2616, June 1999,
rfc2616.txt>. <http://www.ietf.org/rfc/rfc2616.txt>.
[9] Moore, K., "On the use of HTTP as a Substrate", RFC 3205, [9] Moore, K., "On the use of HTTP as a Substrate", RFC 3205,
February 2002, <http://www.ietf.org/rfc/rfc3205.txt>. February 2002, <http://www.ietf.org/rfc/rfc3205.txt>.
[10] Franks, J., Hallam-Baker, P., Hostetler, J., Leach, P., [10] Franks, J., Hallam-Baker, P., Hostetler, J., Leach, P.,
Luotonen, A., Sink, E. and L. Stewart, "An Extension to HTTP: Luotonen, A., Sink, E. and L. Stewart, "An Extension to HTTP:
Digest Access Authentication", RFC 2069, January 1997, <http:// Digest Access Authentication", RFC 2069, January 1997,
www.ietf.org/rfc/rfc2069.txt>. <http://www.ietf.org/rfc/rfc2069.txt>.
[11] Bradner, S., "Key words for use in RFCs to Indicate Requirement [11] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", RFC 2119, March 1997, <http://www.ietf.org/rfc/ Levels", RFC 2119, March 1997,
rfc2119.txt>. <http://www.ietf.org/rfc/rfc2119.txt>.
[12] Dierks, T., Allen, C., Treese, W., Karlton, P., Freier, A. and [12] Dierks, T., Allen, C., Treese, W., Karlton, P., Freier, A. and
P. Kocher, "The TLS Protocol Version 1.0", RFC 2246, January P. Kocher, "The TLS Protocol Version 1.0", RFC 2246, January
1999, <http://www.ietf.org/rfc/rfc2246.txt>. 1999, <http://www.ietf.org/rfc/rfc2246.txt>.
[13] Rigney, C., Willens, S., Rubens, A. and W. Simpson, "Remote [13] Rigney, C., Willens, S., Rubens, A. and W. Simpson, "Remote
Authentication Dial In User Service (RADIUS)", RFC 2865, June Authentication Dial In User Service (RADIUS)", RFC 2865, June
2000, <http://www.ietf.org/rfc/rfc2865.txt>. 2000, <http://www.ietf.org/rfc/rfc2865.txt>.
[14] Rose, M. and D. New, "Reliable Delivery for syslog", RFC 3195, [14] Rose, M. and D. New, "Reliable Delivery for syslog", RFC 3195,
November 2001, <http://www.ietf.org/rfc/rfc3195.txt>. November 2001, <http://www.ietf.org/rfc/rfc3195.txt>.
Informative References [15] Rose, M., "The Blocks Extensible Exchange Protocol Core", RFC
[15] Barton, J., Nielsen, H. and S. Thatte, "SOAP Messages with
Attachments", W3C Note NOTE-SOAP-attachments-20001211, Dec
2000, <http://www.w3.org/TR/2000/
NOTE-SOAP-attachments-20001211>.
[16] Brown, A., Fox, B., Hada, S., LaMacchia, B. and H. Maruyama,
"SOAP Security Extensions: Digital Signature", W3C Note
NOTE-SOAP-dsig-20010206, Feb 2001, <http://www.w3.org/TR/2001/
NOTE-SOAP-dsig-20010206/>.
[17] Rose, M., "The Blocks Extensible Exchange Protocol Core", RFC
3080, March 2001, <http://www.ietf.org/rfc/rfc3080.txt>. 3080, March 2001, <http://www.ietf.org/rfc/rfc3080.txt>.
[18] O'Tuathail, E. and M. Rose, "Using the Simple Object Access [16] O'Tuathail, E. and M. Rose, "Using the Simple Object Access
Protocol (SOAP) in Blocks Extensible Exchange Protocol (BEEP)", Protocol (SOAP) in Blocks Extensible Exchange Protocol (BEEP)",
RFC 3288, June 2002, <http://www.ietf.org/rfc/rfc3288.txt>. RFC 3288, June 2002, <http://www.ietf.org/rfc/rfc3288.txt>.
5.2 Informative References
[17] Barton, J., Nielsen, H. and S. Thatte, "SOAP Messages with
Attachments", W3C Note NOTE-SOAP-attachments-20001211, Dec
2000,
<http://www.w3.org/TR/2000/NOTE-SOAP-attachments-20001211>.
[18] Brown, A., Fox, B., Hada, S., LaMacchia, B. and H. Maruyama,
"SOAP Security Extensions: Digital Signature", W3C Note
NOTE-SOAP-dsig-20010206, Feb 2001,
<http://www.w3.org/TR/2001/NOTE-SOAP-dsig-20010206/>.
Author's Address Author's Address
Ted Goddard Ted Goddard
ICEsoft Technologies Inc. ICEsoft Technologies Inc.
Suite 300, 1717 10th St. NW Suite 300, 1717 10th St. NW
Calgary, AB T2M 4S2 Calgary, AB T2M 4S2
Canada Canada
Phone: (403) 663-3322 Phone: (403) 663-3322
EMail: ted.goddard@icesoft.com EMail: ted.goddard@icesoft.com
skipping to change at page 18, line 9 skipping to change at page 18, line 9
<SOAP:body use="literal" <SOAP:body use="literal"
namespace="urn:ietf:params:xml:ns:netconf:base:1.0"/> namespace="urn:ietf:params:xml:ns:netconf:base:1.0"/>
</output> </output>
</operation> </operation>
</binding> </binding>
</definitions> </definitions>
A.2 Sample Service Definition A.2 Sample Service Definition
The following WSDL document assumes a hypothetical location for the The following WSDL document assumes a hypothetical location for the
NETCONF/SOAP WSDL definitions. A typical deployment of a device NETCONF over SOAP WSDL definitions. A typical deployment of a device
manageable via NETCONF/SOAP would provide a service definition manageable via NETCONF over SOAP would provide a service definition
similar to the following to identify the address of the device. similar to the following to identify the address of the device.
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<definitions <definitions
xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:SOAP="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:SOAP="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:xs="urn:ietf:params:xml:ns:netconf:soap:1.0" xmlns:xs="urn:ietf:params:xml:ns:netconf:soap:1.0"
targetNamespace="urn:myNetconfService" targetNamespace="urn:myNetconfService"
name="myNetconfService.wsdl"> name="myNetconfService.wsdl">
skipping to change at page 19, line 8 skipping to change at page 19, line 8
<port name="rpcPort" binding="xs:rpcBinding"> <port name="rpcPort" binding="xs:rpcBinding">
<SOAP:address location="http://localhost:8080/netconf"/> <SOAP:address location="http://localhost:8080/netconf"/>
</port> </port>
</service> </service>
</definitions> </definitions>
Intellectual Property Statement Intellectual Property Statement
The IETF takes no position regarding the validity or scope of any The IETF takes no position regarding the validity or scope of any
intellectual property or other rights that might be claimed to Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights this document or the extent to which any license under such rights
might or might not be available; neither does it represent that it might or might not be available; nor does it represent that it has
has made any effort to identify any such rights. Information on the made any independent effort to identify any such rights. Information
IETF's procedures with respect to rights in standards-track and on the procedures with respect to rights in RFC documents can be
standards-related documentation can be found in BCP-11. Copies of found in BCP 78 and BCP 79.
claims of rights made available for publication and any assurances of
licenses to be made available, or the result of an attempt made to Copies of IPR disclosures made to the IETF Secretariat and any
obtain a general license or permission for the use of such assurances of licenses to be made available, or the result of an
proprietary rights by implementors or users of this specification can attempt made to obtain a general license or permission for the use of
be obtained from the IETF Secretariat. such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary copyrights, patents or patent applications, or other proprietary
rights which may cover technology that may be required to practice rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF Executive this standard. Please address the information to the IETF at
Director. ietf-ipr@ietf.org.
Full Copyright Statement
Copyright (C) The Internet Society (2004). All Rights Reserved. Disclaimer of Validity
This document and translations of it may be copied and furnished to This document and the information contained herein are provided on an
others, and derivative works that comment on or otherwise explain it "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
or assist in its implementation may be prepared, copied, published OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
and distributed, in whole or in part, without restriction of any ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
kind, provided that the above copyright notice and this paragraph are INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
included on all such copies and derivative works. However, this INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
document itself may not be modified in any way, such as by removing WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be Copyright Statement
revoked by the Internet Society or its successors or assignees.
This document and the information contained herein is provided on an Copyright (C) The Internet Society (2004). This document is subject
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING to the rights, licenses and restrictions contained in BCP 78, and
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING except as set forth therein, the authors retain all their rights.
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Acknowledgment Acknowledgment
Funding for the RFC Editor function is currently provided by the Funding for the RFC Editor function is currently provided by the
Internet Society. Internet Society.
 End of changes. 

This html diff was produced by rfcdiff 1.23, available from http://www.levkowetz.com/ietf/tools/rfcdiff/