idnits 2.17.1 draft-ietf-netconf-ssh-06.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 16. -- Found old boilerplate from RFC 3978, Section 5.5 on line 399. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 376. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 383. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 389. ** 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 : ---------------------------------------------------------------------------- No issues found here. 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 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 6, 2006) is 6588 days in the past. Is this intentional? 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-11 -- Obsolete informational reference (is this intentional?): RFC 2629 (Obsoleted by RFC 7749) Summary: 3 errors (**), 0 flaws (~~), 3 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Wasserman 3 Internet-Draft ThingMagic 4 Expires: September 7, 2006 T. Goddard 5 ICEsoft Technologies, Inc. 6 March 6, 2006 8 Using the NETCONF Configuration Protocol over Secure Shell (SSH) 9 draft-ietf-netconf-ssh-06.txt 11 Status of this Memo 13 By submitting this Internet-Draft, each author represents that any 14 applicable patent or other IPR claims of which he or she is aware 15 have been or will be disclosed, and any of which he or she becomes 16 aware will be disclosed, in accordance with Section 6 of BCP 79. 18 Internet-Drafts are working documents of the Internet Engineering 19 Task Force (IETF), its areas, and its working groups. Note that 20 other groups may also distribute working documents as Internet- 21 Drafts. 23 Internet-Drafts are draft documents valid for a maximum of six months 24 and may be updated, replaced, or obsoleted by other documents at any 25 time. It is inappropriate to use Internet-Drafts as reference 26 material or to cite them other than as "work in progress." 28 The list of current Internet-Drafts can be accessed at 29 http://www.ietf.org/ietf/1id-abstracts.txt. 31 The list of Internet-Draft Shadow Directories can be accessed at 32 http://www.ietf.org/shadow.html. 34 This Internet-Draft will expire on September 7, 2006. 36 Copyright Notice 38 Copyright (C) The Internet Society (2006). 40 Abstract 42 This document describes a method for invoking and running the NETCONF 43 protocol within a Secure Shell (SSH) session as an SSH subsystem. 45 Table of Contents 47 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 48 2. Requirements Terminology . . . . . . . . . . . . . . . . . . . 3 49 3. Starting NETCONF over SSH . . . . . . . . . . . . . . . . . . 3 50 3.1. Capabilities Exchange . . . . . . . . . . . . . . . . . . 4 51 4. Using NETCONF over SSH . . . . . . . . . . . . . . . . . . . . 5 52 5. Exiting the NETCONF Subsystem . . . . . . . . . . . . . . . . 6 53 6. Security Considerations . . . . . . . . . . . . . . . . . . . 7 54 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 55 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 8 56 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9 57 9.1. Normative References . . . . . . . . . . . . . . . . . . . 9 58 9.2. Informative References . . . . . . . . . . . . . . . . . . 9 59 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10 60 Intellectual Property and Copyright Statements . . . . . . . . . . 11 62 1. Introduction 64 The NETCONF protocol [I-D.ietf-netconf-prot] is an XML-based protocol 65 used to manage the configuration of networking equipment. NETCONF is 66 defined to be session-layer and transport independent, allowing 67 mappings to be defined for multiple session-layer or transport 68 protocols. This document defines how NETCONF can be used within a 69 Secure Shell (SSH) session, using the SSH connection protocol 70 [RFC4254] over the SSH transport protocol [RFC4253]. This mapping 71 will allow NETCONF to be executed from a secure shell session by a 72 user or application. 74 Throughout this document, the terms "client" and "server" are used to 75 refer to the two ends of the SSH transport connection. The client 76 actively opens the SSH connection, and the server passively listens 77 for the incoming SSH connection. The terms "manager" and "agent" are 78 used to refer to the two ends of the NETCONF protocol session. The 79 manager issues NETCONF RPC commands, and the agent replies to those 80 commands. When NETCONF is run over SSH using the mapping defined in 81 this document, the client is always the manager, and the server is 82 always the agent. 84 2. Requirements Terminology 86 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 87 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 88 document are to be interpreted as described in RFC 2119 [RFC2119]. 90 3. Starting NETCONF over SSH 92 To run NETCONF over SSH, the client will first establish an SSH 93 transport connection using the SSH transport protocol, and the client 94 and server will exchange keys for message integrity and encryption. 95 The client will then invoke the "ssh-userauth" service to 96 authenticate the user, as described in the SSH authentication 97 protocol [RFC4252]. Once the user has been successfully 98 authenticated, the client will invoke the "ssh-connection" service, 99 also known as the SSH connection protocol. 101 After the ssh-connection service is established, the client will open 102 a channel of type "session", which will result in an SSH session. 104 Once the SSH session has been established, the user (or application) 105 will invoke NETCONF as an SSH subsystem called "netconf". Subsystem 106 support is a feature of SSH version 2 (SSHv2) and is not included in 107 SSHv1. Running NETCONF as an SSH subsystem avoids the need for the 108 script to recognize shell prompts or skip over extraneous 109 information, such as a system message that is sent at shell start-up. 110 However, if a subsystem cannot be used, it should be possible for a 111 client to skip over any system messages that are sent at shell 112 start-up by searching for a NETCONF element. Note that this 113 may not avoid problems if system messages are recieved later in the 114 session. 116 In order to allow NETCONF traffic to be easily identified and 117 filtered by firewalls and other network devices, NETCONF servers MUST 118 default to providing access to the "netconf" SSH subsystem only when 119 the SSH session is established using the IANA-assigned TCP port 120 . Servers SHOULD be configurable to allow access to the netconf 121 SSH subsystem over other ports. 123 A user (or application), could use the following command line to 124 invoke NETCONF as an SSH subsystem on the IANA-assigned port: 126 [user@client]$ ssh -s server.example.org -p netconf 128 Note that the -s option causes the command ("netconf") to be invoked 129 as an SSH subsystem. 131 3.1. Capabilities Exchange 133 The server MUST indicate its capabilities by sending an XML document 134 containing a element as soon as the NETCONF session is 135 established. The user (or application) can parse this message to 136 determine which NETCONF capabilities are supported by the server. 138 The client must also send an XML document containing a 139 element to indicate the client's capabilities to the server. The 140 document containing the element MUST be the first XML 141 document that the client sends after the NETCONF session is 142 established. 144 The following example shows a capability exchange. Messages sent by 145 the client are marked with "C:" and message sent by the server are 146 marked with "S:". 148 S: 149 S: 150 S: 151 S: 152 S: urn:ietf:params:xml:ns:netconf:base:1.0 153 S: 154 S: 155 S: urn:ietf:params:ns:netconf:capability:startup:1.0 156 S: 157 S: 158 S: 4 159 S: 160 S: ]]>]]> 162 C: 163 C: 164 C: 165 C: 166 C: urn:ietf:params:xml:ns:netconf:base:1.0 167 C: 168 C: 169 C: 170 C: ]]>]]> 172 Although the example shows the server sending a message 173 followed by the client's message, both sides will send the message as 174 soon as the NETCONF subsystem is initialized, perhaps simultaneously. 176 As the previous example illustrates, a special character sequence, 177 ]]>]]>, MUST be sent by both the client and the server after each XML 178 document in the NETCONF exchange. This character sequence cannot 179 legally appear in an XML document, so it can be unambigiously used to 180 indentify the end of the current document, allowing resynchronization 181 of the NETCONF exchange in the event of an XML syntax or parsing 182 error. 184 4. Using NETCONF over SSH 186 A NETCONF over SSH session consists of the manager and agent 187 exchanging complete XML documents. Once the session has been 188 established and capabilities have been exchanged, the manager will 189 send complete XML documents to the server containing elements, 190 and the agent will respond with complete XML documents containing 191 elements. 193 To continue the example given above, an NETCONF over SSH session to 194 retrieve a set of configuration information might look like this: 196 C: 197 C: 199 C: 200 C: 201 C: 202 C: 203 C: 204 C: 205 C: 206 C: ]]>]]> 208 S: 209 S: 211 S: 212 S: 213 S: rootsuperuser 214 S: fredadmin 215 S: barneyadmin 216 S: 217 S: 218 S: 219 S: ]]>]]> 221 5. Exiting the NETCONF Subsystem 223 Exiting NETCONF is accomplished using the operation. 224 An agent will process RPC messages from the manager in the order in 225 which the are received. When the agent processes a 226 command, the agent shall respond and terminate the SSH session. The 227 agent MUST NOT process any RPC commands received on the current 228 session after the command. 230 To continue the example used in previous sections, an existing 231 NETCONF subsystem session could be closed as follows: 233 C: 234 C: 236 C: 237 C: 238 C: ]]>]]> 240 S: 241 S: 243 S: 244 S: 245 S: ]]>]]> 247 6. Security Considerations 249 NETCONF is used to access configuration and state information and to 250 modify configuration information, so the ability to access this 251 protocol should be limited to users and systems that are authorized 252 to view the agent's configuration and state or to modify the agent's 253 configuration. 255 The identity of the server MUST be verified and authenticated by the 256 client according to local policy before password-based authentication 257 data or any configuration or state data is sent to or received from 258 the server. The identity of the client MUST also be verified and 259 authenticated by the server according to local policy to ensure that 260 the incoming client request is legitimate before any configuration or 261 state data is sent to or received from the client. Neither side 262 should establish a NETCONF over SSH connection with an unknown, 263 unexpected or incorrect identity on the opposite side. 265 Configuration or state data may include sensitive information, such 266 as usernames or security keys. So, NETCONF should only be used over 267 communications channels that provide strong encryption for data 268 privacy. This document defines a NETCONF over SSH mapping which 269 provides for support of strong encryption and authentication. 271 This document requires that servers default to allowing access to the 272 "netconf" SSH subsystem only when using a specific TCP port assigned 273 by IANA for this purpose. This will allow NETCONF over SSH traffic 274 to be easily identified and filtered by firewalls and other network 275 nodes. However, it will also allow NETCONF over SSH traffic to be 276 more easily identified by attackers. 278 This document also recommends that servers be configurable to allow 279 access to the "netconf" SSH subsystem over other ports. Use of that 280 configuration option without corresponding changes to firewall or 281 network device configuration may unintentionally result in the 282 ability for nodes outside of the firewall or other administrative 283 boundary to gain access to "netconf" SSH subsystem. 285 7. IANA Considerations 287 IANA is requested to assign a TCP port number which will be the 288 default port for NETCONF over SSH sessions as defined in this 289 document. 291 IANA has assigned port for this purpose. 293 [RFC Editor: Please replace two instances of in Section 3 and 294 one instance of in this section to the port number assigned by 295 IANA.] 297 IANA is also requested to assign "netconf" as an SSH Service Name as 298 defined in [RFC4250], as follows: 300 Service Name Reference 301 ------------- --------- 302 netconf [This Document] 304 8. Acknowledgements 306 This document was written using the xml2rfc tool described in RFC 307 2629 [RFC2629]. 309 Extensive input was received from the other members of the NETCONF 310 design team, including: Andy Bierman, Weijing Chen, Rob Enns, Wes 311 Hardaker, David Harrington, Eliot Lear, Simon Leinen, Phil Shafer, 312 Juergen Schoenwaelder and Steve Waldbusser. The following people 313 have also reviewed this document and provided valuable input: Olafur 314 Gudmundsson, Sam Hartman, Scott Hollenbeck, Bill Sommerfeld, Bert 315 Wijnen. 317 9. References 318 9.1. Normative References 320 [I-D.ietf-netconf-prot] 321 Enns, R., "NETCONF Configuration Protocol", 322 draft-ietf-netconf-prot-11 (work in progress), 323 February 2006. 325 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 326 Requirement Levels", BCP 14, RFC 2119, March 1997. 328 [RFC4250] Lehtinen, S. and C. Lonvick, "The Secure Shell (SSH) 329 Protocol Assigned Numbers", RFC 4250, January 2006. 331 [RFC4252] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) 332 Authentication Protocol", RFC 4252, January 2006. 334 [RFC4253] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) 335 Transport Layer Protocol", RFC 4253, January 2006. 337 [RFC4254] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) 338 Connection Protocol", RFC 4254, January 2006. 340 9.2. Informative References 342 [RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, 343 June 1999. 345 Authors' Addresses 347 Margaret Wasserman 348 ThingMagic 349 One Broadway, 5th Floor 350 Cambridge, MA 02142 351 USA 353 Phone: +1 781 405-7464 354 Email: margaret@thingmagic.com 355 URI: http://www.thingmagic.com 357 Ted Goddard 358 ICEsoft Technologies, Inc. 359 Suite 300, 1717 10th St. NW 360 Calgary, AB T2M 4S2 361 Canada 363 Phone: +1 403 663-3322 364 Email: ted.goddard@icesoft.com 365 URI: http://www.icesoft.com 367 Intellectual Property Statement 369 The IETF takes no position regarding the validity or scope of any 370 Intellectual Property Rights or other rights that might be claimed to 371 pertain to the implementation or use of the technology described in 372 this document or the extent to which any license under such rights 373 might or might not be available; nor does it represent that it has 374 made any independent effort to identify any such rights. Information 375 on the procedures with respect to rights in RFC documents can be 376 found in BCP 78 and BCP 79. 378 Copies of IPR disclosures made to the IETF Secretariat and any 379 assurances of licenses to be made available, or the result of an 380 attempt made to obtain a general license or permission for the use of 381 such proprietary rights by implementers or users of this 382 specification can be obtained from the IETF on-line IPR repository at 383 http://www.ietf.org/ipr. 385 The IETF invites any interested party to bring to its attention any 386 copyrights, patents or patent applications, or other proprietary 387 rights that may cover technology that may be required to implement 388 this standard. Please address the information to the IETF at 389 ietf-ipr@ietf.org. 391 Disclaimer of Validity 393 This document and the information contained herein are provided on an 394 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 395 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 396 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 397 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 398 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 399 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 401 Copyright Statement 403 Copyright (C) The Internet Society (2006). This document is subject 404 to the rights, licenses and restrictions contained in BCP 78, and 405 except as set forth therein, the authors retain all their rights. 407 Acknowledgment 409 Funding for the RFC Editor function is currently provided by the 410 Internet Society.