summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc7589.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rfc/rfc7589.txt')
-rw-r--r--doc/rfc/rfc7589.txt619
1 files changed, 619 insertions, 0 deletions
diff --git a/doc/rfc/rfc7589.txt b/doc/rfc/rfc7589.txt
new file mode 100644
index 0000000..a9555b3
--- /dev/null
+++ b/doc/rfc/rfc7589.txt
@@ -0,0 +1,619 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF) M. Badra
+Request for Comments: 7589 Zayed University
+Obsoletes: 5539 A. Luchuk
+Category: Standards Track SNMP Research, Inc.
+ISSN: 2070-1721 J. Schoenwaelder
+ Jacobs University Bremen
+ June 2015
+
+
+ Using the NETCONF Protocol over Transport Layer Security (TLS)
+ with Mutual X.509 Authentication
+
+Abstract
+
+ The Network Configuration Protocol (NETCONF) provides mechanisms to
+ install, manipulate, and delete the configuration of network devices.
+ This document describes how to use the Transport Layer Security (TLS)
+ protocol with mutual X.509 authentication to secure the exchange of
+ NETCONF messages. This revision of RFC 5539 documents the new
+ message framing used by NETCONF 1.1 and it obsoletes RFC 5539.
+
+Status of This Memo
+
+ This is an Internet Standards Track document.
+
+ This document is a product of the Internet Engineering Task Force
+ (IETF). It represents the consensus of the IETF community. It has
+ received public review and has been approved for publication by the
+ Internet Engineering Steering Group (IESG). Further information on
+ Internet Standards is available in Section 2 of RFC 5741.
+
+ Information about the current status of this document, any errata,
+ and how to provide feedback on it may be obtained at
+ http://www.rfc-editor.org/info/rfc7589.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Badra, et al. Standards Track [Page 1]
+
+RFC 7589 NETCONF over TLS June 2015
+
+
+Copyright Notice
+
+ Copyright (c) 2015 IETF Trust and the persons identified as the
+ document authors. All rights reserved.
+
+ This document is subject to BCP 78 and the IETF Trust's Legal
+ Provisions Relating to IETF Documents
+ (http://trustee.ietf.org/license-info) in effect on the date of
+ publication of this document. Please review these documents
+ carefully, as they describe your rights and restrictions with respect
+ to this document. Code Components extracted from this document must
+ include Simplified BSD License text as described in Section 4.e of
+ the Trust Legal Provisions and are provided without warranty as
+ described in the Simplified BSD License.
+
+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
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Badra, et al. Standards Track [Page 2]
+
+RFC 7589 NETCONF over TLS June 2015
+
+
+1. Introduction
+
+ The NETCONF protocol [RFC6241] defines a mechanism through which a
+ network device can be managed. NETCONF is connection-oriented,
+ requiring a persistent connection between peers. This connection
+ must provide integrity, confidentiality, peer authentication, and
+ reliable, sequenced data delivery.
+
+ This document defines how NETCONF messages can be exchanged over
+ Transport Layer Security (TLS) [RFC5246]. Implementations MUST
+ support mutual TLS certificate-based authentication [RFC5246]. This
+ assures the NETCONF server of the identity of the principal who
+ wishes to manipulate the management information. It also assures the
+ NETCONF client of the identity of the server for which it wishes to
+ manipulate the management information.
+
+ 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 the incoming TLS connections. The well-known
+ TCP port number 6513 is used by NETCONF servers to listen for TCP
+ connections established by NETCONF over TLS clients. The TLS client
+ MUST send the TLS ClientHello message to begin the TLS handshake.
+ The TLS server MUST send a CertificateRequest in order to request a
+ certificate from the TLS client. Once the TLS handshake has
+ finished, the client and the server MAY begin to exchange NETCONF
+ messages. Client and server identity verification is done before the
+ NETCONF <hello> message is sent. This means that the identity
+ verification is completed before the NETCONF session is started.
+
+3. Message Framing
+
+ All NETCONF messages MUST be sent as TLS "application data". It is
+ possible for multiple NETCONF messages to be contained in one TLS
+ record, or for a NETCONF message to be transferred in multiple TLS
+ records.
+
+
+
+
+
+
+
+
+
+
+Badra, et al. Standards Track [Page 3]
+
+RFC 7589 NETCONF over TLS June 2015
+
+
+ The previous version of this specification [RFC5539] used the framing
+ sequence defined in [RFC4742]. This version aligns with [RFC6242]
+ and adopts the framing protocol defined in [RFC6242] as follows:
+
+ The NETCONF <hello> message MUST be followed by the character
+ sequence ]]>]]>. Upon reception of the <hello> message, the peers
+ inspect the announced capabilities. If the :base:1.1 capability is
+ advertised by both peers, the chunked framing mechanism defined in
+ Section 4.2 of [RFC6242] is used for the remainder of the NETCONF
+ session. Otherwise, the old end-of-message-based mechanism (see
+ Section 4.3 of [RFC6242]) is used.
+
+4. Connection Closure
+
+ A NETCONF server will process NETCONF messages from the NETCONF
+ client in the order in which they are received. A NETCONF session is
+ closed using 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].
+
+5. Certificate Validation
+
+ Both peers MUST use X.509 certificate path validation [RFC5280] to
+ verify the integrity of the certificate presented by the peer. The
+ presented X.509 certificate may also be considered valid if it
+ matches one obtained by another trusted mechanism, such as using a
+ locally configured certificate fingerprint. If X.509 certificate
+ path validation fails and the presented X.509 certificate does not
+ match a certificate obtained by a trusted mechanism, the connection
+ MUST be terminated as defined in [RFC5246].
+
+6. Server Identity
+
+ The NETCONF client MUST check the identity of the server according to
+ Section 6 of [RFC6125].
+
+7. Client Identity
+
+ The NETCONF server MUST verify the identity of the NETCONF client to
+ ensure that the incoming request to establish a NETCONF session is
+ legitimate before the NETCONF session is started.
+
+ The NETCONF protocol [RFC6241] requires that the transport protocol's
+ authentication process results in an authenticated NETCONF client
+ identity whose permissions are known to the server. The
+ authenticated identity of a client is commonly referred to as the
+ NETCONF username. The following algorithm is used by the NETCONF
+
+
+
+Badra, et al. Standards Track [Page 4]
+
+RFC 7589 NETCONF over TLS June 2015
+
+
+ server to derive a NETCONF username from a certificate. (Note that
+ the algorithm below is the same as the one described in the
+ SNMP-TLS-TM-MIB MIB module defined in [RFC6353] and in the
+ ietf-x509-cert-to-name YANG module defined in [RFC7407].)
+
+ (a) The server maintains an ordered list of mappings of certificates
+ to NETCONF usernames. Each list entry contains
+
+ * a certificate fingerprint (used for matching the presented
+ certificate),
+
+ * a map type (indicates how the NETCONF username is derived
+ from the certificate), and
+
+ * optional auxiliary data (used to carry a NETCONF username if
+ the map type indicates the username is explicitly
+ configured).
+
+ (b) The NETCONF username is derived by considering each list entry
+ in order. The fingerprint member of the current list entry
+ determines whether the current list entry is a match:
+
+ 1. If the list entry's fingerprint value matches the
+ fingerprint of the presented certificate, then consider the
+ list entry as a successful match.
+
+ 2. If the list entry's fingerprint value matches that of 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, then
+ consider the list entry as a successful match.
+
+ (c) Once a matching list entry has been found, the map type of the
+ current list entry is used to determine how the username
+ associated with the certificate should be determined. Possible
+ mapping options are:
+
+ A. The username is taken from the auxiliary data of the current
+ list entry. This means the username is explicitly
+ configured (map type 'specified').
+
+ B. The subjectAltName's rfc822Name field is mapped 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.
+
+
+
+
+
+
+Badra, et al. Standards Track [Page 5]
+
+RFC 7589 NETCONF over TLS June 2015
+
+
+ C. The subjectAltName's dNSName is mapped to the username (map
+ type 'san-dns-name'). The characters of the dNSName are
+ converted to lowercase.
+
+ D. The subjectAltName's iPAddress is mapped 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
+ is mapped to the username (map type 'san-any'). The first
+ matching subjectAltName value found in the certificate of
+ the above types MUST be used when deriving the name.
+
+ F. The certificate's CommonName is mapped to the username (map
+ type 'common-name'). The CommonName is converted to UTF-8
+ encoding. The usage of CommonNames is deprecated and users
+ are encouraged to use subjectAltName mapping methods
+ instead.
+
+ (d) If it is impossible to determine a username from the list
+ entry's data combined with the data presented in the
+ certificate, then additional list entries MUST be searched to
+ look for another potential match. Similarly, if the username
+ does not comply to 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 will be
+ made available to the NETCONF message layer as the NETCONF username
+ without modification.
+
+ The NETCONF server configuration data model [NETCONF-RESTCONF] covers
+ NETCONF over TLS and provides further details such as certificate
+ fingerprint formats exposed to network configuration systems.
+
+8. Cipher Suites
+
+ Implementations MUST support TLS 1.2 [RFC5246] and are REQUIRED to
+ support the mandatory-to-implement cipher suite. Implementations MAY
+ 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].
+
+
+
+
+
+Badra, et al. Standards Track [Page 6]
+
+RFC 7589 NETCONF over TLS June 2015
+
+
+9. Security Considerations
+
+ 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, such
+ as 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 provides for support
+ of strong encryption and authentication. The security considerations
+ for TLS [RFC5246] and NETCONF [RFC6241] apply here as well.
+
+ NETCONF over TLS requires mutual authentication. Neither side should
+ establish a NETCONF over TLS connection with an unknown, unexpected,
+ or incorrect identity on the opposite side. Note that the decision
+ 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 is 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.
+
+ This document does not support third-party authentication (e.g.,
+ backend Authentication, Authorization, and Accounting (AAA) servers)
+ due to the fact that TLS does not specify this way of authentication
+ and that 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 assumes that the end-of-message (EOM) sequence, ]]>]]>,
+ cannot appear in any well-formed XML document, which turned out to be
+ mistaken. The EOM sequence can cause operational problems and open
+ space for attacks if sent deliberately in NETCONF messages. It is
+ however believed that the associated threat is not 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
+ (chunked framing mechanism; see Section 3) is used for the rest of
+ the NETCONF session, to avoid injection attacks.
+
+
+
+
+
+
+
+Badra, et al. Standards Track [Page 7]
+
+RFC 7589 NETCONF over TLS June 2015
+
+
+10. IANA Considerations
+
+ 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.
+ Below is 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
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119,
+ DOI 10.17487/RFC2119, March 1997,
+ <http://www.rfc-editor.org/info/rfc2119>.
+
+ [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
+ (TLS) Protocol Version 1.2", RFC 5246,
+ DOI 10.17487/RFC5246, August 2008,
+ <http://www.rfc-editor.org/info/rfc5246>.
+
+ [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
+ Housley, R., and W. Polk, "Internet X.509 Public Key
+ Infrastructure Certificate and Certificate Revocation List
+ (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008,
+ <http://www.rfc-editor.org/info/rfc5280>.
+
+ [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and
+ Verification of Domain-Based Application Service Identity
+ within Internet Public Key Infrastructure Using X.509
+ (PKIX) Certificates in the Context of Transport Layer
+ Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March
+ 2011, <http://www.rfc-editor.org/info/rfc6125>.
+
+ [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
+ and A. Bierman, Ed., "Network Configuration Protocol
+ (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
+ <http://www.rfc-editor.org/info/rfc6241>.
+
+
+
+
+
+Badra, et al. Standards Track [Page 8]
+
+RFC 7589 NETCONF over TLS June 2015
+
+
+ [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure
+ Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
+ <http://www.rfc-editor.org/info/rfc6242>.
+
+ [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S.
+ Cheshire, "Internet Assigned Numbers Authority (IANA)
+ Procedures for the Management of the Service Name and
+ Transport Protocol Port Number Registry", BCP 165,
+ RFC 6335, DOI 10.17487/RFC6335, August 2011,
+ <http://www.rfc-editor.org/info/rfc6335>.
+
+ [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre,
+ "Recommendations for Secure Use of Transport Layer
+ Security (TLS) and Datagram Transport Layer Security
+ (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May
+ 2015, <http://www.rfc-editor.org/info/rfc7525>.
+
+11.2. Informative References
+
+ [NETCONF-RESTCONF]
+ Watsen, K. and J. Schoenwaelder, "NETCONF Server and
+ RESTCONF Server Configuration Models", Work in Progress,
+ draft-ietf-netconf-server-model-06, February 2015.
+
+ [RFC4742] Wasserman, M. and T. Goddard, "Using the NETCONF
+ Configuration Protocol over Secure SHell (SSH)", RFC 4742,
+ DOI 10.17487/RFC4742, December 2006,
+ <http://www.rfc-editor.org/info/rfc4742>.
+
+ [RFC5539] Badra, M., "NETCONF over Transport Layer Security (TLS)",
+ RFC 5539, DOI 10.17487/RFC5539, May 2009,
+ <http://www.rfc-editor.org/info/rfc5539>.
+
+ [RFC6353] Hardaker, W., "Transport Layer Security (TLS) Transport
+ Model for the Simple Network Management Protocol (SNMP)",
+ STD 78, RFC 6353, DOI 10.17487/RFC6353, July 2011,
+ <http://www.rfc-editor.org/info/rfc6353>.
+
+ [RFC7407] Bjorklund, M. and J. Schoenwaelder, "A YANG Data Model for
+ SNMP Configuration", RFC 7407, DOI 10.17487/RFC7407,
+ December 2014, <http://www.rfc-editor.org/info/rfc7407>.
+
+
+
+
+
+
+
+
+
+
+Badra, et al. Standards Track [Page 9]
+
+RFC 7589 NETCONF over TLS June 2015
+
+
+Appendix A. Changes from RFC 5539
+
+ This section summarizes major changes between this document and RFC
+ 5539.
+
+ o Documented that NETCONF over TLS uses the new message framing if
+ both peers support the :base:1.1 capability.
+
+ o Removed redundant text that can be found in the TLS and NETCONF
+ specifications and restructured the text. Alignment with
+ [RFC6125].
+
+ o Added a high-level description on how NETCONF usernames are
+ derived from certificates.
+
+ o Removed the reference to BEEP.
+
+Acknowledgements
+
+ The authors like to acknowledge 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 for their comments on this document.
+
+ Juergen Schoenwaelder was partly funded by Flamingo, a Network of
+ Excellence project (ICT-318488) supported by the European Commission
+ under its Seventh Framework Programme.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Badra, et al. Standards Track [Page 10]
+
+RFC 7589 NETCONF over TLS June 2015
+
+
+Authors' Addresses
+
+ 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/
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Badra, et al. Standards Track [Page 11]
+