idnits 2.17.1 draft-ietf-netconf-soap-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 15. -- Found old boilerplate from RFC 3978, Section 5.5 on line 893. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 870. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 877. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 883. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 2 instances of too long lines in the document, the longest one being 20 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (March 2, 2006) is 6592 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-12) exists of draft-ietf-netconf-prot-07 -- Possible downref: Non-RFC (?) normative reference: ref. '2' -- Possible downref: Non-RFC (?) normative reference: ref. '3' -- Possible downref: Non-RFC (?) normative reference: ref. '4' ** Obsolete normative reference: RFC 2616 (ref. '5') (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 3205 (ref. '6') (Obsoleted by RFC 9205) ** Obsolete normative reference: RFC 2617 (ref. '7') (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** Obsolete normative reference: RFC 2246 (ref. '9') (Obsoleted by RFC 4346) == Outdated reference: A later version (-02) exists of draft-mrose-rfc3288bis-00 ** Obsolete normative reference: RFC 2434 (ref. '14') (Obsoleted by RFC 5226) Summary: 9 errors (**), 0 flaws (~~), 5 warnings (==), 11 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group T. Goddard 3 Internet-Draft ICEsoft Technologies Inc. 4 Expires: September 3, 2006 March 2, 2006 6 Using the Network Configuration Protocol (NETCONF) Over the Simple 7 Object Access Protocol (SOAP) 8 draft-ietf-netconf-soap-08 10 Status of this Memo 12 By submitting this Internet-Draft, each author represents that any 13 applicable patent or other IPR claims of which he or she is aware 14 have been or will be disclosed, and any of which he or she becomes 15 aware will be disclosed, in accordance with Section 6 of BCP 79. 17 Internet-Drafts are working documents of the Internet Engineering 18 Task Force (IETF), its areas, and its working groups. Note that 19 other groups may also distribute working documents as Internet- 20 Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at any 24 time. It is inappropriate to use Internet-Drafts as reference 25 material or to cite them other than as "work in progress." 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt. 30 The list of Internet-Draft Shadow Directories can be accessed at 31 http://www.ietf.org/shadow.html. 33 This Internet-Draft will expire on September 3, 2006. 35 Copyright Notice 37 Copyright (C) The Internet Society (2006). 39 Abstract 41 The Network Configuration Protocol (NETCONF) is applicable to a wide 42 range of devices in a variety of environments. The emergence of Web 43 Services gives one such environment, and is presently characterized 44 by the use of the Simple Object Access Protocol (SOAP). NETCONF 45 finds many benefits in this environment: from the re-use of existing 46 standards, to ease of software development, to integration with 47 deployed systems. Herein, we describe SOAP over HTTP (Hypertext 48 Transport Protocol) and SOAP over BEEP (Blocks Exchange Extensible 49 Protocol) bindings for NETCONF. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 2. SOAP Background for NETCONF . . . . . . . . . . . . . . . . . 4 55 2.1 Use and Storage of WSDL and XSD . . . . . . . . . . . . . 4 56 2.2 SOAP over HTTP . . . . . . . . . . . . . . . . . . . . . . 5 57 2.3 HTTP Drawbacks . . . . . . . . . . . . . . . . . . . . . . 5 58 2.4 BCP56: On the Use of HTTP as a Substrate . . . . . . . . . 6 59 2.5 Important HTTP 1.1 Features . . . . . . . . . . . . . . . 7 60 2.6 SOAP Over BEEP . . . . . . . . . . . . . . . . . . . . . . 7 61 2.7 SOAP Implementation Considerations . . . . . . . . . . . . 8 62 2.7.1 SOAP Feature Exploitation . . . . . . . . . . . . . . 8 63 2.7.2 SOAP Headers . . . . . . . . . . . . . . . . . . . . . 8 64 2.7.3 SOAP Faults . . . . . . . . . . . . . . . . . . . . . 8 65 3. A SOAP Service for NETCONF . . . . . . . . . . . . . . . . . . 10 66 3.1 Fundamental Use Case . . . . . . . . . . . . . . . . . . . 10 67 3.2 NETCONF Session Establishment . . . . . . . . . . . . . . 10 68 3.3 NETCONF Capabilities Exchange . . . . . . . . . . . . . . 10 69 3.4 NETCONF Session Usage . . . . . . . . . . . . . . . . . . 12 70 3.5 NETCONF Session Teardown . . . . . . . . . . . . . . . . . 12 71 3.6 A NETCONF Over SOAP example . . . . . . . . . . . . . . . 12 72 3.7 NETCONF SOAP WSDL . . . . . . . . . . . . . . . . . . . . 14 73 3.8 Sample Service Definition WSDL . . . . . . . . . . . . . . 16 74 4. Security Considerations . . . . . . . . . . . . . . . . . . . 17 75 4.1 Integrity, Privacy, and Authentication . . . . . . . . . . 17 76 4.2 Vulnerabilities . . . . . . . . . . . . . . . . . . . . . 18 77 4.3 Environmental Specifics . . . . . . . . . . . . . . . . . 18 78 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 79 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 20 80 6.1 Normative References . . . . . . . . . . . . . . . . . . . 20 81 6.2 Informative References . . . . . . . . . . . . . . . . . . 21 82 Author's Address . . . . . . . . . . . . . . . . . . . . . . . 21 83 Intellectual Property and Copyright Statements . . . . . . . . 22 85 1. Introduction 87 Given the use of XML [2] (Extensible Markup Language) and the remote 88 procedure call characteristics, it is natural to consider a binding 89 of the NETCONF [1] operations to a SOAP [3] application protocol. 90 This document proposes a binding of this form. 92 In general, SOAP is a natural messaging scheme for NETCONF, 93 essentially because of the remote procedure call character of both. 94 However, care must be taken with SOAP over HTTP as it is inherently 95 synchronous and client-driven. SOAP over BEEP [11] is technically 96 superior, but is not as widely adopted. 98 Four basic topics are presented: SOAP specifics of interest to 99 NETCONF, specifics on implementing NETCONF as a SOAP-based web 100 service, security considerations, and functional Web Services 101 Description Language (WSDL) definitions. In some sense, the most 102 important part of the document is the brief WSDL document presented 103 in Section 3.7. With the right tools, the WSDL combined with the 104 base NETCONF XML Schemas provide machine readable descriptions 105 sufficient for the development of software applications using 106 NETCONF. 108 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 109 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 110 document are to be interpreted as described in RFC 2119 [8] 112 2. SOAP Background for NETCONF 114 Why introduce SOAP as yet another wrapper around what is already a 115 remote procedure call message? There are, in fact, both technical 116 and practical reasons. The technical reasons are perhaps less 117 compelling, but let's examine them first. 119 The use of SOAP does offer a few technical advantages. SOAP is 120 fundamentally an XML messaging scheme (which is capable of supporting 121 remote procedure call) and it defines a simple message format 122 composed of a "header" and a "body" contained within an "envelope". 123 The "header" contains meta-information relating to the message, and 124 can be used to indicate such things as store-and-forward behaviour or 125 transactional characteristics. In addition, SOAP specifies an 126 optional encoding for the "body" of the message. However, this 127 encoding is not applicable to NETCONF as one of the goals is to have 128 highly readable XML, and SOAP-encoding is optimized instead for ease 129 of automated deserialization. These benefits of the SOAP message 130 structure are simple, but worthwhile due to the fact that they are 131 already standardized. 133 It is the practical reasons that truly make SOAP an interesting 134 choice for device management. It is not difficult to invent a 135 mechanism for exchanging XML messages over TCP, but what is difficult 136 is getting that mechanism supported in a wide variety of tools and 137 operating systems and having that mechanism understood by a great 138 many developers. SOAP over HTTP (with WSDL) is seeing good success 139 at this, and this means that a device management protocol making use 140 of these technologies has advantages in being implemented and 141 adopted. Admittedly, there are interoperability problems with SOAP 142 and WSDL, but such problems have wide attention and can be expected 143 to be resolved. 145 2.1 Use and Storage of WSDL and XSD 147 One of the advantages of using machine readable formats such as Web 148 Services Description Language (WSDL) [16] and XML Schemas [4] is that 149 they can be used automatically in the software development process. 150 With appropriate tools, WSDL and XSD can be used to generate classes 151 that act as remote interfaces or application specific data 152 structures. Other uses, such as document generation and service 153 location, are also common. A great innovation found with many XML- 154 based definition languages is the use of hyperlinks for referring to 155 documents containing supporting definitions. 157 161 For instance, in WSDL, the above import statement imports the 162 definitions of XML types and elements from the base NETCONF schema. 163 Ideally, the file containing that schema is hosted on a web server 164 under the authority of the standards body that defined the schema. 165 In this way, dependent standards can be built up over time and all 166 are accessible to automated software tools that ensure adherence to 167 the standards. The IANA (Internet Assigned Numbers Authority) 168 maintained registry for this purpose is described in The IETF XML 169 Registry [13]. 171 Note that WSDL declarations for SOAP over BEEP bindings are not yet 172 standardized. 174 2.2 SOAP over HTTP 176 While it is true that SOAP focuses on messages and can be bound to 177 different underlying protocols such as HTTP, SMTP, or BEEP, most 178 existing SOAP implementations support only HTTP or HTTP/TLS. 180 There are a number of advantages to considering SOAP over protocols 181 other than HTTP, as HTTP assigns the very distinct client and server 182 roles by connection initiation. This causes difficulties in 183 supporting asynchronous notification and can be relieved in many ways 184 by replacing HTTP with BEEP. 186 2.3 HTTP Drawbacks 188 HTTP is not the ideal transport for messaging, but it is adequate for 189 the most basic interpretation of "remote procedure call". HTTP is 190 based on a communication pattern whereby the client (which initiates 191 the TCP connection) makes a "request" to the server. The server 192 returns a "response" and this process is continued (possibly over a 193 persistent connection, as described below). This matches the basic 194 idea of a remote procedure call where the caller invokes a procedure 195 on a remote server and waits for the return value. 197 Potential criticisms of HTTP could include the following: 199 o server-initiated data flow is awkward to provide 201 o headers are verbose and text-based 203 o idle connections may be closed by intermediate proxies 205 o data encapsulation must adhere to MIME [15] (Multipurpose Internet 206 Mail Extensions) 208 o bulk transfer relies on stream-based ordering 210 In many ways these criticisms are directed at particular compromises 211 in the design of HTTP. As such, they are important to consider, but 212 it is not clear that they result in fatal drawbacks for a device 213 management protocol. 215 2.4 BCP56: On the Use of HTTP as a Substrate 217 Best Current Practice 56 [6] presents a number of important 218 considerations on the use of HTTP in application protocols. In 219 particular, it raises the following concerns: 221 o HTTP may be more complex than is necessary for the application 223 o The use of HTTP may mask the application from some firewalls 225 o A substantially new service should not re-use port 80 as assigned 226 to HTTP 228 o HTTP caching may mask connection state 230 Fundamentally, these concerns lie directly with common usage of SOAP 231 over HTTP, rather than the application of SOAP over HTTP to NETCONF. 232 As BCP 56 indicates, it is debatable whether HTTP is an appropriate 233 protocol for SOAP at all, and it is likely that BEEP would be a 234 superior protocol for most SOAP applications. Unfortunately, SOAP 235 over HTTP is in common use and must be supported if the practical 236 benefits of SOAP are to be realized. Note that the verbose nature of 237 SOAP actually makes it more readily processed by firewalls, albeit 238 firewalls designed to process SOAP messages. 240 HTTP caches SHOULD NOT be inserted between NETCONF managers and 241 agents as NETCONF session state is tied to the state of the 242 underlying transport connection. Three defensive actions can be 243 taken: 245 o Caching MUST be prohibited through the use of HTTP headers Cache- 246 Control and Pragma: no-cache 248 o HTTP proxies SHOULD NOT be deployed within the management network 250 o Use HTTPS 252 It is also possible to respond to the concern on the re-use of port 253 80. Any NETCONF SOAP service MUST always be supported over the new 254 standard port for NETCONF over SOAP and all conforming 255 implementations MUST default to attempting connections over this new 256 standard port for NETCONF. A standard port for NETCONF over SOAP 257 (over HTTP) is requested in the IANA considerations of this document. 259 2.5 Important HTTP 1.1 Features 261 HTTP 1.1 [5] includes two important features that provide for 262 relatively efficient transport of SOAP messages. These features are 263 "persistent connections" and "chunked transfer-coding". 265 Persistent connections allow a single TCP connection to be used 266 across multiple HTTP requests. This permits multiple SOAP request/ 267 response message pairs to be exchanged without the overhead of 268 creating a new TCP connection for each request. Given that a single 269 stream is used for both requests and responses, it is clear that some 270 form of framing is necessary. For messages whose length is known in 271 advance, this is handled by the HTTP header "Content-length". For 272 messages of dynamic length, "Chunking" is required. 274 HTTP "Chunking" or "chunked transfer-coding" allows the sender to 275 send an indefinite amount of binary data. This is accomplished by 276 informing the receiver of the size of each "chunk" (substring of the 277 data) before the chunk is transmitted. The last chunk is indicated 278 by a chunk of zero length. Chunking can be effectively used to 279 transfer a large XML document where the document is generated on-line 280 from a non-XML form in memory. 282 In terms of application to SOAP message exchanges, persistent 283 connections are clearly important for performance reasons, and are 284 particularly important when it is the persistence of authenticated 285 connections that is at stake. When one considers that messages of 286 dynamic length are the rule rather than the exception for SOAP 287 messages, it is also clear that Chunking is very useful. In some 288 cases it is possible to buffer a SOAP response and determine its 289 length before sending, but the storage requirements for this are 290 prohibitive for many devices. Together, these two features provide a 291 good foundation for device management using SOAP over HTTP. HTTP 292 chunking and persistent connections [5] SHOULD be used. 294 2.6 SOAP Over BEEP 296 Although not widely adopted by the Web Services community, BEEP is an 297 excellent substrate for SOAP [12]. In particular, it provides for 298 request/response message exchanges initiated by either BEEP peer and 299 allows the number of response messages to be arbitrary (including 300 zero). The BEEP profile for SOAP simply makes use of a single BEEP 301 channel for exchanging SOAP messages and benefits from BEEP's 302 inherent strengths for message exchange over a single transport 303 connection. 305 2.7 SOAP Implementation Considerations 307 It is not the goal of this document to cover the SOAP [3] 308 specification in detail. Instead, we provide a few comments that may 309 be of interest to an implementor of NETCONF over SOAP. 311 2.7.1 SOAP Feature Exploitation 313 NETCONF over SOAP does not make extensive use of SOAP features. For 314 instance, NETCONF operations are not broken into SOAP message parts, 315 and the SOAP header is not used to convey metadata. This is a 316 deliberate design decision as it allows the implementor to easily 317 provide NETCONF over multiple substrates while handling the messages 318 over those different substrates in a common way. 320 2.7.2 SOAP Headers 322 Implementors of NETCONF over SOAP should be aware of the following 323 characteristic of SOAP headers: a SOAP header may have the attribute 324 "mustUnderstand" and, if so, the recipient must either process the 325 header block or not process the SOAP message at all, and instead 326 generate a fault. A "mustUnderstand" header must not be silently 327 discarded. 329 In general, however, SOAP headers are intended for application- 330 specific uses. The NETCONF SOAP binding does not make use of SOAP 331 headers. 333 2.7.3 SOAP Faults 335 A SOAP Fault is returned in the event of a NETCONF . It 336 is constructed essentially as a wrapper for the , but 337 allow SOAP processors to propagate the to application 338 code using a language-appropriate exception mechanism. 340 A SOAP Fault is constructed from an as follows: the SOAP 341 Fault Code Value is "Receiver" in the SOAP envelope namespace, the 342 SOAP Fault Reason Text is the contents of the NETCONF 343 "error-tag", and the SOAP Fault detail is the original 344 structure. 346 For instance, given the following , 347 348 rpc 349 MISSING_ATTRIBUTE 350 error 351 352 message-id 353 rpc 354 355 357 the associated SOAP Fault message is 359 362 363 364 365 env:Receiver 366 367 368 MISSING_ATTRIBUTE 370 371 372 373 rpc 374 MISSING_ATTRIBUTE 375 error 376 377 message-id 378 rpc 379 380 381 382 383 384 386 3. A SOAP Service for NETCONF 388 3.1 Fundamental Use Case 390 The fundamental use case for NETCONF over SOAP is that of a 391 management console ("manager" role) managing one or more devices 392 running NETCONF agents ("agent" role). The manager initiates an HTTP 393 or BEEP connection to an agent and drives the NETCONF session via a 394 sequence of SOAP messages. When the manager closes the connection, 395 the NETCONF session is also closed. 397 3.2 NETCONF Session Establishment 399 A NETCONF over SOAP session is established by the initial message 400 exchange on the underlying substrate. For HTTP, a NETCONF session is 401 established once a SOAP message is POSTed to the NETCONF web 402 application URI. For BEEP, a NETCONF session is established once the 403 BEEP profile for SOAP handshake establishes the SOAP channel. 405 3.3 NETCONF Capabilities Exchange 407 Capabilities exchange and session ID establishment are performed 408 through the exchange of messages. In the case of SOAP over 409 HTTP, the HTTP client MUST send the first message. The case 410 of SOAP over BEEP imposes no ordering constraints. For instance, the 411 following example shows the exchange of messages and 412 establishes a session ID value of 4. Observe that the management 413 client initiates the exchange and the server agent assigns the 414 session ID. 416 C: POST /netconf HTTP/1.1 417 C: Host: netconfdevice 418 C: Content-Type: text/xml; charset=utf-8 419 C: Accept: application/soap+xml, text/* 420 C: Cache-Control: no-cache 421 C: Pragma: no-cache 422 C: Content-Length: 376 423 C: 424 C: 425 C: 427 C: 428 C: 429 C: 430 C: 431 C: urn:ietf:params:netconf:base:1.0 432 C: 433 C: 434 C: 435 C: 436 C: 437 S: HTTP/1.1 200 OK 438 S: Content-Type: application/soap+xml; charset=utf-8 439 S: Content-Length: 600 440 S: 441 S: 442 S: 444 S: 445 S: 446 S: 447 S: 448 S: urn:ietf:params:netconf:base:1.0 449 S: 450 S: 451 S: urn:ietf:params:netconf:capability:startup:1.0 452 S: 453 S: 454 S: http:/example.net/router/2.3/myfeature 455 S: 456 S: 457 S: 4 458 S: 459 S: 460 S: 462 3.4 NETCONF Session Usage 464 NETCONF sessions are persistent for both performance and semantic 465 reasons. NETCONF session state contains the following: 467 1. Authentication Information 469 2. Capability Information 471 3. Locks 473 4. Pending Operations 475 5. Operation Sequence Numbers 477 Authentication must be maintained throughout a session due to the 478 fact that it is expensive to establish. Capability Information is 479 maintained so that appropriate operations can be applied during a 480 session. Locks are released upon termination of a session as this 481 makes the protocol more robust. Pending operations come and go from 482 existence during the normal course of RPC operations. Operation 483 sequence numbers provide the small but necessary state information to 484 refer to operations during the session. 486 In the case of SOAP over HTTP, a NETCONF session is supported by an 487 HTTP connection with an authenticated user. For SOAP over BEEP, a 488 NETCONF session is supported by a BEEP channel operating according to 489 the BEEP profile for SOAP [12]. 491 3.5 NETCONF Session Teardown 493 To allow automated cleanup, NETCONF over SOAP session teardown takes 494 place when the underlying connection (in the case of HTTP) or channel 495 (in the case of BEEP) is closed. Note that the root cause of such 496 teardown may be the closure of the TCP connection under either HTTP 497 or BEEP as the case may be. NETCONF managers and agents must be 498 capable of programatically closing the transport connections 499 associated with NETCONF sessions, such as in response to a operation; thus, the HTTP or BEEP substrate implementation 501 must expose this appropriately. 503 3.6 A NETCONF Over SOAP example 505 Since the proposed WSDL (in Section 3.7) uses document/literal 506 encoding, the use of a SOAP header and body has little impact on the 507 representation of a NETCONF operation. This example shows HTTP/1.1 508 for simplicity. An example for BEEP would be similar. 510 C: POST /netconf HTTP/1.1 511 C: Host: netconfdevice 512 C: Content-Type: text/xml; charset=utf-8 513 C: Accept: application/soap+xml, text/* 514 C: Cache-Control: no-cache 515 C: Pragma: no-cache 516 C: Content-Length: 465 517 C: 518 C: 519 C: 521 C: 522 C: 524 C: 525 C: 526 C: 527 C: 528 C: 529 C: 530 C: 531 C: 532 C: 533 C: 535 The HTTP/1.1 response is also straightforward: 537 S: HTTP/1.1 200 OK 538 S: Content-Type: application/soap+xml; charset=utf-8 539 S: Content-Length: 917 540 S: 541 S: 542 S: 544 S: 545 S: 547 S: 548 S: 549 S: 550 S: 551 S: root 552 S: superuser 553 S: Charlie Root 554 S: 1 555 S: 1 556 S: 557 S: 558 S: 559 S: fred 560 S: admin 561 S: Fred Flintstone 562 S: 2 563 S: 2 564 S: 565 S: 566 S: 567 S: 568 S: 569 S: 570 S: 571 S: 573 3.7 NETCONF SOAP WSDL 575 The following WSDL document assumes a hypothetical location for the 576 NETCONF schema and a hypothetical identifier for the NETCONF 577 namespace, subject to IANA considerations for the NETCONF [1] 578 protocol. It is valid as verified by the xmlsoft.org tool xmllint 579 against the standard WSDL [16] xmlsoap.org schemas referenced by the 580 "SOAP" and default namespace declarations below. 582 583 591 595 596 597 598 599 600 602 603 604 605 606 607 609 610 611 612 613 614 615 616 617 618 620 621 623 624 625 626 628 629 630 633 634 635 636 637 638 640 641 642 644 645 646 648 650 3.8 Sample Service Definition WSDL 652 The following WSDL document assumes a local location for the NETCONF 653 over SOAP WSDL definitions. A typical deployment of a device 654 manageable via NETCONF over SOAP would provide a service definition 655 similar to the following to identify the address of the device. 657 658 665 669 670 671 672 673 675 677 4. Security Considerations 679 NETCONF is used to access and modify configuration information, so 680 the ability to access this protocol should be limited to users and 681 systems that are authorized to view or modify the agent's 682 configuration data. 684 Because configuration information is sent in both directions, it is 685 not sufficient for just the client or user to be authenticated with 686 the server. The identity of the server should also be authenticated 687 with the client. 689 Configuration data may include sensitive information, such as user 690 names or security keys. So, NETCONF should only be used over 691 communications channels that provide strong encryption for data 692 privacy. 694 If the NETCONF server provides remote access through insecure 695 protocols, such as HTTP, care should be taken to prevent execution of 696 the NETCONF program when strong user authentication or data privacy 697 is not available. 699 The IANA requested port SHOULD be used, as this provides a means for 700 efficient firewall filtering during possible denial-of-service 701 attacks. 703 4.1 Integrity, Privacy, and Authentication 705 The NETCONF SOAP binding relies on an underlying secure transport for 706 integrity and privacy. Such transports are expected to include TLS 707 [9] (which, when combined with HTTP, is referred to as HTTPS) and 708 IPsec. There are a number of options for authentication (some of 709 which are deployment-specific): 711 o within the transport (such as with TLS client certificates) 713 o within HTTP (such as Digest Access Authentication [7]) 715 o within SOAP (such as a digital signature in the header [17]) 717 HTTP, BEEP, and SOAP level authentication can be integrated with 718 RADIUS [10] (Remote Authentication Dial In User Service) to support 719 remote authentication databases. 721 At a miniumum, all conforming NETCONF over SOAP implementations MUST 722 support TLS. Specifically, NETCONF over SOAP over HTTP MUST support 723 NETCONF over SOAP over HTTPS, and NETCONF over SOAP over BEEP MUST 724 support NETCONF over SOAP over BEEP over TLS. 726 4.2 Vulnerabilities 728 The above protocols may have various vulnerabilities, and these may 729 be inherited by NETCONF over SOAP. 731 NETCONF itself may have vulnerabilities due to the fact that an 732 authorization model is not currently specified. 734 It is important that device capabilities and authorization remain 735 constant for the duration of any outstanding NETCONF session. In the 736 case of NETCONF, it is important to consider that device management 737 may be taking place over multiple substrates (in addition to SOAP) 738 and it is important that the different substrates have a common 739 authentication model. 741 4.3 Environmental Specifics 743 Some deployments of NETCONF over SOAP may choose to use transports 744 without encryption. This presents vulnerabilities but may be 745 selected for deployments involving closed networks or debugging 746 scenarios. 748 A device managed by NETCONF may interact (over protocols other than 749 NETCONF) with devices managed by other protocols, all of differing 750 security. Each point of entry brings with it a potential 751 vulnerability. 753 5. IANA Considerations 755 The IANA is requested to assign TCP ports for NETCONF for SOAP over 756 HTTP and SOAP over BEEP. 758 The IANA is requested to allow the assignment of an XML namespace 759 within the NETCONF namespace "urn:ietf:params:xml:ns:netconf" for the 760 NETCONF over SOAP WSDL definitions. Following the policies outlined 761 in RFC 2434 [14], assigned values in this subordinate namespace are 762 requested to be allocated according to the "Specification Required" 763 policy. 765 URI: Please allow the URI assignment 766 "urn:ietf:params:xml:ns:netconf:soap" within the NETCONF namespace 767 for use by NETCONF over SOAP. 769 6. References 771 6.1 Normative References 773 [1] Enns, R., "NETCONF Configuration Protocol", 774 draft-ietf-netconf-prot-07 (work in progress), Feb 2005, 775 . 778 [2] Bray, T., Paoli, J., Sperberg-McQueen, C., and E. Maler, 779 "Extensible Markup Language (XML) 1.0 (Second Edition)", W3C 780 REC REC-xml-20001006, October 2000, 781 . 783 [3] Gudgin, M., Hadley, M., Moreau, JJ., and H. Nielsen, "SOAP 784 Version 1.2 Part 1: Messaging Framework", W3C 785 Recommendation REC-soap12-part1-20030624, June 2002, 786 . 788 [4] Thompson, H., Beech, D., Maloney, M., and N. Mendelsohn, "XML 789 Schema Part 1: Structures", W3C Recommendation REC-xmlschema-1- 790 20010502, May 2001, 791 . 793 [5] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., 794 Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- 795 HTTP/1.1", RFC 2616, June 1999, 796 . 798 [6] Moore, K., "On the use of HTTP as a Substrate", RFC 3205, 799 February 2002, . 801 [7] Franks, J., Hallam-Baker, P., Hostetler, J., Leach, P., 802 Luotonen, A., Sink, E., and L. Stewart, "HTTP Authentication: 803 Basic and Digest Access Authentication", RFC 2617, June 1999, 804 . 806 [8] Bradner, S., "Key words for use in RFCs to Indicate Requirement 807 Levels", RFC 2119, March 1997, 808 . 810 [9] Dierks, T., Allen, C., Treese, W., Karlton, P., Freier, A., and 811 P. Kocher, "The TLS Protocol Version 1.0", RFC 2246, 812 January 1999, . 814 [10] Rigney, C., Willens, S., Rubens, A., and W. Simpson, "Remote 815 Authentication Dial In User Service (RADIUS)", RFC 2865, 816 June 2000, . 818 [11] Rose, M., "The Blocks Extensible Exchange Protocol Core", 819 RFC 3080, March 2001, . 821 [12] O'Tuathail, E. and M. Rose, "Using the Simple Object Access 822 Protocol (SOAP) in Blocks Extensible Exchange Protocol (BEEP)", 823 RFC 3288bis, March 2005, . 826 [13] Mealling, M., "The IETF XML Registry", RFC 3688, January 2004, 827 . 829 [14] Alvestrand, H. and T. Narten, "Guidelines for Writing an IANA 830 Considerations Section in RFCs", RFC 2434, October 1998, 831 . 833 6.2 Informative References 835 [15] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 836 Extensions (MIME) Part One: Format of Internet Message Bodies", 837 RFC 2045, November 1996, . 839 [16] Christensen, E., Curbera, F., Meredith, G., and S. Weerawarana, 840 "Web Services Description Language (WSDL) 1.1", W3C Note NOTE- 841 wsdl-20010315, March 2001, 842 . 844 [17] Brown, A., Fox, B., Hada, S., LaMacchia, B., and H. Maruyama, 845 "SOAP Security Extensions: Digital Signature", W3C Note NOTE- 846 SOAP-dsig-20010206, Feb 2001, 847 . 849 Author's Address 851 Ted Goddard 852 ICEsoft Technologies Inc. 853 Suite 300, 1717 10th St. NW 854 Calgary, AB T2M 4S2 855 Canada 857 Phone: (403) 663-3322 858 Email: ted.goddard@icesoft.com 859 URI: http://www.icesoft.com 861 Intellectual Property Statement 863 The IETF takes no position regarding the validity or scope of any 864 Intellectual Property Rights or other rights that might be claimed to 865 pertain to the implementation or use of the technology described in 866 this document or the extent to which any license under such rights 867 might or might not be available; nor does it represent that it has 868 made any independent effort to identify any such rights. Information 869 on the procedures with respect to rights in RFC documents can be 870 found in BCP 78 and BCP 79. 872 Copies of IPR disclosures made to the IETF Secretariat and any 873 assurances of licenses to be made available, or the result of an 874 attempt made to obtain a general license or permission for the use of 875 such proprietary rights by implementers or users of this 876 specification can be obtained from the IETF on-line IPR repository at 877 http://www.ietf.org/ipr. 879 The IETF invites any interested party to bring to its attention any 880 copyrights, patents or patent applications, or other proprietary 881 rights that may cover technology that may be required to implement 882 this standard. Please address the information to the IETF at 883 ietf-ipr@ietf.org. 885 Disclaimer of Validity 887 This document and the information contained herein are provided on an 888 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 889 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 890 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 891 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 892 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 893 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 895 Copyright Statement 897 Copyright (C) The Internet Society (2006). This document is subject 898 to the rights, licenses and restrictions contained in BCP 78, and 899 except as set forth therein, the authors retain all their rights. 901 Acknowledgment 903 Funding for the RFC Editor function is currently provided by the 904 Internet Society.