draft-ietf-netconf-soap-00.txt   draft-ietf-netconf-soap-01.txt 
netconf T. Goddard Network Working Group T. Goddard
Internet-Draft Wind River Systems Internet-Draft ICEsoft Technologies Inc.
Expires: April 15, 2004 October 16, 2003 Expires: August 13, 2004 February 13, 2004
NETCONF Over SOAP NETCONF Over SOAP
draft-ietf-netconf-soap-00 draft-ietf-netconf-soap-01
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 in full conformance with
all provisions of Section 10 of RFC2026. all provisions of Section 10 of RFC2026.
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 other
groups may also distribute working documents as Internet-Drafts. groups may also distribute working documents as Internet-Drafts.
skipping to change at page 1, line 30 skipping to change at page 1, line 30
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 http://
www.ietf.org/ietf/1id-abstracts.txt. 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 April 15, 2004. This Internet-Draft will expire on August 13, 2004.
Copyright Notice Copyright Notice
Copyright (C) The Internet Society (2003). All Rights Reserved. Copyright (C) The Internet Society (2004). All Rights Reserved.
Abstract Abstract
The configuration protocol NETCONF is applicable to a wide range of The device management protocol NETCONF is applicable to a wide range
devices in a variety of environments. The emergence of Web Services of devices in a variety of environments. The emergence of Web
gives one such environment, and is presently characterized by the use Services gives one such environment, and is presently characterized
of SOAP over HTTP. NETCONF finds many benefits in this environment: by the use of SOAP over HTTP. NETCONF finds many benefits in this
from the use of existing standards, to ease of software development, environment: from the re-use of existing standards, to ease of
to integration with deployed systems. Herein, we describe a SOAP software development, to integration with deployed systems. Herein,
over HTTP binding that, when used with multiple persistent HTTP we describe a SOAP over HTTP binding that, when used with persistent
connections, yields an application protocol sufficient for NETCONF. HTTP connections, yields an application protocol sufficient for
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 Important HTTP 1.1 Features . . . . . . . . . . . . . . . . 6 2.4 BCP56: On the Use of HTTP as a Substrate . . . . . . . . . . 6
3. A SOAP Web Service for NETCONF . . . . . . . . . . . . . . . 7 2.5 Important HTTP 1.1 Features . . . . . . . . . . . . . . . . 6
3.1 Fundamental Use Case . . . . . . . . . . . . . . . . . . . . 7 2.6 SOAP Implementation Considerations . . . . . . . . . . . . . 7
3.2 Mapping NETCONF Channels to HTTP Connections . . . . . . . . 7 2.6.1 SOAP Feature Exploitation . . . . . . . . . . . . . . . . . 7
3.2.1 Asynchronous Functionality . . . . . . . . . . . . . . . . . 7 2.6.2 SOAP Headers . . . . . . . . . . . . . . . . . . . . . . . . 7
3.3 NETCONF Sessions . . . . . . . . . . . . . . . . . . . . . . 8 3. A SOAP Web Service for NETCONF . . . . . . . . . . . . . . . 8
3.4 Capabilities Exchange . . . . . . . . . . . . . . . . . . . 9 3.1 Fundamental Use Case . . . . . . . . . . . . . . . . . . . . 8
3.5 A NETCONF/SOAP example . . . . . . . . . . . . . . . . . . . 9 3.2 NETCONF Sessions . . . . . . . . . . . . . . . . . . . . . . 8
3.6 Managing Multiple Devices . . . . . . . . . . . . . . . . . 10 3.3 Capabilities Exchange . . . . . . . . . . . . . . . . . . . 8
3.4 A NETCONF/SOAP example . . . . . . . . . . . . . . . . . . . 9
4. Security Considerations . . . . . . . . . . . . . . . . . . 11 4. Security Considerations . . . . . . . . . . . . . . . . . . 11
4.1 Integrity, Privacy, and Authentication . . . . . . . . . . . 11 4.1 Integrity, Privacy, and Authentication . . . . . . . . . . . 11
4.2 Vulnerabilities . . . . . . . . . . . . . . . . . . . . . . 11 4.2 Vulnerabilities . . . . . . . . . . . . . . . . . . . . . . 11
4.3 Environmental Specifics . . . . . . . . . . . . . . . . . . 12 4.3 Environmental Specifics . . . . . . . . . . . . . . . . . . 12
Normative References . . . . . . . . . . . . . . . . . . . . 13 Normative References . . . . . . . . . . . . . . . . . . . . 13
Informative References . . . . . . . . . . . . . . . . . . . 15 Informative References . . . . . . . . . . . . . . . . . . . 15
Author's Address . . . . . . . . . . . . . . . . . . . . . . 15 Author's Address . . . . . . . . . . . . . . . . . . . . . . 15
A. WSDL Definitions . . . . . . . . . . . . . . . . . . . . . . 16 A. WSDL Definitions . . . . . . . . . . . . . . . . . . . . . . 16
A.1 NETCONF SOAP Binding . . . . . . . . . . . . . . . . . . . . 16 A.1 NETCONF SOAP Binding . . . . . . . . . . . . . . . . . . . . 16
A.2 Sample Service Definition . . . . . . . . . . . . . . . . . 17 A.2 Sample Service Definition . . . . . . . . . . . . . . . . . 17
Intellectual Property and Copyright Statements . . . . . . . 18 Intellectual Property and Copyright Statements . . . . . . . 18
1. Introduction 1. Introduction
Given the use of XML [1] 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
[13] operations to a SOAP [2] 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.
Note that a SOAP binding for NETCONF is not necessarily intended only
for managing individual devices. For instance, a server providing a
SOAP interface can act as a proxy for multiple devices, possibly
connecting to those devices over BEEP [16] or serial lines. In this
case it is important to define a data model that appropriately
aggregates the devices.
In general, SOAP over HTTP is a natural application protocol for In general, SOAP over HTTP is a natural application protocol for
NETCONF (essentially because both emphasize remote procedure calls) NETCONF, essentially because of the remote procedure call character
but there are three areas that require care: the <rpc-progress> of both, but care must be taken in some cases as HTTP is inherently
operation, the mechanism for aborting operations, and the synchronous and client-driven.
notification channel. The reason for this is that all of these
functions are asynchronous (from the point of view of the manager)
and HTTP is inherently synchronous and client-driven.
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.
2. SOAP Background for NETCONF 2. SOAP Background for NETCONF
Why introduce SOAP as yet another wrapper around what is already a Why introduce SOAP as yet another wrapper around what is already a
remote procedure call message? There are, in fact, both technical remote procedure call message? There are, in fact, both technical
and practical reasons. The technical reasons are perhaps less and practical reasons. The technical reasons are perhaps less
compelling, but let's examine them first. compelling, but let's examine them first.
SOAP is fundamentally an XML messaging scheme (which is capable of The use of SOAP does offer a few technical advantages. SOAP is
supporting remote procedure call) and it defines a simple message fundamentally an XML messaging scheme (which is capable of supporting
format composed of a "header" and a "body" contained within an remote procedure call) and it defines a simple message format
"envelope". The "header" contains meta-information relating to the composed of a "header" and a "body" contained within an "envelope".
message, and can be used to indicate such things as store-and-forward The "header" contains meta-information relating to the message, and
behaviour or transactional characteristics. In addition, SOAP can be used to indicate such things as store-and-forward behaviour or
specifies an optional encoding for the "body" of the message. transactional characteristics. In addition, SOAP specifies an
However, this encoding is not applicable to NETCONF as one of the optional encoding for the "body" of the message. However, this
goals is to have highly readable XML, and SOAP-encoding is optimized encoding is not applicable to NETCONF as one of the goals is to have
instead for ease of automated deserialization. These benefits of the highly readable XML, and SOAP-encoding is optimized instead for ease
SOAP message structure are basic, but worthwhile due to the fact that of automated deserialization. These benefits of the SOAP message
they are already standardized. structure are simple, but worthwhile due to the fact that they are
already standardized.
It is the practical reasons that make SOAP over HTTP an interesting It is the practical reasons that truly make SOAP over HTTP an
choice for device management. It is not difficult to invent a interesting choice for device management. It is not difficult to
mechanism for exchanging XML messages over TCP, but what is difficult invent a mechanism for exchanging XML messages over TCP, but what is
is getting that mechanism supported in a wide variety of tools and difficult is getting that mechanism supported in a wide variety of
operating systems and having that mechanism understood by a great tools and operating systems and having that mechanism understood by a
many developers. SOAP over HTTP (with WSDL) is seeing good success great many developers. SOAP over HTTP (with WSDL) is seeing good
at this, and this means that a device management protocol making use success at this, and this means that a device management protocol
of these technologies has advantages in being implemented and making use of these technologies has advantages in being implemented
adopted. Admittedly, there are interoperability problems with SOAP and adopted. Admittedly, there are interoperability problems with
and WSDL, but such problems have wide attention and can be expected SOAP and WSDL, but such problems have wide attention and can be
to be resolved. expected 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) [3] and XML Schemas [4] 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
XML-based definition languages is the use of hyperlinks for referring XML-based definition languages is the use of hyperlinks for referring
to documents containing supporting definitions. For instance, in to documents containing supporting definitions. For instance, in
WSDL, the import statement WSDL, the import statement
<import namespace="http://iana.org/netconf/1.0/base" <import namespace="http://iana.org/netconf/1.0/base"
skipping to change at page 5, line 28 skipping to change at page 5, line 28
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. For
this discussion we will assume SOAP over HTTP or HTTP/TLS unless this discussion we will assume SOAP over HTTP or HTTP/TLS unless
otherwise specified. (This also includes applications of IPSec to otherwise specified. (This also includes applications of IPSec to
SOAP over HTTP.) SOAP over HTTP.)
Note that there are a number of advantages to considering SOAP over Note that there are a number of advantages to considering SOAP over
protocols other than HTTP, as HTTP assigns its very distinct client protocols other than HTTP, as HTTP assigns the very distinct client
and server roles by connection initiation. This causes difficulties and server roles by connection initiation. This would cause
in supporting asynchronous notification (possibly relieved by difficulties in supporting asynchronous notification and could be
replacing SOAP/HTTP with SOAP/BEEP). However, it is also the case relieved in many ways by replacing HTTP with BEEP.
that the full potential of HTTP is not currently used by SOAP. For
instance, multiple SOAP replies to a single request could be
contained in a multipart MIME [6] response. This would be a similar
strategy to the use of multipart/related with SOAP attachments [14].
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
skipping to change at page 6, line 4 skipping to change at page 5, line 47
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 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 Important HTTP 1.1 Features 2.4 BCP56: On the Use of HTTP as a Substrate
HTTP 1.1 [7] includes two important features that provide for Best Current Practice 56 [9] presents a number of important
considerations on the use of HTTP in application protocols. In
particular, it raises the following concerns:
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 A substantially new service should not re-use port 80 as assigned
to HTTP
Fundamentally, these concerns lie directly with SOAP over HTTP,
rather than the application of SOAP over HTTP to NETCONF. As BCP 56
indicates, it is debatable whether HTTP is an appropriate protocol
for SOAP at all, and it is likely that BEEP would be a superior
protocol for most SOAP applications. Unfortunately, SOAP over HTTP is
in common use and must be supported if the practical benefits of SOAP
are to be realized.
It is possible, however, 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
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
creating a new TCP connection for each request. Given that a single creating a new TCP connection for each request. Given that a single
stream is used for both requests and responses, it is clear that some stream is used for both requests and responses, it is clear that some
form of framing is necessary. For messages whose length is known in form of framing is necessary. For messages whose length is known in
advance, this is handled by the HTTP header "Content-length". For advance, this is handled by the HTTP header "Content-length". For
skipping to change at page 7, line 5 skipping to change at page 7, line 25
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.
3. A SOAP Web Service for NETCONF 2.6 SOAP Implementation Considerations
3.1 Fundamental Use Case
The fundamental use case for NETCONF over SOAP (NETCONF/SOAP) over It is not the goal of this document to cover the SOAP [3]
HTTP is that of a management console ("manager" role) managing one or specification in detail. Instead, we provide a few comments that may
more devices running NETCONF agents ("agent" role). The manager be of interest to an implementor of NETCONF over SOAP.
initiates one or more HTTP connections to the agent and drives the
NETCONF sessions through repeated SOAP messages over HTTP requests.
When the manager closes all HTTP connections associated with a
session, the NETCONF session is also closed.
3.2 Mapping NETCONF Channels to HTTP Connections 2.6.1 SOAP Feature Exploitation
While the transport of SOAP over BEEP [17] has been specified, the NETCONF over SOAP does not make extensive use of SOAP features. For
purpose of this discussion is to describe how to map the channel instance, NETCONF operations are not broken into SOAP message parts,
semantics and performance characteristics already assumed by NETCONF and the SOAP header is not used to convey <rpc> metadata. This is a
onto (possibly persistent) SOAP over HTTP connections. This deliberate design decision as it allows the implementor to easily
configuration is chosen because it is the one that benefits most from provide NETCONF over multiple substrates while handling the messages
existing SOAP tools and implementations. It is true that BEEP has over those different substrates in a common way.
many advantages over HTTP for the transport of SOAP messages, but the
fact remains that HTTP is currently more widely deployed than BEEP.
At some point in the future, NETCONF/SOAP over BEEP may also be of
interest. At that time it can be easily dealt with as many of the
issues already discussed in this document are pertinent. There would
simply be a few enhancements regarding asynchronous notification.
NETCONF employs potentially three channels per session: the 2.6.2 SOAP Headers
management channel, the operation channel, and the notification
channel. In the SOAP over HTTP binding, each of these channels can
be mapped to an individual HTTP connection (although the notification
channel may be a BEEP channel in a separate TCP connection). Thus,
SOAP messages on one connection (corresponding to the management
channel) must be able to refer to SOAP messages on another connection
(corresponding to the operation channel) as the "session" is
potentially spread across multiple TCP connections. For instance, it
may be necessary to abort a time-extended SOAP request on the
"operation" HTTP connection by sending an "<rpc-abort>" message on
the "management" HTTP connection.
Distinct "operation" and "management" HTTP connections are not Implementors of NETCONF over SOAP should be aware of the following
defined; the agent may limit the number of HTTP connections in the characteristic of SOAP headers: a SOAP header may have the attribute
same session, and each is capable those "management" and "operation" "mustUnderstand" and, if so, the recipient must either process the
procedure calls supported by NETCONF over SOAP. header block or not process the SOAP message at all, and instead
generate a fault. A "mustUnderstand" header must not be silently
discarded.
3.2.1 Asynchronous Functionality 3. A SOAP Web Service for NETCONF
NETCONF uses two types of asynchronous functionality, and the mapping 3.1 Fundamental Use Case
of these onto SOAP over HTTP is somewhat problematic. The two
asynchronous functions are <rpc-progress> and notifications on the
notification channel, and these are not supported in the SOAP over
HTTP application protocol. Instead, the client can periodically poll
the appropriate elements of via <get-state> (on a secondary HTTP
connection) to obtain progress information or notification log
entries.
Additionally, the notification mechanism for NETCONF is specified in The fundamental use case for NETCONF over SOAP (NETCONF/SOAP) over
an existing standard for reliable syslog [12] and it is suggested HTTP is that of a management console ("manager" role) managing one or
that the same mechanism be used with the SOAP binding (it is simply more devices running NETCONF agents ("agent" role). The manager
external). If notifications via SOAP over HTTP are desired, it is initiates an HTTP connection to an agent and drives the NETCONF
probably most effective if an HTTP connection is established from the session via a sequence of SOAP messages over HTTP requests. When the
agent to the management console. Such a connection could be manager closes the HTTP connection, the NETCONF session is also
established in response to the manager connecting to the device. closed.
More sophisticated functionality, such as multiple SOAP replies to a
single request, would require enhancements to the SOAP over HTTP
specification.
3.3 NETCONF Sessions 3.2 NETCONF Sessions
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
skipping to change at page 8, line 47 skipping to change at page 8, line 41
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.
Since it is generally not possible to support a full NETCONF session In the case of SOAP over HTTP, a NETCONF "session" is supported by an
with a single HTTP connection, it is necessary to identify the HTTP connection with an authenticated user. To support automated
NETCONF session in a way that can span multiple HTTP connections. cleanup, a NETCONF over SOAP session is closed when the HTTP
This can be performed with the HTTP request URI, as in the following connection is closed.
POST request with the target session "sid-123":
POST /netconf/sid-123 HTTP/1.0
Content-Type: text/xml; charset=utf-8
Content-Length: 470
Note that the session identifier must either be known by the manager
(in order to attach to an existing session) or be communicated from
the agent to the manager prior to the exchange of any significant
NETCONF messages. For this, it is recommended that the session
identifier be determined via <get-state>. An empty session identifier
may be used in the case where only an operations channel is required
(in this case the agent assigns a new session to that HTTP
connection).
Thus, in the case of SOAP over HTTP, a NETCONF "session" is a
collection of HTTP connections with common authenticated users and a
common session identifier as indicated in the HTTP reqest URI header.
To support automated cleanup, a NETCONF over SOAP session is closed
when all connections associated with that session are closed.
3.4 Capabilities Exchange 3.3 Capabilities Exchange
Capabilities exchange, if defined through a NETCONF RPC operation, Capabilities exchange, if defined through a NETCONF RPC operation,
can easily be accommodated in the SOAP binding. can easily be accommodated in the SOAP binding.
3.5 A NETCONF/SOAP example 3.4 A NETCONF/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.
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
skipping to change at page 10, line 42 skipping to change at page 11, line 5
<user> <user>
<name>barney</name> <name>barney</name>
<type>admin</type> <type>admin</type>
</user> </user>
</users> </users>
</config> </config>
</rpc-reply> </rpc-reply>
</soapenv:Body> </soapenv:Body>
</soapenv:Envelope> </soapenv:Envelope>
3.6 Managing Multiple Devices
When a server is acting as a proxy for multiple devices, the URL for
the HTTP POST can be used to indicate which device is the target. It
may also be desirable to use the HTTP POST URL as a means for
selecting from multiple virtual devices on a single device.
4. Security Considerations 4. Security Considerations
NETCONF is used to access and modify configuration information, so NETCONF is used to access and modify configuration information, so
the ability to access this protocol should be limited to users and the ability to access this protocol should be limited to users and
systems that are authorized to view or modify the agent's systems that are authorized to view or modify the agent's
configuration data. configuration data.
Because configuration information is sent in both directions, it is Because configuration information is sent in both directions, it is
not sufficient for just the client or user to be authenticated with not sufficient for just the client or user to be authenticated with
the server. The identity of the server should also be authenticated the server. The identity of the server should also be authenticated
skipping to change at page 11, line 31 skipping to change at page 11, line 31
If the NETCONF server provides remote access through insecure If the NETCONF server provides remote access through insecure
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
[10] 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 [8]) o within HTTP (such as Digest Access Authentication [10])
o within SOAP (such as a digital signature in the header [15]) o within SOAP (such as a digital signature in the header [16])
HTTP and SOAP level authentication can be integrated with RADIUS [11] HTTP and SOAP level authentication can be integrated with RADIUS [13]
to support remote authentication databases. 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/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/SOAP, this constancy must be given particular case of NETCONF, it is important to consider that device management
attention as a session may span multiple HTTP connections. may be taking place over multiple substrates (in addition to SOAP)
and it is important that the different substrates have a common
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/SOAP may choose to use HTTP without
encryption. This presents vulnerabilities but may be selected for encryption. This presents vulnerabilities but may be selected for
deployments involving closed networks or debugging scenarios. 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 Normative References
[1] Bray, T., Paoli, J., Sperberg-McQueen, C. and E. Maler, [1] Enns, R., "XMLCONF Configuration Protocol",
draft-enns-xmlconf-spec-00 (work in progress), Feb 2003,
<http://www.ietf.org/internet-drafts/
draft-enns-xmlconf-spec-00.txt>.
[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, <http://www.w3.org/TR/2000/
REC-xml-20001006>. REC-xml-20001006>.
[2] 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>.
[3] 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, <http://www.w3.org/TR/2001/
NOTE-wsdl-20010315>. NOTE-wsdl-20010315>.
[4] 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, <http://www.w3.org/TR/2001/
REC-xmlschema-1-20010502/>. REC-xmlschema-1-20010502/>.
[5] 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>.
[6] 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>.
[7] 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, <http://www.ietf.org/rfc/
rfc2616.txt>. rfc2616.txt>.
[8] Franks, J., Hallam-Baker, P., Hostetler, J., Leach, P., [9] Moore, K., "On the use of HTTP as a Substrate", RFC 3205,
February 2002, <http://www.ietf.org/rfc/rfc3205.txt>.
[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, <http://
www.ietf.org/rfc/rfc2069.txt>. www.ietf.org/rfc/rfc2069.txt>.
[9] 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, <http://www.ietf.org/rfc/
rfc2119.txt>. rfc2119.txt>.
[10] 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>.
[11] 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>.
[12] 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 Informative References
[13] Enns, R., "NETCONF Configuration Protocol", [15] Barton, J., Nielsen, H. and S. Thatte, "SOAP Messages with
draft-ietf-netconf-prot-00 (work in progress), Aug 2003,
<http://www.ietf.org/internet-drafts/
draft-ietf-netconf-prot-00.txt>.
[14] Barton, J., Nielsen, H. and S. Thatte, "SOAP Messages with
Attachments", W3C Note NOTE-SOAP-attachments-20001211, Dec Attachments", W3C Note NOTE-SOAP-attachments-20001211, Dec
2000, <http://www.w3.org/TR/2000/ 2000, <http://www.w3.org/TR/2000/
NOTE-SOAP-attachments-20001211>. NOTE-SOAP-attachments-20001211>.
[15] Brown, A., Fox, B., Hada, S., LaMacchia, B. and H. Maruyama, [16] Brown, A., Fox, B., Hada, S., LaMacchia, B. and H. Maruyama,
"SOAP Security Extensions: Digital Signature", W3C Note "SOAP Security Extensions: Digital Signature", W3C Note
NOTE-SOAP-dsig-20010206, Feb 2001, <http://www.w3.org/TR/2001/ NOTE-SOAP-dsig-20010206, Feb 2001, <http://www.w3.org/TR/2001/
NOTE-SOAP-dsig-20010206/>. NOTE-SOAP-dsig-20010206/>.
[16] Rose, M., "The Blocks Extensible Exchange Protocol Core", RFC [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>.
[17] O'Tuathail, E. and M. Rose, "Using the Simple Object Access [18] 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>.
Author's Address Author's Address
Ted Goddard Ted Goddard
Wind River Systems ICEsoft Technologies Inc.
#180, 6815-8th Street NE Suite 300, 1717 10th St. NW
Calgary, AB T2E 7H7 Calgary, AB T2M 4S2
Canada Canada
Phone: (403) 730-7590 Phone: (403) 663-3322
EMail: ted.goddard@windriver.com EMail: ted.goddard@icesoft.com
URI: http://www.windriver.com URI: http://www.icesoft.com
Appendix A. WSDL Definitions Appendix A. WSDL Definitions
A.1 NETCONF SOAP Binding A.1 NETCONF SOAP Binding
The following WSDL document assumes a hypothetical location for the The following WSDL document assumes a hypothetical location for the
NETCONF schema. NETCONF schema.
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<definitions <definitions
skipping to change at page 18, line 29 skipping to change at page 18, line 29
be obtained from the IETF Secretariat. be obtained from the IETF Secretariat.
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 which may cover technology that may be required to practice
this standard. Please address the information to the IETF Executive this standard. Please address the information to the IETF Executive
Director. Director.
Full Copyright Statement Full Copyright Statement
Copyright (C) The Internet Society (2003). All Rights Reserved. Copyright (C) The Internet Society (2004). All Rights Reserved.
This document and translations of it may be copied and furnished to This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of Internet organizations, except as needed for the purpose of
 End of changes. 

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