idnits 2.17.1 draft-pala-eap-creds-07.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 10 instances of too long lines in the document, the longest one being 2 characters in excess of 72. == There are 5 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 3, 2020) is 1394 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) -- Looks like a reference, but probably isn't: '1' on line 566 -- Looks like a reference, but probably isn't: '2' on line 582 == Missing Reference: 'N' is mentioned on line 510, but not defined -- Looks like a reference, but probably isn't: '3' on line 505 == Missing Reference: 'RFC3279' is mentioned on line 603, but not defined == Missing Reference: 'RFC4055' is mentioned on line 603, but not defined == Missing Reference: 'RFC4491' is mentioned on line 604, but not defined Summary: 1 error (**), 0 flaws (~~), 6 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Pala 3 Internet-Draft CableLabs 4 Intended status: Standards Track June 3, 2020 5 Expires: December 5, 2020 7 Credentials Provisioning and Management via EAP (EAP-CREDS) 8 draft-pala-eap-creds-07 10 Abstract 12 With the increase number of devices, protocols, and applications that 13 rely on strong credentials (e.g., digital certificates, keys, or 14 tokens) for network access, the need for a standardized credentials 15 provisioning and management framework is paramount. The 802.1x 16 architecture allows for entities (e.g., devices, applications, etc.) 17 to authenticate to the network by providing a communication channel 18 where different methods can be used to exchange different types of 19 credentials. However, the need for managing these credentials (i.e., 20 provisioning and renewal) is still a hard problem to solve. 22 EAP-CREDS, if implemented in Managed Networks (e.g., Cable Modems), 23 could enable our operators to offer a registration and credentials 24 management service integrated in the home WiFi thus enabling 25 visibility about registered devices. During initialization, EAP- 26 CREDS also allows for MUD files or URLs to be transferred between the 27 EAP Peer and the EAP Server, thus giving detailed visibility about 28 devices when they are provisioned with credentials for accessing the 29 networks. The possibility provided by EAP-CREDS can help to secure 30 home or business networks by leveraging the synergies of the security 31 teams from the network operators thanks to the extended knowledge of 32 what and how is registered/authenticated. 34 This specifications define how to support the provisioning and 35 management of authentication credentials that can be exploited in 36 different environments (e.g., Wired, WiFi, cellular, etc.) to users 37 and/or devices by using EAP together with standard provisioning 38 protocols. 40 Status of This Memo 42 This Internet-Draft is submitted in full conformance with the 43 provisions of BCP 78 and BCP 79. 45 Internet-Drafts are working documents of the Internet Engineering 46 Task Force (IETF). Note that other groups may also distribute 47 working documents as Internet-Drafts. The list of current Internet- 48 Drafts is at https://datatracker.ietf.org/drafts/current/. 50 Internet-Drafts are draft documents valid for a maximum of six months 51 and may be updated, replaced, or obsoleted by other documents at any 52 time. It is inappropriate to use Internet-Drafts as reference 53 material or to cite them other than as "work in progress." 55 This Internet-Draft will expire on December 5, 2020. 57 Copyright Notice 59 Copyright (c) 2020 IETF Trust and the persons identified as the 60 document authors. All rights reserved. 62 This document is subject to BCP 78 and the IETF Trust's Legal 63 Provisions Relating to IETF Documents 64 (https://trustee.ietf.org/license-info) in effect on the date of 65 publication of this document. Please review these documents 66 carefully, as they describe your rights and restrictions with respect 67 to this document. Code Components extracted from this document must 68 include Simplified BSD License text as described in Section 4.e of 69 the Trust Legal Provisions and are provided without warranty as 70 described in the Simplified BSD License. 72 Table of Contents 74 1. Requirements notation . . . . . . . . . . . . . . . . . . . . 3 75 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 76 2.1. Overview of existing solutions . . . . . . . . . . . . . 4 77 2.2. Scope Statement . . . . . . . . . . . . . . . . . . . . . 4 78 2.3. EAP-CREDS as tunneled mechanism only . . . . . . . . . . 5 79 2.4. Fragmentation Support . . . . . . . . . . . . . . . . . . 5 80 2.5. Encapsulating Provisioning Protocols in EAP-CREDS . . . . 5 81 2.6. Algorithm Requirements . . . . . . . . . . . . . . . . . 6 82 2.7. Notation . . . . . . . . . . . . . . . . . . . . . . . . 6 83 3. EAP-CREDS Protocol . . . . . . . . . . . . . . . . . . . . . 6 84 3.1. Message Flow . . . . . . . . . . . . . . . . . . . . . . 6 85 3.2. Phase Transitioning Rules . . . . . . . . . . . . . . . . 7 86 3.3. Phase One: Initialization . . . . . . . . . . . . . . . . 8 87 3.4. Phase Two: Provisioning . . . . . . . . . . . . . . . . . 10 88 3.5. Phase Three: Validation . . . . . . . . . . . . . . . . . 12 89 4. EAP-CREDS Message Format . . . . . . . . . . . . . . . . . . 15 90 4.1. Message Header . . . . . . . . . . . . . . . . . . . . . 15 91 4.2. Message Payload . . . . . . . . . . . . . . . . . . . . . 17 92 4.3. EAP-CREDS defined TLVs . . . . . . . . . . . . . . . . . 18 93 4.3.1. The Action TLV . . . . . . . . . . . . . . . . . . . 18 94 4.3.2. The Certificate-Data TLV . . . . . . . . . . . . . . 19 95 4.3.3. The Challenge-Data TLV . . . . . . . . . . . . . . . 20 96 4.3.4. The Challenge-Response TLV . . . . . . . . . . . . . 21 97 4.3.5. The Credentials-Information TLV . . . . . . . . . . . 21 98 4.3.6. The Credentials-Data TLV . . . . . . . . . . . . . . 24 99 4.3.7. The Error TLV . . . . . . . . . . . . . . . . . . . . 25 100 4.3.8. The Network-Usage TLV . . . . . . . . . . . . . . . . 26 101 4.3.9. The Profile TLV . . . . . . . . . . . . . . . . . . . 28 102 4.3.10. The Protocol TLV . . . . . . . . . . . . . . . . . . 29 103 4.3.11. The Provisioning-Data TLV . . . . . . . . . . . . . . 29 104 4.3.12. The Provisioning-Headers TLV . . . . . . . . . . . . 30 105 4.3.13. The Provisioning-Params TLV . . . . . . . . . . . . . 31 106 4.3.14. The Token-Data TLV . . . . . . . . . . . . . . . . . 33 107 4.3.15. The Version TLV . . . . . . . . . . . . . . . . . . . 34 108 5. EAP-CREDS Messages . . . . . . . . . . . . . . . . . . . . . 35 109 5.1. The EAP-CREDS-Init Message . . . . . . . . . . . . . . . 35 110 5.1.1. EAP Server's Init Message . . . . . . . . . . . . . . 35 111 5.1.2. EAP Peer's Init Message . . . . . . . . . . . . . . . 36 112 5.1.2.1. Bootstrapping Peer's Trustworthiness . . . . . . 36 113 5.1.3. The EAP-CREDS-Provisioning Message . . . . . . . . . 37 114 5.1.4. The EAP-CREDS-Validate Message . . . . . . . . . . . 38 115 6. Error Handling in EAP-CREDS . . . . . . . . . . . . . . . . . 39 116 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 39 117 7.1. Provisioning Protocols . . . . . . . . . . . . . . . . . 39 118 7.2. Token Types . . . . . . . . . . . . . . . . . . . . . . . 39 119 7.3. Credentials Types . . . . . . . . . . . . . . . . . . . . 40 120 7.4. Credentials Algorithms . . . . . . . . . . . . . . . . . 40 121 7.5. Credentials Datatypes . . . . . . . . . . . . . . . . . . 41 122 7.6. Challenge Types . . . . . . . . . . . . . . . . . . . . . 41 123 7.7. Network Usage Datatypes . . . . . . . . . . . . . . . . . 42 124 7.8. Credentials Encoding . . . . . . . . . . . . . . . . . . 42 125 7.9. Action Types . . . . . . . . . . . . . . . . . . . . . . 42 126 7.10. Usage Metadata Types . . . . . . . . . . . . . . . . . . 43 127 8. Security Considerations . . . . . . . . . . . . . . . . . . . 43 128 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 44 129 10. Normative References . . . . . . . . . . . . . . . . . . . . 44 130 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 45 132 1. Requirements notation 134 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 135 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 136 document are to be interpreted as described in [RFC2119]. 138 2. Introduction 140 Many environments are, today, moving towards requiring strong 141 authentication when it comes to gain access to networks. The 802.1x 142 architecture provides network administrators with the possibility to 143 check credentials presented by a device even before providing any 144 connectivity or IP services to it. 146 However, the provisioning and management of these credentials is a 147 hard problem to solve and many vendors opt for long-lived credentials 148 that can not be easily revoked, replaced, or simply renewed. 150 This specification addresses the problem of providing a simple-to-use 151 and simple-to-deploy conduit for credentials management by extending 152 the EAP protocol to support credentials provisioning and management 153 functionality. In particular, the EAP-CREDS method defined here 154 provides a generic framework that can carry the messages for 155 provisioning different types of credentials. EAP-CREDS cannot be 156 used as a stand-alone method, it is required that EAP-CREDS is used 157 as an inner method of EAP-TLS, EAP-TEAP, or any other tunneling 158 method that can provide the required secrecy and (at minimum) server- 159 side authentication to make sure that the communication is protected 160 and with the right server. 162 2.1. Overview of existing solutions 164 Currently there are many protocols that address credentials lifecycle 165 management. In particular, when it comes to digital certificates, 166 some of the most deployed management protocols are: Certificate 167 Management Protocol (CMP) [RFC4210], Certificate Management over CMS 168 (CMC) [RFC5272][RFC6402], Enrollment over Secure Transport (EST) 169 [RFC7030], and Automated Certificate Management Environment (ACME) . 170 However, none of these protocols provide native support for client 171 that do not have IP connectivity yet (e.g., because they do not have 172 network-access credentials, yet). EAP-CREDS provides the possibility 173 to use such protocols (i.e., message-based) by defining a series of 174 messages that can be used to encapsulate the provisioning messages 175 for the selected provisioning protocol. 177 2.2. Scope Statement 179 This document focuses on the definition of the EAP-CREDS method to 180 convey credentials provisioning and managing messages between the 181 client and the AAA server. Moreover, the document defines how to 182 encode messages for the main IETF provisioning protocols. 184 This document, however, does not provide specifications for how and 185 where the credentials are generated. In particular, the credentials 186 could be generated directly within the AAA server or at a different 187 location (i.e., the Certificate Service Provider or CSP) site. 188 Different authentication mechanisms (e.g., TLS, etc.) can be used to 189 secure the communication between the server's endpoint and the CSP. 191 2.3. EAP-CREDS as tunneled mechanism only 193 EAP-CREDS requires that an outer mechanism is in place between the 194 Peer and the Server in order to provide authentication and 195 confidentiality of the messages exchanged via EAP-CREDS. In other 196 words, EAP-CREDS assumes that an appropriately encrypted and 197 authenticated channel has been established to prevent the possibility 198 to leak information or to allow man-in-the-middle attacks. 200 This choice was taken to simplify the message flow between Peer and 201 Server, and to abstract EAP-CREDS from the secure-channel 202 establishment mechanism. EAP-TLS, or EAP-TEAP are examples of such 203 mechanisms.s 205 2.4. Fragmentation Support 207 EAP does not directly support handling fragmented packets and it 208 requires the outer method to provide fragmentation support. 210 Because of the outer method requirements in particular, removing any 211 support for fragmented messages in EAP-CREDS removes the duplication 212 of packets (e.g., Acknowledgment Packets) sent across the Peer and 213 the Server, thus resulting in a smaller number of exchanged messages 215 2.5. Encapsulating Provisioning Protocols in EAP-CREDS 217 In order to use EAP-CREDS together with your favorite provisioning 218 protocol, the messages from the provisioning protocol need to be sent 219 to the other party. In EAP-CREDS, this is done by encoding the 220 provisioning protocol messages inside the ('Provisioning-Data') TLV. 221 In case the provisioning protocol uses additional data for its 222 operations (e.g., uses HTTP Headers), this data can be encoded in a 223 separate ('Provisioning-Headers') TLV. 225 Since the implementation of the provisioning endpoint could happen in 226 a (logically or physically) different component, a method is needed 227 to identify when a provisioning protocol has actually ended. In EAP- 228 CREDS, the 'D' bit in the message headers is used for this purpose. 230 In the first message of Phase Two, the Server provides the client 231 with all the selected parameters for one specific credential that 232 needs attention (or for a new credential) to be managed by the 233 network. In particular, the server provides, at minimum, the 234 ('Protocol') TLV, the ('Action') TLV, and the ('Provisioning-Params') 235 or the ('Credentials-Info') TLV. 237 After checking the parameters sent by the Server, if the Peer does 238 not support any of the proposed ones, it MUST send a message with one 239 single ('Error') TLV with the appropriate error code(s). The server, 240 can then decide if to manage a different set of credentials (if more 241 where reported by the Peer in its Phase One message) or if to 242 terminate the EAP session with an error. 244 The Peer and the Server exchange Provisioning messages until an error 245 is detected (and the appropriate error message is sent to the other 246 party) or until Phase Two is successfully completed. 248 2.6. Algorithm Requirements 250 EAP-CREDS uses the SHA-256 hashing algorithm to verify credentials in 251 phase three of the protocol. Peers and Servers MUST support SHA-256 252 for this purpose. 254 2.7. Notation 256 In this document we use the following notation in the diagrams to 257 provide information about the cardinality of the data structures 258 (TLVs) within EAP-CREDS messages: 260 +--------+------------+---------------------------------------------+ 261 | Symbol | Example | Usage | 262 +--------+------------+---------------------------------------------+ 263 | { } | {TLV1} | Curly Brackets are used to indicate a set | 264 | [ ] | {[TLV2]} | Square Brackets are used to indicate that a | 265 | | | field is optional | 266 | ( ) | {TLV1(=V)} | Round Squares are used to specify a value | 267 | + | {TLV_2+} | The Plus character indicates that one or | 268 | | | more instances are allowed | 269 +--------+------------+---------------------------------------------+ 271 Table 1: EAP-CREDS Notation 273 3. EAP-CREDS Protocol 275 In a nutshell, EAP-CREDS provides the abstraction layer on top of 276 which credentials provisioning/managing protocols can be deployed 277 thus enabling their use even before provisioning IP services. 279 This section outlines the operation of the protocol and message 280 flows. The format of the CREDS messages is given in Section 4. 282 3.1. Message Flow 284 EAP-CREDS message flow is logically subdivided into three different 285 phases: Initialization, Provisioning, and Validation. EAP-CREDS 286 enforces the order of phases, i.e. it is not possible to move to an 287 earlier phase. 289 Phase transitioning is controlled by the Server. In particular, the 290 server, after the last message of a phase, it can decide to either 291 (a) start the next phase by sending the first message of the next 292 phase, or (b) continue the same phase by sending another "first" 293 message of the phase (e.g., managing a second set of credentials) - 294 this is allowed only in Phase Two and Phase Three but NOT in Phase 295 One, or (c) terminate the EAP session. 297 Phase One (Required). Initialization. During this phase the Peer 298 and the Server exchange the information needed to select the 299 appropriate credentials management protocol. Phase One flow is 300 composed by only messages. In particular, the Sever sends its 301 initial message of type ('EAP-CREDS-Init'). The Peer replies with 302 the details about which provisioning protocols are supported, and 303 additional information such as the list of installed credentials 304 and, optionally, authorization data (for new credentials 305 registration). 307 Phase Two (Optional). Provisioning Protocol Flow. In this phase, 308 the Peer and the Server exchange the provisioning protocol's 309 messages encapsulated in a EAP-CREDS message of type Provisioning. 310 The messages use two main TLVs. The first one is the 311 ('Provisioning-Headers') TLV which is optional and carries 312 information that might be normally conveyed via the transport 313 protocol (e.g., HTTP headers). The second one is the 314 ('Provisioning-Data'), which is required and carries the 315 provisioning protocol's messages. The server can decide to repeat 316 phase two again to register new credentials or to renew a separate 317 set of credentials by issuing a new ('Provisioning') message for 318 the new target. When no more credentials have to be managed, the 319 Server can start phase three or simply terminate the EAP session. 321 Phase Three (Optional). Credentials Validation. This optional phase 322 can be initiated by the server and it is used to validate that the 323 Peer has properly installed the credentials and can use them to 324 authenticate itself. Depending on the credentials' type, the 325 messages can carry a challenge/nonce, the value of the secret/ 326 token, or other information. The format of the credentials is 327 supposed to be known by the provider and the device. 329 3.2. Phase Transitioning Rules 331 In order to keep track of starting and ending a phase, EAP-CREDS 332 defines several bits and fields in the EAP-CREDS message headers. In 333 particular, as described in Section 4.1, the 'S' bit is used to 334 indicate the beginning (or Start) of a phase, while the 'Phase' field 335 (4 bits) is used to indicate the phase for this message. 337 In EAP-CREDS, phase transitioning is under the sole control of the 338 Server, therefore the value of the 'S' bit is meaningful only in 339 messages sent by the Server. The value of the 'S' bit in Peer's 340 messages SHALL be set to '0x0' and SHALL be ignored by the server. 342 When starting a new phase, the Server MUST set the 'S' bit to '1' and 343 the 'Phase' field to the current phase number (e.g., one, two, or 344 three). 346 In case the first message of a phase is to be repeated (e.g., because 347 of processing multiple credentials), the 'S' bit SHALL be set to '0' 348 (i.e., it should be set to '1' only on the first occurrence and set 349 to '0' in subsequent messages). 351 3.3. Phase One: Initialization 353 The following figure provides the message flow for Phase One: 355 ,--------. ,----------. 356 |EAP Peer| |EAP Server| 357 `---+----' `----+-----' 358 | Outer Tunnel Established | 359 | <--------------------------------------> 360 | | 361 | [1] EAP-Request/EAP-CREDS(Type=Init) | ,---------!. 362 | { [ Version+ ], [ Challenge ] } | |Phase One|_\ 363 | <--------------------------------------- |Begins | 364 | | `-----------' 365 | [2] EAP-Response/EAP-CREDS(Type=Init) | 366 | { Protocol+, [ Encoding+ ], | 367 | [ Format+ ] , [ Version ] | ,---------!. 368 | [ Creds-Info+ ], [ Storage-Info ]| |Phase One|_\ 369 | [ Net-Usage], [ Token ], | |Ends | 370 | [ Challenge-Rsp ], [ Profile+ ] }| `-----------' 371 | ---------------------------------------> 372 | | 373 | | 375 EAP-CREDS Phase One Message Flow 377 [1] Server sends EAP-Request/EAP-CREDS(Type=Init): 379 After the establishment of the outer mechanism (e.g., EAP-TLS, 380 EAP-TEAP, EAP-TTLS, etc.), the server MAY decide to start a 381 credentials management session. In order to do that, the Server 382 sends an EAP-Request/EAP-CREDS(Type=Init) message to the Peer with 383 one ('Phase-Control') TLV with the 'S' bit set to '1' and the 384 value set to '1' (thus indicating the beginning of Phase One). 385 Also, the Server MAY use one or more ('Version') TLVs to indicate 386 the supported versions. 388 The Server MAY also specify which versions of EAP-CREDS are 389 supported by adding one or more ('Version') TLVs. If no 390 ('Version') TLV is added to the message, the Peer SHOULD assume 391 the supported version is 1 ('0x1'). 393 [2] The Peer sends EAP-Response/EAP-CREDS(Type=Init) 395 The Peer, sends back a message that carries one ('Version') TLV to 396 indicate the selected version of EAP-CREDS (i.e. from the list 397 provided by the server) (optional). If the client does not 398 include the ('Version') TLV, the Server MUST use the most recent 399 supported version of EAP-CREDS. Moreover, the Server includes one 400 or more ('Protocol') TLVs to indicate the list of supported 401 provisioning protocols, followed by one ('Credentials-Info') TLVs 402 for each installed credentials to provide their status to the 403 server (i.e., if multiple credentials are configured on the Peer 404 for this Network, then the Peer MUST include one ('Credentials- 405 Info') TLV for each of them). 407 The Peer also provides the list of supported Encodings and Formats 408 by adding one or more ('Supported-Encodings') and ('Supported- 409 Formats') TLVs. The Peer MAY also provide the Server with 410 information about the Peer's credentials storage by using the 411 'Storage-Status' TLV. 413 When there are no available credentials, the Peer MAY include an 414 authorization token that can be consumed by the Server for 415 registering new credentials. In particular, the Peer can include 416 the ('Token-Data') TLV to convey the value of the token. The 417 ('Challenge-Data') and ('Challenge-Response') TLVs, instead, can 418 be used to convey a challenge and its response based on the 419 authorization information (e.g., maybe a public key hash is 420 present in the Token, then the peer can generate some random data 421 - or use the one from the Server - and generate a signature on 422 that value: the signature SHALL be encoded in the ('Challenge- 423 Response') TLV and it should be calculated over the concatenation 424 of values inside the ('Challenge-Data') TLV and the ('Token-Data') 425 TLV. 427 Also, the Peer MAY add one or more ('Profile') TLVs to indicate to 428 the Server which profiles are requested/supported (e.g., a pre- 429 configuration MAY exist on the Peer with these ecosystem-specific 430 identifiers). 432 Ultimately, the Peer MAY include additional metadata regarding the 433 status of the Peer. To this end, the Peer can use a ('Storage- 434 Info') TLV to provide the server with additional data about the 435 Peer's capabilities and resources. Also, the ('Network-Usage') 436 TLV can be used to provide the Server with the indication of which 437 network resources are needed by the Peer and what is its intended 438 utilization pattern(s). 440 The server checks that the Peer's selected protocol, version, and 441 parameters are supported and, if not (or if the server detects an 442 error), it can (a) send a non-recoverable error message to the 443 peer, notify the outer (tunneling) layer, and terminate the EAP- 444 CREDS session, or (b) start phase one again by sending a new 445 ('EAP-CREDS-Init') message that will also carry an ERROR TLV that 446 provides the Peer with the reason the initial response was not 447 acceptable. In this case, the ('Phase-Control') TLV MUST be 448 omitted since it is not the first message of phase one. The 449 server and the peer can repeat phase one until they reach an 450 agreement or the session is terminated by the Server. 452 NOTE WELL: The determination of the need to start phase two or not 453 is based on the contents of the ('Credentials-Info') TLV sent by 454 the Peer (e.g., a credential is about to expire or a credential is 455 simply missing). 457 3.4. Phase Two: Provisioning 459 The following figure provides the message flow for Phase 2: 461 ,--------. ,----------. 462 |EAP Peer| |EAP Server| 463 `---+----' `----+-----' 464 | [1] EAP-Request/EAP-CREDS(Type=Provisioning) | 465 | { Protocol, Action, | ,---------!. 466 | [ CredInfo ], [ Params ], | |Phase Two|_\ 467 | [ ProtoData ], [ ProtoHeaders ] } | |Begins | 468 | <---------------------------------------------- `-----------' 469 | | 470 | [2] EAP-Response/EAP-CREDS(Type=Provisioning) | 471 | { ProtoData, [ ProtoHeaders ] } | 472 | ----------------------------------------------> 473 | | 474 . . 475 . . 476 . . 477 . . 478 | [N] EAP-Response/EAP-CREDS(Type=Provisioning) | 479 | { [ CredInfo ], [ ProtoData ], | 480 | [ ProtoHeaders ] } | 481 | <---------------------------------------------- 482 | | 483 | [N+1] EAP-Request/EAP-CREDS(Type=Provisioning)| ,---------!. 484 | { [ ProtoData ], [ ProtoHeaders ] } | |Phase Two|_\ 485 | ----------------------------------------------> |Ends | 486 | | `-----------' 487 | | 489 EAP-CREDS Phase Two Message Flow 491 [1] The Server sends EAP-Request/EAP-CREDS(Type=Init) 493 The first message of Phase Two indicates that the Server is ready 494 to initiate the selected provisioning protocol. 496 [2] The Peer sends EAP-Response/EAP-CREDS(Type=Init) 498 After that, the Peer sends its first message to the Server by 499 sending the EAP-Response/EAP-CREDS(Type=Provisioning) message. 500 This message contains the selected provisioning protocol's message 501 data and some extra fields (e.g., transport-protocol headers) in 502 the ('Provisioning-Data') and ('Protocol-Headers') TLVs 503 respectively. 505 [3] The Server sends EAP-Request/EAP-CREDS(Type=Init) 506 The Server replies to the Peer's message with EAP-Request/EAP- 507 CREDS(Type=Provisioning) messages until the provisioning protocol 508 reaches an end or an error condition arise (non-recoverable). 510 [N] The Server sends EAP-Request/EAP-CREDS(Type=Provisioning) 512 When the provisioning protocol has been executed for the specific 513 set of credentials, the server sends a last message that MUST 514 include the description of the provisioned credentials in a 515 ('Credentials-Info') TLV and MUST set the 'D' bit in the EAP-CREDS 516 message header to '1' to indicates that the server does not have 517 any more ('Provisioning') messages for this credenital. The final 518 message does not need to be an empty one, i.e. other TLVs are 519 still allowed in the same message (e.g., the 'Provisioning-Data' 520 and the 'Provisioning-Headers' ones). 522 [N+1] The Peer sends EAP-Request/EAP-CREDS(Type=Provisioning) 524 The Peer MUST reply to the server with a ('Provisioning') message 525 that MUST have the 'D' bit in the EAP-CREDS message header set to 526 '1', thus indicating that the credentials have been installed 527 correctly. In case of errors, the Peer MUST include the 528 appropriate ('Error') TLV. Also in this case, the final message 529 does not need to be an empty one, i.e. other TLVs are still 530 allowed in the same message (e.g., the 'Provisioning-Data' and the 531 'Provisioning-Headers' ones). 533 At this point, the Server can decide to provision (or manage) another 534 set of credentials by issuing a new ('Provisioning') message, or it 535 can decide to start Phase Three by sending its first ('Validate') 536 message, or it can terminate the EAP session. 538 3.5. Phase Three: Validation 540 The following figure provides the message flow for Phase 3: 542 ,--------. ,----------. 543 |EAP Peer| |EAP Server| 544 `---+----' `----+-----' 545 | [1] EAP-Request/EAP-CREDS(Type=Validate) | ,-----------!. 546 | { Cred-Info, Challenge } | |Phase Three|_\ 547 | <----------------------------------------- |Begins | 548 | | `-------------' 549 | [2] EAP-Response/EAP-CREDS(Type=Validate)| ,-----------!. 550 | { Challenge-Response } | |Phase Three|_\ 551 | -----------------------------------------> |Ends | 552 | | `-------------' 553 | | 555 EAP-CREDS Phase Three Message Flow 557 Phase three is optional and it is used by the server to request the 558 client to validate (proof) that the new credentials have been 559 installed correctly before issuing the final Success message. 561 NOTE WELL: Phase Three introduces a dependency on the selected 562 hashing algorithm to provide common and easy way to check the 563 integrity and functionality of a newly installed set of 564 credentials. 566 [1] The Server sends EAP-Request/EAP-CREDS(Type=Validate) 568 In order to start Phase Three, the Server sends an EAP-Request/ 569 EAP-CREDS(Type=Validate) message to the Peer. The Server MUST 570 include the ('Credentials-Info') TLV to provide the indication 571 about which set of credentials the Server intends to validate. 572 The Server MUST also include a randomly generated challenge in the 573 message to the client. The type of challenge determines how the 574 ('Challenge-Response') is calculated. EAP-CREDS defines the 575 asymmetric and symmetric challenges in Section 7.6 and others can 576 be defined according to the specified rules. 578 As usual, the Server MUST set, in the headers, the 'S' bit to '1' 579 in its first message of Phase Three and the 'Phase' value shall be 580 set to '3' (beginning of Phase Three). 582 [2] The Peer sends EAP-Response/EAP-CREDS(Type=Validate) 584 When the client receives the Validate message from the server, it 585 calculates the response to the challenge and sends the response 586 back to the server in a EAP-Response/EAP-CREDS(Type=Validate) 587 message. When the EAP-CREDS-ASYMMETRIC-CHALLENGE and EAP-CREDS- 588 SYMMETRIC-CHALLENGE values are used in the Challenge type, the 589 Peer MUST calculate the response as follows: 591 Public-Key 593 For any public-key based credentials (e.g., certificates or 594 raw key pairs), the response to the challenge is calculated 595 by generating a signature over the hashed value of the 596 challenge. The hashing algorithm to be used for this 597 purpose is specified in Section 2.6. The format of the 598 signature in the ('Challenge-Response') TLV is the 599 concatenation of: 601 - The signatureAlgorithm (DER encoded) which contains the 602 identifier for the cryptographic algorithm used by the 603 Peer to generate the signature. [RFC3279], [RFC4055], 604 and [RFC4491] list supported signature algorithms, but 605 other signature algorithms MAY also be supported. The 606 definition of the signatureAlgorithm is provided in 607 Section 4.1.1.2 of [RFC5280]. 609 - The signatureValue (DER encoded) which contains the 610 digital signature itself. The signature value is encoded 611 as a BIT STRING and the details of how to generate the 612 signatures' structures can be found in Section 4.1.1.3 of 613 [RFC5280] and referenced material. 615 Symmetric Secret 617 For any symmetric based credentials (e.g., password or Key), 618 the response to the challenge is calculated by using the 619 selected hash function (see Section 2.6) on the 620 concatenation of (a) the value carried in the server- 621 provided ('Challenge-Data') TLV, and (b) the secret value 622 itself (salted hash). 624 The initial values for the type of challenges are described in the 625 Section 7.6. Other types of challenges MAY be defined according 626 to the specified procedures. 628 In case of issues with the validation of newly deployed 629 credentials, both the Server and the Peer should consider those 630 credentials invalid (or unusable) and should issue the required 631 failure message(s). 633 4. EAP-CREDS Message Format 635 The EAP-CREDS defines the following message types: 637 1. EAP-CREDS/Init 639 2. EAP-CREDS/Provisioning 641 3. EAP-CREDS/Validate 643 Each of these message types have the basic structure as identified in 644 Section 4.1. EAP-CREDS messages contain zero, one, or more TLVs. 645 The internal structure of the different types of TLVs is described in 646 Section 4.2, while a detailed description of the EAP-CREDS message 647 types is provided in Section 5. 649 4.1. Message Header 651 The EAP-CREDS messages consist of the standard EAP header (see 652 Section 4 of [RFC3748]), followed by the version of the EAP-CREDS (4 653 bits) and a field (4 bits) reserved for future use. The header has 654 the following structure: 656 0 1 2 3 657 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 658 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 659 | Code | Identifier | Length | 660 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 661 | Type |J|S|F|D| Phase | Message Length | 662 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 663 | Message Length | Data ... 664 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-. 666 Where the Code, Identifier, Length, and Type fields are all part of 667 the EAP header as defined in [RFC3748]. Since EAP-CREDS can only be 668 used as a tunneled mechanism, the presence of these fields is only 669 for backward compatibility with existing parsers. In particular, the 670 'Length' field is not used (can be ignored): the message length is 671 carried in the 'Message Length' field instead. 673 The Type field in the EAP header is for EAP-CREDS. 675 The Flags bitfield is used to convey status information (e.g., extra 676 long message, phase number, phase transitioning state). The 677 transition-control bit (i.e., the 'S' bit) are set in Server's 678 messages and are ignored in Peer's messages (the Server is the entity 679 that unilaterally controls the phase transition process). The 680 meanings of the bits in the 'Flags' field are as follows: 682 Bit 'J' (Jumbo Message) - If set, it indicates the presence of the 683 'Message Length' field. This bit SHALL be used only when the size 684 of the message exceeds the maximum value allowed in the 'Length' 685 field. In this case, the 'Message Length' field is added to the 686 message and set to the whole message size and the 'Length' field 687 is used for the current fragment length. If not set, the 'Message 688 Length' field is not present in the Message and the 'Length' field 689 is used for the message size (and the 'F' bit MUST be set to '0'). 691 Bit 'S' (Start) - If set, this message is the first one of a new 692 EAP-CREDS phase. The value of the new phase is encoded in the 693 'Phase' field. 695 Bit 'F' - If set, this message is a fragment of a message. In 696 this case, the 'Data' field is to be concatenated with all 697 messages with the 'F' bit set to '1' until the message with the 698 'F' bit set to '0' that indicates the end of the message. If the 699 message is not fragmented, the 'F' bit MUST be set to '0'. The 700 use of this bit is required when the tunneling method does not 701 provide support for messages up to 2^32 bits in size. 703 Bit 'D' - This bit is used in Phase Two and Phase Three to 704 indicate that the specific operation for the identified credential 705 is over. For example, when multiple credentials exist on the Peer 706 and the Server needs to manage and validate one of them. In its 707 last message, when the provisioning protocol is done, the server 708 sets the 'D' (Done) bit to indicate that it is done. The Peer, in 709 its reply, sets the bit to indicate the end of provisioning for 710 this credentials is also over. After that, the Server can 711 continue Phase Two, transition to Phase Three, or terminate the 712 EAP session. 714 The Phase field is a 4-bits value and identifies the EAP-CREDS phase 715 for the current message. The version of EAP-CREDS described in this 716 document supports three values for this field: 718 0x01 - Phase One 720 0x02 - Phase Two 722 0x03 - Phase Three 724 A detailed explanation of the 'Phase' and 'Flags' fields of the 725 message headers is provided in Section 3.2. 727 The Data field is the message payload. The full description of this 728 field is provided in the next section. 730 4.2. Message Payload 732 The Data part of the message is organized as zero, one, or more TLV 733 objects whose structure is defined in this section. 735 Each TLV object has the same basic structure that is defined as 736 follows: 738 0 1 2 3 739 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 740 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 741 | TLV Type | TLV Length | 742 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 743 | TLV Value ... 744 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 746 Where: 748 TLV-Type (uint8) 750 This field is used to indicate the type of data that the TLV 751 carries. The type of TLV determines its internal structure. The 752 supported values for this fields are provided in the following 753 table: 755 Length (uint24) 757 This field carries the size of the value of the TLV. In 758 particular, the overall size of a TLV (i.e., the header plus the 759 value) can be calculated by adding the size of the header (6 760 octets) to the value of the Length field (i.e., the size of the 761 TLV's value). 763 +----------+--------------------------+------------------------+ 764 | TLV Name | TLV Type | Scope/Usage | 765 +----------+--------------------------+------------------------+ 766 | | Action TLV | Phase Two | 767 | | Certificate-Data TLV | Phase Two | 768 | | Challenge-Data TLV | Phase Two, Phase Three | 769 | | Challenge-Response TLV | Phase Two, Phase Three | 770 | | Credentials-Data TLV | Phase Two | 771 | | Credentials-Info TLV | Phase Two, Phase Three | 772 | | Error TLV | All Phases | 773 | | Network-Usage TLV | Phase One | 774 | | Profile TLV | Phase Two | 775 | | Protocol TLV | Phase One, Phase Two | 776 | | Provisioning-Data TLV | Phase Two | 777 | | Provisioning-Headers TLV | Phase Two | 778 | | Provisioning-Params TLV | Phase Two | 779 | | Token-Data TLV | Phase One | 780 | | Version TLV | Phase One | 781 +----------+--------------------------+------------------------+ 783 Table 2: EAP-CREDS Supported TLVs Types 785 TLV Value ( > 1 octet ) 787 This field carries data for the identified TLV. The internal 788 structure is determined by the TLV Type field. 790 The rest of this section describes the structure of the different 791 supported TLVs and their usage in the different messages. 793 4.3. EAP-CREDS defined TLVs 795 EAP-CREDS messages's payload comprises zero, one, or more TLVs that 796 are encoded in a single EAP-CREDS message. The values for the TLV 797 Type that are supported by this specifications are listed in Table 2. 799 4.3.1. The Action TLV 801 0 1 2 3 802 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 803 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 804 | TLV Type | TLV Length | 805 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 806 | Flags | Action Type | 807 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 809 TLV Type (uint8) 811 - Action TLV 813 TLV Length (uint24) 815 Fixed value (=2) 817 Flags (uint8) 819 Reserved 821 4.3.2. The Certificate-Data TLV 823 0 1 2 3 824 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 825 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 826 | TLV Type | TLV Length | 827 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 828 | Flags | Encoding | Value ... 829 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 831 TLV Type (uint8) 833 - Certificate-Data TLV 835 Length (uint24) 837 Provides the length of the TLV (> 3 octets) 839 Flags (uint8) 841 Provides a BITMASK that can be used to provide additional 842 information related to the encapsulated certificate. The bits 843 have the following meaning: 845 Bit 0 - If set, the certificate is trusted (Trust Anchor) 847 Bit 1 - If set, the certificate is a CA certificate 849 Bit 2 - If set, the certificate is self-signed 851 Bit 3 - If set, the certificate is a proxy certificate 853 Bit 4 - If set, the certificate is an attribute certificate 854 Bit 5 - Reserved 856 Bit 6 - Reserved 858 Bit 7 - Reserved 860 For a Trusted Root CA, the value of the flags shall be 0x7 (0000 861 0111). For an intermediate CA certificate that is not implicitly 862 trusted, the value of the flags field should be set to 0x02 (0000 863 0010). For an End-Entity certificate, the value of the Flags will be 864 0x0 (0000 0000). 866 Format (uint8) 868 Provides the indication of the Format the certificate is in. The 869 allowed values for this field are listed in Section 7.5. 871 Encoding (uint8) 873 Provides the indication of the Encoding the certificate is in. 874 The allowed values for this field are listed in Section 7.8. 876 Value (octet string) 878 This field carries the data for the certificate. 880 4.3.3. The Challenge-Data TLV 882 0 1 2 3 883 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 884 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 885 | TLV Type | TLV Length | 886 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 887 | Ch. Type | Challenge Data ... 888 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 890 TLV Type (uint8) 892 - Challenge-Data TLV 894 Length (uint24) 896 3 octets 898 Challenge Type (uint8) 899 This field carries the type of Challenge. In particular, the 900 challenge type determines how the Peer MUST calculate the 901 ('Challenge-Response'). The initial values for this field are 902 listed in Section 7.6. Please refer to Section 3.5 for a detailed 903 explanation of how to calculate the response to the challenge for 904 the challenge types defined in this document. 906 Challenge Data (> 1 octet) 908 This field carries the data to be used as a challenge when 909 validating newly deployed credentials. 911 4.3.4. The Challenge-Response TLV 913 0 1 2 3 914 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 915 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 916 | TLV Type | TLV Length | 917 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 918 | Challenge Response ... 919 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 921 TLV Type (uint8) 923 - Challenge-Response TLV 925 Length (uint24) 927 3 octets 929 Challenge Response (> 1 octet) 931 This field carries the data that resulted from the use of the 932 credentials to be validated. 934 4.3.5. The Credentials-Information TLV 935 0 1 2 3 936 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 937 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 938 | TLV Type | TLV Length | 939 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 940 | Flags | CredsType | ProtoID | 941 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 942 | | 943 | IssuedOn (GMT) | 944 | | 945 | | 946 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 947 | | 948 | Expires On (GMT) | 949 | | 950 | | 951 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 952 | Credentials Length | 953 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 954 | CredIDValue ... 955 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 957 The Credential-Information TLV is used by the Peer to provide a 958 description of the installed credentials that are relevant for the 959 network that is being accessed. 961 For example, when a set of credentials need to be renewed, the server 962 checks the ('Credentials-Info') from the Peer and eventually selects 963 the right one for renewal. The TLV structure is as follows: 965 TLV Type (uint8) 967 - Credentials-Information TLV 969 Length (uint24) 971 Provides the total length of the body of the Credential- 972 Information TLV. 974 Flags (uint8) 976 Provides a BITMASK that can be used to provide information about 977 the status of the credentials (e.g., if the use marks the 978 credentials to be compromised). The bits have the following 979 meaning: 981 Bit 0 - If set, the credential is marked as compromised 982 Bit 1 - If set, the credential is immutable and cannot be 983 updated 985 Bit 2 - Private Key or Secret Immutable, the public part of the 986 credential (e.g., a certificate) can still be updated 988 Bit 3 - If set, the credential cannot be updated (both public 989 and private parts) 991 Bit 4 - If set, the credential is ready to be used 993 Bit 5 - If set, the credential was generated on the server 995 Bit 6 - If set, the Peer would like to update the credential 996 even if they are not expired 998 Bit 7 - Reserved 1000 CredType (uint8) 1002 This field provides the description of the type of credential. 1003 The type of credentials are listed in Section 7.3 1005 ProtoID (uint16) 1007 This field indicates the protocol that was used to retrieve the 1008 target credential. When the TLV is used in a Request by the 1009 Server, this field is ignored. The values for this field are 1010 listed in Section 7.1. 1012 IssuedOn (16 octets) 1014 This field carries the GMT date for when this credential was 1015 issued. This field is 16 bytes long (the last byte must be set to 1016 '0x00') and contains the NULL-terminated ASCII string that 1017 represents the timestamp where the credential was issued. When 1018 the value is not set, the field should be set to { 0x00 }. The 1019 format of the string is as follows: 1021 YYYYMMDDHHmmssZ 1023 Where: 1025 YYYY - is the 4 digits representation of the year 1027 MM - is the 2 digits representation of the month 1028 DD - is the 2 digits representation of the day of the month 1030 HH - is the 2 digits representation of the hour of the day (24 1031 hour format) 1033 mm - is the 2 digits representation of the minutes of the hour 1035 ss - is the 2 digits representation of the seconds of the 1036 minute 1038 Z - is the character 'Z' 1040 ExpiresOn (16 octets) 1042 This field carries the GMT date for when this credential is to be 1043 considered expired. This field is 16 bytes long (the last byte 1044 must be set to '0x00') and contains the NULL-terminated ASCII 1045 string that represents the timestamp where the credential was 1046 issued. The format is the same as the ('IssuedOn') field. When 1047 the value is not set, the field should be set to { 0x00 }. 1049 Credentials Length (uint16) 1051 Length (in bytes) of the Credentials value. When used with a 1052 public-key type of credentials, this is the size of the key (e.g., 1053 for an RSA 2048 bit keys, this field should carry the value of 1054 256). When used with a symmetric secret, this field carries the 1055 size of the secret (in bytes). 1057 CredIDValue (> 1 octet) 1059 The binary value of the credentials' identifier. This identifier 1060 can be the binary value of the SHA-256 calculated over the 1061 certificate, a username, or it could be a random handle. As long 1062 as the ID allows the peer and the server to uniquely (in its 1063 context) identify the credentials, the value of this field can be 1064 calculated in any way. 1066 4.3.6. The Credentials-Data TLV 1067 0 1 2 3 1068 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1069 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1070 | TLV Type | TLV Length | 1071 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1072 | Cred Type | Format | Encoding | Value ... 1073 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1075 TLV Type (uint8) 1077 - Credentials-Data TLV 1079 Length (uint24) 1081 Provides the length of the TLV (> 3 octets) 1083 Cred Type (uint8) 1085 Provides the indication of the type of credentials. The allowed 1086 values for this field are listed in Section 7.3. 1088 Format (uint8) 1090 Provides the indication of the Format the credentials are in. The 1091 allowed values for this field are listed in Section 7.5. 1093 Encoding (uint8) 1095 Provides the indication of the Encoding the credentials are in. 1096 The allowed values for this field are listed in Section 7.8. 1098 Value (octet string) 1100 This field carries the data for the credentials. 1102 4.3.7. The Error TLV 1103 0 1 2 3 1104 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1105 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1106 | TLV Type | TLV Length | 1107 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1108 | EAP-CREDS Error Code | Secondary Error Code | 1109 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1110 | Description ... 1111 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1113 TLV Type (uint8) 1115 - Challenge-Response-Data TLV 1117 Length (uint24) 1119 3 octets 1121 EAP-CREDS Error Code (2 octets) 1123 This field carries the EAP-CREDS error code. These code are 1124 related to the EAP-CREDS operations only and it should not be used 1125 to carry the Provisioning-Protocol specific error codes. 1127 The error codes supported by this specifications are listed in 1128 Section 4.3.7. 1130 Secondary Error Code (2 octets) 1132 This field is used to convey an error at the encapsulation layer 1133 (i.e., the provisioning protocol error). For example, this field 1134 can be used to convey a transport protocol error code (e.g., HTTP 1135 status code). Do not use this field to convery EAP-CREDS specific 1136 errors. 1138 Description ( > 1 octet) 1140 The Description field is optional (i.e., when the Description Size 1141 is set to zero) and carries information about the error that 1142 occurred. The message may or may not be used by a user or an 1143 automated process for debugging purposes. 1145 4.3.8. The Network-Usage TLV 1146 0 1 2 3 1147 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1148 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1149 | TLV Type | TLV Length | 1150 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1151 |U| Desc Format | Encoding | Network-Usage Data ... 1152 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1154 TLV Type (uint8) 1156 - Network-Usage TLV 1158 Length (uint24) 1160 Variable Length TLV (Value must be > 2 ) 1162 Description Format (uint8) 1164 The Type of data encoded in the Peer Description Data. The 1165 initial values for this field are listed in Section 7.10. 1167 Encoding (uint8) 1169 Provides the indication of the Encoding the network usage 1170 description data is in. The allowed values for this field are 1171 listed in Section 7.8. 1173 The 'U' field (1 bit) 1175 The 'URL' bit ('U') is used to indicate if the value of the 1176 Network-Usage Data field is to be interpreted as a URL or as the 1177 actual data. In particular, if the value in the 'URL' bit is '1', 1178 then the value in the Network-Usage Data field is to be 1179 interpreted as the URL where the actual data can be downloaded 1180 from. Otherwise, if the 'URL' bit is set to '0', then the value 1181 in the Network-Usage Data field is to be interpreted as the actual 1182 data (not a URL referencing it). 1184 An example use of this bit is when the Peer wants to convey the 1185 URL of the MUD file [RFC8520]. In this case, the Peer can set the 1186 Network-Usage Data field to the Url of the MUD file related to the 1187 Peer. 1189 Desc Format (7 bits) 1191 This field provide the expected data format for the Network-Usage 1192 Data. For example, the value in this field could be set to 'MUD' 1193 and have the 'U' bit set to '1' to provide the MUD-related 1194 information at credentials management time instead of at network- 1195 provisioning time (DHCP option). This possibility could help the 1196 Network controller to decide if the device shall be allowed to 1197 register its credentials or not. 1199 The list of initial values for this field is provided in 1200 Section 7.7. 1202 Network-Usage Data (octet string) 1204 This is additional information related to the device. In 1205 particular, this TLV can be used by the Peer to provide the Server 1206 with the description of the intended network usage or a URL that 1207 points to the same information. 1209 For example, this field can be used to convey a MUD file 1210 (Manufacturer Usage Description) or the latest firmware-update 1211 manifest. 1213 4.3.9. The Profile TLV 1215 0 1 2 3 1216 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1217 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1218 | TLV Type | TLV Length | 1219 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1220 | Profile Identifier ... 1221 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1223 TLV Type (uint8) 1225 - Profile Identifying Data TLV 1227 Length (uint24) 1229 Length value should be >= 1 1231 Profile Identifier (octet string) 1233 The Profile Identifier is used to provide indication to the other 1234 party about which profiles are supported when requesting 1235 credentials management. 1237 Also in this case, the data used in this field is left to be 1238 interpreted by the end-point and it is independent from the EAP- 1239 CREDS data types. This could be a raw byte value, a string, or a 1240 more complex structured data (e.g., an OID). 1242 An example of values for this field, an end-point could use the 1243 string representation (i.e., dotted representation) of the Object 1244 Identifier (OID) of the specific profile supported (e.g., could be 1245 defined in the Certificate Policy of the credentials' provider). 1247 4.3.10. The Protocol TLV 1249 0 1 2 3 1250 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1251 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1252 | TLV Type | TLV Length | 1253 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1254 | Protocol ID | Version | 1255 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1257 TLV Type (uint8) 1259 - Protocol TLV 1261 TLV Length (uint24) 1263 Fixed TLV Length value of 4. 1265 Protocol ID (uint16) 1267 The Protocol ID value carries the id of a supported provisioning 1268 protocol. The initial list of values for the provisioning 1269 protocol identifiers can be found in Section 7.1. 1271 Version (uint16) 1273 The Version (Protocol Version) value represents the specific 1274 version of the identified provisioning protocol. When no version 1275 is specified for a protocol (i.e., either it does not support 1276 multiple versions or it does not matter), the value of this field 1277 should be set to '0x0'. 1279 4.3.11. The Provisioning-Data TLV 1280 0 1 2 3 1281 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1282 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1283 | TLV Type | TLV Length | 1284 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1285 | Provisioning Data ... 1286 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1288 TLV Type (uint8) 1290 - Provisioning-Data TLV 1292 Length (uint24) 1294 3 octets 1296 Headers Data (> 1 octet) 1298 This field carries the provisioning protocol's messages. 1300 4.3.12. The Provisioning-Headers TLV 1302 0 1 2 3 1303 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1304 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1305 | TLV Type | TLV Length | 1306 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1307 | Headers Data ... 1308 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1310 TLV Type (uint8) 1312 - Provisioning-Headers TLV 1314 Length (uint24) 1316 3 octets 1318 Headers Data (> 1 octet) 1320 This field carries the meta-data (if any) that might be associated 1321 with the transport-layer normally used with the provisioning 1322 protocol. For example, this TLV can carry the set of HTTP headers 1323 required by EST or ACME. 1325 4.3.13. The Provisioning-Params TLV 1327 0 1 2 3 1328 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1329 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1330 | TLV Type | TLV Length | 1331 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1332 | Min Length | Max Length | 1333 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1334 | Algorithm | Flags | OBJECT IDENTIFIER (DER) ... 1335 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1337 TLV Type (uint8) 1339 - Provisioning-Params TLV 1341 Length (uint24) 1343 Provides the length of the TLV (>= 6 octets) 1345 Min Length (uint16) 1347 Provides the minimum allowed size size for the credentials. This 1348 value has meaning depending on the context of the credentials, 1349 however sizes are always expressed in bytes. 1351 For example, when used with a symmetric key or a password, the 1352 ('Min Length') and ('Max Length') refer to the minimum and maximum 1353 size of the password data. The ('Algor OID') field can be omitted 1354 in this case. 1356 On the other hand, when referring public-key credentials, this 1357 field should carry the size of the modulus of the key. For 1358 example, for an RSA 2048 bit keys, the field should carry the 1359 value of 256. For an ECDSA that uses the prime256r1 curve, this 1360 field should carry the value of 32 and the Algor OID should be the 1361 DER representation of the specific value of the curve (i.e., the 1362 DER representation of '1.2.840.10045.3.1.7'). 1364 Max Length (uint16) 1366 Provides the indication maximum size of the credentials. This 1367 value has meaning depending on the context of the credentials, 1368 however sizes are always expressed in bytes. 1370 The same considerations apply to this field as well as the ('Min 1371 Length') one discussed above. 1373 Flags (uint8) 1375 Provides a BITMASK that can be used to provide information about 1376 the status of the credentials (e.g., if the use marks the 1377 credentials to be compromised). The bits have the following 1378 meaning: 1380 Bit 0 - Credentials (or part of it) are to be generated on the 1381 server 1383 Bit 1 - Credentials (or part of it) are to be generated on the 1384 peer 1386 Bit 2 - Credentials are to be generated on dedicated hardware 1388 Bit 3 - Reserved 1390 Bit 4 - Reserved 1392 Bit 5 - Reserved 1394 Bit 6 - Reserved 1396 Bit 7 - Reserved 1398 When using public-key based credentials, the bits 0 and 1 are 1399 mutually exclusive. 1401 When using passwords or shared secrets, if bit 0 is set, then the 1402 secret is generated by the server and then sent to the client. On 1403 the other hand, if bit 1 is set, then the secret is generated by 1404 the peer and then sent to the server. Ultimately, if both bits 1405 are set, then the Server generates the first part of the password 1406 and sends it to the Peer, while the Peer generates the second part 1407 of the password and sends it to the Server. The password to be 1408 used for future authentication is the concatenation of the two 1409 shares of the password: first the one from the Server, then the 1410 one from the Client. 1412 NOTE WELL: Last but not least, since these passwords/secrets 1413 are meant to be used in a automated fashion, there is no 1414 restriction around the character set to use or their 1415 interpretation. Therefore, it is good practice to generate 1416 random pass-phrases that use the full 8-bit character set (on 1417 client and server) to maximize the secret's search space. 1419 Algorithm (uint8) 1421 Provides the indication of the algorithm used for the generation 1422 of the credentials. The allowed values for this field are listed 1423 in Section 7.4. 1425 Object Identifier (binary; > 1 octet) 1427 Provides the indication of additional parameters that are needed 1428 to be encoded for the credentials. This value is used only when 1429 the credentials use public-key cryptography - this field carries 1430 additional information about the generation algorithm to be used. 1431 We provide some useful values that can be used as reference: 1433 +----------------+----------------------+---------------------------+ 1434 | OID Name | Dotted | Binary Encoding | 1435 | | Representation | | 1436 +----------------+----------------------+---------------------------+ 1437 | secp256r1 | 1.2.840.10045.3.1.7 | 06 08 2A 86 48 CE 3D 03 | 1438 | curve | | 01 07 | 1439 | secp384r1 | 1.2.840.10045.3.1.34 | 06 08 2A 86 48 CE 3D 03 | 1440 | curve | | 01 22 | 1441 | secp521r1 | 1.2.840.10045.3.1.35 | 06 08 2A 86 48 CE 3D 03 | 1442 | curve | | 01 23 | 1443 | X25519 curve | 1.3.101.110 | 06 03 2B 65 6E | 1444 | X25519 curve | 1.3.101.110 | 06 03 2B 65 6E | 1445 | X448 curve | 1.3.101.111 | 06 03 2B 65 6F | 1446 | Ed25519 curve | 1.3.101.112 | 06 03 2B 65 70 | 1447 | Ed448 curve | 1.3.101.113 | 06 03 2B 65 71 | 1448 +----------------+----------------------+---------------------------+ 1450 Table 3: Object Identifiers Examples 1452 4.3.14. The Token-Data TLV 1454 0 1 2 3 1455 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1456 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1457 | TLV Type | TLV Length | 1458 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1459 | Token Type | Encoding | Value ... 1460 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1462 TLV Type (uint8) 1464 - Token-Data TLV 1466 TLV Length (uint24) 1468 Provides the length of the TLV (> 3 octets) 1470 Token Type (uint8) 1472 Provides the indication of the type of credentials. The allowed 1473 values for this field are listed in Section 7.2. 1475 Encoding (uint8) 1477 Provides the indication of the Encoding the credentials are in. 1478 The allowed values for this field are listed in Section 7.8. 1480 Value (octet string) 1482 This field carries the data for the credentials. 1484 4.3.15. The Version TLV 1486 0 1 2 3 1487 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1488 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1489 | TLV Type | TLV Length | 1490 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1491 | Version | 1492 +-+-+-+-+-+-+-+-+ 1494 TLV Type (uint8) 1496 - Version TLV 1498 TLV Length (uint24) 1500 Provides the length of the TLV. The field has a fixed value of 1. 1502 Version (uint8) 1504 The Version field represents the specific version of the EAP-CREDS 1505 protocol that are supported by the end point. When multiple 1506 versions of EAP-CREDS are supported, multiple ('Version') TLVs can 1507 be used. 1509 When no version is specified (i.e., either it does not support 1510 multiple versions or it does not matter), the value of this field 1511 should be set to '0x0' (any version). 1513 5. EAP-CREDS Messages 1515 This section describes each message and what TLVs are allowed or 1516 required. EAP-CREDS defines the following values for the Message 1517 Type (Type): 1519 +-----------+------------------------+------------------------------+ 1520 | Message | Name | Description | 1521 | Type | | | 1522 +-----------+------------------------+------------------------------+ 1523 | 0 | EAP-CREDS-Init | Initialization Phase | 1524 | 1 | EAP-CREDS-Provisioning | Carries Provisioning | 1525 | | | Protocol Messages | 1526 | 2 | EAP-CREDS-Validate | Validates newly installed | 1527 | | | credentials | 1528 +-----------+------------------------+------------------------------+ 1530 Table 4: EAP-CREDS Message Types 1532 5.1. The EAP-CREDS-Init Message 1534 The EAP-CREDS-Init message type is used in Phase One only of EAP- 1535 CREDS. The message flow is depicted in Section 3.3. This message 1536 supports the following TLVs: Version, Protocol, Credentials-Info, and 1537 Error. 1539 5.1.1. EAP Server's Init Message 1541 EAP-CREDS starts with an ('EAP-CREDS-Init') message from the server. 1542 This message MAY contain zero, one, or more ('Version') TLVs and, 1543 optionally, a ('Challenge-Data') TLV. 1545 The first message from the server is the one that starts Phase One, 1546 therefore the Server MUST set the headers' 'S' bit to '1' (Start) and 1547 the headers' 'Phase' value to '1' (Phase One). 1549 The Server uses one or more ('Version') TLVs in the EAP-Request/EAP- 1550 CREDS(Type=Init) message to provide the Peer with the list of EAP- 1551 CREDS versions supported. If omitted, the implicit version of EAP- 1552 CREDS used in the session is one ('0x1'). If the Server detects 1553 multiple occurrences of this TLV in the reply from the Peer, an error 1554 shall be issued and the EAP-CREDS session should be terminated. 1556 In case Token-Based registration is enabled on the Server, the Server 1557 MUST include, in its Init message, a ('Challenge-Data') field that 1558 can be used by the client to provide challenge data for proof-of- 1559 possession of secrets. 1561 5.1.2. EAP Peer's Init Message 1563 The Peer MUST reply to the Server's ('EAP-CREDS-Init') message with 1564 its own ('EAP-CREDS-Init') one. The Peer SHOULD include one 1565 ('Version') TLV in its first message to indicate the version of EAP- 1566 CREDS that the client wants to use for the session. The Peer MUST 1567 also provide the list of supported provisioning protocols (via one or 1568 more the 'Protocol' TLV), the list and status of the installed 1569 credentials (via the 'Credentials-Info' TLV). The Peer MAY include 1570 authorization data when registering new credentials (e.g., an 1571 authorization token or a device certificate) via the ('Token-Data') 1572 and ('Challenge-Response') TLV. 1574 The Peer MUST include one ('Credentials-Info') TLV for each 1575 credential the Network is authorized to manage. Typically, a Peer 1576 will include only one ('Credentials-Info') TLV in its ('EAP-CREDS- 1577 Init') message, but there might be cases where multiple types of 1578 credentials are available and selected depending on the location and 1579 other factors (e.g., X.509 certificate and username/password 1580 combination). 1582 In case the Peer does not have any credentials available yet, it does 1583 not add any ('Credentials-Info') TLV - leaving the Server with the 1584 only action possible: Registration. In this case, the Peer SHOULD 1585 include authorization information via the ('Token-Data') TLV as 1586 described in Section 5.1.2.1. Additionally, the Peer can add the 1587 ('Profile') TLV to indicate a preferred profile for the credentials. 1589 5.1.2.1. Bootstrapping Peer's Trustworthiness 1591 When the Peer does not have any valid credentials for the Network 1592 that it is authenticating to, it does not provide any ('Credentials- 1593 Info') TLV. This indicates to the Server that new credentials MUST 1594 be registered before the Peer is allowed on the network. 1596 The Registration process might rely on information exchanged during 1597 the Provisioning Process in Phase Two. However, if an authorization 1598 mechanism is not available from the supported provisioning protocol 1599 and no credentials are available on the Peer, EAP-CREDS provides a 1600 simple mechanism for the Peer to leverage an out-of-band 1601 token/passphrase/ott that may be already available on the Peer (e.g., 1602 a device certificate or a 'spendable' credentials token like a 1603 kerberos ticket or a crypto-currency transaction) and that can be 1604 verified by the Server. 1606 In particular, when the Peer wants to register new credentials (and 1607 the Server requires the use of additional authorization data) it may 1608 need to provide (a) a Token, (b) a challenge value, and (c) a 1609 response to the challenge value. To do so, the Peer MUST encode the 1610 token in a ('Token-Data') TLV, the challenge value in a ('Challenge- 1611 Data') TLV, and, finally, the response to the challenge in the 1612 ('Challenge-Response') TLV. 1614 The use of ('Challenge-Data') and ('Challenge-Response') TLVs is 1615 optional, however it is suggested that if a token is used for 1616 bootstrapping the trust, it should provide a way to verify a secret 1617 associated with it. 1619 It is also very important that the authorization token is disclosed 1620 only to authorized servers - the Peer MUST NOT disclose authorization 1621 tokens that are not meant for the network that is being accessed. 1622 This can be done, usually, by verifying the identity of the Server 1623 first (in the outer mechanism) and then verify that the target of the 1624 Token is the Server the Client is talking to. 1626 5.1.3. The EAP-CREDS-Provisioning Message 1628 The EAP-CREDS-Provisioning message type is used in Phase Two only of 1629 EAP-CREDS. The message flow is depicted in Section 3.4. This 1630 message type supports the following TLVs: Protocol, Profile, 1631 Credentials-Info, Provisioning-Headers, Provisioning-Data, Token- 1632 Data, and Error. 1634 After the exchange of phase one messages, the Server MAY start phase 1635 two by issuing an ('EAP-CREDS-Provisioning') message for the Peer 1636 where it encodes all the required details for starting the 1637 provisioning process. In particular, the server sends the selected 1638 ('Action'), ('Protocol'), and metadata to the client in a EAP- 1639 Request/EAP-CREDS(Type=Provisioning) message. The header's 'S' bit 1640 MUST be set to '1' (Start) and the 'Phase' value set to '2' (Phase 1641 Two begins). 1643 NOTE WELL: After the initial message, the only TLVs that are 1644 allowed in messages coming from the server are the usual 1645 ('Provisioning-Headers') ('Provisioning-Data'), and ('Error'). 1647 The client checks that all the selected parameters are supported for 1648 the selected credentials and, if no errors are detected, it sends its 1649 first ('EAP-CREDS-Provisioning') message to the Server with the 1650 ('Provisioning-Headers') and ('Provisioning-Data') TLVs only. 1652 From now on, the conversation between the Peer and the Server 1653 continues until an error is detected or the provisioning protocol 1654 completes successfully. 1656 If no other actions, the server MAY continue with phase three or 1657 issue a success message and terminate the EAP session. 1659 5.1.4. The EAP-CREDS-Validate Message 1661 The EAP-CREDS-Validate message type is used in Phase Three only of 1662 EAP-CREDS. The message flow is depicted in Section 3.5. This 1663 message type supports the following TLVs: Protocol, Credentials-Info, 1664 Provisioning-Headers, Provisioning-Data, Token-Data, and Error. 1666 After Phase One (and/or Phase Two) ends, the Server MAY start phase 1667 three by issuing an ('EAP-CREDS-Validate') message for the Peer where 1668 it encodes all the required details for starting the validation 1669 process. In particular, the server sends the ('Credentials-Info'), a 1670 ('Challenge'), and the ('Phase-Control') TLVs in a EAP-Request/EAP- 1671 CREDS(Type=Validate) message. The ('Phase-Control') TLV should carry 1672 the '1' value for the 'S' bit (Start) and the number '3' for its 1673 value (Phase Three begins). 1675 The Peer generates the answer to the Challenge and sends back a EAP- 1676 Response/EAP-CREDS(Type=Validate) message with the ('Challenge- 1677 Response') and an optional ('Challenge') field (only for server-side 1678 validation of the symmetric credentials). If the Peer requested 1679 server-side validation of the credentials, the Server MUST include 1680 (if a symmetric secret) the response to the Peer-issued ('Challenge') 1681 TLV by computing the response and adding it to the ('Challenge- 1682 Response') TLV in its reply. 1684 Finally, in the last message, the Server (if Phase Three is to be 1685 ended) SHALL include the ('Phase-Control') TLV with the 'S' bit set 1686 to '0' (end of phase) and the value set to '3' (Phase Three ended). 1688 At this point, EAP-CREDS has terminated all possible operations and 1689 can be terminated. The Server can now terminate the EAP session 1690 successfully. In case the Peer was not authenticated during the 1691 tunnel establishment (i.e., no credentials were already available on 1692 the Peer), the Server should terminate the EAP session with a Failure 1693 (thus requiring the device to re-attach and authenticate to the 1694 network - phase two should have provided the Peer with the 1695 credentials to use for authenticating to the Network). 1697 6. Error Handling in EAP-CREDS 1699 This section provides a description of the error handling by using 1700 the CREDS-Error-TLV in a CREDS message. 1702 7. IANA Considerations 1704 This document uses a new EAP type, EAP-CREDS, whose value (TBD) MUST 1705 be allocated by IANA from the EAP TYPEs sub-registry of the RADIUS 1706 registry. This section provides guidance to the Internet Assigned 1707 Numbers Authority (IANA) regarding registration of values related to 1708 the EAP-CREDS protocol, in accordance with [RFC8126]. 1710 The EAP Method Type number for EAP-CREDS needs to be assigned. 1712 This document also requires IANA to create new registries as defined 1713 in the following subsections. 1715 7.1. Provisioning Protocols 1717 +-----------------+-------------------------------------------------+ 1718 | Message Type | Purpose | 1719 +-----------------+-------------------------------------------------+ 1720 | 0 | Unspecified | 1721 | 1 | Simple Provisioning Protocol (SPP) | 1722 | 2 | Basic Certificate Management Protocol (CMP-S) | 1723 | 3 | Full Certificate Management Protocol (CMP-F) | 1724 | 4 | Enrollment over Secure Transport (EST) | 1725 | 5 | Certificate Management over CMS (CMC) | 1726 | 6 | Automatic Certificate Management Environment | 1727 | | (ACME) | 1728 | ... | ... | 1729 | 49141 ... 65534 | Vendor Specific | 1730 +-----------------+-------------------------------------------------+ 1732 Table 5: EAP-CREDS Inner Protocol Identifiers 1734 Assignment of new values for new cryptosuites MUST be done through 1735 IANA with "Specification Required" and "IESG Approval" as defined in 1736 [RFC8126]. 1738 7.2. Token Types 1739 +------------+-----------------+ 1740 | Token Type | Description | 1741 +------------+-----------------+ 1742 | 0 | Unspecified | 1743 | 1 | JWT | 1744 | 2 | Kerberos | 1745 | 3 | OAuth | 1746 | 4 | Certificate | 1747 | 200..254 | Vendor Specific | 1748 +------------+-----------------+ 1750 Table 6: Token Types 1752 Assignment of new values for new Message Types MUST be done through 1753 IANA with "Expert Review" as defined in [RFC8126]. 1755 7.3. Credentials Types 1757 +------------------+-----------------------+ 1758 | Credentials Type | Description | 1759 +------------------+-----------------------+ 1760 | 0 | X.509 Certificate | 1761 | 1 | Public Key | 1762 | 2 | Symmetric Key | 1763 | 3 | Username and Password | 1764 | 4 | AKA Subscriber Key | 1765 | 5 | Bearer Token | 1766 | 6 | One-Time Token | 1767 | 7 | API Key | 1768 +------------------+-----------------------+ 1770 Table 7: Credentials Types 1772 Assignment of new values for new Message Types MUST be done through 1773 IANA with "Expert Review" as defined in [RFC8126]. 1775 7.4. Credentials Algorithms 1776 +---------+--------------------+ 1777 | ID | Algorithm | 1778 +---------+--------------------+ 1779 | 0 | None | 1780 | 1 | RSA | 1781 | 2 | ECDSA | 1782 | 3 | XMMS | 1783 | 4 | AKA Subscriber Key | 1784 | 5 | OAuth | 1785 | 6 | Kerberos4 | 1786 | 7 | Kerberos5 | 1787 | 200-254 | Reserved | 1788 +---------+--------------------+ 1790 Table 8: Credentials Algorithms 1792 Assignment of new values for new Message Types MUST be done through 1793 IANA with "Expert Review" as defined in [RFC8126]. 1795 7.5. Credentials Datatypes 1797 +---------+---------------+ 1798 | ID | Data Type | 1799 +---------+---------------+ 1800 | 0 | None (Binary) | 1801 | 1 | PKCS#8 | 1802 | 2 | PKCS#10 | 1803 | 3 | PKCS#12 | 1804 | 4 | PublicKeyInfo | 1805 | 200-254 | Reserved | 1806 +---------+---------------+ 1808 Table 9: Credentials Datatypes 1810 Assignment of new values for new Message Types MUST be done through 1811 IANA with "Expert Review" as defined in [RFC8126]. 1813 7.6. Challenge Types 1815 +----+----------------------+ 1816 | ID | Data Type | 1817 +----+----------------------+ 1818 | 0 | Not Specified | 1819 | 1 | EAP-CREDS-ASYMMETRIC | 1820 | 2 | EAP-CREDS-SYMMETRIC | 1821 +----+----------------------+ 1823 Table 10: Challenge Type 1825 Assignment of new values for new Message Types MUST be done through 1826 IANA with "Expert Review" as defined in [RFC8126]. 1828 7.7. Network Usage Datatypes 1830 +--------+------------------------------------------+ 1831 | ID | Data Type | 1832 +--------+------------------------------------------+ 1833 | 0 | Vendor-Specific | 1834 | 1 | Manufacturer Usage Description [RFC8520] | 1835 | 2 | Network Access Granting System | 1836 | 3 | Firmware Manifest | 1837 | 4..127 | Reserved for Future Use | 1838 +--------+------------------------------------------+ 1840 Table 11: Network Usage Datatypes 1842 Assignment of new values for new Message Types MUST be done through 1843 IANA with "Expert Review" as defined in [RFC8126]. 1845 7.8. Credentials Encoding 1847 +---------+------------+ 1848 | ID | Encoding | 1849 +---------+------------+ 1850 | 0 | None (Raw) | 1851 | 1 | DER | 1852 | 2 | PEM | 1853 | 3 | Base64 | 1854 | 4 | JSON | 1855 | 5 | XML | 1856 | 6 | ASCII | 1857 | 7 | UTF-8 | 1858 | 200-254 | Reserved | 1859 +---------+------------+ 1861 Table 12: Credentials Encoding 1863 Assignment of new values for new Message Types MUST be done through 1864 IANA with "Expert Review" as defined in [RFC8126]. 1866 7.9. Action Types 1867 +---------+--------------+--------------------------------+ 1868 | ID | Data Type | Description | 1869 +---------+--------------+--------------------------------+ 1870 | 0 | Registration | Registers New Credentials | 1871 | 1 | Renewal | Renew an Existing Credential | 1872 | 2 | Remove | Removes an Existing Credential | 1873 | 200-254 | n/a | Reserved | 1874 +---------+--------------+--------------------------------+ 1876 Table 13: Action Types 1878 Assignment of new values for new Message Types MUST be done through 1879 IANA with "Expert Review" as defined in [RFC8126]. 1881 7.10. Usage Metadata Types 1883 +------+----------------------+ 1884 | Type | Description | 1885 +------+----------------------+ 1886 | 0 | Binary (Unspecified) | 1887 | 1 | MUD File | 1888 | 2 | TEEP Manifest | 1889 +------+----------------------+ 1891 Table 14: Usage Metadata Types 1893 Assignment of new values for new Message Types MUST be done through 1894 IANA with "Expert Review" as defined in [RFC8126]. 1896 8. Security Considerations 1898 Several security considerations need to be explicitly considered for 1899 the system administrators and application developers to understand 1900 the weaknesses of the overall architecture. 1902 The most important security consideration when deploying EAP-CREDS is 1903 related to the security of the outer channel. In particular, EAP- 1904 CREDS assumes that the communication channel has been properly 1905 authenticated and that the information exchanged between the Peer and 1906 the Server are protected (i.e., confidentiality and integrity). 1908 For example, if certificate-based authentication is used, the server 1909 presents a certificate to the peer as part of the trust establishment 1910 (or negotiation). The peer SHOULD verify the validity of the EAP 1911 server certificate and SHOULD also examine the EAP server name 1912 presented in the certificate in order to determine whether the EAP 1913 server can be trusted. When performing server certificate 1914 validation, implementations MUST provide support for the rules in 1915 [RFC5280] for validating certificates against a known trust anchor. 1917 9. Acknowledgments 1919 The authors would like to thank everybody who provided insightful 1920 comments and helped in the definition of the deployment 1921 considerations. 1923 10. Normative References 1925 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1926 Requirement Levels", BCP 14, RFC 2119, 1927 DOI 10.17487/RFC2119, March 1997, 1928 . 1930 [RFC3748] Aboba, B., Blunk, L., Vollbrecht, J., Carlson, J., and H. 1931 Levkowetz, Ed., "Extensible Authentication Protocol 1932 (EAP)", RFC 3748, DOI 10.17487/RFC3748, June 2004, 1933 . 1935 [RFC4210] Adams, C., Farrell, S., Kause, T., and T. Mononen, 1936 "Internet X.509 Public Key Infrastructure Certificate 1937 Management Protocol (CMP)", RFC 4210, 1938 DOI 10.17487/RFC4210, September 2005, 1939 . 1941 [RFC5272] Schaad, J. and M. Myers, "Certificate Management over CMS 1942 (CMC)", RFC 5272, DOI 10.17487/RFC5272, June 2008, 1943 . 1945 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1946 Housley, R., and W. Polk, "Internet X.509 Public Key 1947 Infrastructure Certificate and Certificate Revocation List 1948 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 1949 . 1951 [RFC6402] Schaad, J., "Certificate Management over CMS (CMC) 1952 Updates", RFC 6402, DOI 10.17487/RFC6402, November 2011, 1953 . 1955 [RFC7030] Pritikin, M., Ed., Yee, P., Ed., and D. Harkins, Ed., 1956 "Enrollment over Secure Transport", RFC 7030, 1957 DOI 10.17487/RFC7030, October 2013, 1958 . 1960 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 1961 Writing an IANA Considerations Section in RFCs", BCP 26, 1962 RFC 8126, DOI 10.17487/RFC8126, June 2017, 1963 . 1965 [RFC8520] Lear, E., Droms, R., and D. Romascanu, "Manufacturer Usage 1966 Description Specification", RFC 8520, 1967 DOI 10.17487/RFC8520, March 2019, 1968 . 1970 Author's Address 1972 Massimiliano Pala 1973 CableLabs 1974 858 Coal Creek Cir 1975 Louisville, CO 80027 1976 US 1978 Email: m.pala@openca.org 1979 URI: http://www.linkedin.com/in/mpala