idnits 2.17.1 draft-pala-eap-creds-03.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 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 == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: When registering new credentials, the first message from the Server, MUST not carry a ('Credentials-Info') TLV since there is no targeted credentials to apply the action on (i.e., for other actions - like 'renew' or 'remove' - the TLV would be required to identify the right set of credentials to renew or delete). -- The document date (June 10, 2019) is 1782 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 2229 -- Looks like a reference, but probably isn't: '2' on line 2235 -- Looks like a reference, but probably isn't: '3' on line 2239 -- Looks like a reference, but probably isn't: '4' on line 598 == Missing Reference: 'N' is mentioned on line 623, but not defined == Missing Reference: 'RFC3279' is mentioned on line 741, but not defined == Missing Reference: 'RFC4055' is mentioned on line 741, but not defined == Missing Reference: 'RFC4491' is mentioned on line 742, but not defined Summary: 0 errors (**), 0 flaws (~~), 7 warnings (==), 5 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 10, 2019 5 Expires: December 12, 2019 7 Credentials Provisioning and Management via EAP (EAP-CREDS) 8 draft-pala-eap-creds-03 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 12, 2019. 57 Copyright Notice 59 Copyright (c) 2019 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 . . . . . . . . . . . . . . . . . . . . 4 75 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 76 2.1. Overview of existing solutions . . . . . . . . . . . . . 5 77 2.2. Scope Statement . . . . . . . . . . . . . . . . . . . . . 5 78 2.3. EAP-CREDS as tunneled mechanism only . . . . . . . . . . 5 79 2.4. Fragmentation Support . . . . . . . . . . . . . . . . . . 6 80 2.5. Encapsulating Provisioning Protocols in EAP-CREDS . . . . 6 81 2.6. Algorithm Requirements . . . . . . . . . . . . . . . . . 7 82 2.7. Notation . . . . . . . . . . . . . . . . . . . . . . . . 7 83 3. EAP-CREDS Protocol . . . . . . . . . . . . . . . . . . . . . 7 84 3.1. Message Flow . . . . . . . . . . . . . . . . . . . . . . 7 85 3.1.1. Phase Transitioning Rules . . . . . . . . . . . . . . 8 86 3.2. Phase One: Initialization . . . . . . . . . . . . . . . . 9 87 3.2.1. Phase One State Machine . . . . . . . . . . . . . . . 11 88 3.3. Phase Two: Provisioning . . . . . . . . . . . . . . . . . 13 89 3.3.1. Phase Two State Machine . . . . . . . . . . . . . . . 14 90 3.4. Phase Three: Validation . . . . . . . . . . . . . . . . . 15 91 3.4.1. Phase Three State Machine . . . . . . . . . . . . . . 18 92 4. EAP-CREDS Message Format . . . . . . . . . . . . . . . . . . 19 93 4.1. Message Header . . . . . . . . . . . . . . . . . . . . . 20 94 4.2. Message Payload . . . . . . . . . . . . . . . . . . . . . 21 95 4.2.1. EAP-CREDS defined TLVs . . . . . . . . . . . . . . . 23 96 4.2.1.1. The Action TLV . . . . . . . . . . . . . . . . . 23 97 4.2.1.2. The Certificate-Data TLV . . . . . . . . . . . . 24 98 4.2.1.3. The Challenge-Data TLV . . . . . . . . . . . . . 25 99 4.2.1.4. The Challenge-Response TLV . . . . . . . . . . . 26 100 4.2.1.5. The Credentials-Information TLV . . . . . . . . . 26 101 4.2.1.6. The Credentials-Data TLV . . . . . . . . . . . . 29 102 4.2.1.7. The Error TLV . . . . . . . . . . . . . . . . . . 30 103 4.2.1.8. The Network-Usage TLV . . . . . . . . . . . . . . 31 104 4.2.1.9. The Profile TLV . . . . . . . . . . . . . . . . . 33 105 4.2.1.10. The Protocol TLV . . . . . . . . . . . . . . . . 34 106 4.2.1.11. The Provisioning-Data TLV . . . . . . . . . . . . 34 107 4.2.1.12. The Provisioning-Headers TLV . . . . . . . . . . 35 108 4.2.1.13. The Provisioning-Params TLV . . . . . . . . . . . 36 109 4.2.1.14. The Certificate-Request TLV . . . . . . . . . . . 38 110 4.2.1.15. The Storage-Info TLV . . . . . . . . . . . . . . 39 111 4.2.1.16. The Supported-Formats TLV . . . . . . . . . . . . 40 112 4.2.1.17. The Supported-Encoding TLV . . . . . . . . . . . 41 113 4.2.1.18. The Token-Data TLV . . . . . . . . . . . . . . . 41 114 4.2.1.19. The Version TLV . . . . . . . . . . . . . . . . . 42 115 5. EAP-CREDS Messages . . . . . . . . . . . . . . . . . . . . . 43 116 5.1. The EAP-CREDS-Init Message . . . . . . . . . . . . . . . 43 117 5.1.1. EAP Server's Init Message . . . . . . . . . . . . . . 43 118 5.1.2. EAP Peer's Init Message . . . . . . . . . . . . . . . 44 119 5.1.2.1. Bootstrapping Peer's Trustworthiness . . . . . . 44 120 5.2. The EAP-CREDS-ProtoFlow Message . . . . . . . . . . . . . 45 121 5.3. The EAP-CREDS-Validate Message . . . . . . . . . . . . . 46 122 6. Error Handling in EAP-CREDS . . . . . . . . . . . . . . . . . 47 123 7. The Simple Provisioning Protocol (SPP) . . . . . . . . . . . 47 124 7.1. SPP Message Format . . . . . . . . . . . . . . . . . . . 48 125 7.2. SPP Message Flow . . . . . . . . . . . . . . . . . . . . 48 126 7.2.1. SPP Symmetric Secrets Management . . . . . . . . . . 51 127 7.2.1.1. Server Side Only Generation . . . . . . . . . . . 52 128 7.2.1.2. Client Side Only Generation . . . . . . . . . . . 53 129 7.2.1.3. Client and Server Side Generation . . . . . . . . 54 130 7.2.2. SPP Key Pair Provisioning . . . . . . . . . . . . . . 55 131 7.2.2.1. Server Side Only Generation . . . . . . . . . . . 55 132 7.2.2.2. Client Side Only Generation . . . . . . . . . . . 55 133 7.2.2.3. Client and Server Side Generation . . . . . . . . 55 134 7.2.3. SPP Certificate Provisioning . . . . . . . . . . . . 55 135 7.2.3.1. Server Side Only Generation . . . . . . . . . . . 55 136 7.2.3.2. Client Side Only Generation . . . . . . . . . . . 55 137 7.2.3.3. Client and Server Side Generation . . . . . . . . 56 138 7.2.4. SPP Token Provisioning . . . . . . . . . . . . . . . 56 139 7.2.4.1. Server Side Only Generation . . . . . . . . . . . 56 140 7.2.4.2. Client Side Only Generation . . . . . . . . . . . 56 141 7.2.4.3. Client and Server Side Generation . . . . . . . . 56 142 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 56 143 8.1. Provisioning Protocols . . . . . . . . . . . . . . . . . 56 144 8.2. Token Types . . . . . . . . . . . . . . . . . . . . . . . 57 145 8.3. Credentials Types . . . . . . . . . . . . . . . . . . . . 57 146 8.4. Credentials Algorithms . . . . . . . . . . . . . . . . . 58 147 8.5. Credentials Datatypes . . . . . . . . . . . . . . . . . . 58 148 8.6. Network Usage Datatypes . . . . . . . . . . . . . . . . . 59 149 8.7. Credentials Encoding . . . . . . . . . . . . . . . . . . 59 150 8.8. Action Types . . . . . . . . . . . . . . . . . . . . . . 60 151 8.9. Usage Metadata Types . . . . . . . . . . . . . . . . . . 60 152 9. Security Considerations . . . . . . . . . . . . . . . . . . . 61 153 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 61 154 11. Normative References . . . . . . . . . . . . . . . . . . . . 61 155 Appendix A. EAP-CREDS Example Message Flow for Provisioning 156 Standards . . . . . . . . . . . . . . . . . . . . . 62 157 A.1. EAP-CREDS and CMP . . . . . . . . . . . . . . . . . . . . 62 158 A.2. EAP-CREDS and EST . . . . . . . . . . . . . . . . . . . . 62 159 A.3. EAP-CREDS and CMS . . . . . . . . . . . . . . . . . . . . 62 160 A.4. EAP-CREDS and ACME . . . . . . . . . . . . . . . . . . . 62 161 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 63 163 1. Requirements notation 165 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 166 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 167 document are to be interpreted as described in [RFC2119]. 169 2. Introduction 171 Many environments are, today, moving towards requiring strong 172 authentication when it comes to gain access to networks. The 802.1x 173 architecture provides network administrators with the possibility to 174 check credentials presented by a device even before providing any 175 connectivity or IP services to it. 177 However, the provisioning and management of these credentials is a 178 hard problem to solve and many vendors opt for long-lived credentials 179 that can not be easily revoked, replaced, or simply renewed. 181 This specification addresses the problem of providing a simple-to-use 182 and simple-to-deploy conduit for credentials management by extending 183 the EAP protocol to support credentials provisioning and management 184 functionality. In particular, the EAP-CREDS method defined here 185 provides a generic framework that can carry the messages for 186 provisioning different types of credentials. EAP-CREDS cannot be 187 used as a stand-alone method, it is required that EAP-CREDS is used 188 as an inner method of EAP-TLS, EAP-TEAP, or any other tunnelling 189 method that can provide the required secrecy and (at minimum) server- 190 side authentication to make sure that the communication is protected 191 and with the right server. 193 2.1. Overview of existing solutions 195 Currently there are many protocols that address credentials lifecycle 196 management. In particular, when it comes to digital certificates, 197 some of the most deployed management protocols are: Certificate 198 Management Protocol (CMP) [RFC4210], Certificate Management over CMS 199 (CMC) [RFC5272][RFC6402], Enrollment over Secure Transport (EST) 200 [RFC7030], and Automated Certificate Management Environment (ACME) . 201 However, none of these protocols provide native support for client 202 that do not have IP connectivity yet (e.g., because they do not have 203 network-access credentials, yet). EAP-CREDS provides the possibility 204 to use such protocols (i.e., message-based) by defining a series of 205 messages that can be used to encapsulate the provisioning messages 206 for the selected provisioning protocol. 208 In addition to these protocols, EAP-CREDS also defines a series of 209 simple messages that provide a generic enrollment protocol that 210 allows not only certificates but also other types of credentials 211 (e.g., username/password pairs, tokens, or symmetric secrets) to be 212 delivered to the client as part of the provisioning and/or renewal 213 process. The set of messages that make up the generic provisioning 214 protocol is referred to as the Simple Provisioning Protocol protocol 215 or SPP. 217 2.2. Scope Statement 219 This document focuses on the definition of the EAP-CREDS method to 220 convey credentials provisioning and managing messages between the 221 client and the AAA server. Moreover, the document defines how to 222 encode messages for the main IETF provisioning protocols. 224 This document, however, does not provide specifications for how and 225 where the credentials are generated. In particular, the credentials 226 could be generated directly within the AAA server or at a different 227 location (i.e., the Certificate Service Provider or CSP) site. 228 Different authentication mechanisms (e.g., TLS, etc.) can be used to 229 secure the communication between the server's endpoint and the CSP. 231 2.3. EAP-CREDS as tunneled mechanism only 233 EAP-CREDS requires that an outer mechanism is in place between the 234 Peer and the Server in order to provide authentication and 235 confidentiality of the messages exchanged via EAP-CREDS. In other 236 words, EAP-CREDS assumes that an appropriatly encrypted and 237 authenticated channel has been established to prevent the possibility 238 to leak information or to allow man-in-the-middle attacks. 240 This choice was taken to simplify the message flow between Peer and 241 Server, and to abstract EAP-CREDS from the secure-channel 242 establishment mechanism. EAP-TLS, or EAP-TEAP are examples of such 243 mechanisms.s 245 2.4. Fragmentation Support 247 EAP does not directly support handling fragmented packets and it 248 requires the outer method to provide fragmentation support. 250 Because of the outer method requirements in particular, removing any 251 support for fragmented messages in EAP-CREDS removes the duplication 252 of packets (e.g., Acknowledgment Packets) sent across the Peer and 253 the Server, thus resulting in a smaller number of exchanged messages 255 2.5. Encapsulating Provisioning Protocols in EAP-CREDS 257 In order to use EAP-CREDS together with your favorite provisioning 258 protocol, the messages from the provisioning protcol need to be sent 259 to the other party. In EAP-CREDS, this is done by encoding the 260 provisioning protocol messages inside the ('Provisioning-Data') TLV. 261 In case the provisioning protocol uses additional data for its 262 operations (e.g., uses HTTP Headers), this data can be encoded in a 263 separate ('Provisioning-Headers') TLV. 265 Since the implementation of the provisioning endpoint could happen in 266 a (logically or physically) different component, a method is needed 267 to identify when a provisioning protocol has actually ended. In EAP- 268 CREDS, the 'S' and 'E' bits in the message headers are used for this 269 purpose. 271 In the first message of Phase Two, the Server provides the client 272 with all the selected parameters for one specific credential that 273 needs attention (or for a new credential) to be managed by the 274 network. In particular, the server provides, at minimum, the 275 ('Protocol') TLV, the ('Action') TLV, and the ('Provisioning-Params') 276 or the ('Credentials-Info') TLV. 278 After checking the parameters sent by the Server, if the Peer does 279 not support any of the proposed ones, it MUST send a message with one 280 single ('Error') TLV with the appropriate error code(s). The server, 281 can then decide if to manage a different set of credentials (if more 282 where reported by the Peer in its Phase One message) or if to 283 terminate the EAP session with an error. 285 The Peer and the Server exchange ProtoFlow messages until an error is 286 detected (and the appropriate error message is sent to the other 287 party) or until Phase Two is successfully completed. 289 2.6. Algorithm Requirements 291 EAP-CREDS uses the SHA-256 hashing algorithm to verify credentials in 292 phase three of the protocol. Peers and Servers MUST support SHA-256 293 for this purpose. 295 2.7. Notation 297 In this document we use the following notation in the diagrams to 298 provide information about the cardinality of the data structures 299 (TLVs) within EAP-CREDS messages: 301 +--------+------------+---------------------------------------------+ 302 | Symbol | Example | Usage | 303 +--------+------------+---------------------------------------------+ 304 | { } | {TLV1} | Curly Brackets are used to indicate a set | 305 | [ ] | {[TLV2]} | Square Brackets are used to indicate that a | 306 | | | field is optional | 307 | ( ) | {TLV1(=V)} | Round Squares are used to specify a value | 308 | + | {TLV_2+} | The Plus character indicates that one or | 309 | | | more instances are allowed | 310 +--------+------------+---------------------------------------------+ 312 Table 1: EAP-CREDS Notation 314 3. EAP-CREDS Protocol 316 In a nutshell, EAP-CREDS provides the abstraction layer on top of 317 which credentials provisioning/managing protocols can be deployed 318 thus enabling their use even before provisioning IP services. 320 This section outlines the operation of the protocol and message 321 flows. The format of the CREDS messages is given in Section 4. 323 3.1. Message Flow 325 EAP-CREDS message flow is logically subdivided into three different 326 phases: Initialization, Provisioning, and Validation. EAP-CREDS 327 enforces the order of phases, i.e. it is not possible to move to an 328 earlier phase. 330 Phase transitioning is controlled by the Server via the ('Phase- 331 Control') TLV: when a messages is the last of one phase or the first 332 of another one, the ('Phase-Control') TLV is added to the message 333 with the 'S' bit set appropriately, and the value set to the phase 334 number that is transitioning. 336 Phase One (Required). Initialization. During this phase the Peer 337 and the Server exchange the information needed to select the 338 appropriate credentials management protocol. In particular, the 339 Sever sends its initial message of type ('EAP-CREDS-Init'). The 340 Peer replies with the details about which provisioning protocols 341 are supported, and additional information such as the list of 342 installed credentials and, optionally, authorization data (for new 343 credentials registration). 345 Phase Two (Optional). Provisioning Protocol Flow. In this phase, 346 the Peer and the Server exchange the provisioning protocol's 347 messages encapsulated in a EAP-CREDS message of type ProtoFlow. 348 The messages use two main TLVs. The first one is the 349 ('Provisioning-Headers') TLV which is optional and carries 350 information that might be normally coveyed via the transport 351 protocol (e.g., HTTP headers). The second one is the 352 ('Provisioning-Data'), which is required and carries the 353 provisioning protocol's messages. The server can decide to repeat 354 phase two again to register new credentials or to renew a separate 355 set of credentials. When no more credentials have to be managed, 356 the Server can start phase three or simply terminate the EAP 357 session. 359 Phase Three (Optional). Credentials Validation. This optional phase 360 can be initiated by the server and it is used to validate that the 361 Peer has properly installed the credentials and can use them to 362 authenticate itself. Depending on the credentials' type, the 363 messages can carry a challenge/nonce, the value of the secret/ 364 token, or other information. The format of the credentials is 365 supposed to be known by the provider and the device. 367 3.1.1. Phase Transitioning Rules 369 In order to keep track of starting and ending a phase, EAP-CREDS 370 defines several bits and fields in the EAP-CREDS message headers. In 371 particular, as described in Section 4.1, the 'S' and 'E' bits are 372 used to indicate the 'S'tart or the 'E'nd of a phase, while the 373 'Phase' field (4 bits) is used to indicate the phase for this 374 message. 376 In EAP-CREDS, phase transitioning is under the sole control of the 377 Server, therefore the 'S' or 'E' bits are meaningful only in messages 378 sent by the Server. The value of the 'S' and 'E' bits in Peer's 379 messages are ignored. 381 When starting a new phase, the Server MUST set the 'S' bit to '1' and 382 the 'Phase' field to the current phase number (e.g., one, two, or 383 three). On the other hand, when a phase is to be completed, the last 384 message from the Server MUST have the 'E' (End) bit set to '1' and 385 the value of the 'Phase' field MUST be set to the phase number that 386 is ending. 388 In case the first message of a phase is to be repeated (e.g., because 389 of a recoverable error or becuase processing multiple credentials), 390 the 'S' bit SHALL be set to '1' only on the first occurrency and set 391 to '0' in subsequent messages. 393 NOTE WELL: Once EAP-CREDS transitions from one phase to the next, 394 the state machine MUST prohibit going back to a previous phase. 396 3.2. Phase One: Initialization 398 The following figure provides the message flow for Phase One: 400 ,--------. ,----------. 401 |EAP Peer| |EAP Server| 402 `---+----' `----+-----' 403 | Outer Tunnel Established | 404 | <--------------------------------------> 405 | | 406 | [1] EAP-Request/EAP-CREDS(Type=Init) | ,---------!. 407 | { [ Version+ ], [ Challenge ] } | |Phase One|_\ 408 | <--------------------------------------- |Begins | 409 | | `-----------' 410 | [2] EAP-Response/EAP-CREDS(Type=Init) | 411 | { Protocol+, Encodings, | 412 | Formats, [ Version ] | 413 | [ Creds-Info+ ], [ Storage-Info ]| 414 | [ Net-Usage], [ Token ], | 415 | [ Challenge-Rsp ], [ Profile+ ] }| 416 | ---------------------------------------> 417 | | 418 | [3] EAP-Request/EAP-CREDS(Type=Init) | ,---------!. 419 | { Version } | |Phase One|_\ 420 | <--------------------------------------- |Ends | 421 | | `-----------' 422 | | 424 [1] Server sends EAP-Request/EAP-CREDS(Type=Init): 426 After the establishment of the outer mechanism (e.g., EAP-TLS, 427 EAP-TEAP, EAP-TTLS, etc.), the server MAY decide to start a 428 credentials management session. In order to do that, the Server 429 sends an EAP-Request/EAP-CREDS(Type=Init) message to the Peer with 430 one ('Phase-Control') TLV with the 'S' bit set to '1' and the 431 value set to '1' (thus indicating the beginning of Phase One). 432 Also, the Server MAY use one or more ('Version') TLVs to indicate 433 the supported versions. 435 The Server MAY also specify which versions of EAP-CREDS are 436 supported by adding one or more ('Version') TLVs. If no 437 ('Version') TLV is added to the message, the Peer SHOULD assume 438 the supported version is 1 ('0x1'). 440 [2] The Peer sends EAP-Response/EAP-CREDS(Type=Init) 442 The Peer, sends back a message that carries one ('Version') TLV to 443 indicate the selected version of EAP-CREDS (i.e. from the list 444 provided by the server) (optional). If the client does not 445 include the ('Version') TLV, the Server MUST use the most recent 446 supported version of EAP-CREDS. Moreover, the Server includes one 447 or more ('Protocol') TLVs to indicate the list of supported 448 provisioning protocols, followed by one ('Credentials-Info') TLVs 449 for each installed credentials to provide their status to the 450 server (i.e., if multiple credentials are configured on the Peer 451 for this Network, then the Peer MUST include one ('Credentials- 452 Info') TLV for each of them). 454 The Peer also provides the list of supported Encodings and Formats 455 by adding one or more ('Supported-Encodings') and ('Supported- 456 Formats') TLVs. The Peer MAY also provide the Server with 457 information about the Peer's credentials storage by using the 458 'Storage-Status' TLV. 460 When there are no abailable credentials, the Peer MAY include an 461 authorization token that can be consumed by the Server for 462 registering new credentials. In particular, the Peer can include 463 the ('Token-Data') TLV to convey the value of the token. The 464 ('Challenge-Data') and ('Challenge-Response') TLVs, instead, can 465 be used to convey a challenge and its response based on the 466 authorization information (e.g., maybe a public key hash is 467 present in the Token, then the peer can generate some random data 468 - or use the one from the Server - and generate a signature on 469 that value: the signature SHALL be encoded in the ('Challenge- 470 Response') TLV and it should be calculated over the concatenation 471 of values inside the ('Challenge-Data') TLV and the ('Token-Data') 472 TLV. 474 Also, the Peer MAY add one or more ('Profile') TLVs to indicate to 475 the Server which profiles are requested/supported (e.g., a pre- 476 configuration MAY exist on the Peer with these ecosystem-specific 477 identifiers). 479 Ultimately, the Peer MAY include additional metadata regarding the 480 status of the Peer. To this end, the Peer can use a ('Storage- 481 Info') TLV to provide the server with additional data about the 482 Peer's capabilities and resources. Also, the ('Network-Usage') 483 TLV can be used to provide the Server with the network resources 484 needed and the intended utilization patterns by the device. 486 The server checks that the Peer's selected protocol, version, and 487 parameters are supported and, if not (or if the server detects an 488 error), it can (a) send a non-recoverable error message to the 489 peer, notify the outer (tunneling) layer, and terminate the EAP- 490 CREDS session, or (b) start phase one again by sending a new 491 ('EAP-CREDS-Init') message that will also carry an ERROR TLV that 492 provides the Peer with the reason the initial response was not 493 acceptable. In this case, the ('Phase-Control') TLV MUST be 494 omitted since it is not the first message of phase one. The 495 server and the peer can repeat phase one until they reach an 496 agreement or the session is terminated by the Server. 498 NOTE WELL: The determination of the need to start phase two or not 499 is based on the contents of the ('Credentials-Info') TLV sent by 500 the Peer (e.g., a credential is about to expire or a credential is 501 simply missing). 503 [3] The Server sends EAP-Request/EAP-CREDS(Type=Init) 505 In order to terminate Phase One, the Server sends a last message 506 that carries the ('Phase-Control') TLV with the 'S' bit set to '0' 507 (end of phase) and the value shall be set to '1' (phase one). On 508 top of that, the Server also sends one ('Version') TLV (mandatory) 509 to announce the selected EAP-CREDS version to speak. 511 When registering new credentials (e.g., no 'Credentials-Info' TLV 512 was sent by the Peer and the Peer is authorized to present new 513 credentials), the Server MAY add a ('Profile') TLV to indicate the 514 selected profile for the new credentials that will be provisioned 515 in Phase Two. 517 3.2.1. Phase One State Machine 519 The Server's state machine is depicted in the following Figure: 521 +-------------------+ 522 | Start Phase One | 523 +-------------------+ 524 | 525 v 526 +-------------------+ 527 | Send the Init Msg |<------------------+ 528 +-------------------+ | 529 | | 530 v | 531 +-------------------+ | 532 | Receives Peer's | | 533 | Init Msg | | 534 +-------------------+ | 535 | | Yes 536 v ^ 537 +------------------+ Yes +---------------------+ 538 | Checks for Error |>------>| Recoverable ? | 539 +------------------+ +---------------------+ 540 | No | 541 v v 542 +-------------------+ +---------------------+ 543 | End Phse One | | Send Error Msg | 544 +-------------------+ +---------------------+ 545 | 546 v 547 +---------------------+ 548 | End EAP Session | 549 +---------------------+ 551 The first message from the server starts the phase by using the 552 ('Phase-Control') TLV. 554 The Server selects the action, the provisioning protocol, and 555 associated parameters. Phase Two officially begins with the next 556 message exchanged (i.e. an EAP-Request/EAP- 557 CREDS(Type=ProtoFlow)),which MUST include the ('Phase-Control') TLV 558 with the 'S' bit set to '1' and the value set to '2'. The message 559 MUST also includes, at minimum, the selected ('Action') and 560 ('Protocol') TLVs. 562 When renewing existing credentials or registering new ones, the 563 Server MUST include the ('Provisioning-Params') TLVs. 565 When removing or renewing existing credentials, the Server MUST 566 include the ('Credentials-Info') TLV to identify the set of 567 credentials to which the action applies. 569 If multiple values are detected in the message, the message shall be 570 discarded and the appropriate error message shall be issued by the 571 Peer. 573 3.3. Phase Two: Provisioning 575 The following figure provides the message flow for Phase 2: 577 ,--------. ,----------. 578 |EAP Peer| |EAP Server| 579 `---+----' `----+-----' 580 | [1] EAP-Request/EAP-CREDS(Type=ProtoFlow) | 581 | { Protocol, Action, | ,---------!. 582 | [ CredInfo ], [ Params ], | |Phase Two|_\ 583 | [ ProtoData ], [ Profile ] } | |Begins | 584 | <------------------------------------------ `-----------' 585 | | 586 | [2] EAP-Response/EAP-CREDS(Type=ProtoFlow)| 587 | { ProtoData, [ ProtoHeaders ] } | 588 | ------------------------------------------> 589 | | 590 | [3] EAP-Response/EAP-CREDS(Type=ProtoFlow)| 591 | { ProtoData, [ ProtoHeaders ] } | 592 | <------------------------------------------ 593 | | 594 . . 595 . . 596 . . 597 . . 598 | [4] EAP-Request/EAP-CREDS(Type=ProtoFlow) | ,---------!. 599 | { [ ProtoData ] } | |Phase Two|_\ 600 | <------------------------------------------ |Ends | 601 | | `-----------' 602 | | 604 [1] The Server sends EAP-Request/EAP-CREDS(Type=Init) 606 The first message of Phase Two indicates that the Server is ready 607 to initiate the selected provisioning protocol. 609 [2] The Peer sends EAP-Response/EAP-CREDS(Type=Init) 611 After that, the Peer sends its first message to the Server by 612 sending the EAP-Response/EAP-CREDS(Type=ProtoFlow) message. This 613 message contains the selected provisioning protocol's message data 614 and some extra fields (e.g., transport-protocol headers) in the 615 ('Provisioning-Data') and ('Protocol-Headers') TLVs respectively. 617 [3] The Server sends EAP-Request/EAP-CREDS(Type=Init) 619 The Server replies to the Peer's message with EAP-Request/EAP- 620 CREDS(Type=ProtoFlow) messages until the provisioning protocol 621 reaches an end or an error condition arise (non-recoverable). 623 [N] The Server sends EAP-Request/EAP-CREDS(Type=ProtoFlow) 625 The Server terminates Phase Two by sending a final message 626 carrying the ('Phase-Control') TLV with the 'S' bit set to '0' and 627 the value set to '2' (thus indicating the end of Phase Two). The 628 final message does not need to be an empty one, i.e. other TLVs 629 are still allowed in the same message (e.g., the 'Provisioning- 630 Data' and the 'Provisioning-Headers' ones). 632 3.3.1. Phase Two State Machine 634 The Server's state machine for Phase Two is depicted in the following 635 Figure: 637 +-------------------+ 638 | Start Phase Two | 639 +-------------------+ 640 | 641 v 642 Yes +-------------------+ No 643 +-----<| New Credentials |>-----+ 644 | | Available ? | | 645 | +-------------------+ | 646 | ^ | 647 v | v 648 +-------------------+ | +-------------------+ 649 | Action Needed for |>-----+ | Register New | 650 | Credentials ? | No | Credentials | 651 +-------------------+ +-------------------+ 652 v Yes Yes v v No 653 | | | 654 | +-------------------+ | | 655 +----->| Provisioning |<--+ | 656 | Protocol | | 657 +-------------------+ | 658 | No | 659 v | 660 +------------------+ | 661 | End of Provision | | 662 +------------------+ | 663 | | 664 v | 665 +------------------+ | 666 | End of Phase Two |<-----------+ 667 +------------------+ 669 The Server can decide to repeat phase two as many times as needed: 670 each time, the combination of the ('Credentials-Info') TLV (a.k.a. 671 CredInfo) and the ('Action') TLV MUST be unique for each session to 672 make sure notto repeat the same operation on the same credential over 673 and over again. In case all credentials for the Network do not need 674 maintenance at this time, the Server can decide to end the EAP-CREDS 675 session (no actions to be taken) and successfully complete the EAP 676 session. 678 3.4. Phase Three: Validation 680 The following figure provides the message flow for Phase 3: 682 ,--------. ,----------. 683 |EAP Peer| |EAP Server| 684 `---+----' `----+-----' 685 | [1] EAP-Request/EAP-CREDS(Type=Validate) | ,-----------!. 686 | { Cred-Info, Challenge } | |Phase Three|_\ 687 | <----------------------------------------- |Begins | 688 | | `-------------' 689 | [2] EAP-Response/EAP-CREDS(Type=Validate)| 690 | { Challenge-Response, [ Challenge ] }| 691 | -----------------------------------------> 692 | | 693 | [3] EAP-Request/EAP-CREDS(Type=Validate) | ,-----------!. 694 | { [ Challenge-Response ] } | |Phase Three|_\ 695 | <----------------------------------------- |Ends | 696 | | `-------------' 697 | | 699 Phase three is optional and it is used by the server to request the 700 client to validate (proof) that the new credentials have been 701 installed correctly before issuing the final Success message. 703 NOTE WELL: Phase Three introduces a dependency on the selected 704 hashing algorithm to provide common and easy way to check the 705 integrity and functionality of a newly installed set of 706 credentials. 708 [1] The Server sends EAP-Request/EAP-CREDS(Type=Validate) 710 In order to start Phase Three, the Server sends an EAP-Request/ 711 EAP-CREDS(Type=Validate) message to the Peer. The Server MUST 712 include the ('Credentials-Info') TLV to provide the indication 713 about which set of credentials the Server intends to validate. 714 The Server MUST also include a randomly generated challenge in the 715 message to the client. 717 As usual, the Server MUST also include the ('Phase-Control') TLV 718 in its first message of Phase Three. In this case, the 'S' bit 719 shall be set to '1' and the value shall be set to '3' (beginning 720 of Phase Three). 722 [2] The Peer sends EAP-Response/EAP-CREDS(Type=Validate) 724 When the client receives the Validate message from the server, it 725 calculates the response to the challenge and sends the response 726 back to the server in a EAP-Response/EAP-CREDS(Type=Validate) 727 message. The Peer MUST calculate the response as follows: 729 Public-Key 731 For any public-key based credentials (e.g., certificates or 732 raw key pairs), the response to the challenge is calculated 733 by generating a signature over the hashed value of the 734 challenge. The hashing algorithm to be used for this 735 purpose is specified in Section 2.6. The format of the 736 signature in the ('Challenge-Response') TLV is the 737 concatenation of: 739 - The signatureAlgorithm (DER encoded) which contains the 740 identifier for the cryptographic algorithm used by the 741 Peer to generate the signature. [RFC3279], [RFC4055], 742 and [RFC4491] list supported signature algorithms, but 743 other signature algorithms MAY also be supported. The 744 definition of the signatureAlgorithm is provided in 745 Section 4.1.1.2 of [RFC5280]. 747 - The signatureValue (DER encoded) which contains the 748 digital signature itself. The signature value is encoded 749 as a BIT STRING and the details of how to generate the 750 signatures' structures can be found in Section 4.1.1.3 of 751 [RFC5280] and referenced material. 753 Symmetric Secret 755 For any symmetric based credentials (e.g., password or Key), 756 the response to the challenge is calculated by using the 757 selected hash function (see Section 2.6) on the 758 concatenation of (a) the value carried in the server- 759 provided ('Challenge-Data') TLV, and (b) the secret value 760 itself (salted hash). 762 Optionally, the client can add a separate ('Challenge-Data') TLV 763 in its reply to request that the network proves it can calculate 764 responses. This extra challenge is only available for symmetric 765 secrets (it is not used to verify again the identity of the 766 server, but it is used for the server to prove it does have the 767 right symmetric data on its side too). This 'extra' challenge 768 carries the Peer-generated challenge information that the Server 769 MUST use to calculate the corresponding ('Challenge-Response') 770 TLV. 772 NOTE WELL: The Server might not be able to respond to the extra 773 challenge from the client because it might not posses the 774 secret key (e.g., in case of public-key cryptography, the 775 private key might not be shared with the Server, therefore it 776 cannot generate signatures that the client can verify). In 777 that case, the Server will NOT add the ('Challenge-Response') 778 TLV to its reply, but it MUST add the appropriate ('Errror') 779 TLV. 781 [3] The Server sends EAP-Request/EAP-CREDS(Type=Validate) 783 When the server receives the EAP-Response/EAP-CREDS(Type=Validate) 784 with the Challenge TLV in it, it MUST calculate the response to 785 the challenge and send back the response to the client in an EAP- 786 Request/EAP-CREDS(Type=Validate) with the ('Challenge-Response') 787 TLV. 789 In case of issues with the validation of the newly deployed 790 credentials, both the Server and the Peer should consider those 791 credentials invalid (or unusable) and should issue the required 792 failure message(s). 794 3.4.1. Phase Three State Machine 796 The Server's state machine for Phase Three is depicted in the 797 following Figure: 799 +-------------------+ 800 | Start Phase Three | 801 +-------------------+ 802 | 803 v 804 +---------------------+ No 805 +------------------------------->| New Credentials |>-------+ 806 | +------------------->| Available ? |<---+ | 807 | | +---------------------+ | | 808 | | Yes | ^ | | 809 | | v | | | 810 | | +-------------------+ | | | 811 | | | Validate |>-----+ | | 812 | | | Credentials ? | No | | 813 | | +-------------------+ | | 814 | | v Yes | | 815 | | | | | 816 | | | +---------------------+ | | 817 | | +----->| Send Validate | | | 818 | | | Messsage | | | 819 | | +---------------------+ | | 820 | | | | | 821 | | v | | 822 | +---------------------+ No +---------------------+ | | 823 | | Report the Error |<----<| Response Error? |----+ | 824 | +---------------------+ +---------------------+ No | 825 | Yes | | 826 | v | 827 | No +---------------------+ | 828 +------------------------------<| End Validation ? | | 829 +---------------------+ | 830 Yes | | 831 v | 832 +---------------------+ | 833 | End Phase Three |<--------+ 834 +---------------------+ 836 4. EAP-CREDS Message Format 838 The EAP-CREDS defines the following message types: 840 1. EAP-CREDS/Init 842 2. EAP-CREDS/ProtoFlow 844 3. EAP-CREDS/Validate 845 Each of these message types have the basic structure as identified in 846 Section 4.1. EAP-CREDS messages contain zero, one, or more TLVs. 847 The internal structure of the different types of TLVs is described in 848 Section 4.2, while a detailed description of the EAP-CREDS message 849 types is provided in Section 5. 851 4.1. Message Header 853 The EAP-CREDS messages consist of the standard EAP header (see 854 Section 4 of [RFC3748]), followed by the version of the EAP-CREDS (4 855 bits) and a field (4 bits) reserved for future use. The header has 856 the following structure: 858 0 1 2 3 859 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 860 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 861 | Code | Identifier | Length | 862 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 863 | Type |J|S|E|F| Phase | Message Length | 864 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 865 | Message Length | Data ... 866 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-. 868 Where the Code, Identifier, Length, and Type fields are all part of 869 the EAP header as defined in [RFC3748]. Since EAP-CREDS can only be 870 used as a tunneled mechanism, the presence of these fields is only 871 for backward compatibility with existing parsers. In particular, the 872 'Length' field is not used (can be ignored): the message length is 873 carried in the 'Message Length' field instead. 875 The Type field in the EAP header is for EAP-CREDS. 877 The Flags bitfield is used to convey status information (e.g., extra 878 long message, phase number, phase transitioning state). The 879 transition-control bits (i.e., 'S' and 'E' bits) are set in Server's 880 messages and are ignored in Peer's messages (the Server is the entity 881 that unilaterally controls the phase transition process). The 882 meanins of the bits in the 'Flags' field are as follows: 884 Bit 'J' (Jumbo Message) - If set, it idicates the presence of the 885 'Message Length' field. This bit SHALL be used only when the size 886 of the message exceeds the maximum value allowed in the 'Length' 887 field. In this case, the 'Message Length' field is added to the 888 message and set to the whole message size and the 'Length' field 889 is used for the current fragment length. If not set, the 'Message 890 Length' field is not present in the Message and the 'Length' field 891 is used for the message size (and the 'F' bit MUST be set to '0'). 893 Bit 'S' (Start) - If set, this message is the first one of a new 894 EAP-CREDS phase. The value of the new phase is encoded in the 895 'Phase' field. 897 Bit 'E' (End) - If set, this message is the last of an EAP-CREDS 898 phase. The value of the new phase is encoded in the 'Phase' 899 field. 901 Bit 'F' - If set, this message is a fragment of a message. In 902 this case, the 'Data' field is to be concatenated with all 903 messages with the 'F' bit set to '1' until the message with the 904 'F' bit set to '0' that indicates the end of the message. If the 905 message is not fragmented, the 'F' bit MUST be set to '0'. The 906 use of this bit is required when the tunneling method does not 907 provide support for messages up to 2^32 bits in size. 909 The Phase field is a uint4 and identifies the EAP-CREDS phase for the 910 current message. The version of EAP-CREDS described in this document 911 supports three values for this field: 913 0x01 - Phase One 915 0x02 - Phase Two 917 0x03 - Phase Three 919 A detailed explanation of the 'Phase' and 'Flags' fields of the 920 message headers is provided in Section 3.1.1. 922 The Data field is the message payload. The full description of this 923 field is provided in the next section. 925 4.2. Message Payload 927 The Data part of the message is organized as zero, one, or more TLV 928 objects whose structure is defined in this section. 930 Each TLV object has the same basic structure that is defined as 931 follows: 933 0 1 2 3 934 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 935 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 936 | TLV Type | TLV Length | 937 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 938 | TLV Value ... 939 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 941 Where: 943 TLV-Type (uint8) 945 This field is used to indicate the type of data that the TLV 946 carries. The type of TLV determines its internal structure. The 947 supported values for this fields are provided in the following 948 table: 950 Length (uint24) 952 This field carries the size of the value of the TLV. In 953 particular, the overall size of a TLV (i.e., the header plus the 954 value) can be calculated by adding the size of the header (6 955 octects) to the value of the Length field (i.e., the size of the 956 TLV's value). 958 +----------+--------------------------+------------------------+ 959 | TLV Name | TLV Type | Scope/Usage | 960 +----------+--------------------------+------------------------+ 961 | | Action TLV | Phase Two | 962 | | Certificate-Data TLV | Phase Two/SPP | 963 | | Challenge-Data TLV | Phase Two, Phase Three | 964 | | Challenge-Response TLV | Phase Two, Phase Three | 965 | | Credentials-Data TLV | Phase Two/SPP | 966 | | Credentials-Info TLV | Phase Two, Phase Three | 967 | | Error TLV | All Phases | 968 | | Network-Usage TLV | Phase One | 969 | | Profile TLV | Phase Two | 970 | | Protocol TLV | Phase One, Phase Two | 971 | | Provisioning-Data TLV | Phase Two | 972 | | Provisioning-Headers TLV | Phase Two | 973 | | Provisioning-Params TLV | Phase Two | 974 | | Certificate-Request TLV | SPP | 975 | | Storage-Info TLV | SPP | 976 | | Supported-Format TLV | SPP | 977 | | Supported-Encoding TLV | SPP | 978 | | Token-Data TLV | Phase One | 979 | | Version TLV | Phase One | 980 +----------+--------------------------+------------------------+ 982 Table 2: EAP-CREDS Supported TLVs Types 984 TLV Value ( > 1 octet ) 986 This field carries data for the identified TLV. The internal 987 structure is determined by the TLV Type field. 989 The rest of this section describes the structure of the different 990 supported TLVs and their usage in the different messages. 992 4.2.1. EAP-CREDS defined TLVs 994 EAP-CREDS messages's payload comprieses zero, one, or more TLVs that 995 are encoded in a single EAP-CREDS message. The values for the TLV 996 Type that are supported by this specifications are listed in Table 2. 998 4.2.1.1. The Action TLV 999 0 1 2 3 1000 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 1001 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1002 | TLV Type | TLV Length | 1003 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1004 | Flags | Action Type | 1005 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1007 TLV Type (uint8) 1009 - Action TLV 1011 TLV Length (uint24) 1013 Fixed value (=2) 1015 Flags (uint8) 1017 Reserved 1019 4.2.1.2. The Certificate-Data TLV 1021 0 1 2 3 1022 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 1023 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1024 | TLV Type | TLV Length | 1025 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1026 | Flags | Format | Encoding | Value ... 1027 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1029 TLV Type (uint8) 1031 - Certificate-Data TLV 1033 Length (uint24) 1035 Provides the length of the TLV (> 3 octets) 1037 Flags (uint8) 1039 Provides a BITMASK that can be used to provide additional 1040 information related to the encapsulated certificate. The bits 1041 have the following meaning: 1043 Bit 0 - If set, the certificate is trusted (Trust Anchor) 1044 Bit 1 - If set, the certificate is a CA certificate 1046 Bit 2 - If set, the certificate is self-signed 1048 Bit 3 - If set, the certificate is a proxy certificate 1050 Bit 4 - If set, the certificate is an attribute certificate 1052 Bit 5 - Reserved 1054 Bit 6 - Reserved 1056 Bit 7 - Reserved 1058 For a Trusted Root CA, the value of the flags shall be 0x7 (0000 1059 0111). For an intermediate CA certificate that is not implicitly 1060 trusted, the value of the flags field should be set to 0x02 (0000 1061 0010). For an End-Entity certificate, the value of the Flags will be 1062 0x0 (0000 0000). 1064 Format (uint8) 1066 Provides the indication of the Format the certificate is in. The 1067 allowed values for this field are listed in Section 8.5. 1069 Encoding (uint8) 1071 Provides the indication of the Encoding the certificate is in. 1072 The allowed values for this field are listed in Table 11. 1074 Value (octet string) 1076 This field carries the data for the certificate. 1078 4.2.1.3. The Challenge-Data TLV 1080 0 1 2 3 1081 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 1082 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1083 | TLV Type | TLV Length | 1084 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1085 | Challenge Data ... 1086 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1088 TLV Type (uint8) 1089 - Challenge-Data TLV 1091 Length (uint24) 1093 3 octets 1095 Challenge Data (> 1 octet) 1097 This field carries the data to be used as a challenge when 1098 validating newly deployed credentials. 1100 4.2.1.4. The Challenge-Response TLV 1102 0 1 2 3 1103 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 1104 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1105 | TLV Type | TLV Length | 1106 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1107 | Challenge Response ... 1108 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1110 TLV Type (uint8) 1112 - Challenge-Response TLV 1114 Length (uint24) 1116 3 octets 1118 Challenge Response (> 1 octet) 1120 This field carries the data that resulted from the use of the 1121 credentials to be validated. 1123 4.2.1.5. The Credentials-Information TLV 1124 0 1 2 3 1125 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 1126 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1127 | TLV Type | TLV Length | 1128 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1129 | Flags | CredsType | ProtoID | 1130 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1131 | | 1132 | IssuedOn (GMT) | 1133 | | 1134 | | 1135 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1136 | | 1137 | Expires On (GMT) | 1138 | | 1139 | | 1140 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1141 | Credentials Length | 1142 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1143 | CredIDValue ... 1144 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1146 The Credential-Information TLV is used by the Peer to provide a 1147 description of the installed credentials that are relevant for the 1148 network that is being accessed. 1150 For example, when a set of credentials need to be renewed, the server 1151 checks the ('Credentials-Info') from the Peer and eventually selects 1152 the right one for renewal. The TLV structure is as follows: 1154 TLV Type (uint8) 1156 - Credentials-Information TLV 1158 Length (uint24) 1160 Provides the total length of the body of the Credential- 1161 Information TLV. 1163 Flags (uint8) 1165 Provides a BITMASK that can be used to provide information about 1166 the status of the credentials (e.g., if the use marks the 1167 credentials to be compromised). The bits have the following 1168 meaning: 1170 Bit 0 - If set, the credential is marked as compromised 1171 Bit 1 - If set, the credential is immutable and cannot be 1172 updated 1174 Bit 2 - Private Key or Secret Immutable, the public part of the 1175 credential (e.g., a certificate) can still be updated 1177 Bit 3 - If set, the credential cannot be updated (both public 1178 and private parts) 1180 Bit 4 - If set, the credential is ready to be used 1182 Bit 5 - If set, the credential was generated on the server 1184 Bit 6 - If set, the Peer would like to update the credential 1185 even if they are not expired 1187 Bit 7 - Reserved 1189 CredType (uint8) 1191 This field provides the description of the type of credential. 1192 The type of credentials are listed in Table 7 1194 ProtoID (uint16) 1196 This field indicates the protocol that was used to retrieve the 1197 target credential. When the TLV is used in a Request by the 1198 Server, this field is ignored. The values for this field are 1199 listed in Table 5. 1201 IssuedOn (16 octets) 1203 This field carries the GMT date for when this credential was 1204 issued. This field is 16 bytes long (the last byte must be set to 1205 '0x00') and contains the NULL-terminated ASCII string that 1206 represents the timestamp where the credential was issued. When 1207 the value is not set, the field should be set to { 0x00 }. The 1208 format of the string is as follows: 1210 YYYYMMDDHHmmssZ 1212 Where: 1214 YYYY - is the 4 digits representation of the year 1216 MM - is the 2 digits representation of the month 1217 DD - is the 2 digits representation of the day of the month 1219 HH - is the 2 digits representation of the hour of the day (24 1220 hour format) 1222 mm - is the 2 digits representation of the minutes of the hour 1224 ss - is the 2 digits representation of the seconds of the 1225 minute 1227 Z - is the character 'Z' 1229 ExpiresOn (16 octets) 1231 This field carries the GMT date for when this credential is to be 1232 considered expired. This field is 16 bytes long (the last byte 1233 must be set to '0x00') and contains the NULL-terminated ASCII 1234 string that represents the timestamp where the credential was 1235 issued. The format is the same as the ('IssuedOn') field. When 1236 the value is not set, the field should be set to { 0x00 }. 1238 Credentials Length (uint16) 1240 Length (in bytes) of the Credentials value. When used with a 1241 public-key type of credentials, this is the size of the key (e.g., 1242 for an RSA 2048 bit keys, this field should carry the value of 1243 256). When used with a symmetric secret, this field carries the 1244 size of the secred (in bytes). 1246 CredIDValue (> 1 octet) 1248 The binary value of the credentials' identifier. This identifier 1249 can be the binary value of the SHA-256 calculated over the 1250 certificate, a username, or it could be a random handle. As long 1251 as the ID allows the peer and the server to uniquely (in its 1252 context) identify the credentials, the value of this field can be 1253 calculated in any way. 1255 4.2.1.6. The Credentials-Data TLV 1256 0 1 2 3 1257 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 1258 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1259 | TLV Type | TLV Length | 1260 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1261 | Cred Type | Format | Encoding | Value ... 1262 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1264 TLV Type (uint8) 1266 - Credentials-Data TLV 1268 Length (uint24) 1270 Provides the length of the TLV (> 3 octets) 1272 Cred Type (uint8) 1274 Provides the indication of the type of credentials. The allowed 1275 values for this field are listed in Table 7. 1277 Format (uint8) 1279 Provides the indication of the Format the credentials are in. The 1280 allowed values for this field are listed in Section 8.5. 1282 Encoding (uint8) 1284 Provides the indication of the Encoding the credentials are in. 1285 The allowed values for this field are listed in Table 11. 1287 Value (octet string) 1289 This field carries the data for the credentials. 1291 4.2.1.7. The Error TLV 1292 0 1 2 3 1293 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 1294 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1295 | TLV Type | TLV Length | 1296 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1297 | EAP-CREDS Error Code | Secondary Error Code | 1298 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1299 | Description ... 1300 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1302 TLV Type (uint8) 1304 - Challenge-Response-Data TLV 1306 Length (uint24) 1308 3 octets 1310 EAP-CREDS Error Code (2 octets) 1312 This field carries the EAP-CREDS error code. These code are 1313 related to the EAP-CREDS operations only and it should not be used 1314 to carry the Provisioning-Protocol specific error codes. 1316 The error codes supported by this specifications are listed in 1317 Section 4.2.1.7. 1319 Secondary Error Code (2 octets) 1321 This field is used to convery an error at the encapsulation layer 1322 (i.e., the provisioning protocol error). For example, this field 1323 can be used to convey a transport protocol error code (e.g., HTTP 1324 status code). Do not use this field to convery EAP-CREDS specific 1325 errors. 1327 Description ( > 1 octet) 1329 The Description field is optional (i.e., when the Description Size 1330 is set to zero) and carries information about the error that 1331 occurred. The message may or may not be used by a user or an 1332 automated process for debugging purposes. 1334 4.2.1.8. The Network-Usage TLV 1335 0 1 2 3 1336 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 1337 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1338 | TLV Type | TLV Length | 1339 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1340 |U| Desc Format | Encoding | Network-Usage Data ... 1341 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1343 TLV Type (uint8) 1345 - Network-Usage TLV 1347 Length (uint24) 1349 Variable Length TLV (Value must be > 2 ) 1351 Description Format (uint8) 1353 The Type of data encoded in the Peer Description Data. The 1354 initial values for this field are listed in Section 8.9. 1356 Encoding (uint8) 1358 Provides the indication of the Encoding the network usage 1359 description data is in. The allowed values for this field are 1360 listed in Table 11. 1362 The 'U' field (1 bit) 1364 The 'URL' bit ('U') is used to indicate if the value of the 1365 Network-Usage Data field is to be interpreted as a URL or as the 1366 actual data. In particular, if the value in the 'URL' bit is '1', 1367 then the value in the Network-Usage Data field is to be 1368 interpreted as the URL where the actual data can be downloaded 1369 from. Otherwise, if the 'URL' bit is set to '0', then the value 1370 in the Netowrk-Usage Data field is to be interpreted as the actual 1371 data (not a URL referencing it). 1373 An example use of this bit is when the Peer wants to convey the 1374 URL of the MUD file [RFC8520]. In this case, the Peer can set the 1375 Network-Usage Data field to the Url of the MUD file related to the 1376 Peer. 1378 Desc Format (7 bits) 1380 This field provide the expected data format for the Network-Usage 1381 Data. For example, the value in this field could be set to 'MUD' 1382 and have the 'U' bit set to '1' to provide the MUD-related 1383 information at credentials management time instead of at network- 1384 provisioning time (DHCP option). This possibility could help the 1385 Network controller to decide if the device shall be allowed to 1386 register its credentials or not. 1388 The list of initial values for this field is provided in 1389 Section 8.6. 1391 Network-Usage Data (octet string) 1393 This is additional information related to the device. In 1394 particular, this TLV can be used by the Peer to provide the Server 1395 with the description of the intended network usage or a URL that 1396 points to the same information. 1398 For example, this field can be used to convey a MUD file 1399 (Manufacturer Usage Description) or the latest firmware-update 1400 manifest. 1402 4.2.1.9. The Profile TLV 1404 0 1 2 3 1405 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 1406 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1407 | TLV Type | TLV Length | 1408 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1409 | Profile Identifying Data ... 1410 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1412 TLV Type (uint8) 1414 - Profile Identifying Data TLV 1416 Length (uint24) 1418 Length value should be >= 1 1420 Profile Identifying Data (octet string) 1422 The Profile Identifying Data is used to provide indication to the 1423 other party about which profiles are supported when requesting 1424 credentials management. 1426 Also in this case, the data used in this field is left to be 1427 interpreted by the end-point and it is orthogonal to EAP-CREDS 1428 data types. 1430 An example of values for this field, an end-point could use the 1431 string representation (i.e., dotted representation) of the Object 1432 Identifier (OID) of the specific profile supported (e.g., could be 1433 defined in the Certificate Policy of the credentials' provider). 1435 4.2.1.10. The Protocol TLV 1437 0 1 2 3 1438 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 1439 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1440 | TLV Type | TLV Length | 1441 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1442 | Protocol ID | Version | 1443 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1445 TLV Type (uint8) 1447 - Protocol TLV 1449 TLV Length (uint24) 1451 Fixed TLV Length value of 4. 1453 Protocol ID (uint16) 1455 The Protocol ID value carries the id of a supported provisioning 1456 protocol. The initial list of values for the provisioning 1457 protocol identifiers can be found in Section 8.1. 1459 Version (uint16) 1461 The Version (Protocol Version) value represents the specific 1462 version of the identified provisioning protocol. When no version 1463 is specified for a protocol (i.e., either it does not support 1464 multiple versions or it does not matter), the value of this field 1465 should be set to '0x0'. 1467 4.2.1.11. The Provisioning-Data TLV 1468 0 1 2 3 1469 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 1470 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1471 | TLV Type | TLV Length | 1472 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1473 | Provisioning Data ... 1474 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1476 TLV Type (uint8) 1478 - Provisioning-Data TLV 1480 Length (uint24) 1482 3 octets 1484 Headers Data (> 1 octet) 1486 This field carries the provisioning protocol's messages. 1488 4.2.1.12. The Provisioning-Headers TLV 1490 0 1 2 3 1491 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 1492 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1493 | TLV Type | TLV Length | 1494 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1495 | Headers Data ... 1496 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1498 TLV Type (uint8) 1500 - Provisioning-Headers TLV 1502 Length (uint24) 1504 3 octets 1506 Headers Data (> 1 octet) 1508 This field carries the meta-data (if any) that might be associated 1509 with the transport-layer normally used with the provisioning 1510 protocol. For example, this TLV can carry the set of HTTP headers 1511 required by EST or ACME. 1513 4.2.1.13. The Provisioning-Params TLV 1515 0 1 2 3 1516 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 1517 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1518 | TLV Type | TLV Length | 1519 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1520 | Min Length | Max Length | 1521 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1522 | Algorithm | Flags | OBJECT IDENTIFIER (DER) ... 1523 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1525 TLV Type (uint8) 1527 - Provisioning-Params TLV 1529 Length (uint24) 1531 Provides the length of the TLV (>= 6 octets) 1533 Min Length (uint16) 1535 Provides the minimum allowed size size for the credentials. This 1536 value has meaning depending on the context of the credentials, 1537 however sizes are always expressed in bytes. 1539 For example, when used with a symmetric key or a password, the 1540 ('Min Length') and ('Max Length') refer to the minimum and maximum 1541 size of the password data. The ('Algor OID') field can be omitted 1542 in this case. 1544 On the other hand, when referring public-key credentials, this 1545 field should carry the size of the modulus of the key. For 1546 example, for an RSA 2048 bit keys, the field should carry the 1547 value of 256. For an ECDSA that uses the prime256r1 curve, this 1548 field should carry the value of 32 and the Algor OID should be the 1549 DER representation of the specific value of the curve (i.e., the 1550 DER representation of '1.2.840.10045.3.1.7'). 1552 Max Length (uint16) 1554 Provides the indication maximum size of the credentials. This 1555 value has meaning depending on the context of the credentials, 1556 however sizes are always expressed in bytes. 1558 The same considerations apply to this field as well as the ('Min 1559 Length') one discussed above. 1561 Flags (uint8) 1563 Provides a BITMASK that can be used to provide information about 1564 the status of the credentials (e.g., if the use marks the 1565 credentials to be compromised). The bits have the following 1566 meaning: 1568 Bit 0 - Credentials (or part of it) are to be generated on the 1569 server 1571 Bit 1 - Credentials (or part of it) are to be generated on the 1572 peer 1574 Bit 2 - Credentials are to be generated on dedicated hardware 1576 Bit 3 - Reserved 1578 Bit 4 - Reserved 1580 Bit 5 - Reserved 1582 Bit 6 - Reserved 1584 Bit 7 - Reserved 1586 When using public-key based credentials, the bits 0 and 1 are 1587 mutually exclusive. 1589 When using passwords or shared secrets, if bit 0 is set, then the 1590 secret is generated by the server and then sent to the client. On 1591 the other hand, if bit 1 is set, then the secret is generated by 1592 the peer and then sent to the server. Ultimately, if both bits 1593 are set, then the Server generates the first part of the password 1594 and sends it to the Peer, while the Peer generates the second part 1595 of the password and sends it to the Server. The password to be 1596 used for future authentication is the concatenation of the two 1597 shares of the password: first the one from the Server, then the 1598 one from the Client. 1600 NOTE WELL: Last but not least, since these passwords/secrets 1601 are meant to be used in a automated fashion, there is no 1602 restriction around the character set to use or their 1603 interpretation. Therefore,it is good practice to generate 1604 random passphrases that use the full 8-bit character set (on 1605 client and server) to maximize the secret's search space. 1607 Algorithm (uint8) 1609 Provides the indication of the algorithm used for the generation 1610 of the credentials. The allowed values for this field are listed 1611 in Table 8. 1613 Object Identifier (binary; > 1 octet) 1615 Provides the indication of additional parameters that are needed 1616 to be encoded for the credentials. This value is used only when 1617 the credentials use public-key cryptography - this field carries 1618 additional information about the generation algorithm to be used. 1619 We provide some useful values that can be used as reference: 1621 +----------------+----------------------+---------------------------+ 1622 | OID Name | Dotted | Binary Encoding | 1623 | | Representation | | 1624 +----------------+----------------------+---------------------------+ 1625 | secp256r1 | 1.2.840.10045.3.1.7 | 06 08 2A 86 48 CE 3D 03 | 1626 | curve | | 01 07 | 1627 | secp384r1 | 1.2.840.10045.3.1.34 | 06 08 2A 86 48 CE 3D 03 | 1628 | curve | | 01 22 | 1629 | secp521r1 | 1.2.840.10045.3.1.35 | 06 08 2A 86 48 CE 3D 03 | 1630 | curve | | 01 23 | 1631 | X25519 curve | 1.3.101.110 | 06 03 2B 65 6E | 1632 | X25519 curve | 1.3.101.110 | 06 03 2B 65 6E | 1633 | X448 curve | 1.3.101.111 | 06 03 2B 65 6F | 1634 | Ed25519 curve | 1.3.101.112 | 06 03 2B 65 70 | 1635 | Ed448 curve | 1.3.101.113 | 06 03 2B 65 71 | 1636 +----------------+----------------------+---------------------------+ 1638 Table 3: Object Identifiers Examples 1640 4.2.1.14. The Certificate-Request TLV 1642 0 1 2 3 1643 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 1644 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1645 | TLV Type | TLV Length | 1646 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1647 | Encoding | Format | Value ... 1648 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1650 TLV Type (uint8) 1652 - Token-Data TLV 1654 TLV Length (uint24) 1656 Provides the length of the TLV (> 3 octets) 1658 Encoding (uint8) 1660 Provides the indication of the Encoding the credentials are in. 1661 The allowed values for this field are listed in Table 11. 1663 Format (uint8) 1665 Provides the indication of the type of credentials. The allowed 1666 values for this field are listed in Table 9. 1668 Value (octet string) 1670 This field carries the data for the credentials. 1672 4.2.1.15. The Storage-Info TLV 1674 0 1 2 3 1675 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 1676 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1677 | TLV Type | Flags | Spare Slots | 1678 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1679 | Available Memory | 1680 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1682 TLV Type (uint8) 1684 - Store-Info TLV 1686 Flags (8 bits) 1688 Provides information about the status and type of store and 1689 limited information about its capabilities. The bits have the 1690 following meaning: 1692 Bit 0 - If set, the store supports RSA keys (software) 1694 Bit 1 - If set, the store supports RSA keys (hardware) 1695 Bit 2 - If set, the store supports ECDSA keys (software) 1697 Bit 3 - If set, the store supports ECDSA keys (hardware) 1699 Bit 4 - If set, the store supports symmetric keys 1701 Bit 5 - If set, the store supports generic tokens 1703 Bit 6 - If set, the store is immutable (no key generation or 1704 deletion) 1706 Bit 7 - Not Used 1708 Spare Slots (uint16) 1710 Provides the number of available slots where to store credentials. 1711 When no more slots are available, the value of '0' should be used 1712 to indicate to the Server that a credential must be deleted before 1713 a new one can be created. 1715 When the number of slots is not fixed or not known, the value of { 1716 0xFF, 0xFF } shall be used. 1718 Available Memory (uint32) 1720 This field carries the size (in bytes) of the spare memory on the 1721 Peer's secrets' store. 1723 4.2.1.16. The Supported-Formats TLV 1725 0 1 2 3 1726 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 1727 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1728 | TLV Type | TLV Length | 1729 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1730 | Format | 1731 +-+-+-+-+-+-+-+-+ 1733 TLV Type (uint8) 1735 - Supported-Format TLV 1737 TLV Length (uint24) 1739 Provides the length of the TLV. This field must be set to 1. 1741 Format (uint8) 1743 Provides the details about the supported format. Multiple formats 1744 TLVs can be used in the Peer's ('Init') message to provide the 1745 Server with the Peer's capabilities. 1747 4.2.1.17. The Supported-Encoding TLV 1749 0 1 2 3 1750 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 1751 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1752 | TLV Type | TLV Length | 1753 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1754 | Encoding | 1755 +-+-+-+-+-+-+-+-+ 1757 TLV Type (uint8) 1759 - Store-Info TLV 1761 TLV Length (uint24) 1763 Provides the length of the TLV. The field has a fixed value of 1. 1765 Encoding (uint8) 1767 Provides the indication of the supported Encoding by the End 1768 Point. This provides the indication to the Server of the 1769 capability of the Peer. The allowed values for this field are 1770 listed in Table 11. 1772 4.2.1.18. The Token-Data TLV 1774 0 1 2 3 1775 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 1776 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1777 | TLV Type | TLV Length | 1778 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1779 | Token Type | Encoding | Value ... 1780 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1782 TLV Type (uint8) 1784 - Token-Data TLV 1786 TLV Length (uint24) 1788 Provides the length of the TLV (> 3 octets) 1790 Token Type (uint8) 1792 Provides the indication of the type of credentials. The allowed 1793 values for this field are listed in Table 6. 1795 Encoding (uint8) 1797 Provides the indication of the Encoding the credentials are in. 1798 The allowed values for this field are listed in Table 11. 1800 Value (octet string) 1802 This field carries the data for the credentials. 1804 4.2.1.19. The Version TLV 1806 0 1 2 3 1807 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 1808 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1809 | TLV Type | TLV Length | 1810 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1811 | Version | 1812 +-+-+-+-+-+-+-+-+ 1814 TLV Type (uint8) 1816 - Version TLV 1818 TLV Length (uint24) 1820 Provides the length of the TLV. The field has a fixed value of 1. 1822 Version (uint8) 1824 The Version field represents the specific version of the EAP-CREDS 1825 protocol that are supported by the end point. When multiple 1826 versions of EAP-CREDS are supported, multiple ('Version') TLVs can 1827 be used. 1829 When no version is specified (i.e., either it does not support 1830 multiple versions or it does not matter), the value of this field 1831 should be set to '0x0' (any version). 1833 5. EAP-CREDS Messages 1835 This section describes each message and what TLVs are allowed or 1836 required. EAP-CREDS defines the following values for the Message 1837 Type (Type): 1839 +------------+---------------------+--------------------------------+ 1840 | Message | Name | Description | 1841 | Type | | | 1842 +------------+---------------------+--------------------------------+ 1843 | 0 | EAP-CREDS-Init | Initialization Phase | 1844 | 1 | EAP-CREDS-ProtoFlow | Carries Provisioning Protocol | 1845 | | | Messages | 1846 | 2 | EAP-CREDS-Validate | Validates newly installed | 1847 | | | credentials | 1848 +------------+---------------------+--------------------------------+ 1850 Table 4: EAP-CREDS Message Types 1852 5.1. The EAP-CREDS-Init Message 1854 The EAP-CREDS-Init message type is used in Phase One only of EAP- 1855 CREDS. The message flow is depicted in Section 3.2. This message 1856 supports the following TLVs: Version, Protocol, Credentials-Info, and 1857 Error. 1859 5.1.1. EAP Server's Init Message 1861 EAP-CREDS starts with an ('EAP-CREDS-Init') message from the server. 1862 This message MAY contain zero, one, or more ('Version') TLVs and, 1863 optionally, a ('Challenge-Data') TLV. 1865 The first message from the server is the one that starts Phase One, 1866 therefore the Server MUST set the headers' 'S' bit to '1' (Start) and 1867 the headers' 'Phase' value to '1' (Phase One). The 'E' bit MUST be 1868 set to '0'. 1870 The Server uses one or more ('Version') TLVs in the EAP-Request/EAP- 1871 CREDS(Type=Init) message to provide the Peer with the list of EAP- 1872 CREDS versions supported. If omitted, the implict version of EAP- 1873 CREDS used in the session is one ('0x1'). If the Server detects 1874 multiple occurrences of this TLV in the reply from the Peer, an error 1875 shall be issued and the EAP-CREDS session should be terminated. 1877 In case Token-Based registration is enabled on the Server, the Server 1878 MUST include, in its Init message, a ('Challenge-Data') field that 1879 can be used by the client to provide challenge data for proof-of- 1880 possession of secrets. 1882 5.1.2. EAP Peer's Init Message 1884 The Peer MUST reply to the Server's ('EAP-CREDS-Init') message with 1885 its own ('EAP-CREDS-Init') one. The Peer SHOULD include one 1886 ('Version') TLV in its first message to indicate the version of EAP- 1887 CREDS that the client wants to use for the session. The Peer MUST 1888 also provide the list of supported provisioning protocols (via one or 1889 more the 'Protocol' TLV), the list and status of the installed 1890 credentials (via the 'Credentials-Info' TLV). The Peer MAY include 1891 authorization data when registering new credentials (e.g., an 1892 authorization token or a device certifcate) via the ('Token-Data') 1893 and ('Challenge-Response') TLV. 1895 The Peer MUST include one ('Credentials-Info') TLV for each 1896 credential the Network is authorized to manage. Typically, a Peer 1897 will include only one ('Credentials-Info') TLV in its ('EAP-CREDS- 1898 Init') message, but there might be cases where multiple types of 1899 credentials are available and selected depending on the location and 1900 other factors (e.g., X.509 certificate and username/password 1901 combination). 1903 In case the Peer does not have any credentials available yet, it does 1904 not add any ('Credentials-Info') TLV - leaving the Server with the 1905 only action possible: Registration. In this case, the Peer SHOULD 1906 include authorization information via the ('Token-Data') TLV as 1907 described in Section 5.1.2.1. Additionally, the Peer can add the 1908 ('Profile') TLV to indicate a preferred profile for the credentials. 1910 5.1.2.1. Bootstrapping Peer's Trustworthiness 1912 When the Peer does not have any valid credentials for the Network 1913 that it is authenticating to, it does not provide any ('Credentials- 1914 Info') TLV. This indicates to the Server that new credentials MUST 1915 be registered before the Peer is allowed on the network. 1917 The Registration process might rely on information exchanged during 1918 the Provisioning Process in Phase Two. However, if an authorization 1919 mechanism is not available from the supported provisioning protocol 1920 and no credentials are available on the Peer, EAP-CREDS provides a 1921 simple machanism for the Peer to leverage an out-of-band 1922 token/passphrase/ott that may be already available on the Peer (e.g., 1923 a device certificate or a 'spendable' credentials token like a 1924 kerberos ticket or a crypto-currency transaction) and that can be 1925 verified by the Server. 1927 In particular, when the Peer wants to register new credentials (and 1928 the Server requires the use of additional authorization data) it may 1929 need to provide (a) a Token, (b) a challenge value, and (c) a 1930 response to the challenge value. To do so, the Peer MUST encode the 1931 token in a ('Token-Data') TLV, the challenge value in a ('Challenge- 1932 Data') TLV, and, finally, the response to the challenge in the 1933 ('Challenge-Response') TLV. 1935 The use of ('Challenge-Data') and ('Challenge-Response') TLVs is 1936 optional, however it is suggested that if a token is used for 1937 bootstrapping the trust, it should provide a way to verify a secret 1938 associated with it. 1940 It is also very important that the authorization token is disclosed 1941 only to authorized servers - the Peer MUST NOT disclose authorization 1942 tokens that are not meant for the network that is being accessed. 1943 This can be done, usually, by verifying the identity of the Server 1944 first (in the outer mechanism) and then verify that the target of the 1945 Token is the Server the Client is talking to. 1947 5.2. The EAP-CREDS-ProtoFlow Message 1949 The EAP-CREDS-ProtoFlow message type is used in Phase Two only of 1950 EAP-CREDS. The message flow is depicted in Section 3.3. This 1951 message type supports the following TLVs: Protocol, Profile, 1952 Credentials-Info, Provisioning-Headers, Provisioning-Data, Token- 1953 Data, and Error. 1955 After the exchange of phase one messages, the Server MAY start phase 1956 two by issuing an ('EAP-CREDS-ProtoFlow') message for the Peer where 1957 it encodes all the required details for starting the provisioning 1958 process. In particular, the server sends the selected ('Action'), 1959 ('Protocol'), and metadata to the client in a EAP-Request/EAP- 1960 CREDS(Type=ProtoFlow) message. The header's 'S' bit MUST be set to 1961 '1' (Start) and the 'Phase' value set to '2' (Phase Two begins). 1963 NOTE WELL: After the initial message, the only TLVs that are 1964 allowed in messages coming from the server are the usual 1965 ('Provisioning-Headers') ('Provisioning-Data'), and ('Error'). 1967 The client checks that all the selected parameters are supported for 1968 the selected credentials and, if no errors are detected, it sends its 1969 first ('EAP-CREDS-ProtoFlow') message to the Server with the 1970 ('Provisioning-Headers') and ('Provisioning-Data') TLVs only. 1972 From now on, the conversation between the Peer and the Server 1973 continues until an error is detected or the provisioning protocol 1974 completes successfully. 1976 If no other actions, the server MAY continue with phase three or 1977 issue a success message and terminate the EAP session. 1979 NOTE WELL: When the SPP protocol is used, the protocol messages 1980 that are encoded inside the ('Protocol-Data') TLV are composed of 1981 sets of TLVs as defined in this document. The overall message 1982 size is provided by the size of the ('Protocol-Data') TLV that 1983 encapsulates the SPP-specific TLVs. This design choice provides 1984 symmetry in implementing support for SPP when compared to other 1985 provisioning protocols. 1987 In order to terminate Phase Two, the server MUST set, in its last 1988 Phase Two message, the headers' 'E' bit to '1' (End of Phase) and the 1989 'S' bit to '0'. The Server MUST also set the 'Phase' field to '0x2' 1990 value (Phase Two). 1992 NOTE WELL: The last message of a phase can still carry the 1993 ('Provisioning-Data') and ('Provisioning-Headers') TLVs. 1995 5.3. The EAP-CREDS-Validate Message 1997 The EAP-CREDS-Validate message type is used in Phase Three only of 1998 EAP-CREDS. The message flow is depicted in Section 3.4. This 1999 message type supports the following TLVs: Protocol, Credentials-Info, 2000 Provisioning-Headers, Provisioning-Data, Token-Data, and Error. 2002 After Phase One (and/or Phase Two) ends, the Server MAY start phase 2003 three by issuing an ('EAP-CREDS-Validate') message for the Peer where 2004 it encodes all the required details for starting the validation 2005 process. In particular, the server sends the ('Credentials-Info'), a 2006 ('Challenge'), and the ('Phase-Control') TLVs in a EAP-Request/EAP- 2007 CREDS(Type=Validate) message. The ('Phase-Control') TLV should carry 2008 the '1' value for the 'S' bit (Start) and the number '3' for its 2009 value (Phase Three begins). 2011 The Peer generates the answer to the Challenge and sends back a EAP- 2012 Response/EAP-CREDS(Type=Validate) message with the ('Challenge- 2013 Response') and an optional ('Challenge') field (only for server-side 2014 validation of the symmetric credentials). If the Peer requested 2015 server-side validation of the credentials, the Server MUST include 2016 (if a symmetric secret) the response to the Peer-issued ('Challenge') 2017 TLV by computing the response and adding it to the ('Challenge- 2018 Response') TLV in its reply. 2020 Finally, in the last message, the Server (if Phase Three is to be 2021 ended) SHALL include the ('Phase-Control') TLV with the 'S' bit set 2022 to '0' (end of phase) and the value set to '3' (Phase Three ended). 2024 At this point, EAP-CREDS has terminated all possible operations and 2025 can be terminated. The Server can now terminate the EAP session 2026 successfully. In case the Peer was not authenticated during the 2027 tunnel establishment (i.e., no credentials were already available on 2028 the Peer), the Server should terminate the EAP session with a Failure 2029 (thus requiring the device to re-attach and authenticate to the 2030 network - phase two should have provided the Peer with the 2031 credentials to use for authenticating to the Network). 2033 6. Error Handling in EAP-CREDS 2035 This section provides a description of the error handling by using 2036 the CREDS-Error-TLV in a CREDS message. 2038 7. The Simple Provisioning Protocol (SPP) 2040 EAP-CREDS supports a Simple Provisioning Protocol (SPP) which 2041 comprises of a series of messages that enable the management not only 2042 of certificates, but also of other types of credentials like 2043 username/password pairs, asymmetric keys, and symmetric keys. 2045 The Simple Provisioning Protocol (SPP), described in this section, 2046 behaves as any other provisioning protocol: its messages are 2047 encapsulated in the ('Provisioning-Data') TLVs in the second phase of 2048 the protocol. SPP does not make use of any ('Provisioning-Headers') 2049 TLVs because its messages are all self-contained (no transport- 2050 protocol specific options are needed). 2052 When no ('Credentials-Info') TLVs have been provided by the client, 2053 the Server knows that the device does not have valid credentials it 2054 wants to use to access the Network. In this case, EAP-CREDS/SPP 2055 supports the use of Tokens to kick-off the registration process. The 2056 type, format, or encoding of the Token is orthogonal to EAP-CREDS/SPP 2057 which treats the token as a black-box field (i.e., it SHOULD NOT try 2058 to interpret or parse its contents). 2060 NOTE WELL: During Phase One, the Peer MAY include the ('Token- 2061 Data') TLV in its EAP-CREDS-Init message to provide the needed 2062 authorization to register a new set of credentials. The Server 2063 might not allow the registration of new credentials if the 2064 required authorization (i.e., the Token) was not provided during 2065 the initialization phase. 2067 In the case where an authorization token is used, different usage 2068 patterns are supported. For tokens that require an associated 2069 verifiable proof-of-possession, the Peer can include a ('Challenge- 2070 Response') TLVs. 2072 The ('Challenge-Data') TLV provided by the Server MUST be used to 2073 convey the challenge data (usually some random value) to compute the 2074 contents of the ('Challenge-Response') TLV. 2076 The ('Challenge-Response') TLV is used, instead, to encode the 2077 response to the challenge data. The ('Challenge-Response') TLV is 2078 generated by the Peer and verified by the Server. At minimum, the 2079 ('Challenge-Response') TLV SHOULD be calculated over the values of 2080 the ('Token-Data') and the ('Challenge-Data') TLVs to make sure that 2081 the authentication covers the token's data as well. 2083 NOTE WELL: The use of the ('Token-Data'), ('Challenge-Data'), and 2084 ('Challenge-Response') TLVs in the Peer's Init message is be used 2085 only to bootstrap trust between the Server and the Peer. If the 2086 Server accepts the authorization information as valid, the Peer is 2087 enabled for registering new credentials. This should happen only 2088 when the Peer does not have valid credentials or when the server 2089 wants to provision a different type of credentials (i.e., 2090 Action=(Register)). Other methods to provide authorization 2091 information might be provided by the selected provisioning 2092 protocol: in this case, the Server MAY enable registration of new 2093 credentials when no authorization data is provided in the 'Init' 2094 message from the client and delegate the validation of the 2095 authorization data during Phase Two. 2097 7.1. SPP Message Format 2099 The SPP Messages are constructed with zero, one, or more TLVs and 2100 encoded in the ('Provisioning-Data') TLV in EAP-CREDS/ProtoFlow 2101 message types. The size of the encpasulating ('Provisioning-Data') 2102 TLV provides the size of the whole message. 2104 7.2. SPP Message Flow 2105 ,--------. ,----------. 2106 |EAP Peer| |EAP Server| 2107 `---+----' `----+-----' 2108 | [1] EAP-Request/EAP-CREDS(Type=ProtoFlow) | 2109 | { Protocol(=SPP), Action, | 2110 | [ CredsInfo ] [ Params ], | 2111 | [ ProvData(=CredsData) ] } | 2112 | <------------------------------------------ 2113 | | 2114 | [2] EAP-Response/EAP-CREDS(Type=ProtoFlow)| 2115 | { [ ProvData(=CredsData) ] } | 2116 | ------------------------------------------> 2117 | | 2118 | [3] EAP-Response/EAP-CREDS(Type=ProtoFlow)| 2119 | { [ ProvData(=CredsData) ] } | 2120 | <------------------------------------------ 2121 | | 2122 | | 2124 SPP was designed to provide an easy alternative to more complex 2125 provisioning protocols. When no extra flexibility is needed, SPP 2126 provides an easy-to-implement alternative that can handle not only 2127 certificates, but also symmetric secrets and access tokens 2128 provisioning. In this section we provide the generic flow of 2129 messages for SPP and specific examples for certificates, username/ 2130 password, and token provisioning. 2132 EAP-CREDS defines several actions for a set of credentials and they 2133 are listed in Section 8.8. 2135 When a Peer wants to join a network it may or may not have have the 2136 needed credentials to do so. In case the Peer does not have valid 2137 credentials yet, the Server MAY start Phase Two with the intention of 2138 registering a new set of credentials. Alternatively, the Server MAY 2139 start Phase Two when the presented credentials information from the 2140 Peer triggers the Renew or the Remove action. 2142 [1] The Server sends EAP-Request/EAP-CREDS(Type=ProtoFlow) 2144 When registering new credentials, the first message from the 2145 Server, MUST not carry a ('Credentials-Info') TLV since there is 2146 no targeted credentials to apply the action on (i.e., for other 2147 actions - like 'renew' or 'remove' - the TLV would be required to 2148 identify the right set of credentials to renew or delete). 2150 In SPP, the Server sets the ('Protocol') TLV to SPP, the 2151 ('Action') TLV to 'Register', 'Renew', or 'Remove'. When 2152 provisioning (or registering) new credentials for the Peer, the 2153 Server also sets the ('Provisioning-Params') TLV (or Params) to 2154 the type of credentials to be provisioned. The Server also sets 2155 any relevant constraints, and, optionally, the ('Profile') TLV. 2157 NOTE WELL: If the Peer is authorized to register a new set of 2158 credentials, then the first message from the Server will have 2159 the ('Action') TLV set to 'register' and no ('Credentials- 2160 Info') TLV is present in the Server's message. In case server- 2161 side generation is used, an additional ('Credentials-Info') TLV 2162 MAY be encoded inside the ('Provisioning-Data') TLV. 2164 If the type of credentials is symmetric and the parameters call 2165 for server-side generation of a symmetric key share, the Server 2166 MUST also include its own generated share in a ('Credentials- 2167 Data') TLV inside the ('Provisioning-Data') one (the data for the 2168 provisioning protocol are encapsulated in the 'Provisioning-Data' 2169 TLV for any protocol used during Phase Two - SPP is no exception 2170 to this rule). 2172 In case Server-side only is selected, the Server MUST send the new 2173 credentials in its message and include the ('Credentials-Info') 2174 TLV. If no other credentials need to be managed, the Server MUST 2175 end Phase Two by setting the appropriate bits in the EAP-CREDS 2176 headers as well. 2178 [2] The Peer sends EAP-Response/EAP-CREDS(Type=ProtoFlow) 2180 When Peer-generation is selected (either Peer-only or combined 2181 Peer and Server side) and Phase Two has not terminated yet, the 2182 Peer MUST reply to the Server's message with its own 'ProtoFlow' 2183 response. The response MUST carry either (a) its own generated 2184 share of the key in a ('Credentials-Data') TLV (if the credentials 2185 that are provisioned are symmetric and the configuration calls for 2186 a share of the key to be provided by the Peer) or (b) a PKCS#10 2187 request in a ('Certificate-Request') TLV (also in this case, only 2188 if client-side generation was enabled by the Server) that is 2189 generated by using the parameters provided by the Server in the 2190 ('Provisioning-Params') TLV. 2192 [3] The Server sends EAP-Request/EAP-CREDS(Type=ProtoFlow) 2194 The last message of SPP is from the Server and it is used to 2195 deliver the finalized value of the credentials and/or associated 2196 metadata. In case the credentials being provisioned are 2197 Certificate-based, the Server MUST include the issued certificate 2198 in its reply. The issued credentials shall be encoded in a 2199 ('Credentials-Data') TLV inside the ('Provisioning-Data') one. In 2200 case that the selected format supported/selected by the Peer and 2201 the Server does not provide the possibility to encode the full 2202 chain (i.e., intermediate and Root CAs) in the response, the 2203 Server MUST add one ('Certificate-Data') TLV for each certificate 2204 in the chain (including the Root CA's certificate). 2206 The Server MUST include the ('Credentials-Info') TLV in its 2207 message. This provide the Peer with some additional data (e.g., 2208 the 'Profile' or the 'Identifier' associated with the credentials 2209 that were provisioned/managed). 2211 In the case where additional credentials need to be managed, the 2212 Server can continue Phase Two by issuing a new [1] message where 2213 the tuple Action/Credentials must be unique for the current EAP- 2214 CREDS session. 2216 If the message from the Server marks the end of the last phase of 2217 EAP-CREDS, the Server MUST set the message header's 'E' bit set to 2218 '1' (end of phase) and the 'Phase' field set to '2' (Phase Two 2219 ends). 2221 The Server can now decide to start Phase Three (suggested if new 2222 credentials were provisioned or renewed) or to terminate the EAP 2223 session successfully. 2225 7.2.1. SPP Symmetric Secrets Management 2226 ,--------. ,----------. 2227 |EAP Peer| |EAP Server| 2228 `---+----' `----+-----' 2229 | [1] EAP-Request/EAP-CREDS(Type=ProtoFlow) | 2230 | { Protocol(=SPP), Action, [ Creds-Info ], | 2231 | [ Prov-Params ], [ Profile ] | 2232 | [ Prov-Data(=[Creds-Info],[Creds-Data]) ] }| 2233 | <----------------------------------------------- 2234 | | 2235 | [2] EAP-Response/EAP-CREDS(Type=ProtoFlow) | 2236 | { [ Prov-Data(=[Creds-Data]) ] } | 2237 | -----------------------------------------------> 2238 | | 2239 | [3] EAP-Response/EAP-CREDS(Type=ProtoFlow) | 2240 | { [ Prov-Data(=Creds-Info,[Creds-Data]) ] } | 2241 | <----------------------------------------------- 2242 | | 2243 | | 2245 EAP-CREDS/SPP can provision symmetric secrets (e.g, username/ 2246 password, API keys, or SIM-based keys), tokens (e.g., username/ 2247 password OAuth or Kerberos tokens), or asymmetric credentials (e.g., 2248 X.509 certificates or Key Pairs). This section focuses on 2249 provisioning symmetric secrets only. The message flow is provided in 2250 Section 7.2.1 2252 EAP-CREDS/SPP provides the possibility for shared secret to be 2253 generated in different ways: 2255 1. Server-Side Generated 2257 2. Client-Side Generated 2259 3. Both Client-Side and Server-Side Generated 2261 In particular, when initiating the second phase of the protocol, the 2262 ('Provisioning-Params') TLV is used to specify how to generate the 2263 secret (see Section 4.2.1.13). 2265 7.2.1.1. Server Side Only Generation 2267 [ TO BE EDITED ] 2269 Figure 1: SPP Message Flow for Server-Side only secrets provisioning 2270 The message flow for deploying a server-side only credential (i.e., 2271 during registration or renewal) consists of only one message from the 2272 server. The flow is depicted in Figure 1. 2274 In this case, the Server sends the first ProtoFlow message (which is 2275 also the last one), which MUST carry, the following data: 2277 o The ('Credentials-Info') TLV that specifies the info for the 2278 provisioned secret, and 2280 o The ('Protocol') TLV that specifies the provisioning protocol to 2281 be used, and 2283 o The ('Action') TLV that provides the action to be performed 2284 ('Registration') or ('Renew'), and 2286 o The ('Provisioning-Params') TLV that provides the generation 2287 parameters to the Peer, and 2289 The Server also includes, encoded in the ('Provisioning-Data') TLV, 2290 the following data: 2292 The ('Credentials-Info') TLV that provides the metadata associated 2293 with teh generated secret 2295 The ('Credentials-Data') TLV that provides the secret that is 2296 provisioned to the Peer 2298 Server-side secrets' generation can be used to generate username/ 2299 password combinations, API Keys, SIM-based credentials, or tokens. 2301 7.2.1.2. Client Side Only Generation 2303 [ TO BE EDITED ] 2305 Figure 2: SPP Message Flow for Client-Side only secrets provisioning 2307 The message flow for deploying a client-side only credential (i.e., 2308 during registration or renewal) consists of the full three messages 2309 exchange. The flow is depicted in Figure 2. 2311 In this case, the Server MUST include, in its first ProtoFlow message 2312 and encoded in the ('Provisioning-Data') TLV, the following data: 2314 o The ('Credentials-Info') TLV that specifies the target 2315 credentials, and 2317 o The ('Protocol') TLV that specifies the provisioning protocol to 2318 be used, and 2320 o The ('Action') TLV that provides the action to be performed 2321 ('Registration') or ('Renew'), and 2323 o The ('Provisioning-Params') TLV that provides the generation 2324 parameters to the Peer, and 2326 Notice that the Server does not include any ('Credentials-Data') TLV 2327 in its first message because the Server is not involved in the secret 2328 generation (client-side only). 2330 The Peer MUST reply with its own ProtoFlow message where the Peer 2331 MUST encode the following data in the ('Provisioning-Data') TLV: 2333 The ('Credentials-Data') TLV that provides the secret that is 2334 being registered 2336 The credentials data MUST conform to the specifications the Server 2337 provided in the ('Provisioning-Params') TLV. 2339 The final message is from the Server and it MUST contain (if no 2340 errors were detected), the following TLVs encoded, as usual, in the 2341 ('Provisioning-Data') TLV: 2343 The ('Credentials-Info') TLV that specifies the metadata 2344 associated with the generated secret, and 2346 The ('Credentials-Data') TLV that provides the secret that is 2347 provisioned to the Peer 2349 Client-side secrets' generation should be used with caution and an 2350 evaluation of the quality of the generated credentials MUST be 2351 performed to make sure that the security of the generated secret is 2352 adequate for accessing the network. Since evaluating the quality of 2353 a secret is quite a difficult tasks, the use of this generation mode 2354 MUST be evaluated carefully and selected accordingly to acceptable 2355 risk profiles. 2357 7.2.1.3. Client and Server Side Generation 2359 When registering or renewing credentials and the secret generation is 2360 split between the Server (1st share) and the Peer (2nd share), the 2361 message flow is the same as Section 7.2.1.2 with the following 2362 exceptions: 2364 o The Server MUST send its own share of the secret by including a 2365 ('Credentials-Data') TLV in its first message. 2367 All other parameters remain the same. 2369 Co-generation of the secret is the most secure option because both 2370 parties can provide the required randomness in their own share of the 2371 secret. 2373 7.2.2. SPP Key Pair Provisioning 2375 EAP-CREDS/SSP defines the following flow of messages for requesting 2376 the provisioning of key pairs (public and private keys). 2378 7.2.2.1. Server Side Only Generation 2380 [ This case covers the server-side generation of KeyPair and 2381 Certificate ] 2383 7.2.2.2. Client Side Only Generation 2385 [ This case covers the registration of a self-signed or already 2386 available (e.g., device) certificate ] 2388 7.2.2.3. Client and Server Side Generation 2390 This use-case is not supported. In other words, for the provisioning 2391 of Key Pairs, the ('Provisioning-Params') can not have both the peer- 2392 generation and server-generation bits set. 2394 7.2.3. SPP Certificate Provisioning 2396 EAP-CREDS/SSP defines the following flow of messages for requesting 2397 the provisioning of credentials. 2399 7.2.3.1. Server Side Only Generation 2401 [ This case covers the server-side generation of KeyPair and 2402 Certificate ] 2404 7.2.3.2. Client Side Only Generation 2406 [ This case covers the registration of a self-signed or already 2407 available (e.g., device) certificate ] 2409 7.2.3.3. Client and Server Side Generation 2411 [ This case covers the generation of the KeyPair on the Peer and the 2412 generation of the certificate on the Server ] 2414 7.2.4. SPP Token Provisioning 2416 EAP-CREDS/SSP defines the following flow of messages for requesting 2417 the provisioning of token-based credentials. 2419 7.2.4.1. Server Side Only Generation 2421 [ This case covers the server-side generation of the Token and 2422 possibly associated key ] 2424 7.2.4.2. Client Side Only Generation 2426 [ This case covers the registration of a self-signed or already 2427 available (e.g., device) certificate ] 2429 7.2.4.3. Client and Server Side Generation 2431 [ This case covers the generation of the KeyPair on the Peer and the 2432 generation of the Token that cointains the reference to the key on 2433 the Server ] 2435 8. IANA Considerations 2437 This document uses a new EAP type, EAP-CREDS, whose value (TBD) MUST 2438 be allocated by IANA from the EAP TYPEs subregistry of the RADIUS 2439 registry. This section provides guidance to the Internet Assigned 2440 Numbers Authority (IANA) regarding registration of values related to 2441 the EAP-CREDS protocol, in accordance with [RFC8126]. 2443 The EAP Method Type number for EAP-CREDS needs to be assigned. 2445 This document also requires IANA to create new registries as defined 2446 in the following subsections. 2448 8.1. Provisioning Protocols 2449 +-----------------+-------------------------------------------------+ 2450 | Message Type | Purpose | 2451 +-----------------+-------------------------------------------------+ 2452 | 0 | Unspecified | 2453 | 1 | Simple Provisioning Protocol (SPP) | 2454 | 2 | Basic Certificate Management Protocol (CMP-S) | 2455 | 3 | Full Certificate Management Protocol (CMP-F) | 2456 | 4 | Enrollment over Secure Transport (EST) | 2457 | 5 | Certificate Management over CMS (CMC) | 2458 | 6 | Automatic Certificate Management Environment | 2459 | | (ACME) | 2460 | ... | ... | 2461 | 49141 ... 65534 | Vendor Specific | 2462 +-----------------+-------------------------------------------------+ 2464 Table 5: EAP-CREDS Inner Protocol Identifiers 2466 Assignment of new values for new cryptosuites MUST be done through 2467 IANA with "Specification Required" and "IESG Approval" as defined in 2468 [RFC8126]. 2470 8.2. Token Types 2472 +------------+-----------------+ 2473 | Token Type | Description | 2474 +------------+-----------------+ 2475 | 0 | Unspecified | 2476 | 1 | JWT | 2477 | 2 | Kerberos | 2478 | 3 | OAuth | 2479 | 200..254 | Vendor Specific | 2480 +------------+-----------------+ 2482 Table 6: Token Types 2484 Assignment of new values for new Message Types MUST be done through 2485 IANA with "Expert Review" as defined in [RFC8126]. 2487 8.3. Credentials Types 2488 +------------------+-----------------------+ 2489 | Credentials Type | Description | 2490 +------------------+-----------------------+ 2491 | 0 | X.509 Certificate | 2492 | 1 | Public Key | 2493 | 2 | Symmetric Key | 2494 | 3 | Username and Password | 2495 | 4 | AKA Subscriber Key | 2496 | 5 | Bearer Token | 2497 | 6 | One-Time Token | 2498 | 7 | API Key | 2499 +------------------+-----------------------+ 2501 Table 7: Credentials Types 2503 Assignment of new values for new Message Types MUST be done through 2504 IANA with "Expert Review" as defined in [RFC8126]. 2506 8.4. Credentials Algorithms 2508 +---------+--------------------+ 2509 | ID | Algorithm | 2510 +---------+--------------------+ 2511 | 0 | None | 2512 | 1 | RSA | 2513 | 2 | ECDSA | 2514 | 3 | XMMS | 2515 | 4 | AKA Subscriber Key | 2516 | 5 | OAuth | 2517 | 6 | Kerberos4 | 2518 | 7 | Kerberos5 | 2519 | 200-254 | Reserved | 2520 +---------+--------------------+ 2522 Table 8: Credentials Algorithms 2524 Assignment of new values for new Message Types MUST be done through 2525 IANA with "Expert Review" as defined in [RFC8126]. 2527 8.5. Credentials Datatypes 2528 +---------+---------------+ 2529 | ID | Data Type | 2530 +---------+---------------+ 2531 | 0 | None (Binary) | 2532 | 1 | PKCS#8 | 2533 | 2 | PKCS#10 | 2534 | 3 | PKCS#12 | 2535 | 4 | PublicKeyInfo | 2536 | 200-254 | Reserved | 2537 +---------+---------------+ 2539 Table 9: Credentials Datatypes 2541 Assignment of new values for new Message Types MUST be done through 2542 IANA with "Expert Review" as defined in [RFC8126]. 2544 8.6. Network Usage Datatypes 2546 +--------+------------------------------------------+ 2547 | ID | Data Type | 2548 +--------+------------------------------------------+ 2549 | 0 | Vendor-Specific | 2550 | 1 | Manufacturer Usage Description [RFC8520] | 2551 | 2 | Network Access Granting System | 2552 | 3 | Firmware Manifest | 2553 | 4..127 | Reserved for Future Use | 2554 +--------+------------------------------------------+ 2556 Table 10: Network Usage Datatypes 2558 Assignment of new values for new Message Types MUST be done through 2559 IANA with "Expert Review" as defined in [RFC8126]. 2561 8.7. Credentials Encoding 2562 +---------+------------+ 2563 | ID | Encoding | 2564 +---------+------------+ 2565 | 0 | None (Raw) | 2566 | 1 | DER | 2567 | 2 | PEM | 2568 | 3 | Base64 | 2569 | 4 | JSON | 2570 | 5 | XML | 2571 | 6 | ASCII | 2572 | 7 | UTF-8 | 2573 | 200-254 | Reserved | 2574 +---------+------------+ 2576 Table 11: Credentials Encoding 2578 Assignment of new values for new Message Types MUST be done through 2579 IANA with "Expert Review" as defined in [RFC8126]. 2581 8.8. Action Types 2583 +---------+--------------+--------------------------------+ 2584 | ID | Data Type | Description | 2585 +---------+--------------+--------------------------------+ 2586 | 0 | Registration | Registers New Credentials | 2587 | 1 | Renewal | Renew an Existing Credential | 2588 | 2 | Remove | Removes an Existing Credential | 2589 | 200-254 | n/a | Reserved | 2590 +---------+--------------+--------------------------------+ 2592 Table 12: Action Types 2594 Assignment of new values for new Message Types MUST be done through 2595 IANA with "Expert Review" as defined in [RFC8126]. 2597 8.9. Usage Metadata Types 2599 +------+----------------------+ 2600 | Type | Description | 2601 +------+----------------------+ 2602 | 0 | Binary (Unspecified) | 2603 | 1 | MUD File | 2604 | 2 | TEEP Manifest | 2605 +------+----------------------+ 2607 Table 13: Usage Metadata Types 2609 Assignment of new values for new Message Types MUST be done through 2610 IANA with "Expert Review" as defined in [RFC8126]. 2612 9. Security Considerations 2614 Several security considerations need to be explicitly considered for 2615 the system administrators and application developers to understand 2616 the weaknesses of the overall architecture. 2618 The most important security consideration when deploying EAP-CREDS is 2619 related to the security of the outer channel. In particular, EAP- 2620 CREDS assumes that the communication channel has been properly 2621 authenticated and that the information exchanged between the Peer and 2622 the Server are protected (i.e., confidentiality and integrity). 2624 For example, if certificate-based authentication is used, the server 2625 presents a certificate to the peer as part of the trust establishment 2626 (or negotiation). The peer SHOULD verify the validity of the EAP 2627 server certificate and SHOULD also examine the EAP server name 2628 presented in the certificate in order to determine whether the EAP 2629 server can be trusted. When performing server certificate 2630 validation, implementations MUST provide support for the rules in 2631 [RFC5280] for validating certificates against a known trust anchor. 2633 10. Acknowledgments 2635 The authors would like to thank everybody who provided insightful 2636 comments and helped in the definition of the deployment 2637 considerations. 2639 11. Normative References 2641 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2642 Requirement Levels", BCP 14, RFC 2119, 2643 DOI 10.17487/RFC2119, March 1997, 2644 . 2646 [RFC3748] Aboba, B., Blunk, L., Vollbrecht, J., Carlson, J., and H. 2647 Levkowetz, Ed., "Extensible Authentication Protocol 2648 (EAP)", RFC 3748, DOI 10.17487/RFC3748, June 2004, 2649 . 2651 [RFC4210] Adams, C., Farrell, S., Kause, T., and T. Mononen, 2652 "Internet X.509 Public Key Infrastructure Certificate 2653 Management Protocol (CMP)", RFC 4210, 2654 DOI 10.17487/RFC4210, September 2005, 2655 . 2657 [RFC5272] Schaad, J. and M. Myers, "Certificate Management over CMS 2658 (CMC)", RFC 5272, DOI 10.17487/RFC5272, June 2008, 2659 . 2661 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 2662 Housley, R., and W. Polk, "Internet X.509 Public Key 2663 Infrastructure Certificate and Certificate Revocation List 2664 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 2665 . 2667 [RFC6402] Schaad, J., "Certificate Management over CMS (CMC) 2668 Updates", RFC 6402, DOI 10.17487/RFC6402, November 2011, 2669 . 2671 [RFC7030] Pritikin, M., Ed., Yee, P., Ed., and D. Harkins, Ed., 2672 "Enrollment over Secure Transport", RFC 7030, 2673 DOI 10.17487/RFC7030, October 2013, 2674 . 2676 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 2677 Writing an IANA Considerations Section in RFCs", BCP 26, 2678 RFC 8126, DOI 10.17487/RFC8126, June 2017, 2679 . 2681 [RFC8520] Lear, E., Droms, R., and D. Romascanu, "Manufacturer Usage 2682 Description Specification", RFC 8520, 2683 DOI 10.17487/RFC8520, March 2019, 2684 . 2686 Appendix A. EAP-CREDS Example Message Flow for Provisioning Standards 2688 A.1. EAP-CREDS and CMP 2690 Describe how to use EAP-CREDS with CMP. 2692 A.2. EAP-CREDS and EST 2694 Describe how to use EAP-CREDS with EST. 2696 A.3. EAP-CREDS and CMS 2698 Describe how to use EAP-CREDS with CMS. 2700 A.4. EAP-CREDS and ACME 2702 Describe how to use EAP-CREDS with ACME. 2704 Author's Address 2706 Massimiliano Pala 2707 CableLabs 2708 858 Coal Creek Cir 2709 Louisville, CO 80027 2710 US 2712 Email: m.pala@openca.org 2713 URI: http://www.linkedin.com/in/mpala