RFC 4744

Using the NETCONF Protocol over the Blocks Extensible Exchange Protocol (BEEP) 💖

Okay bestie, this is RFC 4744 🎀 It's a Standards Track doc from the Network Working Group, written by E. Lear of Cisco Systems and K. Crozier, and it dropped in December 2006 ✨ It doesn't list anything it obsoletes or updates, so no drama there 💅

Status of This Memo 📜

This doc is an Internet standards track protocol for the whole Internet community, and it's basically asking for discussion and suggestions for improvements 💬 For the current standardization state and status of this protocol, check the current edition of the "Internet Official Protocol Standards" (STD 1) 📚 Distribution of this memo is unlimited 🦋

Copyright Notice ⚖️

Copyright (C) The IETF Trust (2006) 💅

Abstract 🌸

This doc describes an application protocol mapping for the Network Configuration Protocol (NETCONF) over the Blocks Extensible Exchange Protocol (BEEP) 🧚

Table of Contents 🗂️

1. Introduction ....................................................2
   1.1. Why BEEP? ..................................................2
2. BEEP Transport Mapping ..........................................2
   2.1. NETCONF Session Establishment ..............................2
   2.2. Starting a Channel for NETCONF .............................4
   2.3. NETCONF Session Usage ......................................5
   2.4. NETCONF Session Teardown ...................................5
   2.5. BEEP Profile for NETCONF ...................................6
3. Security Considerations .........................................6
4. IANA Considerations .............................................7
5. Acknowledgments .................................................7
6. References ......................................................8
   6.1. Normative References .......................................8
   6.2. Informative References .....................................8

1. Introduction 🦋

So, the NETCONF protocol [1] is the simple mechanism that lets you manage a network device, and it's designed to work over a bunch of different application protocols 🌈 This doc is the application protocol mapping for NETCONF over the Blocks Extensible Exchange Protocol (BEEP) [7] 💜

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [2] 📖

1.1. Why BEEP? 🤔

Using BEEP for transporting XML is honestly so natural 🫶 BEEP is peer-to-peer, so it's easy to implement NETCONF no matter which side of the connection started it ✨ That "bidirectionality" means either the manager or the agent can initiate a connection, and that's a big deal for lots of devices that connect now and then, or for devices that have to flip the management connection around when firewalls and network address translators (NATs) are in the way 🔥

BEEP uses the Simple Authentication and Security Layer (SASL) [3] 🔐 The SASL profile BEEP uses maps directly onto the existing security model for the command line interface (CLI), and Transport Layer Security (TLS) [4] brings a strong, well-tested encryption mechanism with server-side authentication, or server and client-side authentication 💖

2. BEEP Transport Mapping 🎀

All NETCONF over BEEP implementations MUST implement the profile and functional mapping between NETCONF and BEEP as described below 👑

For this doc, a manager is a NETCONF client and an agent is a NETCONF server 🧚 Client/server language isn't used in BEEP, since people usually think of clients as the ones that connect to servers, and that could get confusing 🙈

2.1. NETCONF Session Establishment 🤝

Managers can be BEEP listeners or initiators, and agents can be listeners or initiators too 🦋 To set up a connection, the initiator connects to the listener on TCP port 831 💫 So the first exchange happens no matter whether the manager or the agent started it 🌸 Once the transport connection is up and the greetings start flying, they SHOULD each announce their support for TLS and optionally SASL 📣 After the BEEP greeting messages are exchanged, if both parties want TLS and both have it available, the listener STARTs a channel with the TLS profile 🔐

After TLS has started, both the initiator and the listener send a new BEEP greeting message, as the BEEP RFC requires 📜

Once all the BEEP greetings are exchanged and roles are clear, the agent MUST advertise the NETCONF profile 🫶 The manager MUST NOT advertise the NETCONF profile 🙅‍♀️ If the agent side (initiator or listener) gets a BEEP <greeting> element that contains the NETCONF profile, it MUST close the connection 💀 And if neither side issues a NETCONF profile, that's an error too, and the listener MUST close the connection 😭

If SASL is wanted, the initiator starts a BEEP channel to do a SASL exchange and authenticate itself 🔑 When authentication finishes, that channel is closed, since the channel is only there to authenticate 🧁

Examples of both the TLS and SASL profiles can be found in [7] 📚

The SASL PLAIN mechanism is expected to get a lot of use together with TLS [5] 🌈 In that case, following RFC 2595, the PLAIN mechanism MUST NOT be advertised in the first BEEP <greeting>, only in the one that comes after a successful TLS negotiation 🙌 This only applies when both TLS and SASL PLAIN are going to be used 🎀 To avoid eavesdropping risk, the SASL PLAIN mechanism MUST NOT be used over unencrypted channels 🚫 More about using SASL and TLS is in Security Considerations below 🛡️

Once authentication has happened, there's no need to tell initiator and listener apart anymore 🦋 Now we distinguish between manager and agent, and each one is assumed to know its role in the conversation 💜

2.2. Starting a Channel for NETCONF 🧚

The manager now sets up a new channel and specifies the single NETCONF profile 🎀 Here's an example:

         (M = Manager; A = Agent)

         M: MSG 0 1 . 10 48 118
         M: Content-type: application/beep+xml
         M:
         M: <start number="1">
         M:   <profile uri="http://iana.org/beep/netconf" />
         M: </start>
         M: END
         A: RPY 0 1 . 38 87
         A: Content-Type: application/beep+xml
         A:
         A: <profile uri="http://iana.org/beep/netconf" />
         A: END

Now we're ready to do NETCONF operations on BEEP channel 1 ✨

NETCONF messages go out with a Content-type header set to "text/xml" 📝

Next, the manager and the agent swap NETCONF <hello> elements on the new channel so each side can learn what the other one can do 🤝 This happens through a MSG, and then each side responds positively 🙌 The following example is adapted from [1] Section 8.1 💅

    A: MSG 1 0 . 0 457
    A: Content-type: application/beep+xml
    A:
    A: <?xml version='1.0' encoding="UTF-8"?>
    A: <hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
    A:   <capabilities>
    A:     <capability>
    A:       urn:ietf:params:netconf:base:1.0
    A:     </capability>
    A:     <capability>
    A:       urn:ietf:params:netconf:capability:startup:1.0
    A:     </capability>
    A:     <capability>
    A:       http://example.net/router/2.3/core#myfeature
    A:     </capability>
    A:   </capabilities>
    A:   <session-id>4</session-id>
    A: </hello>
    A: END

    M: RPY 1 0 . 0 0
    M: END

Future NETCONF capabilities might need extra BEEP channels 🌸 When those get defined, a BEEP mapping must be defined as well 🧩

And that's it! The NETCONF session is established and capabilities have been exchanged 🥳

2.3. NETCONF Session Usage 💻

Almost every NETCONF operation runs through the <rpc> element 🍓 To make a remote procedure call (RPC), the manager sends a BEEP MSG on the operational channel, and that MSG contains the RPC and its arguments 📦 Following the BEEP standard, RPC requests can be split across several BEEP frames 🧩

Once the agent gets and processes the request, it answers with BEEP RPY messages on the same channel, carrying the response to the RPC 💌 And again, per the BEEP standard, responses can be split across several BEEP frames too 🎁

2.4. NETCONF Session Teardown 🌙

When the manager sends <close-session>, the agent closes BEEP channel 0 once it has finished all the RPCs 👋 If the agent needs to start a close, it does that by closing BEEP channel 0 as well 🚪 The agent isn't required to, but it should give the manager a reasonable amount of time to release an existing lock before it starts closing 🕰️ Once the agent has closed channel 0, all the locks are released, and each side follows the teardown procedures specified in [8] 🔓 After a BEEP close comes in, or after sending <close-session>, a manager MUST NOT send further requests 🙅‍♀️ If there's extra activity from expanded capabilities, it MUST cease in an orderly manner and should be properly described in the capability mapping 🫶

3. Security Considerations ✨

Okay bestie, this is the section where we talk about the serious stuff 🔐 Configuration info is super sensitive, no cap. If it gets sent in the clear with zero integrity checking, devices are wide open to the classic "person-in-the-middle" attacks 😭 Configs often hold passwords, user names, service descriptions, and topology details, and all of that is sensitive. So a NETCONF application protocol MUST, at minimum, support options for both confidentiality and authentication 💜

Good news: the BEEP mapping in this document handles both confidentiality and authentication, and it's flexible about it 🦋 It does this with TLS and SASL profiles. Confidentiality comes from the TLS profile, used the way we talked about above. Also, the server certificate shall serve as the server's authentication to the client. The client MUST be prepared to recognize and validate a server certificate, and it SHOULD by default reject invalid certificates 🎀

3.1. Trust Anchors and Validation 🧚

To validate a certificate, the client has to be able to reach a trust anchor. The methods for doing that are out of scope for this document, since they depend on the type of device and the situation 🌸 Implementors and administrators are both cautioned to watch out for any circular dependencies that different methods might introduce. For example, OCSP servers might not be available during a network cold start, so it would be ill-advised for core routers to rely on them to get configuration at boot 💀

3.2. Client Authentication 🔥

For client-side authentication there are a few options. The client MAY provide a certificate during the initiation phase of TLS, and in that case the subject of that certificate shall be considered principal for authentication purposes 👑 Server implementors should again be aware of any interdependencies that could come up through the protocols used to validate trust anchors 🫶

3.3. Authorization by Subject or CA 💅

TLS endpoints can be authorized based on subject name or certificate authority (CA), depending on the circumstances. For instance, it would be unwise for a core Internet router to let a netconf agent connect just because it has a valid certificate signed by a common CA 😭 But allowing a connection from an agent with a particular distinguished name? Totally reasonable 💖 On the flip side, enterprises might want to trust certificates signed by CAs run by their own network operations team 🌈

3.4. SASL Profiles 🍓

If the client hasn't authenticated through TLS, the server SHOULD advertise one or more SASL profiles, and the client picks from those 🎀 When TLS is already established, the minimum profile MAY be PLAIN. Otherwise, implementations MUST support the DIGEST-MD5 profile as described in [6], and they MAY support other profiles, such as the One-Time Password (OTP) mechanism [10] ✨

3.5. Authorization Model ⭐

Different environments might allow different rights before and after authentication. An authorization model is NOT specified in this document, so no spoilers there 🙈 When an operation isn't properly authorized, a simple rpc-error containing "permission denied" is enough 💜 Also, authorization info can travel as configuration information, which is all the more reason to lock down the connection 🔒

Wait, I need to correct the above. The authorization model line in the original does not use a BCP 14 keyword, so "NOT specified" should not be capitalized. Here is the corrected version of that paragraph:

Different environments might allow different rights before and after authentication. An authorization model is not specified in this document, so no spoilers there 🙈 When an operation isn't properly authorized, a simple rpc-error containing "permission denied" is enough 💜 Also, authorization info can travel as configuration information, which is all the more reason to lock down the connection 🔒

4. IANA Considerations 🦋

IANA assigned TCP port (831) for NETCONF over BEEP 🌸

5. Acknowledgments 💖

This work is the product of the NETCONF IETF working group, and so many people contributed to the NETCONF discussion 🫶 Most notably, Rob Ens, Phil Schafer, Andy Bierman, Wes Hardiger, Ted Goddard, and Margaret Wasserman all helped in some way with this work, which was originally going to live in the NETCONF base protocol specification 🧚 Thanks also to Weijing Chen, Keith Allen, Juergen Schoenwaelder, Marshall Rose, and Eamon O'Tuathail for their super constructive participation 👑 The authors would also like to thank Elwyn Davies for his constructive review 🌈

6. References 📚

6.1. Normative References 🔥

• [1] Enns, R., Ed., "NETCONF Configuration Protocol", RFC 4741, December 2006.
• [2] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
• [3] Melnikov, A. and K. Zeilenga, "Simple Authentication and Security Layer (SASL)", RFC 4422, June 2006.
• [4] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.1", RFC 4346, April 2006.
• [5] Newman, C., "Using TLS with IMAP, POP3 and ACAP", RFC 2595, June 1999.
• [6] Leach, P. and C. Newman, "Using Digest Authentication as a SASL Mechanism", RFC 2831, May 2000.
• [7] Rose, M., "The Blocks Extensible Exchange Protocol Core", RFC 3080, March 2001.
• [8] Rose, M., "Mapping the BEEP Core onto TCP", RFC 3081, March 2001.

6.2. Informative References 🧚

• [9] Sperberg-McQueen, C., Paoli, J., Maler, E., and T. Bray, "Extensible Markup Language (XML) 1.0 (Second Edition)", World Wide Web Consortium, First Edition, http://www.w3.org/TR/2000/REC-xml-20001006, October 2000.
• [10] Newman, C., "The One-Time-Password SASL Mechanism", RFC 2444, October 1998.

Authors' Addresses 🎀

Eliot Lear Cisco Systems Glatt-com CH-8301 Glattzentrum, Zurich CH

EMail: lear@cisco.com

Ken Crozier

EMail: ken.crozier@gmail.com

Full Copyright Statement 💅

Copyright (C) The IETF Trust (2006).

This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.

This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST, AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property 🌈

The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79.

Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr.

The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org.

Acknowledgement 🫶

Funding for the RFC Editor function is currently provided by the Internet Society.