idnits 2.17.1 draft-winter-opsec-netconfig-metadata-00.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 18, 2016) is 2961 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) == Unused Reference: 'RFC7593' is defined on line 880, but no explicit reference was found in the text == Unused Reference: 'HS20' is defined on line 885, but no explicit reference was found in the text -- Obsolete informational reference (is this intentional?): RFC 6982 (Obsoleted by RFC 7942) Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OPSEC Working Group S. Winter 3 Internet-Draft RESTENA 4 Intended status: Standards Track March 18, 2016 5 Expires: September 19, 2016 7 A Configuration File Format for Network Services on Leaf Devices 8 draft-winter-opsec-netconfig-metadata-00 10 Abstract 12 This document specifies a YANG module for transfering configuration 13 information of deployments of network services towards leaf nodes 14 (hosts) on the internet. Such configuration files are meant to be 15 discovered, consumed and used by configuration agents on the host to 16 achieve correct and secure setup of these services on the consuming 17 device. This iteration of the I-D concentrates on Wi-Fi network 18 setup and EAP credentials, but is extensible to cover a wide range 19 including VPN, E-Mail and other services. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on September 19, 2016. 38 Copyright Notice 40 Copyright (c) 2016 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 1.1. Problem Statement . . . . . . . . . . . . . . . . . . . . 2 54 1.2. Approach . . . . . . . . . . . . . . . . . . . . . . . . 3 55 1.3. Other Approaches . . . . . . . . . . . . . . . . . . . . 4 56 1.4. Requirements Language . . . . . . . . . . . . . . . . . . 5 57 1.5. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 58 2. YANG module for Network Service Configuration . . . . . . . . 5 59 2.1. Location of the YANG module and derived XML Schema . . . 5 60 2.2. Description of YANG Module Elements . . . . . . . . . . . 5 61 2.2.1. Overall structure . . . . . . . . . . . . . . . . . . 5 62 2.2.2. The 'AuthenticationMethods' container . . . . . . . . 7 63 2.2.3. The 'ProviderInfo' container . . . . . . . . . . . . 10 64 2.3. Internationalisation / Multi-language support . . . . . . 11 65 3. Derivation of formats from YANG source . . . . . . . . . . . 12 66 4. Issuer Authentication, Integrity Protection and Encryption of 67 EAP Metadata configuration files . . . . . . . . . . . . . . 12 68 5. XML Farget Format: File Discovery . . . . . . . . . . . . . . 12 69 5.1. By MIME-Type: application/netconfig-metadata-xml . . . . 12 70 5.2. By filename extension: .netconfig-metadata-xml . . . . . 12 71 5.3. By network location: SCAD . . . . . . . . . . . . . . . . 13 72 6. JSON Farget Format: File Discovery . . . . . . . . . . . . . 13 73 6.1. By MIME-Type: application/netconfig-metadata-json . . . . 13 74 6.2. By filename extension: .netconfig-metadata-json . . . . . 13 75 6.3. By network location: SCAD . . . . . . . . . . . . . . . . 13 76 7. Design Decisions . . . . . . . . . . . . . . . . . . . . . . 13 77 7.1. Why YANG and not directly XML, JSON or $FOO? . . . . . . 13 78 7.2. Shallow vs. Deep definition of EAP method properties . . 14 79 7.3. EAP tunneling inside EAP tunnels . . . . . . . . . . . . 14 80 7.4. Placement of 'OuterIdentity' inside 81 'AuthenticationMethod' . . . . . . . . . . . . . . . . . 14 82 8. Implementation Status . . . . . . . . . . . . . . . . . . . . 14 83 9. Security Considerations . . . . . . . . . . . . . . . . . . . 17 84 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 85 11. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 18 86 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 87 12.1. Normative References . . . . . . . . . . . . . . . . . . 18 88 12.2. Informative References . . . . . . . . . . . . . . . . . 19 89 Appendix A. Appendix A: MIME Type Registration Template . . . . 20 91 1. Introduction 93 1.1. Problem Statement 95 The IETF produces many protocols which require configuration by the 96 respective end users. Many of those protocols can be configured 97 securely or not, depending on whether features are turned on or off. 99 One random example is E-Mail: "STARTTLS when available" allows MITM 100 attacks towards plaintext; "STARTTLS always" prevents them. Another 101 example is the Extensible Authentication Protocol (EAP, [RFC3748]) 102 and its numerous EAP methods (for example EAP-TTLS [RFC5281], EAP-TLS 103 [RFC5216] and EAP-pwd [RFC5931]); the methods have many properties 104 which need to be setup on the EAP server and matched as configuration 105 items on the EAP peer for a secure EAP deployment. 107 Setting up these protocols and services is comparatively easy if the 108 end-user devices which are to be configured are under central 109 administrative control, e.g. in closed enterprise environments. 110 Group policies or device provisioning by the IT department can push 111 the settings to user devices. 113 In other environments, for example "BYOD" scenarios where users bring 114 their own devices which are not under enterprise control, service 115 configuration is significantly harder as it has to be done by 116 potentially very non-technical end users. 118 In the case of Wi-Fi and EAP, correct configuration of all EAP 119 deployment parameters is required to make the resulting 120 authentications 122 o functional (i.e. the end user can authenticate to an EAP server at 123 all) 125 o secure (i.e. the end user device can unambiguously authenticate 126 the EAP server prior to releasing any sensitive client-side 127 credentials) 129 o privacy-preserving (i.e. the end user is able to conceal his 130 username from the EAP authenticator) 132 It would be desirable to be able to convey the configuration 133 information of a deployment in a machine parseable way to the end- 134 user device, so that all the details need not be known/understood by 135 the user. Instead, the configuration agent on the device could 136 consume the configuration information and set up all details 137 automatically. 139 However, there is currently no standard way of communicating 140 configuration parameters to devices. 142 1.2. Approach 144 This specification defines such a file format for network service 145 configuration metadata. The source definition is a YANG module which 146 allows for automatic derivation of XML and JSON formats. 148 The specification contains several top-level elements which form the 149 building blocks of service configuration: 151 o a "Certificates" section which can contain trust roots, 152 intermediate CA certificates, and client certificates. 154 o a "ClientSideCredentials" section which contains a list of 155 credentials which are valid for one or more services, possibly 156 referencing a client certificate 158 o a "EAPIdentityProviderList" section with a collection of EAP 159 method details, possibly referencing certificates and 160 ClientSideCredentials as defined above 162 o a "IPSettingsList" with network configuration items needed to use 163 a network after the authentication 165 o one or more "WiFiNetwork" blocks which specify layer 2 details of 166 a Wi-Fi connection, referencing IPSettings and possibly 167 EAPIdentityProvider if the network is secured with EAP 169 o exactly one "ProviderInfo" block with user-displayable information 170 about the entity that provides this configuration file 172 The specification allows for unique identification of all elements by 173 attaching a UUID to each setting. Using this unique identification, 174 all parts of the configuration file can then refer to this particular 175 piece of information. In particular, several different Wi-Fi 176 networks can reference the same EAPIdentityProvider (and thus the 177 same ClientSideCredential) to indicate that the same authentication 178 settings are valid on all the networks. Configuration agents 179 consuming the file can then ask for the corresponding client-side 180 password once and apply it to all configuration blocks referencing 181 that credential. When considering a hypothetical setup of three Wi- 182 Fi networks, a VPN connection and an E-Mail account which all use the 183 same username and password, all of those can be installed by asking 184 the user for that username/password combination only once. 186 1.3. Other Approaches 188 Device manufacturers sometimes have developed their own proprietary 189 configuration formats, examples include Apple's "mobileconfig" (MIME 190 type application/x-apple-aspen-config), Microsoft's XML schemata for 191 EAP methods for use with the command-line "netsh" tool, or Intel's 192 "PRO/Set Wireless" binary configuration files. The multitude of 193 proprietary file formats and their different levels of richness in 194 expression of EAP details create a very heterogenous and non- 195 interoperable landscape. 197 All of the solutions have their own excentricities or drawbacks. The 198 Microsoft and Intel file formats are limited to Wi-Fi purposes. The 199 Apple mobileconfig approach treats each service as distinct; the same 200 hypothetical situation from the previous paragraph would trigger a 201 username/password prompt five times consecutively during the 202 installation which is rather annoying for end users. 204 New devices which would like to benefit from machine-parseable 205 configuration information currently either have to choose to follow a 206 competitor's approach and use that competitor's file format or have 207 to develop their own. This situation is very unsatisfactory. 209 1.4. Requirements Language 211 In this document, several words are used to signify the requirements 212 of the specification. The key words "MUST", "MUST NOT", "REQUIRED", 213 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 214 and "OPTIONAL" in this document are to be interpreted as described in 215 RFC 2119. [RFC2119] 217 1.5. Terminology 219 2. YANG module for Network Service Configuration 221 2.1. Location of the YANG module and derived XML Schema 223 The schema files are currently hosted on this location: 225 o YANG module: https://www.supplicants.net/site/standardisation/ 226 ietf-winter-netconfig-metadata-00 228 o XML Schema: https://www.supplicants.net/site/standardisation/ietf- 229 winter-netconfig-metadata-00.xsd 231 2.2. Description of YANG Module Elements 233 2.2.1. Overall structure 235 The root of the Yang module is the container 'NetworkConfiguration', 236 which contains any of the five elements Certificates, 237 ClientSideCredentials, EAPIdentityProviderList, IPSettingsList, 238 WiFiNetwork, ProviderInfo. These blocks carry the actual 239 configuration information. Individual configuration elements are 240 linked among each other to allow for re-use of the elements: a root 241 CA certificate can be the trust root for multiple purposes; a client 242 credential can be valid for multiple services. 244 Each linkable element is unique in the sense that it is identified by 245 a UUID value which is required to be unique across the file. These 246 linkable elements ("building blocks") are: 248 o zero or more Certificate. A Certificate contains the actual blob 249 of the certificate, an indicator what the type of the certificate 250 is, and a display name to present in end user UI. 252 o zero or more ClientSideCredential. Besides the core information - 253 the ability to store username and password, or link to a client 254 certificate, it contains some meta information such as: 256 * a 'ValidUntil' date-and-time timestamp with an indication of 257 possible expiry of the information in the configuration file. 258 Configuration agents importing the configuration file can use 259 this information for example to re-assess whether the account 260 is still valid (e.g. if the ValidUntil timestamp has passed, 261 and authentication attempts consistently fail, the supplicant 262 should consider the information stale and ask the user to 263 verify his access authorisation with the identity provider). 264 Typical use case: student account which expires at end of 265 semester and needs to be reinstated. 267 * whether or not the system is allowed to save passwords when 268 they are supplied by the user (allow-save) 270 * the format requirements on the username, if there are any (e.g. 271 to enforce that users enter their username as a full NAI realm 272 in the form user@suffix or as an AD domain identifier 273 DOMAIN\user ) 275 Consumers of configuration files MUST be able to fall back to 276 user-interactive configuration for these parts if they are not 277 specified (e.g. ask for the username and password during import of 278 the configuration data). Configuration files which contain 279 sensitive elements such as 'Password' MUST be handled with due 280 care after the import on the device (e.g. ensure minimal file 281 permissions, or delete the source file after installing). 283 o zero or more EAPIdentityProvider containers with a list of EAP 284 authentication details for services requiring EAP Authentication. 285 The contents of this container are described in more detail in 286 section Section 2.2.2 288 o exactly one 'ProviderInfo' container can provide additional 289 information about the supplier of the configuration file, e.g. a 290 logo to allow visual identification of the provider to the user in 291 a user interface, or Acceptable Use Policies pertaining to the use 292 of the configured services. This element is described in more 293 detail in section Section 2.2.3 295 o zero or more IPSettings. This block describes details on how to 296 access the wider internet after authentication has completed. It 297 includes ways to get an IP address (DHCP, SLAAC, manual) and proxy 298 settings. 300 o zero or more WiFiNetwork. This block describes Wi-Fi specific 301 properties of a network and references IPSettings for layer 3, and 302 possibly an EAPIdentityProvider for EAP authentication. 304 2.2.2. The 'AuthenticationMethods' container 306 'AuthenticationMethods' contains a sequence of 'AuthenticationMethod' 307 groupings. Each such grouping specifies the properties of one 308 supported authentication method of an EAPIdentityProvider. The 309 content of this grouping is enumerated in section Section 2.2.2.1 The 310 set of configuration parameters specified in the grouping depends on 311 the particular EAP method to be configured. 313 For instance, EAP-PWD [RFC5931] does not require any server 314 certificate parameters; EAP-FAST and TEAP are the only ones making 315 use of Protected Access Credential (PAC) provisioning. On the other 316 hand, properties such as outer ("anonymous") identity or the need for 317 a trusted root Certification Authority are common to several EAP 318 methods. The server- and client-side credential types of EAP methods 319 are defined as a flat list of elements to choose from (see 320 'ServerSideCredential' and 'EAPClientSideCredential' below); see 321 section Section 7.2 for a rationale. 323 Where the sequence of 'AuthenticationMethod' groupings contains more 324 than one element, the order of appearance in the file indicates the 325 server operator's preference for the supported EAP types; occurences 326 earlier in the file indicate a more preferred authentication method. 328 When a consuming device receives multiple 'AuthenticationMethod' 329 groupings inside 'AuthenticationMethods', it should attempt to 330 install more preferred methods first. During interactive 331 provisioning of EAP properties, if the configuration information for 332 a preferred method is insufficient (e.g. the 'AuthenticationMethod' 333 is EAP-TLS, but the configuration file does not contain the client 334 certificate/private key and the device's credential store is not pre- 335 loaded with the client's certificate), the device should query 336 whether this more preferred method should be used (requiring the user 337 to supplement the missing data) or whether a less-preferred method 338 should be configured instead. In non-interactive provisioning 339 scenarios, all methods should be tried non-interactively in order 340 until one method can be installed; if no method can be installed in a 341 fully automated way, provisioning is aborted. 343 2.2.2.1. Authentication Method Properties 345 The 'AuthenticationMethod' grouping contains 347 o exactly one 'EAPMethod' leaf, which is an enumerated integer of 348 the EAP method identifier as assigned by IANA (typedef eap-method) 350 o zero or one container 'ServerSideCredential' which defines means 351 to authenticate the EAP server to the EAP peer (for a list of the 352 elements comprising this container, see section Section 2.2.2.2) 354 o zero or one container 'EAPClientSideCredential' which defines 355 means to authenticate the EAP peer to the EAP server (for a list 356 of the elements comprising this container, see section 357 Section 2.2.2.3) 359 o zero or more 'InnerAuthenticationMethod' lists. Occurence of this 360 list indicates that a tunneled EAP method is in use, and that 361 further server-side and/or client-side credentials are defined 362 inside the tunnel. The presence of more than one 363 'InnerAuthenticationMethod' indicates that EAP Method Chaining is 364 in use, i.e. that several inner EAP methods are to be executed in 365 sequence inside the tunnel. The order of occurence of the inner 366 EAP methods defines the chaining order of the methods. 368 The 'InnerAuthenticationMethod' list itself contains the same 369 'EAPMethod', 'ServerSideCredentials' and 'EAPClientSideCredentials' 370 elements as described in the preceding list, but differs in two 371 points: 373 o It can optionally contain the leaf 'NonEAPAuthMethod' (an 374 enumerated integer of authentication methods not based on EAP) 375 instead of 'EAPMethod' because some tunneled EAP types do not 376 necessarily contain EAP inside the tunnel (e.g. TTLS-PAP, TEAP). 377 The YANG definition ensures that EAPMethod and NonEAPAuthMethod 378 are mutually exclusive in instantiations of the YANG module. 380 o It can NOT contain a further 'InnerAuthenticationMethod' because 381 establishing a secure tunnel inside an already established secure 382 tunnel is considered a pathological case which needs not be 383 considered. See section Section 7.3 for a rationale. 385 2.2.2.2. The 'ServerSideCredential' container 387 The server-side authentication of a mutually authenticating EAP 388 method is typically based on X.509 certificates, which requires the 389 EAP peer to be pre-provisioned with one or more trusted root 390 Certification Authority (CA) prior to authenticating. A server is 391 uniquely identified by presenting a certificate which is signed by 392 these trusted CAs, and by the EAP peer verifying that the name of the 393 server matches the expected one. Consequently, a (set of) CAs and a 394 (set of) server names make up the ServerSideCredentials block. 396 Note that different EAP methods use different terminology when 397 referring to trusted CA roots, server certificates, and server name 398 identification. They also differ or have inherent ambiguity in their 399 interpretation on where to extract the server name from (e.g. is the 400 server name the CN part of the DistinguishedName, or is the server 401 name one of the subjectAltName:DNS entries; what to do if there is a 402 mismatch?). This specification introduces one single element for CA 403 trust roots and naming; these notions map into the naming of the 404 particular EAP methods very naturally. This specification can not 405 remove the CN vs. sAN:DNS ambiguity in many EAP methods. 407 o zero or more 'CA' lists: a Certification Authority which is 408 trusted to sign the expected server certificate. The set of 'CA' 409 occurences SHOULD contain self-signed root certificates to 410 establish trust, and MAY contain additional intermediate CA 411 certificates which ultimately root in these self-signed root CAs. 412 A configuration file can, but SHOULD NOT include only an 413 intermediate CA certificate (i.e. without also including the 414 corresponding self-signed root) because trusting only an 415 intermediate CA without being able to verify to a self-signed root 416 is an unsupported notion in many EAP peers. 418 o zero or more 'ServerID' leafs: these leafs contain the expected 419 server names in incoming X.509 EAP server certificates. For EAP 420 methods not using X.509 certificates for their mutual 421 authentication, these elements contain other string-based handles 422 which identify the server (Example: EAP-pwd). 424 2.2.2.3. The 'EAPClientSideCredential' container 426 The actual ClientSideCredential is defined on the top-level and 427 referenced here only by its UUID. 429 Besides the credentials themselves, there are a variety of EAP- 430 specific properties pertaining to the credential. EAP methods make 431 use of a subset of these properties only. One such property is the 432 "Outer Identity" that some EAP methods support; another one the 433 ClientSideMTU which is relevant when the client has to send large 434 amounts of client credential data (e.g. a large client certificate). 435 As with server-side credentials, the terminology for the properties 436 may differ slightly between EAP types. The naming convention in this 437 specification maps nicely into the method-specific terminology. Not 438 all the criteria make sense in all contexts; for EAP methods which do 439 not support a criterion, configuration files SHOULD NOT contain the 440 corresponding elements, and consumers of the file MUST ignore these 441 elements. 443 Specifying any one of these elements except the UUID of the 444 ClientSideCredential is optional. 446 Leaf 'AnonymousIdentity' is typically used on the outside of a 447 tunneled EAP method and allows to specify which user identity 448 should be used outside the tunnel. This string is not used for 449 actual user authentication, but may contain routing hints to send 450 the request to the right EAP server. 452 'PAC' contains the Protected Access Credential, typically used in 453 EAP-FAST and TEAP. 455 'ProvisionPAC' is a boolean which indicates whether a PAC should 456 be provisioned on the first connection. Note that this 457 specification allows to use 'ProvisionPAC' without a CA nor 458 ServerID in 'ServerSideCredential'. While this allows the 459 operation mode of "Anonymous PAC Provisioning" as used in many 460 field deployments of EAP-FAST (and is thus supported here), due to 461 the known security vulnerabilities of anonymous PAC provisioning, 462 this combination SHOULD NOT be used. 464 2.2.3. The 'ProviderInfo' container 466 This specification needs to consider that user interaction during the 467 installation time may be required; the user at the very least must be 468 empowered to decide whether the configuration file was issued by a 469 provider he has an account with; the provider may have hints for the 470 user (e.g. which password to use for the login), or may want to 471 display links to helpdesk pages in case the user has problems with 472 the setup or use of his identity. 474 The 'ProviderInfo' container allows to specify a range of potentially 475 useful information for display to the user (some of which is relevant 476 only during installation time, other pieces of information could be 477 retained by the configuration agent and displayed e.g. in case of 478 failed authentication): 480 o 'DisplayName' specifies a user-friendly name for the configuration 481 data provider. Consumers of this specification should be aware 482 that this is simple text, and self-asserted by the producer of the 483 configuration file. If more authoritative information about the 484 issuer is available (e.g. if the file is signed with S/MIME and 485 carries an Organisation name (O attribute) in the signing 486 certificate) then the more authoritative information should be 487 displayed with more prominence than the self-asserted one. 489 o 'Description' specifies a generic descriptive text which should be 490 displayed to the user prior to the installation of the 491 configuration data. 493 o 'ProviderLocation' specifies the approximate geographic 494 location(s) of the configuration data provider and/or his Points 495 of Presence. This can be useful if a configuration agent has 496 stored or access to many configuration files and tries to suggest 497 probable matching providers based on the device location. 499 o 'ProviderLogo' specifies the logo of the configuration data 500 provider. The same self-assertion considerations as for 501 'DisplayName' above apply. 503 o 'TermsOfUse' contains terms of use to be displayed to and 504 acknowledged by the user prior to the installation of the 505 configuration on the user's system 507 o 'Helpdesk' is a container with three possible sub-elements: 508 'EmailAddress', 'WebAddress' and 'Phone', all of which can be 509 displayed to the user and possibly retained for future debugging 510 hints. 512 2.3. Internationalisation / Multi-language support 514 Some elements in this specification contain text to be displayed in 515 User Interfaces; depending on the user's language preferences, it 516 would be desirable to present the information in a local language. 517 Other elements contain contact information, and those contact points 518 may only be able to handle requests in a number of languages; it may 519 be desirable to present only contact points to the user which are 520 compatible with his language capabilities. 522 All elements which either contain localisable text, or which point to 523 external resources in localised languages, use the grouping 524 'localized-non-interactive' or 'localized-interactive'. These 525 groupings can occur more than once in the specification, which 526 enables an iteration of all applicable languages. If the grouping is 527 omitted or its 'lang' leaf is set to "C", the instance of the element 528 is considered a default choice which is to be displayed if no other 529 language is a better match. 531 If the entire file content consistently uses only one language set, 532 e.g. all the elements are to be treated as "default" choices, the 533 language can also be set for the entire 'EAPIdentityProvider' element 534 in its own 'lang-tag' leaf. 536 3. Derivation of formats from YANG source 538 The utility 'pyang' is used to derive XML Schema (XSD) from the YANG 539 source. The Schema for this Internet-Draft was generated with pyang 540 1.4.1. 542 4. Issuer Authentication, Integrity Protection and Encryption of EAP 543 Metadata configuration files 545 S/MIME, XMLDSIG, JOSE or underlying transport security. Decisions 546 TBD. Nuff said :-) 548 5. XML Farget Format: File Discovery 550 5.1. By MIME-Type: application/netconfig-metadata-xml 552 For transports where the categorisation of file types via MIME types 553 is possible (e.g. HTTP, E-Mail), this document assigns the MIME type 555 application/netconfig-metadata-xml 557 Edge devices can associate this MIME type to incoming files on such 558 transports, and register the configuration agent which can consume 559 the data in XML format as the default handler for this file type. By 560 doing so, for example a single click or tap on a link to the file in 561 the device's browser will invoke the configuration process. 563 This method of discovery is analogous to the Apple "mobileconfig" 564 discovery on recent versions of Mac OS and iOS. 566 5.2. By filename extension: .netconfig-metadata-xml 568 In situations where file types can not be determined by MIME type 569 meta-information (e.g. when the file gets stored on a local 570 filesystem), this document RECOMMENDs that configuration data in XML 571 format files be stored with the extension 573 .netconfig-metadata-xml 574 to identify the file as containing configuration information in XML 575 format. Edge devices can register the configuration agent which can 576 consume the data with this file extension. By doing so, for example 577 a single click or tap on the filename in the device's User Interface 578 will invoke the configuration process. 580 5.3. By network location: SCAD 582 6. JSON Farget Format: File Discovery 584 6.1. By MIME-Type: application/netconfig-metadata-json 586 For transports where the categorisation of file types via MIME types 587 is possible (e.g. HTTP, E-Mail), this document assigns the MIME type 589 application/netconfig-metadata-json 591 Edge devices can associate this MIME type to incoming files on such 592 transports, and register the configuration agent which can consume 593 the data in JSON format as the default handler for this file type. 594 By doing so, for example a single click or tap on a link to the file 595 in the device's browser will invoke the configuration process. 597 6.2. By filename extension: .netconfig-metadata-json 599 In situations where file types can not be determined by MIME type 600 meta-information (e.g. when the file gets stored on a local 601 filesystem), this document RECOMMENDs that configuration data in JSON 602 format files be stored with the extension 604 .netconfig-metadata-json 606 to identify the file as containing configuration information in JSON 607 format. Edge devices can register the configuration agent which can 608 consume the data with this file extension. By doing so, for example 609 a single click or tap on the filename in the device's User Interface 610 will invoke the configuration process. 612 6.3. By network location: SCAD 614 7. Design Decisions 616 7.1. Why YANG and not directly XML, JSON or $FOO? 618 XML is a popular choice for EAP configurations: Microsoft's "netsh" 619 files, Apple's "mobileconfig" files, the Wi-Fi Alliance's 620 "PerProviderSubscription Managed Object", and other vendor/SDO 621 definitions are all using XML. 623 JSON file formats for EAP configuration exist as well; most notable 624 are Google's most recent efforts for their Chromebook Operating 625 system. 627 YANG has a very rich feature set, and can codify restrictions on 628 which element is allowed when in a much more fine-grained way than 629 XML Schema could. Since YANG modules can be converted to XML Schema 630 and be instantiated as XML or JSON, they can serve as an abstract 631 notion of EAP configuration which can be deployed on consumer devices 632 in either of those two more popular formats as needed by the device 633 in question. 635 7.2. Shallow vs. Deep definition of EAP method properties 637 7.3. EAP tunneling inside EAP tunnels 639 7.4. Placement of 'OuterIdentity' inside 'AuthenticationMethod' 641 8. Implementation Status 643 RFC Editor Note: Please remove this section and the reference to 644 [RFC6982] prior to publication. 646 This section records the status of known implementations of the 647 protocol defined by this specification at the time of posting of this 648 Internet-Draft, and is based on a proposal described in [RFC6982]. 649 The description of implementations in this section is intended to 650 assist the IETF in its decision processes in progressing drafts to 651 RFCs. Please note that the listing of any individual implementation 652 here does not imply endorsement by the IETF. Furthermore, no effort 653 has been spent to verify the information presented here that was 654 supplied by IETF contributors. This is not intended as, and must not 655 be construed to be, a catalog of available implementations or their 656 features. Readers are advised to note that other implementations may 657 exist. 659 According to [RFC6982], "this will allow reviewers and working groups 660 to assign due consideration to documents that have the benefit of 661 running code, which may serve as evidence of valuable experimentation 662 and feedback that have made the implemented protocols more mature. 663 It is up to the individual working groups to use this information as 664 they see fit". 666 All of the implementations listed below interoperate from producer- 667 to consumer-side of the EAP metadata specification. 669 Producers of the configuration files 670 o eduroam Configuration Assistant Tool 672 Organisation: Nicolaus Copernicus University, Torun, Poland 674 Implementation Name: eduroam Configuration Assistant Tool 676 This existing tool already produces EAP configuration files in 677 various proprietary formats for hundreds of EAP Identity 678 Providers. A module which produces configuration files in the 679 XML variant as specified in an eralier revision of this draft 680 (-00) is in production deployment. 682 Link to production version: https://cat.eduroam.org 684 Maturity: production 686 Coverage: entire specification; XML structure aligns with 687 version -00 of this draft 689 Licensing: freely distributable with acknowledgement (BSD 690 style) 692 Implementation experience: given that the specification is XML, 693 it is easy to produce a configuration file with common XML 694 libraries. The CAT Framework is written in PHP, which provides 695 ample procedures to produce well-formed XML. 697 Contact Information: Tomasz Wolniewicz (see Section 11); the 698 CAT software homepage at http://forge.geant.net/CAT/ 700 Consumers of the configuration files 702 o Android 704 Organisation: Swansea University, Swansea, Wales, U.K. 706 Implementation Name: eduroam CAT app 708 An Android app, compatible with API level 18 of Android (i.e. 709 version 4.3 and above); the app consumes the -00 revision of 710 this specification. The information in the config files is 711 used to push settings to the SSID 'eduroam' (hard-coded) via 712 the WifiEnterpriseConfig API. The app is in production 713 deployment, with a 4-four digit amount of downloads one month 714 after launch. 716 Link to production version: https://play.google.com/store/apps/ 717 details?id=uk.ac.swansea.eduroamcat 718 Maturity: production 720 Coverage: entire specification; XML structure aligns with 721 version -00 of this draft 723 Licensing: Apache 2.0 725 Implementation experience: parsing XML is rather 726 straightfoward. The ability to verify signatures on XML files 727 (S/MIME vs. XMLDSIG as discussed in Section 4) remains unclear 728 at this point. 730 Contact Information: eduroam CAT Play Store app contact address 731 ( playstore@eduroam.org ) 733 o Windows 735 Organisation: Amebis, d.o.o.i, Kamnik, Slovenia 737 Implementation Name: ArnesLink 739 A Windows supplicant/Enterprise WiFi installer/debugging 740 assistant. The application consumes the -02 revision of this 741 specification. The information from the XML variant of this 742 specification is embedded in a larger XML file. The additional 743 parts of the overall configuration file include information 744 regarding the SSID to configure and other useful, but not EAP- 745 specific information. The complete set of information is used 746 to push settings into the Windows Wi-Fi configuration via the 747 'netsh' tool. The app is in production deployment. 749 Link to production version: http://ftp.arnes.si/software/ 750 eduroam/ArnesLink/ 752 Maturity: production 754 Coverage: entire specification; XML structure aligns with 755 version -02 of this draft 757 Licensing: GPL 759 Implementation experience: parsing XML is rather 760 straightfoward. For Wi-Fi configuration use, the lack of 761 802.11 specific details in the config file is an issue. 763 Contact Information: info@amebis.si 765 o Linux: the authors of this specification are currently developing 766 an application for UNIX-like operating systems which configure 767 enterprise networks via the NetworkManager daemon; the application 768 can consume the file format as defined in this draft specification 769 (XML format) and configure the settings via Networkmanager's D-BUS 770 interface. 772 9. Security Considerations 774 10. IANA Considerations 776 IANA is requested to allocate the MIME type "application/netconfig- 777 metadata-xml" in the MIME Media Types / application registry (see 778 section Section 5.1). The allocation should contain the following 779 values: 781 o Name: netconfig-metadata-xml 783 o Template: see Appendix A (RFC editor note: remove this appendix 784 prior to publication; replace this line with the URL to the 785 application as posted online) 787 o Reference: RFCabcd (RFC editor note: replace with the RFC number 788 of this document) 790 IANA is requested to allocate the MIME type "application/netconfig- 791 metadata-json" in the MIME Media Types / application registry (see 792 section Section 5.1). The allocation should contain the following 793 values: 795 o Name: netconfig-metadata-json 797 o Template: see Appendix A (RFC editor note: remove this appendix 798 prior to publication; replace this line with the URL to the 799 application as posted online) 801 o Reference: RFCabcd (RFC editor note: replace with the RFC number 802 of this document) 804 IANA is requested to allocate the location "TBD" in the "well-known 805 URIs" registry. The allocation should contain the following values: 807 o URI Suffix: TBD 809 o Change Controller: IETF 811 o Reference: RFCabcd (RFC editor note: replace with the RFC number 812 of this document) 814 o Related Information: none 816 IANA is requested to register the XML namespace 817 "urn:ietf:params:xml:ns:netconfig-metadata-xml" in the "IETF XML 818 Registry / ns". The allocation should contain the following values: 820 o ID: netconfig-metadata-xml 822 o URI: urn:ietf:params:xml:ns:netconfig-metadata-xml 824 o Filename: https://www.iana.org/assignments/xml-registry/ns/ 825 netconfig-metadata-xml.txt (to be created by IANA) 827 o Reference: RFCabcd (RFC editor note: replace with the RFC number 828 of this document) 830 IANA is requested to register the XML schema 831 "urn:ietf:params:xml:schema:netconfig-metadata-xml" in the "IETF XML 832 Registry / schema". The allocation should contain the following 833 values: 835 o ID: netconfig-metadata-xml 837 o URI: urn:ietf:params:xml:schema:netconfig-metadata-xml 839 o Filename: https://www.iana.org/assignments/xml-registry/schema/ 840 netconfig-metadata-xml.xsd (to be created by IANA; current XSD 841 file is linked to in section Section 2.1) 843 o Reference: RFCabcd (RFC editor note: replace with the RFC number 844 of this document) 846 11. Contributors 848 Tomasz Wolniewicz of Nicolaus Copernicus University in Torun, Poland, 849 and Gareth J. Ayres of Swansea University in Swansea, United Kingdom, 850 provided significant input into this specification. 852 12. References 854 12.1. Normative References 856 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 857 Requirement Levels", BCP 14, RFC 2119, March 1997. 859 12.2. Informative References 861 [RFC3748] Aboba, B., Blunk, L., Vollbrecht, J., Carlson, J., and H. 862 Levkowetz, "Extensible Authentication Protocol (EAP)", RFC 863 3748, June 2004. 865 [RFC5216] Simon, D., Aboba, B., and R. Hurst, "The EAP-TLS 866 Authentication Protocol", RFC 5216, March 2008. 868 [RFC5281] Funk, P. and S. Blake-Wilson, "Extensible Authentication 869 Protocol Tunneled Transport Layer Security Authenticated 870 Protocol Version 0 (EAP-TTLSv0)", RFC 5281, August 2008. 872 [RFC5931] Harkins, D. and G. Zorn, "Extensible Authentication 873 Protocol (EAP) Authentication Using Only a Password", RFC 874 5931, August 2010. 876 [RFC6982] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 877 Code: The Implementation Status Section", RFC 6982, July 878 2013. 880 [RFC7593] Wierenga, K., Winter, S., and T. Wolniewicz, "The eduroam 881 Architecture for Network Roaming", RFC 7593, DOI 10.17487/ 882 RFC7593, September 2015, 883 . 885 [HS20] Wi-Fi Alliance, "Hotspot 2.0 Technical Specification", 886 2012, . 889 Appendix A. Appendix A: MIME Type Registration Template 891 The following values will be used for the online MIME type 892 registration at https://www.iana.org/form/media-types 894 Your Name: Stefan Winter 896 Your Email Address: stefan.winter@restena.lu 898 Media Type Name: Application 900 Subtype name: 1) (Standards tree) netconfig-metadata-xml 902 Subtype name: 2) (Standards tree) netconfig-metadata-json 904 Required parameters: (none) 906 Optional parameters: (none) 908 Encoding Considerations: 8-Bit text 910 Security Considerations: This file type carries configuration 911 information for consumer devices. It has the potential to 912 substantially alter the consumer's device; particularly to install 913 a new trusted Certification Authority. Applications consuming 914 files of this type need to be cautious to explain to the end user 915 what is being altered, so that they understand the consequences. 916 For further explanations, see Section 9 of this draft. (Note to 917 RFC Editor: replace with the number of this RFC once known) 919 Interoperability Considerations: The file content is in 1) XML 920 version 1.0 or later; 2) JSON. The encoding SHOULD be UTF-8, but 921 implementations consuming the file SHOULD be prepared to encounter 922 different encodings. 924 Published Specification: draft-winter-opsec-netconfig-metadata 925 (Note to RFC Editor: replace this reference with the RFC number of 926 this document once known) 928 Applications which use this media type: files of this type are 929 intended for consumption by sortware on edge devices; they consume 930 the information therein to configure authentication parameters of 931 various network services which are then applied to network or 932 application authentication scenarios. 934 Fragment Identifier Considerations: files of this type are 935 expected to be transmitted in their entirety. If a reference to a 936 specific part of the content is to be made, XML XPath expressions 937 are to be used. I.e. fragment identifier formats are not expected 938 to be used. 940 Restrictions on Usage: none 942 Provisional registration: initial submission of this form will be 943 executed after adoption in the IETF; it will be a provisional 944 registration. Final registration will be done after IESG review. 946 Additional information: 948 Deprecated alias types for this name: none 950 Magic numbers: none 952 File extensions: 1) netconfig-metadata-xml 954 File extensions: 2) netconfig-metadata-json 956 Macintosh File Type Codes: TBD 958 Object Identifiers or OIDs: none 960 Intended Usage: Common (no further provisions) 962 Other Information/General Comment: none 964 Person to contact for further information: 966 Name: Stefan Winter 968 E-Mail: stefan.winter@restena.lu 970 Author/Change controller: IETF 972 DATA 974 Author's Address 975 Stefan Winter 976 Fondation RESTENA 977 6, rue Richard Coudenhove-Kalergi 978 Luxembourg 1359 979 LUXEMBOURG 981 Phone: +352 424409 1 982 Fax: +352 422473 983 EMail: stefan.winter@restena.lu 984 URI: http://www.restena.lu.