idnits 2.17.1 draft-badra-netconf-rfc5539bis-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 9 instances of too long lines in the document, the longest one being 3 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to use 'NOT RECOMMENDED' as an RFC 2119 keyword, but does not include the phrase in its RFC 2119 key words list. -- The document date (February 13, 2012) is 4453 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) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 5539 (Obsoleted by RFC 7589) Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF Working Group M. Badra 3 Internet-Draft DU 4 Obsoletes: 5539 (if approved) February 13, 2012 5 Intended status: Standards Track 6 Expires: August 16, 2012 8 NETCONF Over Transport Layer Security (TLS) 9 draft-badra-netconf-rfc5539bis-01 11 Abstract 13 The Network Configuration Protocol (NETCONF) provides mechanisms to 14 install, manipulate, and delete the configuration of network devices. 15 This document describes how to use the Transport Layer Security (TLS) 16 protocol to secure NETCONF exchanges. This document obsoletes RFC 17 5539. 19 Status of this Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on August 16, 2012. 36 Copyright Notice 38 Copyright (c) 2012 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 1.1. Conventions Used in This Document . . . . . . . . . . . . 3 55 2. NETCONF over TLS . . . . . . . . . . . . . . . . . . . . . . . 3 56 2.1. Connection Initiation . . . . . . . . . . . . . . . . . . 3 57 2.2. Connection Closure . . . . . . . . . . . . . . . . . . . . 4 58 3. Endpoint Authentication, Identification and Authorization . . 5 59 3.1. Server Identity . . . . . . . . . . . . . . . . . . . . . 5 60 3.2. Client Identity . . . . . . . . . . . . . . . . . . . . . 6 61 3.2.1. Deriving NETCONF Usernames From NETCONF Client 62 Certificates . . . . . . . . . . . . . . . . . . . . . 6 63 4. Security Considerations . . . . . . . . . . . . . . . . . . . 16 64 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 65 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 17 66 7. Contributor's Address . . . . . . . . . . . . . . . . . . . . 18 67 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18 68 8.1. Normative References . . . . . . . . . . . . . . . . . . . 18 69 8.2. Informative References . . . . . . . . . . . . . . . . . . 19 70 Appendix A. Change Log (to be removed by RFC Editor before 71 publication) . . . . . . . . . . . . . . . . . . . . 19 72 A.1. From -00 to -01 . . . . . . . . . . . . . . . . . . . . . 19 73 A.2. From RFC5539 to draft-badra-netconf-rfc5539bis-00 . . . . 19 74 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 20 76 1. Introduction 78 The NETCONF protocol [RFC6241] defines a mechanism through which a 79 network device can be managed. NETCONF is connection-oriented, 80 requiring a persistent connection between peers. This connection 81 must provide integrity, confidentiality, peer authentication, and 82 reliable, sequenced data delivery. 84 This document defines "NETCONF over TLS", which includes support for 85 certificate and pre-shared key (PSK)-based authentication and key 86 derivation, utilizing the protected ciphersuite negotiation, mutual 87 authentication, and key management capabilities of the TLS (Transport 88 Layer Security) protocol, described in [RFC5246]. 90 1.1. Conventions Used in This Document 92 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 93 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 94 document are to be interpreted as described in [RFC2119]. 96 2. NETCONF over TLS 98 Since TLS is application-protocol-independent, NETCONF can operate on 99 top of the TLS protocol transparently. This document defines how 100 NETCONF can be used within a TLS session. 102 2.1. Connection Initiation 104 The peer acting as the NETCONF client MUST also act as the TLS 105 client. It MUST connect to the server that passively listens for the 106 incoming TLS connection on the TCP port 6513. It MUST therefore send 107 the TLS ClientHello message to begin the TLS handshake. Once the TLS 108 handshake has finished, the client and the server MAY begin to 109 exchange NETCONF data. In particular, the client will send complete 110 XML documents to the server containing elements, and the server 111 will respond with complete XML documents containing 112 elements. The client MAY indicate interest in receiving event 113 notifications from a server by creating a subscription to receive 114 event notifications [RFC5277]. In this case, the server replies to 115 indicate whether the subscription request was successful and, if it 116 was successful, the server begins sending the event notifications to 117 the client as the events occur within the system. 119 All NETCONF messages MUST be sent as TLS "application data". It is 120 possible that multiple NETCONF messages be contained in one TLS 121 record, or that a NETCONF message be transferred in multiple TLS 122 records. 124 The previous version [RFC5539] of this document used the same framing 125 sequence defined in [RFC6242], under the assumption that it could not 126 be found in well-formed XML documents. However, this assumption is 127 not correct [RFC6242]. In order to solve this problem, and at the 128 same time be compatible with existing implementations, this document 129 uses the framing protocol defined in [RFC6242] as following : 131 The message MUST be followed by the character sequence 132 ]]>]]>. Upon reception of the message, the receiving peer's 133 TLS Transport layer conceptually passes the message to the 134 Messages layer. If the :base:1.1 capability is advertised by both 135 peers, the chunked framing mechanism defined in Section 4.2 of 136 [RFC6242] is used for the remainder of the NETCONF session. 137 Otherwise, the old end-of-message-based mechanism (see Section 4.3 of 138 [RFC6242]) is used. 140 Implementation of the protocol specified in this document MAY 141 implement any TLS cipher suite that provides mutual authentication 142 [RFC5246]. 144 Implementations MUST support TLS 1.2 [RFC5246] and are REQUIRED to 145 support the mandatory-to-implement cipher suite, which is 146 TLS_RSA_WITH_AES_128_CBC_SHA. This document is assumed to apply to 147 future versions of TLS; in which case, the mandatory-to-implement 148 cipher suite for the implemented version MUST be supported. 150 2.2. Connection Closure 152 A TLS client MUST close the associated TLS connection if the 153 connection is not expected to issue any NETCONF RPC commands later. 154 It MUST send a TLS close_notify alert before closing the connection. 155 The TLS client MAY choose to not wait for the TLS server close_notify 156 alert and simply close the connection, thus generating an incomplete 157 close on the TLS server side. Once the TLS server gets a 158 close_notify from the TLS client, it MUST reply with a close_notify 159 unless it becomes aware that the connection has already been closed 160 by the TLS client (e.g., the closure was indicated by TCP). 162 When no data is received from a connection for a long time (where the 163 application decides what "long" means), a NETCONF peer MAY close the 164 connection. The NETCONF peer MUST attempt to initiate an exchange of 165 close_notify alerts with the other NETCONF peer before closing the 166 connection. The close_notify's sender that is unprepared to receive 167 any more data MAY close the connection after sending the close_notify 168 alert, thus generating an incomplete close on the close_notify's 169 receiver side. 171 3. Endpoint Authentication, Identification and Authorization 173 3.1. Server Identity 175 During the TLS negotiation, the client MUST carefully examine the 176 certificate presented by the server to determine if it meets the 177 client's expectations. Particularly, the client MUST check its 178 understanding of the server hostname against the server's identity as 179 presented in the server Certificate message, in order to prevent man- 180 in-the-middle attacks. 182 Matching is performed according to the rules below (following the 183 example of [RFC4642]): 185 o The client MUST use the server hostname it used to open the 186 connection (or the hostname specified in the TLS "server_name" 187 extension [RFC5246]) as the value to compare against the server 188 name as expressed in the server certificate. The client MUST NOT 189 use any form of the server hostname derived from an insecure 190 remote source (e.g., insecure DNS lookup). CNAME canonicalization 191 is not done. 193 o If a subjectAltName extension of type dNSName is present in the 194 certificate, it MUST be used as the source of the server's 195 identity. 197 o Matching is case-insensitive. 199 o A "*" wildcard character MAY be used as the leftmost name 200 component in the certificate. For example, *.example.com would 201 match a.example.com, foo.example.com, etc., but would not match 202 example.com. 204 o If the certificate contains multiple names (e.g., more than one 205 dNSName field), then a match with any one of the fields is 206 considered acceptable. 208 If the match fails, the client MUST either ask for explicit user 209 confirmation or terminate the connection and indicate the server's 210 identity is suspect. 212 Additionally, clients MUST verify the binding between the identity of 213 the servers to which they connect and the public keys presented by 214 those servers. Clients SHOULD implement the algorithm in Section 6 215 of [RFC5280] for general certificate validation, but MAY supplement 216 that algorithm with other validation methods that achieve equivalent 217 levels of verification (such as comparing the server certificate 218 against a local store of already-verified certificates and identity 219 bindings). 221 If the client has external information as to the expected identity of 222 the server, the hostname check MAY be omitted. 224 3.2. Client Identity 226 The server MUST verify the identity of the client to ensure that the 227 incoming client request is legitimate before any configuration or 228 state data is sent to or received from the client. 230 The NETCONF protocol [RFC6241] requires that the transport protocol's 231 authentication process MUST result in an authenticated client 232 identity whose permissions are known to the server. The 233 authenticated identity of a client is commonly referred to as the 234 NETCONF username. 236 The username provided by the TLS implementation will be made 237 available to the NETCONF message layer as the NETCONF username 238 without modification. If the username does not comply to the NETCONF 239 requirements on usernames [RFC6241], i.e., the username is not 240 representable in XML, the TLS session MUST be dropped. 242 Algorithms for mapping certificates or PSK identities (sent by the 243 client) to NETCONF usernames are described below. 245 3.2.1. Deriving NETCONF Usernames From NETCONF Client Certificates 247 The algorithm for deriving NETCONF usernames from TLS certificates is 248 patterned after the algorithm for deriving tmSecurityNames from TLS 249 certificates specified in Transport Layer Security (TLS) Transport 250 Model for the Simple Network Management Protocol (SNMP) [RFC6353]. 251 The NETCONF server MUST implement the algorithms for deriving NETCONF 252 usernames from presented certificates that are documented in the 253 ietf-netconf-tls YANG module. This YANG module lets the NETCONF 254 security administrator configure how the NETCONF server derives 255 NETCONF usernames from presented certificates. It also lets 256 different certificate-to-username derivation algorithms be used for 257 different certificates. 259 When a NETCONF server accepts a TLS connection from a NETCONF client, 260 the NETCONF server attempts to derive a NETCONF username from the 261 certificate presented by the NETCONF client. If the NETCONF server 262 cannot derive a valid NETCONF username from the client's presented 263 certificate, then the NETCONF server MUST close the TLS connection, 264 and MUST NOT accept NETCONF messages over it. The NETCONF server MAY 265 use any of the following algorithms to produce the NETCONF username 266 from the certificate presented by the NETCONF client: 268 o Map a certificate directly to a specified, pre-configured, NETCONF 269 username; 271 o Extract the subjectAltName's rfc822Name from the certificate, then 272 use the extracted rfc822Name as the NETCONF username; 274 o Extract the subjectAltName's dnsName from the certificate, then 275 use the extracted dnsName as the NETCONF username; 277 o Extract the subjectAltName's iPAddress from the certificate, then 278 use the extracted iPAddress as the NETCONF username; 280 o Examine the subjectAltName's rfc822Name, dnsName, and iPAddress 281 fields in a pre-defined order. Return the value from the first 282 subjectAltName field that is examined, defined, and populated with 283 a non-empty value. If no subjectAltName field of a specific type 284 is defined, then the examination skips that field and proceeds to 285 examine the next field type. If a subjectAltName field is 286 defined, but the value is not populated, or is populated by an 287 empty value, then the examination skips that field and proceeds to 288 examine the next field type. 290 The NETCONF server MUST implement all of these algorithms, and allow 291 the deployer to choose the algorithm used. The certificate-to- 292 username-transforms container in the ietf-netconf-tls YANG module 293 specifies how a NETCONF server transforms a certificate into a 294 NETCONF username. 296 3.2.1.1. Identifying a Certificate 298 A client certificate has an identity: the certificate. The TLS and 299 corresponding protocols provide an identity. The identity shows that 300 "this client certificate has shown that it, indeed, is on the other 301 side of the connection". With a complete certificate, the 302 certificate receiver can be certain that for someone or something on 303 the other side to use that certificate successfully, it has the 304 associated private key. 306 The problem with using the entire certificates as the identity is 307 that they are difficult for people to use. It is generally accepted 308 that a fingerprint of a certificate is not likely to come up with a 309 collision against a fingerprint of another (different) certificate. 310 Thus, assuming a good hash algorithm, a fingerprint can be a safe 311 short-hand for identifying a certificate. 313 If a locally held copy of a trusted CA certificate is configured in 314 the transformation container, and that CA certificate was used to 315 validate the path to the presented certificate, then the NETCONF 316 server SHOULD use that list entry in the transformation container. 317 All presented certificates validated by the configured CA certificate 318 will be transformed to NETCONF usernames using the same 319 transformation algorithm. 321 3.2.1.2. Deriving NETCONF Usernames From PSK identities 323 Implementations MAY optionally support TLS Pre-Shared Key (PSK) 324 authentication [RFC4279]. RFC4279 describes pre-shared key 325 ciphersuites for TLS. During the TLS Handshake, the client indicates 326 which key to use by including a "PSK identity" in the TLS 327 ClientKeyExchange message [RFC4279]. On the server side, this PSK 328 identity is used to look up the key corresponding to the presented 329 PSK identity. If the selected pre-shared keys match and the key is 330 valid, then the client is authenticated and the NETCONF username 331 associated with the PSK identity. For details on how the PSK 332 identity MAY be encoded in UTF-8, see section 5.1. of RFC [RFC6241]. 334 3.2.1.3. Remote Configuration 336 The ietf-netconf-tls YANG module defines objects for remotely 337 configuring the mapping of TLS certficates and of PSK Identities to 338 NETCONF usernames. 340 module ietf-netconf-tls { 342 namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-tls"; 344 prefix "nctls"; 346 import ietf-yang-types { 347 prefix yang; 348 } 350 organization 351 "IETF NETCONF (Network Configuration) Working Group"; 353 contact 354 "WG Web: 355 WG List: 357 WG Chair: Mehmet Ersue 358 360 WG Chair: Bert Wijnen 361 363 Editor: Mohamad Badra 364 "; 366 description 367 "This module applies to NETCONF over TLS. It specifies how 368 NETCONF servers transform X.509 certificates presented by 369 clients into NETCONF usernames. It also specifies how NETCONF 370 clients transform NETCONF usernames into X.509 certificates 371 for presentation to NETCONF servers. 373 This YANG module is patterned after, and closely models, parts of 374 the SNMP-TLS-TM-MIB defined in RFC 6353. Much of the description 375 text has been copied directly from the SNMP-TLS-TM-MIB, and modified 376 as necessary. 378 Copyright (c) 2012 IETF Trust and the persons identified as 379 authors of the code. All rights reserved. 381 Redistribution and use in source and binary forms, with or 382 without modification, is permitted pursuant to, and subject 383 to the license terms contained in, the Simplified BSD 384 License set forth in Section 4.c of the IETF Trust's 385 Legal Provisions Relating to IETF Documents 386 (http://trustee.ietf.org/license-info). 388 This version of this YANG module is part of RFC XXXX; see 389 the RFC itself for full legal notices."; 390 // RFC Ed.: replace XXXX with actual RFC number and 391 // remove this note 393 // RFC Ed.: please update the date to the date of publication 395 revision "2012-02-13" { 396 description 397 "Initial version"; 398 reference 399 "RFC XXXX: NETCONF over Transport Layer Security (TLS)"; 400 } 402 typedef tls-fingerprint-type { 403 type binary { 404 length "0..255"; 405 } 406 description 407 "A fingerprint value that can be used to uniquely reference 408 other data of potentially arbitrary length. 410 An tls-fingerprint-type value is composed of a 1-octet hashing 411 algorithm identifier followed by the fingerprint value. The 412 octet value encoded is taken from the IANA TLS HashAlgorithm 413 Registry (RFC 5246). The remaining octets are filled using the 414 results of the hashing algorithm. 416 This typedef allows for a zero-length (blank) tls-fingerprint-type 417 value for use in containers where the fingerprint value MAY be 418 optional. YANG definitions or implementations MAY refuse to 419 accept a zero-length value as appropriate."; 420 } 422 // 423 // Objects related to deriving NETCONF usernames from X.509 certificates. 424 // 425 leaf certificate-to-username-transform-count { 426 type yang:gauge32; 427 description 428 "A count of the number of certificate-to-username-transforms."; 429 config false; 430 } 432 leaf certificate-to-username-transform-last-changed { 433 type yang:date-and-time; 434 description 435 "The date and time when the certificate-to-username-transforms 436 was last modified through any means. The value 0 means the 437 certificate-to-username-transforms has not been modified since 438 the NETCONF server was started."; 439 config false; 440 } 442 container certificate-to-username-transforms { 443 config true; 444 description 445 "This container is used by a NETCONF server to map the NETCONF 446 client's presented X.509 certificate to a NETCONF username. 448 On an incoming TLS connection, the client's presented 449 certificate MUST either be validated based on an established 450 trust anchor, or it MUST directly match a fingerprint in this 451 container. This container does not provide any mechanisms for 452 configuring the trust anchors; the transfer of any needed 453 trusted certificates for path validation is expected to occur 454 through an out-of-band transfer. 456 Once the certificate has been found acceptable (either by path 457 validation or directly matching a fingerprint in this container), 458 this container is consulted to determine the appropriate 459 NETCONF username to associate with the remote connection. This 460 is done by considering each active list entry from this container 461 in prioritized order according to its index value. 462 Each list entry's certificate-fingerprint value determines 463 whether the list entry is a match for the incoming connection: 465 1) If the list entry's certificate-fingerprint value 466 matches that of the presented certificate, then consider 467 the list entry as a successful match. 469 2) If the list entry's certificate-fingerprint value 470 matches that of a locally held copy of a trusted CA 471 certificate, and that CA certificate was used to 472 validate the path to the presented certificate, then 473 consider the list entry as a successful match. 475 This feature lets the NETCONF server derive NETCONF 476 usernames from all certificates signed by the trusted 477 CA certificate. The NETCONF server will derive all 478 NETCONF usernames using the same derivation algorithm. 479 The NETCONF server requires only a single container 480 entry to configure this behavior. 482 Once a matching list entry has been found, the NETCONF server uses 483 the map-type value to determine how the NETCONF username 484 associated with the session should be determined. See the map- 485 type leaf's description for details on determining the NETCONF 486 username value. If it is impossible to determine a NETCONF 487 username from the list entry's data combined with the data 488 presented in the certificate, then additional list entries MUST be 489 searched looking for another potential match. If a resulting 490 NETCONF username mapped from a given list entry is not compatible 491 with the needed requirements of a NETCONF username, then it MUST 492 be considered an invalid match and additional list entries MUST be 493 searched looking for another potential match. 495 If no matching and valid list entry can be found, then the NETCONF 496 server MUST close the connection, and MUST NOT accept NETCONF 497 messages over it. 499 Non-consecutive values of index are acceptable and implementations 500 should continue to the next highest numbered list entry. It is 501 recommended that administrators skip index values to leave room 502 for the insertion of future list entries (for example, use values 503 of 10 and 20 when creating initial list entries). 504 Security administrators are encouraged to make use of certificates 505 with subjectAltName fields that can be used as NETCONF usernames 506 so that a single root CA certificate can allow all child 507 certificate's subjectAltName to map directly to a NETCONF 508 usernames via a 1:1 transformation. However, this container is 509 flexible to allow for situations where existing deployed 510 certificate infrastructures do not provide adequate subjectAltName 511 values for use as NETCONF usernames."; 513 // Certificates MAY also be mapped to NETCONF usernames using the 514 // CommonName portion of the Subject field. However, the usage 515 // of the CommonName field is deprecated and thus this usage is 516 // NOT RECOMMENDED. Direct mapping from each individual 517 // certificate fingerprint to a NETCONF username is also possible 518 // but requires one entry in the container per NETCONF username and 519 // requires more management operations to completely configure a 520 // device."; 522 list certificate-to-username-transform { 523 key "index"; 524 description 525 "A single list entry that specifies a mapping for an incoming 526 TLS certificate to a NETCONF username."; 528 leaf index { 529 type uint32 { 530 range "1..4294967295"; 531 } 532 description 533 "A unique, prioritized index for the given entry. Lower 534 numbers indicate a higher priority."; 535 } 537 leaf certificate-fingerprint { 538 type tls-fingerprint-type { 539 length "1..255"; 540 } 541 description 542 "A cryptographic hash of a X.509 certificate. The results of 543 a successful matching fingerprint to either the trusted CA in 544 the certificate validation path or to the certificate itself 545 is dictated by the map-type leaf."; 546 } 548 leaf map-type { 549 type enumeration { 550 enum specified { value 1; } 551 enum rfc822Name { value 2; } 552 enum dnsName { value 3; } 553 enum ipAddress { value 4; } 554 enum rfc822Name-dnsName-ipAddress { value 5; } 555 enum rfc822Name-ipAddress-dnsName { value 6; } 556 enum dnsName-ipAddress-rfc822Name { value 7; } 557 enum dnsName-rfc822Name-ipAddress { value 8; } 558 enum ipAddress-dnsName-rfc822Name { value 9; } 559 enum ipAddress-rfc822Name-dnsName { value 10; } 560 } 562 description 563 "Specifies the algorithm for deriving a NETCONF username from 564 a certificate. If a mapping succeeds, then it will return a 565 NETCONF username. 567 If the resulting mapped value is not compatible with the needed 568 requirements of a NETCONF username, then future list entries MUST 569 be searched for additional NETCONF username matches to look for a 570 mapping that succeeds. 572 For each enumerated value listed above, the NETCONF server 573 derives the NETCONF from the presented client certificate 574 as described: 576 specified 578 Directly specifies the NETCONF username to be used for 579 this certificate. The value of the NETCONF username 580 to use is specified in the data leaf of the list. The 581 data leaf MUST contain a non-zero length value or the 582 mapping described in this list entry MUST be considered a 583 failure. 585 rfc822Name 587 Maps a subjectAltName's rfc822Name to a NETCONF username. 588 The local part of the rfc822Name is passed unaltered but 589 the host-part of the name MUST be passed in lowercase. 590 This mapping results in a 1:1 correspondence between 591 equivalent subjectAltName rfc822Name values and NETCONF 592 username values except that the host-part of the name 593 MUST be passed in lowercase. 595 Example rfc822Name Field: FooBar@Example.COM 596 is mapped to NETCONF username: FooBar@example.com. 598 dnsName 600 Maps a subjectAltName's dNSName to a NETCONF username after 601 first converting it to all lowercase (RFC 5280 does not 602 specify converting to lowercase so this involves an extra 603 step). This mapping results in a 1:1 correspondence between 604 subjectAltName dNSName values and the NETCONF username values. 606 reference: RFC 5280 - Internet X.509 Public Key Infrastructure 607 Certificate and Certificate Revocation 608 List (CRL) Profile. 610 ipAddress 612 Maps a subjectAltName's iPAddress to a NETCONF username by 613 transforming the binary encoded address as follows: 615 1) for IPv4, the value is converted into a 616 decimal-dotted quad address (e.g., '192.0.2.1'). 618 2) for IPv6 addresses, the value is converted into a 619 32-character all lowercase hexadecimal string 620 without any colon separators. 622 This mapping results in a 1:1 correspondence between 623 subjectAltName iPAddress values and the NETCONF username 624 values. 626 rfc822Name-dnsName-ipAddress 627 rfc822Name-ipAddress-dnsName 628 dnsName-ipAddress-rfc822Name 629 dnsName-rfc822Name-ipAddress 630 ipAddress-dnsName-rfc822Name 631 ipAddress-rfc822Name-dnsName 633 For each of these enumerations, the NETCONF server derives the 634 NETCONF username in a similar manner. The NETCONF server 635 derives the NETCONF username from the subjectAltName fields 636 rfc822Name, dnsName, and ipAddress, as described in sections 637 above. However, each of these subjectAltName fields is 638 examined in the order specified by the enumeration name. 639 The first matching subjectAltName value found in the certificate 640 MUST be used when deriving the NETCONF username. 642 For example, the rfc822Name-dnsName-ipAddress enumeration 643 specifies the NETCONF server first examines the rfc822Name, 644 then examines the dnsName, then finally examines the ipAddress. 645 In contrast, the ipAddress-rfc822Name-dnsName enumeration 646 specifies the NETCONF server first examines the ipAddress 647 name, then examines the rfc822Name, then finally examines 648 the dnsName. 650 These mappings result in a 1:1 correspondence between 651 subjectAltName values and NETCONF username values. The 652 sub-mapping algorithms produced by these combined algorithms 653 cannot produce conflicting results between themselves."; 654 } // leaf map-type 656 leaf data { 657 type string { 658 length "1..max"; 659 } 660 description 661 "Auxiliary data used as optional configuration information for 662 a given mapping specified by the map-type leaf. Only some 663 mapping systems will make use of this leaf. When the NETCONF 664 server derives the NETCONF username from the client's presented 665 certificate, the value in this leaf MUST be ignored for any 666 mapping type that does not require data present in this leaf."; 667 } 668 } // list certificate-to-username-transform 669 } // container certificate-to-username-transform 671 container psk-map { 672 list psk { 673 key psk-identity; 675 leaf psk-identity { 676 type string; 677 description 678 "The PSK identity encoded as a UTF-8 string."; 679 reference 680 "RFC 4279: Pre-Shared Key Ciphersuites for Transport Layer 681 Security (TLS)"; 682 } 684 leaf user-name { 685 type nacm:user-name-type; 686 mandatory true; 687 description 688 "The NETCONF username associated with this PSK identity."; 689 } 691 leaf valid-not-before { 692 type yang:date-and-time; 693 description 694 "This PSK identity is not valid before the given data 695 and time."; 696 } 697 leaf valid-not-after { 698 type yang:date-and-time; 699 description 700 "This PSK identity is not valid before the given data 701 and time."; 702 } 704 leaf key { 705 type binary; 706 nacm:default-deny-all; 707 description 708 "The key associated with the PSK identity"; 709 } 710 } 711 } // container psk-identity-to-username-transform 712 } 714 4. Security Considerations 716 The security considerations described throughout [RFC5246] and 717 [RFC6241] apply here as well. 719 This document in its current version does not support third-party 720 authentication (e.g., backend Authentication, Authorization, and 721 Accounting (AAA) servers) due to the fact that TLS does not specify 722 this way of authentication and that NETCONF depends on the transport 723 protocol for the authentication service. If third-party 724 authentication is needed, BEEP or SSH transport can be used. 726 An attacker might be able to inject arbitrary NETCONF messages via 727 some application that does not carefully check exchanged messages. 728 When the :base:1.1 capability is not advertised by both peers, an 729 attacker might be able to deliberately insert the delimiter sequence 730 ]]>]]> in a NETCONF message to create a DoS attack. If the :base:1.1 731 capability is not advertised by both peers, applications and NETCONF 732 APIs MUST ensure that the delimiter sequence ]]>]]> never appears in 733 NETCONF messages; otherwise, those messages can be dropped, garbled, 734 or misinterpreted. More specifically, if the delimiter sequence is 735 found in a NETCONF message by the sender side, a robust 736 implementation of this document SHOULD warn the user that illegal 737 characters have been discovered. If the delimiter sequence is found 738 in a NETCONF message by the receiver side (including any XML 739 attribute values, XML comments, or processing instructions), a robust 740 implementation of this document MUST silently discard the message 741 without further processing and then stop the NETCONF session. 743 Finally, this document does not introduce any new security 744 considerations compared to [RFC6242]. 746 5. IANA Considerations 748 Based on the previous version of this document, RFC 5539, IANA has 749 assigned a TCP port number (6513) in the "Registered Port Numbers" 750 range with the name "netconf-tls". This port will be the default 751 port for NETCONF over TLS, as defined in this document. 753 Registration Contact: Mohamad Badra, mbadra@gmail.com. 754 Transport Protocol: TCP. 755 Port Number: 6513 756 Broadcast, Multicast or Anycast: No. 757 Port Name: netconf-tls. 758 Service Name: netconf. 759 Reference: RFC 5539 761 6. Acknowledgements 763 A significant amount of the text in Section 3 was lifted from 764 [RFC4642]. 766 The author would like to acknowledge David Harrington, Miao Fuyou, 767 Eric Rescorla, Juergen Schoenwaelder, Simon Josefsson, Olivier 768 Coupelon, Alfred Hoenes, and the NETCONF mailing list members for 769 their comments on the document. The author also appreciates Bert 770 Wijnen, Mehmet Ersue, and Dan Romascanu for their efforts on issues 771 resolving discussion; and Charlie Kaufman, Pasi Eronen, and Tim Polk 772 for the thorough review of previous versions of this document. 774 7. Contributor's Address 776 Ibrahim Hajjeh 777 Ineovation 778 France 780 EMail: ibrahim.hajjeh@ineovation.fr 782 Alan Luchuk 783 SNMP Research, Inc. 784 3001 Kimberlin Heights Road 785 Knoxville, TN 37920-9716 787 EMail: luchuk@snmp.com 789 Juergen Schoenwaelder 790 Jacobs University Bremen 791 Campus Ring 1 792 28725 Bremen 793 Germany 795 EMail: j.schoenwaelder@jacobs-university.de 797 8. References 799 8.1. Normative References 801 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 802 Requirement Levels", BCP 14, RFC 2119, March 1997. 804 [RFC4279] Eronen, P. and H. Tschofenig, "Pre-Shared Key Ciphersuites 805 for Transport Layer Security (TLS)", RFC 4279, 806 December 2005. 808 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 809 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 811 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 812 Housley, R., and W. Polk, "Internet X.509 Public Key 813 Infrastructure Certificate and Certificate Revocation List 814 (CRL) Profile", RFC 5280, May 2008. 816 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 817 Shell (SSH)", RFC 6242, June 2011. 819 [RFC6353] Hardaker, W., "Transport Layer Security (TLS) Transport 820 Model for the Simple Network Management Protocol (SNMP)", 821 RFC 6353, July 2011. 823 8.2. Informative References 825 [RFC4642] Murchison, K., Vinocur, J., and C. Newman, "Using 826 Transport Layer Security (TLS) with Network News Transfer 827 Protocol (NNTP)", RFC 4642, October 2006. 829 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 830 Notifications", RFC 5277, July 2008. 832 [RFC5539] Badra, M., "NETCONF over Transport Layer Security (TLS)", 833 RFC 5539, May 2009. 835 [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 836 Bierman, "Network Configuration Protocol (NETCONF)", 837 RFC 6241, June 2011. 839 Appendix A. Change Log (to be removed by RFC Editor before publication) 841 A.1. From -00 to -01 843 o Move RFC5539 to informative references and remove RFC4742. 845 o Shorten the YANG object names; 847 o Extend the YANG module to support configuration of PSK; 849 A.2. From RFC5539 to draft-badra-netconf-rfc5539bis-00 851 o Added text on how the generation of a NETCONF username is done. 853 o Added text on how does this document fulfill the requirements in 854 6241 for the format of the username. 856 o Removed unneeded wording about client/server, and changed use of 857 client/server, manager/agent to SSH client/server and NETCONF 858 client/server. 860 o Added text to Security Considerations about EOM issues. 862 o Added option for the chunked encoding described in RFC6242. 864 o Added 1.1 capability to enable the chunked encoding described in 865 RFC6242. 867 Author's Address 869 Mohamad Badra 870 Dhofar University 872 Email: mbadra@gmail.com