RFC 7589

Using the NETCONF Protocol over Transport Layer Security (TLS) with Mutual X.509 Authentication

📅 published June 2015, from ietf

RFC 7589: Using NETCONF over TLS with Mutual X.509 Auth 🎀

okay bestie, this one is RFC 7589, titled Using the NETCONF Protocol over Transport Layer Security (TLS) with Mutual X.509 Authentication 💖 It's a Standards Track doc from June 2015, so it's an actual official spec. The authors are M. Badra (Zayed University), A. Luchuk (SNMP Research, Inc.), and J. Schoenwaelder (Jacobs University Bremen). It's also the revision of RFC 5539, and it obsoletes RFC 5539 🧚 It's published as ISSN 2070-1721 and it updates the framing stuff for NETCONF 1.1.

Abstract ✨

so NETCONF is the protocol that lets you install, change, and delete the config on network devices 🖥️ this doc explains how to wrap NETCONF in TLS using mutual X.509 authentication, so the messages are actually secure 🔐 it's a revision of RFC 5539, and it documents the new message framing that NETCONF 1.1 uses. this one replaces RFC 5539 🦋

Status of This Memo 📋

this is an Internet Standards Track document 💅

it's a product of the Internet Engineering Task Force (IETF), so it represents the consensus of the IETF community. it got public review and was approved for publication by the Internet Engineering Steering Group (IESG). if you want more info on Internet Standards, check Section 2 of RFC 5741 🌸

info about the current status of this doc, any errata, and how to give feedback lives at http://www.rfc-editor.org/info/rfc7589 🔗

Copyright (c) 2015 IETF Trust and the persons identified as the document authors. All rights reserved. 🌈

this doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as they were in effect on the publication date. please actually read these, bestie, because they explain your rights and restrictions 🙈 code components pulled out of this doc must include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come without warranty, as the Simplified BSD License describes 🫶

Table of Contents 🗂️

1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
2.  Connection Initiation . . . . . . . . . . . . . . . . . . . .   3
3.  Message Framing . . . . . . . . . . . . . . . . . . . . . . .   3
4.  Connection Closure  . . . . . . . . . . . . . . . . . . . . .   4
5.  Certificate Validation  . . . . . . . . . . . . . . . . . . .   4
6.  Server Identity . . . . . . . . . . . . . . . . . . . . . . .   4
7.  Client Identity . . . . . . . . . . . . . . . . . . . . . . .   4
8.  Cipher Suites . . . . . . . . . . . . . . . . . . . . . . . .   6
9.  Security Considerations . . . . . . . . . . . . . . . . . . .   7
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . .   8
11. References  . . . . . . . . . . . . . . . . . . . . . . . . .   8
  11.1.  Normative References . . . . . . . . . . . . . . . . . .   8
  11.2.  Informative References . . . . . . . . . . . . . . . . .   9
Appendix A.  Changes from RFC 5539  . . . . . . . . . . . . . . .  10
Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .  10
Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  11

1. Introduction 🌸

okay so NETCONF is defined in [RFC6241], and it's how you manage a network device 🖥️ it's connection-oriented, which means it needs a persistent connection between peers. that connection has to give you integrity, confidentiality, peer authentication, and reliable, sequenced data delivery. it's giving security checklist 💅

this doc says how NETCONF messages get exchanged over Transport Layer Security (TLS) [RFC5246]. Implementations MUST support mutual TLS certificate-based authentication [RFC5246]. 🔥 this is the part that makes it iconic: the NETCONF server knows who the principal is that wants to change the management info, and the NETCONF client knows the identity of the server it's about to manipulate 🫶

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 [RFC2119] 📚

2. Connection Initiation 🦋

the peer acting as the NETCONF client MUST act as the TLS client. the TLS client actively opens the TLS connection, and the TLS server passively listens for incoming TLS connections 🧚 NETCONF servers listen on the well-known TCP port number 6513 for TCP connections that NETCONF-over-TLS clients set up ✨

the TLS client MUST send the TLS ClientHello message to start the TLS handshake. the TLS server MUST send a CertificateRequest so it can ask the TLS client for a certificate 🎀 once the TLS handshake is done, the client and server MAY start exchanging NETCONF messages. identity verification happens before the NETCONF <hello> message is sent, which means it's completed before the NETCONF session even starts 🙈 very organized, very iconic

3. Message Framing 💜

all NETCONF messages MUST be sent as TLS "application data" 💖 a bunch of NETCONF messages can be packed into one TLS record, or one NETCONF message can be spread across multiple TLS records. lowkey flexible 🌈

the previous version of this spec [RFC5539] used the framing sequence from [RFC4742]. this version lines up with [RFC6242] and adopts the framing protocol defined there, like this 🍓

the NETCONF <hello> message MUST be followed by the character sequence ]]>]]>. when peers get the <hello> message, they check the capabilities that got announced. if both peers advertise the :base:1.1 capability, the chunked framing mechanism from Section 4.2 of [RFC6242] is used for the rest of the NETCONF session 🔥 otherwise, the old end-of-message-based mechanism (see Section 4.3 of [RFC6242]) gets used ✨

4. Connection Closure 🌙

a NETCONF server processes NETCONF messages from the NETCONF client in the order they arrive 🦋 a NETCONF session gets closed with the <close-session> operation. when the NETCONF server processes a <close-session> operation, the NETCONF server SHALL respond and close the TLS session, as described in Section 7.2.1 of [RFC5246] 💀 no skipping the response, periodt

5. Certificate Validation 🔐

both peers MUST use X.509 certificate path validation [RFC5280] to check the integrity of the certificate the other peer shows them 🫶 a presented X.509 certificate can also count as valid if it matches one from another trusted mechanism, like a locally configured certificate fingerprint. if X.509 path validation fails and the certificate doesn't match one from a trusted mechanism, the connection MUST be terminated as defined in [RFC5246] 🚫 no vibes, just termination 💅

6. Server Identity 👑

the NETCONF client MUST check the server's identity according to Section 6 of [RFC6125] 🧚 this is how the client makes sure it's talking to the right server, bestie 💖

7. Client Identity ✨

okay bestie, first things first: the NETCONF server MUST verify the identity of the NETCONF client 🔐 before a session even starts, so random requests can't just waltz in 💅

the NETCONF protocol [RFC6241] needs the transport's authentication to end up with an authenticated client identity whose permissions the server already knows 🎀. that identity is usually called the NETCONF username. here's the algorithm the server uses to get a NETCONF username out of a certificate 🧚 (ngl it's the same one as in the SNMP-TLS-TM-MIB from [RFC6353] and the ietf-x509-cert-to-name YANG module from [RFC7407], so everything is giving consistency 💜)

  • (a) the server keeps an ordered list of mappings from certificates to NETCONF usernames 📜. each list entry has:
    • a certificate fingerprint (used to match the certificate that's presented) 🫆
    • a map type (tells the server how to derive the NETCONF username from the certificate) 🗺️
    • optional auxiliary data (carries a NETCONF username if the map type says the username is explicitly configured) 🍓
  • (b) the NETCONF username is derived by going through each list entry in order 🚶‍♀️. the fingerprint of the current entry decides whether it's a match:
    1. if the entry's fingerprint matches the fingerprint of the presented certificate, the entry counts as a successful match ✨
    2. if the entry's fingerprint matches a locally held copy of a trusted certification authority (CA) certificate, and that CA certificate was part of the CA certificate chain to the presented certificate, the entry counts as a successful match 🔗
  • (c) once a matching entry is found, its map type decides how the username tied to the certificate gets figured out 🧩. the options are:
    • A. the username comes from the auxiliary data of the current entry. so the username is explicitly configured (map type specified) 🎀
    • B. the subjectAltName's rfc822Name field maps to the username (map type san-rfc822-name). the local part of the rfc822Name is used unaltered, but the host-part of the name must be converted to lowercase 💌
    • C. the subjectAltName's dNSName maps to the username (map type san-dns-name). the characters of the dNSName get converted to lowercase 🔡
    • D. the subjectAltName's iPAddress maps to the username (map type san-ip-address). IPv4 addresses are converted into decimal-dotted quad notation (e.g., 192.0.2.1) 🌐. IPv6 addresses are converted into a 32-character, all lowercase hexadecimal string without any colon separators 🫧
    • E. the rfc822Name, dNSName, or iPAddress of the subjectAltName maps to the username (map type san-any). the first matching subjectAltName value of the above types that's found in the certificate MUST be used when deriving the name 👑
    • F. the certificate's CommonName maps to the username (map type common-name). the CommonName gets converted to UTF-8 encoding. the usage of CommonNames is deprecated, and users are encouraged to use the subjectAltName mapping methods instead 🙈
  • (d) if it's impossible to figure out a username from the list entry's data combined with the data in the certificate, then additional list entries MUST be searched to look for another potential match 🔍. likewise, if the username doesn't comply with the NETCONF requirements on usernames [RFC6241], then additional list entries MUST be searched to look for another potential match 🙅‍♀️. if there are no further list entries, the TLS session MUST be terminated 💀

the username provided by the NETCONF over TLS implementation gets passed up to the NETCONF message layer as the NETCONF username, without any changes 🫶

the NETCONF server configuration data model [NETCONF-RESTCONF] covers NETCONF over TLS and gives more details, like the certificate fingerprint formats that get exposed to network configuration systems 📊

8. Cipher Suites 🔐

okay so implementations MUST support TLS 1.2 [RFC5246] and are REQUIRED to support the mandatory-to-implement cipher suite 🎀. implementations MAY also implement additional TLS cipher suites that provide mutual authentication [RFC5246] and confidentiality as required by NETCONF [RFC6241] 🧁. implementations SHOULD follow the recommendations given in [RFC7525] 🌸

9. Security Considerations 🚨

this section is serious, so grab a snack and pay attention 🍿😭

NETCONF is used to access configuration and state information and to modify configuration information 🗂️. so the ability to access this protocol should be limited to users and systems that are authorized to view the NETCONF server's configuration and state, or to modify the NETCONF server's configuration 🔒.

configuration or state data may include sensitive information, like usernames or security keys 🗝️. so NETCONF requires communications channels that provide strong encryption for data privacy 🛡️. this document defines a NETCONF over TLS mapping that supports strong encryption and authentication ✨. the security considerations for TLS [RFC5246] and NETCONF [RFC6241] apply here too 💅.

NETCONF over TLS requires mutual authentication 🤝. neither side should establish a NETCONF over TLS connection with an unknown, unexpected, or incorrect identity on the other side 🚫. note that the decision on whether a certificate presented by the client is accepted can depend on whether a trusted CA certificate is white listed (see Section 7) 📝. if deployments make use of this option, it's recommended that the white-listed CA certificate is used only to issue certificates that are used for accessing NETCONF servers 🎯. should the CA certificate be used to issue certificates for other purposes, then all certificates created for other purposes will be accepted by a NETCONF server as well, which is likely not suitable 😬.

main character warning: if the CA certificate issues certificates for other purposes, a NETCONF server will accept all of them, and that's likely not suitable at all 🚨

this document doesn't support third-party authentication (e.g., backend Authentication, Authorization, and Accounting (AAA) servers) 🙅‍♀️. the reason is that TLS doesn't specify this way of authentication, and NETCONF depends on the transport protocol for the authentication service 🧠. if third-party authentication is needed, the Secure Shell (SSH) transport [RFC6242] can be used 🔑.

RFC 5539 assumed that the end-of-message (EOM) sequence, ]]>]]>, can't appear in any well-formed XML document, and that turned out to be mistaken 🙈. the EOM sequence can cause operational problems and open space for attacks if it's sent on purpose in NETCONF messages 💥. it is, however, believed that the associated threat isn't very high 🤞. this document still uses the EOM sequence for the initial <hello> message to avoid incompatibility with existing implementations 🫤. when both peers implement the :base:1.1 capability, a proper framing protocol (the chunked framing mechanism; see Section 3) is used for the rest of the NETCONF session, to avoid injection attacks 🧱✨.

10. IANA Considerations 📋

okay so per RFC 5539, IANA assigned TCP port number 6513 in the "Registered Port Numbers" range, with the service name "netconf-tls" 🎀. this port is the default port for NETCONF over TLS, as defined in Section 2 🔌. here's the registration template, following the rules in [RFC6335] 👇

   Service Name:           netconf-tls
   Transport Protocol(s):  TCP
   Assignee:               IESG <iesg@ietf.org>
   Contact:                IETF Chair <chair@ietf.org>
   Description:            NETCONF over TLS
   Reference:              RFC 7589
   Port Number:            6513

11. References 📚

11.1. Normative References

11.2. Informative References

Appendix A. Changes from RFC 5539 🎀

okay so this section is the glow-up recap 💅 it sums up the major changes between this doc and RFC 5539, so you can see what's new ✨

  • Documented that NETCONF over TLS uses the new message framing if both peers support the :base:1.1 capability 🫶
  • Removed redundant text that can be found in the TLS and NETCONF specifications and restructured the text. Alignment with [RFC6125]. 🧹
  • Added a high-level description on how NETCONF usernames are derived from certificates 🔑
  • Removed the reference to BEEP 👋

Acknowledgements 🌸

the authors want to thank everyone who gave comments on this doc, and that's giving main character energy for the whole NETCONF mailing list too 🫶 literally a whole village 😭

Martin Bjorklund, Olivier Coupelon, Pasi Eronen, Mehmet Ersue, Stephen Farrell, Miao Fuyou, Ibrahim Hajjeh, David Harrington, Sam Hartman, Alfred Hoenes, Simon Josefsson, Charlie Kaufman, Barry Leiba, Tom Petch, Tim Polk, Eric Rescorla, Dan Romascanu, Kent Watsen, Bert Wijnen, Stefan Winter, and the NETCONF mailing list members

Juergen Schoenwaelder was partly funded by Flamingo, a Network of Excellence project (ICT-318488) supported by the European Commission under its Seventh Framework Programme 💜 the funding is a whole mood 🇪🇺

Authors' Addresses 💖

here's where you can find the authors, bestie 🦋

Mohamad Badra
Zayed University
P.O. Box 19282
Dubai, United Arab Emirates

Phone: +971 4 4021879
EMail: mohamad.badra@zu.ac.ae
URI:   http://www.zu.ac.ae
Alan Luchuk
SNMP Research, Inc.
3001 Kimberlin Heights Road
Knoxville, TN  37920
United States

Phone: +1 865 573 1434
EMail: luchuk@snmp.com
URI:   http://www.snmp.com/
Juergen Schoenwaelder
Jacobs University Bremen
Campus Ring 1
28759 Bremen
Germany

Phone: +49 421 200 3587
EMail: j.schoenwaelder@jacobs-university.de
URI:   http://www.jacobs-university.de/
📦 where this page comes from