idnits 2.17.1 draft-pala-eap-creds-04.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 (July 23, 2019) is 1739 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 2223 -- Looks like a reference, but probably isn't: '2' on line 2229 == Missing Reference: 'N' is mentioned on line 606, but not defined -- Looks like a reference, but probably isn't: '3' on line 2233 == Missing Reference: 'RFC3279' is mentioned on line 746, but not defined == Missing Reference: 'RFC4055' is mentioned on line 746, but not defined == Missing Reference: 'RFC4491' is mentioned on line 747, but not defined Summary: 0 errors (**), 0 flaws (~~), 7 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Pala 3 Internet-Draft CableLabs 4 Intended status: Standards Track July 23, 2019 5 Expires: January 24, 2020 7 Credentials Provisioning and Management via EAP (EAP-CREDS) 8 draft-pala-eap-creds-04 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 January 24, 2020. 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 . . . . . . . . . . . . . 4 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 . . . . . . . . . . . . . . . . . 6 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 . . . . . . . . . . . . . . . . . 16 91 3.4.1. Phase Three State Machine . . . . . . . . . . . . . . 18 92 4. EAP-CREDS Message Format . . . . . . . . . . . . . . . . . . 19 93 4.1. Message Header . . . . . . . . . . . . . . . . . . . . . 19 94 4.2. Message Payload . . . . . . . . . . . . . . . . . . . . . 21 95 4.2.1. EAP-CREDS defined TLVs . . . . . . . . . . . . . . . 22 96 4.2.1.1. The Action TLV . . . . . . . . . . . . . . . . . 22 97 4.2.1.2. The Certificate-Data TLV . . . . . . . . . . . . 23 98 4.2.1.3. The Challenge-Data TLV . . . . . . . . . . . . . 24 99 4.2.1.4. The Challenge-Response TLV . . . . . . . . . . . 25 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 . . . . . . . . . . . . . . . . . . 29 103 4.2.1.8. The Network-Usage TLV . . . . . . . . . . . . . . 30 104 4.2.1.9. The Profile TLV . . . . . . . . . . . . . . . . . 32 105 4.2.1.10. The Protocol TLV . . . . . . . . . . . . . . . . 33 106 4.2.1.11. The Provisioning-Data TLV . . . . . . . . . . . . 33 107 4.2.1.12. The Provisioning-Headers TLV . . . . . . . . . . 34 108 4.2.1.13. The Provisioning-Params TLV . . . . . . . . . . . 35 109 4.2.1.14. The Certificate-Request TLV . . . . . . . . . . . 37 110 4.2.1.15. The Storage-Info TLV . . . . . . . . . . . . . . 38 111 4.2.1.16. The Supported-Formats TLV . . . . . . . . . . . . 39 112 4.2.1.17. The Supported-Encoding TLV . . . . . . . . . . . 40 113 4.2.1.18. The Token-Data TLV . . . . . . . . . . . . . . . 40 114 4.2.1.19. The Version TLV . . . . . . . . . . . . . . . . . 41 115 5. EAP-CREDS Messages . . . . . . . . . . . . . . . . . . . . . 42 116 5.1. The EAP-CREDS-Init Message . . . . . . . . . . . . . . . 42 117 5.1.1. EAP Server's Init Message . . . . . . . . . . . . . . 42 118 5.1.2. EAP Peer's Init Message . . . . . . . . . . . . . . . 43 119 5.1.2.1. Bootstrapping Peer's Trustworthiness . . . . . . 43 120 5.2. The EAP-CREDS-Provisioning Message . . . . . . . . . . . 44 121 5.3. The EAP-CREDS-Validate Message . . . . . . . . . . . . . 45 122 6. Error Handling in EAP-CREDS . . . . . . . . . . . . . . . . . 46 123 7. The Simple Provisioning Protocol (SPP) . . . . . . . . . . . 46 124 7.1. SPP Message Format . . . . . . . . . . . . . . . . . . . 47 125 7.2. SPP Message Flow . . . . . . . . . . . . . . . . . . . . 47 126 7.2.1. SPP Symmetric Secrets Management . . . . . . . . . . 50 127 7.2.1.1. Server Side Only Generation . . . . . . . . . . . 51 128 7.2.1.2. Client Side Only Generation . . . . . . . . . . . 51 129 7.2.1.3. Client and Server Side Generation . . . . . . . . 53 130 7.2.2. SPP Key Pair Provisioning . . . . . . . . . . . . . . 53 131 7.2.2.1. Server Side Only Generation . . . . . . . . . . . 53 132 7.2.2.2. Client Side Only Generation . . . . . . . . . . . 53 133 7.2.2.3. Client and Server Side Generation . . . . . . . . 53 134 7.2.3. SPP Certificate Provisioning . . . . . . . . . . . . 53 135 7.2.3.1. Server Side Only Generation . . . . . . . . . . . 53 136 7.2.3.2. Client Side Only Generation . . . . . . . . . . . 54 137 7.2.3.3. Client and Server Side Generation . . . . . . . . 54 138 7.2.4. SPP Token Provisioning . . . . . . . . . . . . . . . 54 139 7.2.4.1. Server Side Only Generation . . . . . . . . . . . 54 140 7.2.4.2. Client Side Only Generation . . . . . . . . . . . 54 141 7.2.4.3. Client and Server Side Generation . . . . . . . . 54 142 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 54 143 8.1. Provisioning Protocols . . . . . . . . . . . . . . . . . 55 144 8.2. Token Types . . . . . . . . . . . . . . . . . . . . . . . 55 145 8.3. Credentials Types . . . . . . . . . . . . . . . . . . . . 55 146 8.4. Credentials Algorithms . . . . . . . . . . . . . . . . . 56 147 8.5. Credentials Datatypes . . . . . . . . . . . . . . . . . . 56 148 8.6. Challenge Types . . . . . . . . . . . . . . . . . . . . . 57 149 8.7. Network Usage Datatypes . . . . . . . . . . . . . . . . . 57 150 8.8. Credentials Encoding . . . . . . . . . . . . . . . . . . 58 151 8.9. Action Types . . . . . . . . . . . . . . . . . . . . . . 58 152 8.10. Usage Metadata Types . . . . . . . . . . . . . . . . . . 58 153 9. Security Considerations . . . . . . . . . . . . . . . . . . . 59 154 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 59 155 11. Normative References . . . . . . . . . . . . . . . . . . . . 59 156 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 60 158 1. Requirements notation 160 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 161 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 162 document are to be interpreted as described in [RFC2119]. 164 2. Introduction 166 Many environments are, today, moving towards requiring strong 167 authentication when it comes to gain access to networks. The 802.1x 168 architecture provides network administrators with the possibility to 169 check credentials presented by a device even before providing any 170 connectivity or IP services to it. 172 However, the provisioning and management of these credentials is a 173 hard problem to solve and many vendors opt for long-lived credentials 174 that can not be easily revoked, replaced, or simply renewed. 176 This specification addresses the problem of providing a simple-to-use 177 and simple-to-deploy conduit for credentials management by extending 178 the EAP protocol to support credentials provisioning and management 179 functionality. In particular, the EAP-CREDS method defined here 180 provides a generic framework that can carry the messages for 181 provisioning different types of credentials. EAP-CREDS cannot be 182 used as a stand-alone method, it is required that EAP-CREDS is used 183 as an inner method of EAP-TLS, EAP-TEAP, or any other tunnelling 184 method that can provide the required secrecy and (at minimum) server- 185 side authentication to make sure that the communication is protected 186 and with the right server. 188 2.1. Overview of existing solutions 190 Currently there are many protocols that address credentials lifecycle 191 management. In particular, when it comes to digital certificates, 192 some of the most deployed management protocols are: Certificate 193 Management Protocol (CMP) [RFC4210], Certificate Management over CMS 194 (CMC) [RFC5272][RFC6402], Enrollment over Secure Transport (EST) 195 [RFC7030], and Automated Certificate Management Environment (ACME) . 196 However, none of these protocols provide native support for client 197 that do not have IP connectivity yet (e.g., because they do not have 198 network-access credentials, yet). EAP-CREDS provides the possibility 199 to use such protocols (i.e., message-based) by defining a series of 200 messages that can be used to encapsulate the provisioning messages 201 for the selected provisioning protocol. 203 In addition to these protocols, EAP-CREDS also defines a series of 204 simple messages that provide a generic enrollment protocol that 205 allows not only certificates but also other types of credentials 206 (e.g., username/password pairs, tokens, or symmetric secrets) to be 207 delivered to the client as part of the provisioning and/or renewal 208 process. The set of messages that make up the generic provisioning 209 protocol is referred to as the Simple Provisioning Protocol protocol 210 or SPP. 212 2.2. Scope Statement 214 This document focuses on the definition of the EAP-CREDS method to 215 convey credentials provisioning and managing messages between the 216 client and the AAA server. Moreover, the document defines how to 217 encode messages for the main IETF provisioning protocols. 219 This document, however, does not provide specifications for how and 220 where the credentials are generated. In particular, the credentials 221 could be generated directly within the AAA server or at a different 222 location (i.e., the Certificate Service Provider or CSP) site. 223 Different authentication mechanisms (e.g., TLS, etc.) can be used to 224 secure the communication between the server's endpoint and the CSP. 226 2.3. EAP-CREDS as tunneled mechanism only 228 EAP-CREDS requires that an outer mechanism is in place between the 229 Peer and the Server in order to provide authentication and 230 confidentiality of the messages exchanged via EAP-CREDS. In other 231 words, EAP-CREDS assumes that an appropriatly encrypted and 232 authenticated channel has been established to prevent the possibility 233 to leak information or to allow man-in-the-middle attacks. 235 This choice was taken to simplify the message flow between Peer and 236 Server, and to abstract EAP-CREDS from the secure-channel 237 establishment mechanism. EAP-TLS, or EAP-TEAP are examples of such 238 mechanisms.s 240 2.4. Fragmentation Support 242 EAP does not directly support handling fragmented packets and it 243 requires the outer method to provide fragmentation support. 245 Because of the outer method requirements in particular, removing any 246 support for fragmented messages in EAP-CREDS removes the duplication 247 of packets (e.g., Acknowledgment Packets) sent across the Peer and 248 the Server, thus resulting in a smaller number of exchanged messages 250 2.5. Encapsulating Provisioning Protocols in EAP-CREDS 252 In order to use EAP-CREDS together with your favorite provisioning 253 protocol, the messages from the provisioning protcol need to be sent 254 to the other party. In EAP-CREDS, this is done by encoding the 255 provisioning protocol messages inside the ('Provisioning-Data') TLV. 256 In case the provisioning protocol uses additional data for its 257 operations (e.g., uses HTTP Headers), this data can be encoded in a 258 separate ('Provisioning-Headers') TLV. 260 Since the implementation of the provisioning endpoint could happen in 261 a (logically or physically) different component, a method is needed 262 to identify when a provisioning protocol has actually ended. In EAP- 263 CREDS, the 'D' bit in the message headers is used for this purpose. 265 In the first message of Phase Two, the Server provides the client 266 with all the selected parameters for one specific credential that 267 needs attention (or for a new credential) to be managed by the 268 network. In particular, the server provides, at minimum, the 269 ('Protocol') TLV, the ('Action') TLV, and the ('Provisioning-Params') 270 or the ('Credentials-Info') TLV. 272 After checking the parameters sent by the Server, if the Peer does 273 not support any of the proposed ones, it MUST send a message with one 274 single ('Error') TLV with the appropriate error code(s). The server, 275 can then decide if to manage a different set of credentials (if more 276 where reported by the Peer in its Phase One message) or if to 277 terminate the EAP session with an error. 279 The Peer and the Server exchange Provisioning messages until an error 280 is detected (and the appropriate error message is sent to the other 281 party) or until Phase Two is successfully completed. 283 2.6. Algorithm Requirements 285 EAP-CREDS uses the SHA-256 hashing algorithm to verify credentials in 286 phase three of the protocol. Peers and Servers MUST support SHA-256 287 for this purpose. 289 2.7. Notation 291 In this document we use the following notation in the diagrams to 292 provide information about the cardinality of the data structures 293 (TLVs) within EAP-CREDS messages: 295 +--------+------------+---------------------------------------------+ 296 | Symbol | Example | Usage | 297 +--------+------------+---------------------------------------------+ 298 | { } | {TLV1} | Curly Brackets are used to indicate a set | 299 | [ ] | {[TLV2]} | Square Brackets are used to indicate that a | 300 | | | field is optional | 301 | ( ) | {TLV1(=V)} | Round Squares are used to specify a value | 302 | + | {TLV_2+} | The Plus character indicates that one or | 303 | | | more instances are allowed | 304 +--------+------------+---------------------------------------------+ 306 Table 1: EAP-CREDS Notation 308 3. EAP-CREDS Protocol 310 In a nutshell, EAP-CREDS provides the abstraction layer on top of 311 which credentials provisioning/managing protocols can be deployed 312 thus enabling their use even before provisioning IP services. 314 This section outlines the operation of the protocol and message 315 flows. The format of the CREDS messages is given in Section 4. 317 3.1. Message Flow 319 EAP-CREDS message flow is logically subdivided into three different 320 phases: Initialization, Provisioning, and Validation. EAP-CREDS 321 enforces the order of phases, i.e. it is not possible to move to an 322 earlier phase. 324 Phase transitioning is controlled by the Server. In particular, the 325 server, after the last message of a phase, it can decide to either 326 (a) start the next phase by sending the first message of the next 327 phase, or (b) continue the same phase by sending another "first" 328 message of the phase (e.g., managing a second set of credentials) - 329 this is allowed only in Phase Two and Phase Three but NOT in Phase 330 One, or (c) terminate the EAP session. 332 Phase One (Required). Initialization. During this phase the Peer 333 and the Server exchange the information needed to select the 334 appropriate credentials management protocol. Phase One flow is 335 composed by only messages. In particular, the Sever sends its 336 initial message of type ('EAP-CREDS-Init'). The Peer replies with 337 the details about which provisioning protocols are supported, and 338 additional information such as the list of installed credentials 339 and, optionally, authorization data (for new credentials 340 registration). 342 Phase Two (Optional). Provisioning Protocol Flow. In this phase, 343 the Peer and the Server exchange the provisioning protocol's 344 messages encapsulated in a EAP-CREDS message of type Provisioning. 345 The messages use two main TLVs. The first one is the 346 ('Provisioning-Headers') TLV which is optional and carries 347 information that might be normally coveyed via the transport 348 protocol (e.g., HTTP headers). The second one is the 349 ('Provisioning-Data'), which is required and carries the 350 provisioning protocol's messages. The server can decide to repeat 351 phase two again to register new credentials or to renew a separate 352 set of credentials by issuing a new ('Provisioning') message for 353 the new target. When no more credentials have to be managed, the 354 Server can start phase three or simply terminate the EAP session. 356 Phase Three (Optional). Credentials Validation. This optional phase 357 can be initiated by the server and it is used to validate that the 358 Peer has properly installed the credentials and can use them to 359 authenticate itself. Depending on the credentials' type, the 360 messages can carry a challenge/nonce, the value of the secret/ 361 token, or other information. The format of the credentials is 362 supposed to be known by the provider and the device. 364 3.1.1. Phase Transitioning Rules 366 In order to keep track of starting and ending a phase, EAP-CREDS 367 defines several bits and fields in the EAP-CREDS message headers. In 368 particular, as described in Section 4.1, the 'S' bit is used to 369 indicate the beginning (or Start) of a phase, while the 'Phase' field 370 (4 bits) is used to indicate the phase for this message. 372 In EAP-CREDS, phase transitioning is under the sole control of the 373 Server, therefore the value of the 'S' bit is meaningful only in 374 messages sent by the Server. The value of the 'S' bit in Peer's 375 messages SHALL be set to '0x0' and SHALL be ignored by the server. 377 When starting a new phase, the Server MUST set the 'S' bit to '1' and 378 the 'Phase' field to the current phase number (e.g., one, two, or 379 three). 381 In case the first message of a phase is to be repeated (e.g., because 382 of processing multiple credentials), the 'S' bit SHALL be set to '0' 383 (i.e., it should be set to '1' only on the first occurrency and set 384 to '0' in subsequent messages). 386 NOTE WELL: Once EAP-CREDS transitions from one phase to the next, 387 the state machine MUST prohibit going back to a previous phase. 389 3.2. Phase One: Initialization 391 The following figure provides the message flow for Phase One: 393 ,--------. ,----------. 394 |EAP Peer| |EAP Server| 395 `---+----' `----+-----' 396 | Outer Tunnel Established | 397 | <--------------------------------------> 398 | | 399 | [1] EAP-Request/EAP-CREDS(Type=Init) | ,---------!. 400 | { [ Version+ ], [ Challenge ] } | |Phase One|_\ 401 | <--------------------------------------- |Begins | 402 | | `-----------' 403 | [2] EAP-Response/EAP-CREDS(Type=Init) | 404 | { Protocol+, [ Encoding+ ], | 405 | [ Format+ ] , [ Version ] | ,---------!. 406 | [ Creds-Info+ ], [ Storage-Info ]| |Phase One|_\ 407 | [ Net-Usage], [ Token ], | |Ends | 408 | [ Challenge-Rsp ], [ Profile+ ] }| `-----------' 409 | ---------------------------------------> 410 | | 411 | | 413 EAP-CREDS Phase One Message Flow 415 [1] Server sends EAP-Request/EAP-CREDS(Type=Init): 417 After the establishment of the outer mechanism (e.g., EAP-TLS, 418 EAP-TEAP, EAP-TTLS, etc.), the server MAY decide to start a 419 credentials management session. In order to do that, the Server 420 sends an EAP-Request/EAP-CREDS(Type=Init) message to the Peer with 421 one ('Phase-Control') TLV with the 'S' bit set to '1' and the 422 value set to '1' (thus indicating the beginning of Phase One). 423 Also, the Server MAY use one or more ('Version') TLVs to indicate 424 the supported versions. 426 The Server MAY also specify which versions of EAP-CREDS are 427 supported by adding one or more ('Version') TLVs. If no 428 ('Version') TLV is added to the message, the Peer SHOULD assume 429 the supported version is 1 ('0x1'). 431 [2] The Peer sends EAP-Response/EAP-CREDS(Type=Init) 432 The Peer, sends back a message that carries one ('Version') TLV to 433 indicate the selected version of EAP-CREDS (i.e. from the list 434 provided by the server) (optional). If the client does not 435 include the ('Version') TLV, the Server MUST use the most recent 436 supported version of EAP-CREDS. Moreover, the Server includes one 437 or more ('Protocol') TLVs to indicate the list of supported 438 provisioning protocols, followed by one ('Credentials-Info') TLVs 439 for each installed credentials to provide their status to the 440 server (i.e., if multiple credentials are configured on the Peer 441 for this Network, then the Peer MUST include one ('Credentials- 442 Info') TLV for each of them). 444 The Peer also provides the list of supported Encodings and Formats 445 by adding one or more ('Supported-Encodings') and ('Supported- 446 Formats') TLVs. The Peer MAY also provide the Server with 447 information about the Peer's credentials storage by using the 448 'Storage-Status' TLV. 450 When there are no abailable credentials, the Peer MAY include an 451 authorization token that can be consumed by the Server for 452 registering new credentials. In particular, the Peer can include 453 the ('Token-Data') TLV to convey the value of the token. The 454 ('Challenge-Data') and ('Challenge-Response') TLVs, instead, can 455 be used to convey a challenge and its response based on the 456 authorization information (e.g., maybe a public key hash is 457 present in the Token, then the peer can generate some random data 458 - or use the one from the Server - and generate a signature on 459 that value: the signature SHALL be encoded in the ('Challenge- 460 Response') TLV and it should be calculated over the concatenation 461 of values inside the ('Challenge-Data') TLV and the ('Token-Data') 462 TLV. 464 Also, the Peer MAY add one or more ('Profile') TLVs to indicate to 465 the Server which profiles are requested/supported (e.g., a pre- 466 configuration MAY exist on the Peer with these ecosystem-specific 467 identifiers). 469 Ultimately, the Peer MAY include additional metadata regarding the 470 status of the Peer. To this end, the Peer can use a ('Storage- 471 Info') TLV to provide the server with additional data about the 472 Peer's capabilities and resources. Also, the ('Network-Usage') 473 TLV can be used to provide the Server with the indication of which 474 network resources are needed by the Peer and what is its intended 475 utilization pattern(s). 477 The server checks that the Peer's selected protocol, version, and 478 parameters are supported and, if not (or if the server detects an 479 error), it can (a) send a non-recoverable error message to the 480 peer, notify the outer (tunneling) layer, and terminate the EAP- 481 CREDS session, or (b) start phase one again by sending a new 482 ('EAP-CREDS-Init') message that will also carry an ERROR TLV that 483 provides the Peer with the reason the initial response was not 484 acceptable. In this case, the ('Phase-Control') TLV MUST be 485 omitted since it is not the first message of phase one. The 486 server and the peer can repeat phase one until they reach an 487 agreement or the session is terminated by the Server. 489 NOTE WELL: The determination of the need to start phase two or not 490 is based on the contents of the ('Credentials-Info') TLV sent by 491 the Peer (e.g., a credential is about to expire or a credential is 492 simply missing). 494 3.2.1. Phase One State Machine 496 The Server's state machine is depicted in the following Figure: 498 +-------------------+ 499 | Start Phase One | 500 +-------------------+ 501 | 502 v 503 +-------------------+ 504 | Send the Init Msg | 505 +-------------------+ 506 | 507 v 508 +-------------------+ 509 | Receives Peer's | 510 | Init Msg | 511 +-------------------+ 512 | 513 v 514 +------------------+ Yes +---------------------+ 515 | Checks for Error |------->| Send Error Msg | 516 +------------------+ +---------------------+ 517 | No | 518 v v 519 +-------------------+ No +---------------------+ 520 | Provisioning ? |------->| End EAP Session | 521 +-------------------+ +---------------------+ 522 | Yes 523 v 524 +-------------------+ 525 | Start Phase Two | 526 +-------------------+ 528 EAP Creds Phase One State Machine 530 The first message from the server starts the phase by using the 531 ('Phase-Control') TLV. 533 The Server selects the action, the provisioning protocol, and 534 associated parameters. Phase Two officially begins with the next 535 message exchanged (i.e. an EAP-Request/EAP- 536 CREDS(Type=Provisioning)),which MUST include the ('Phase-Control') 537 TLV with the 'S' bit set to '1' and the value set to '2'. The 538 message MUST also includes, at minimum, the selected ('Action') and 539 ('Protocol') TLVs. 541 When renewing existing credentials or registering new ones, the 542 Server MUST include the ('Provisioning-Params') TLVs. 544 When removing or renewing existing credentials, the Server MUST 545 include the ('Credentials-Info') TLV to identify the set of 546 credentials to which the action applies. 548 If multiple values are detected in the message, the message shall be 549 discarded and the appropriate error message shall be issued by the 550 Peer. 552 3.3. Phase Two: Provisioning 554 The following figure provides the message flow for Phase 2: 556 ,--------. ,----------. 557 |EAP Peer| |EAP Server| 558 `---+----' `----+-----' 559 | [1] EAP-Request/EAP-CREDS(Type=Provisioning) | 560 | { Protocol, Action, | ,---------!. 561 | [ CredInfo ], [ Params ], | |Phase Two|_\ 562 | [ ProtoData ], [ ProtoHeaders ] } | |Begins | 563 | <---------------------------------------------- `-----------' 564 | | 565 | [2] EAP-Response/EAP-CREDS(Type=Provisioning) | 566 | { ProtoData, [ ProtoHeaders ] } | 567 | ----------------------------------------------> 568 | | 569 . . 570 . . 571 . . 572 . . 573 | [N] EAP-Response/EAP-CREDS(Type=Provisioning) | 574 | { [ CredInfo ], [ ProtoData ], | 575 | [ ProtoHeaders ] } | 576 | <---------------------------------------------- 577 | | 578 | [N+1] EAP-Request/EAP-CREDS(Type=Provisioning)| ,---------!. 579 | { [ ProtoData ], [ ProtoHeaders ] } | |Phase Two|_\ 580 | ----------------------------------------------> |Ends | 581 | | `-----------' 582 | | 584 EAP-CREDS Phase Two Message Flow 586 [1] The Server sends EAP-Request/EAP-CREDS(Type=Init) 588 The first message of Phase Two indicates that the Server is ready 589 to initiate the selected provisioning protocol. 591 [2] The Peer sends EAP-Response/EAP-CREDS(Type=Init) 593 After that, the Peer sends its first message to the Server by 594 sending the EAP-Response/EAP-CREDS(Type=Provisioning) message. 595 This message contains the selected provisioning protocol's message 596 data and some extra fields (e.g., transport-protocol headers) in 597 the ('Provisioning-Data') and ('Protocol-Headers') TLVs 598 respectively. 600 [3] The Server sends EAP-Request/EAP-CREDS(Type=Init) 602 The Server replies to the Peer's message with EAP-Request/EAP- 603 CREDS(Type=Provisioning) messages until the provisioning protocol 604 reaches an end or an error condition arise (non-recoverable). 606 [N] The Server sends EAP-Request/EAP-CREDS(Type=Provisioning) 608 When the provisioning protocol has been executed for the specific 609 set of credentials, the server sends a last message that MUST 610 include the description of the provisioned credentials in a 611 ('Credentials-Info') TLV and MUST set the 'D' bit in the EAP-CREDS 612 message header to '1' to indicates that the server does not have 613 any more ('Provisioning') messages for this credenital. The final 614 message does not need to be an empty one, i.e. other TLVs are 615 still allowed in the same message (e.g., the 'Provisioning-Data' 616 and the 'Provisioning-Headers' ones). 618 [N+1] The Peer sends EAP-Request/EAP-CREDS(Type=Provisioning) 620 The Peer MUST reply to the server with a ('Provisioning') message 621 that MUST have the 'D' bit in the EAP-CREDS message header set to 622 '1', thus indicating that the credentials have been installed 623 correctly. In case of errors, the Peer MUST include the 624 appropriate ('Error') TLV. Also in this case, the final message 625 does not need to be an empty one, i.e. other TLVs are still 626 allowed in the same message (e.g., the 'Provisioning-Data' and the 627 'Provisioning-Headers' ones). 629 At this point, the Server can decide to provision (or manage) another 630 set of credentials by issuing a new ('Provisioning') message, or it 631 can decide to start Phase Three by sending its first ('Validate') 632 message, or it can terminate the EAP session. 634 3.3.1. Phase Two State Machine 636 The Server's state machine for Phase Two is depicted in the following 637 Figure: 639 +-------------------+ 640 | Start Phase Two | 641 +-------------------+ 642 | 643 v 644 +-------------------+ 645 +----------------->| New Credentials | 646 | +----<| Available ? |>-----+ 647 | | Yes +-------------------+ No | 648 | | ^ | 649 | v | v 650 | +-------------------+ | +-------------------+ 651 | | Action Needed for |>----+ | Register New | 652 | | Credentials ? | No | Credentials | 653 | +-------------------+ +-------------------+ 654 | v Yes Yes v v No 655 | | | | 656 | | +-------------------+ | | 657 | +---->| Provisioning |<--+ | 658 | | Protocol | | 659 | +-------------------+ | 660 | | | 661 | v | 662 | No +------------------+ | 663 +-----------------<| End of Provision | | 664 +------------------+ | 665 Yes | | 666 v | 667 +------------------+ | 668 | End of Phase Two |<-----------+ 669 +------------------+ 671 EAP-CREDS Phase Two State Machine 673 The Server can decide to repeat phase two as many times as needed: 674 each time, the combination of the ('Credentials-Info') TLV (a.k.a. 675 CredInfo) and the ('Action') TLV MUST be unique for each session to 676 make sure notto repeat the same operation on the same credential over 677 and over again. In case all credentials for the Network do not need 678 maintenance at this time, the Server can decide to end the EAP-CREDS 679 session (no actions to be taken) and successfully complete the EAP 680 session. 682 3.4. Phase Three: Validation 684 The following figure provides the message flow for Phase 3: 686 ,--------. ,----------. 687 |EAP Peer| |EAP Server| 688 `---+----' `----+-----' 689 | [1] EAP-Request/EAP-CREDS(Type=Validate) | ,-----------!. 690 | { Cred-Info, Challenge } | |Phase Three|_\ 691 | <----------------------------------------- |Begins | 692 | | `-------------' 693 | [2] EAP-Response/EAP-CREDS(Type=Validate)| ,-----------!. 694 | { Challenge-Response } | |Phase Three|_\ 695 | -----------------------------------------> |Ends | 696 | | `-------------' 697 | | 699 EAP-CREDS Phase Three Message Flow 701 Phase three is optional and it is used by the server to request the 702 client to validate (proof) that the new credentials have been 703 installed correctly before issuing the final Success message. 705 NOTE WELL: Phase Three introduces a dependency on the selected 706 hashing algorithm to provide common and easy way to check the 707 integrity and functionality of a newly installed set of 708 credentials. 710 [1] The Server sends EAP-Request/EAP-CREDS(Type=Validate) 712 In order to start Phase Three, the Server sends an EAP-Request/ 713 EAP-CREDS(Type=Validate) message to the Peer. The Server MUST 714 include the ('Credentials-Info') TLV to provide the indication 715 about which set of credentials the Server intends to validate. 716 The Server MUST also include a randomly generated challenge in the 717 message to the client. The type of challenge determines how the 718 ('Challenge-Response') is calculated. EAP-CREDS defines the 719 asymmetric and symmetric challenges in Section 8.6 and others can 720 be defined according to the specified rules. 722 As usual, the Server MUST set, in the headers, the 'S' bit to '1' 723 in its first message of Phase Three and the 'Phase' value shall be 724 set to '3' (beginning of Phase Three). 726 [2] The Peer sends EAP-Response/EAP-CREDS(Type=Validate) 727 When the client receives the Validate message from the server, it 728 calculates the response to the challenge and sends the response 729 back to the server in a EAP-Response/EAP-CREDS(Type=Validate) 730 message. When the EAP-CREDS-ASYMMETRIC-CHALLENGE and EAP-CREDS- 731 SYMMETRIC-CHALLENGE values are used in the Challenge type, the 732 Peer MUST calculate the response as follows: 734 Public-Key 736 For any public-key based credentials (e.g., certificates or 737 raw key pairs), the response to the challenge is calculated 738 by generating a signature over the hashed value of the 739 challenge. The hashing algorithm to be used for this 740 purpose is specified in Section 2.6. The format of the 741 signature in the ('Challenge-Response') TLV is the 742 concatenation of: 744 - The signatureAlgorithm (DER encoded) which contains the 745 identifier for the cryptographic algorithm used by the 746 Peer to generate the signature. [RFC3279], [RFC4055], 747 and [RFC4491] list supported signature algorithms, but 748 other signature algorithms MAY also be supported. The 749 definition of the signatureAlgorithm is provided in 750 Section 4.1.1.2 of [RFC5280]. 752 - The signatureValue (DER encoded) which contains the 753 digital signature itself. The signature value is encoded 754 as a BIT STRING and the details of how to generate the 755 signatures' structures can be found in Section 4.1.1.3 of 756 [RFC5280] and referenced material. 758 Symmetric Secret 760 For any symmetric based credentials (e.g., password or Key), 761 the response to the challenge is calculated by using the 762 selected hash function (see Section 2.6) on the 763 concatenation of (a) the value carried in the server- 764 provided ('Challenge-Data') TLV, and (b) the secret value 765 itself (salted hash). 767 The initial values for the type of challenges are described in the 768 Section 8.6. Other types of challenges MAY be defined according 769 to the specified procedures. 771 In case of issues with the validation of newly deployed 772 credentials, both the Server and the Peer should consider those 773 credentials invalid (or unusable) and should issue the required 774 failure message(s). 776 3.4.1. Phase Three State Machine 778 The Server's state machine for Phase Three is depicted in the 779 following Figure: 781 +-------------------+ 782 | Start Phase Three | 783 +-------------------+ 784 | 785 v 786 +---------------------+ No 787 +------------------------------->| New Credentials |>-------+ 788 | +------------------->| Available ? |<---+ | 789 | | +---------------------+ | | 790 | | Yes | ^ | | 791 | | v | | | 792 | | +-------------------+ | | | 793 | | | Validate |>-----+ | | 794 | | | Credentials ? | No | | 795 | | +-------------------+ | | 796 | | v Yes | | 797 | | | | | 798 | | | +---------------------+ | | 799 | | +----->| Send Validate | | | 800 | | | Messsage | | | 801 | | +---------------------+ | | 802 | | | | | 803 | | v | | 804 | +---------------------+ No +---------------------+ | | 805 | | Report the Error |<----<| Response Error? |----+ | 806 | +---------------------+ +---------------------+ No | 807 | Yes | | 808 | v | 809 | No +---------------------+ | 810 +------------------------------<| End Validation ? | | 811 +---------------------+ | 812 Yes | | 813 v | 814 +---------------------+ | 815 | End Phase Three |<--------+ 816 +---------------------+ 818 EAP-CREDS Phase Three State Machine 820 4. EAP-CREDS Message Format 822 The EAP-CREDS defines the following message types: 824 1. EAP-CREDS/Init 826 2. EAP-CREDS/Provisioning 828 3. EAP-CREDS/Validate 830 Each of these message types have the basic structure as identified in 831 Section 4.1. EAP-CREDS messages contain zero, one, or more TLVs. 832 The internal structure of the different types of TLVs is described in 833 Section 4.2, while a detailed description of the EAP-CREDS message 834 types is provided in Section 5. 836 4.1. Message Header 838 The EAP-CREDS messages consist of the standard EAP header (see 839 Section 4 of [RFC3748]), followed by the version of the EAP-CREDS (4 840 bits) and a field (4 bits) reserved for future use. The header has 841 the following structure: 843 0 1 2 3 844 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 845 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 846 | Code | Identifier | Length | 847 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 848 | Type |J|S|F|D| Phase | Message Length | 849 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 850 | Message Length | Data ... 851 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-. 853 Where the Code, Identifier, Length, and Type fields are all part of 854 the EAP header as defined in [RFC3748]. Since EAP-CREDS can only be 855 used as a tunneled mechanism, the presence of these fields is only 856 for backward compatibility with existing parsers. In particular, the 857 'Length' field is not used (can be ignored): the message length is 858 carried in the 'Message Length' field instead. 860 The Type field in the EAP header is for EAP-CREDS. 862 The Flags bitfield is used to convey status information (e.g., extra 863 long message, phase number, phase transitioning state). The 864 transition-control bit (i.e., the 'S' bit) are set in Server's 865 messages and are ignored in Peer's messages (the Server is the entity 866 that unilaterally controls the phase transition process). The 867 meanins of the bits in the 'Flags' field are as follows: 869 Bit 'J' (Jumbo Message) - If set, it idicates the presence of the 870 'Message Length' field. This bit SHALL be used only when the size 871 of the message exceeds the maximum value allowed in the 'Length' 872 field. In this case, the 'Message Length' field is added to the 873 message and set to the whole message size and the 'Length' field 874 is used for the current fragment length. If not set, the 'Message 875 Length' field is not present in the Message and the 'Length' field 876 is used for the message size (and the 'F' bit MUST be set to '0'). 878 Bit 'S' (Start) - If set, this message is the first one of a new 879 EAP-CREDS phase. The value of the new phase is encoded in the 880 'Phase' field. 882 Bit 'F' - If set, this message is a fragment of a message. In 883 this case, the 'Data' field is to be concatenated with all 884 messages with the 'F' bit set to '1' until the message with the 885 'F' bit set to '0' that indicates the end of the message. If the 886 message is not fragmented, the 'F' bit MUST be set to '0'. The 887 use of this bit is required when the tunneling method does not 888 provide support for messages up to 2^32 bits in size. 890 Bit 'D' - This bit is used in Phase Two and Phase Three to 891 indicate that the specific operation for the identified credential 892 is over. For example, when multiple credentials exist on the Peer 893 and the Server needs to manage and validate one of them. In its 894 last message, when the provisioning protocol is done, the server 895 sets the 'D' (Done) bit to indicate that it is done. The Peer, in 896 its reply, sets the bit to indicate the end of provisioning for 897 this credentials is also over. After that, the Server can 898 continue Phase Two, transition to Phase Three, or terminate the 899 EAP session. 901 The Phase field is a 4-bits value and identifies the EAP-CREDS phase 902 for the current message. The version of EAP-CREDS described in this 903 document supports three values for this field: 905 0x01 - Phase One 907 0x02 - Phase Two 909 0x03 - Phase Three 911 A detailed explanation of the 'Phase' and 'Flags' fields of the 912 message headers is provided in Section 3.1.1. 914 The Data field is the message payload. The full description of this 915 field is provided in the next section. 917 4.2. Message Payload 919 The Data part of the message is organized as zero, one, or more TLV 920 objects whose structure is defined in this section. 922 Each TLV object has the same basic structure that is defined as 923 follows: 925 0 1 2 3 926 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 927 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 928 | TLV Type | TLV Length | 929 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 930 | TLV Value ... 931 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 933 Where: 935 TLV-Type (uint8) 937 This field is used to indicate the type of data that the TLV 938 carries. The type of TLV determines its internal structure. The 939 supported values for this fields are provided in the following 940 table: 942 Length (uint24) 944 This field carries the size of the value of the TLV. In 945 particular, the overall size of a TLV (i.e., the header plus the 946 value) can be calculated by adding the size of the header (6 947 octects) to the value of the Length field (i.e., the size of the 948 TLV's value). 950 +----------+--------------------------+------------------------+ 951 | TLV Name | TLV Type | Scope/Usage | 952 +----------+--------------------------+------------------------+ 953 | | Action TLV | Phase Two | 954 | | Certificate-Data TLV | Phase Two/SPP | 955 | | Challenge-Data TLV | Phase Two, Phase Three | 956 | | Challenge-Response TLV | Phase Two, Phase Three | 957 | | Credentials-Data TLV | Phase Two/SPP | 958 | | Credentials-Info TLV | Phase Two, Phase Three | 959 | | Error TLV | All Phases | 960 | | Network-Usage TLV | Phase One | 961 | | Profile TLV | Phase Two | 962 | | Protocol TLV | Phase One, Phase Two | 963 | | Provisioning-Data TLV | Phase Two | 964 | | Provisioning-Headers TLV | Phase Two | 965 | | Provisioning-Params TLV | Phase Two | 966 | | Certificate-Request TLV | SPP | 967 | | Storage-Info TLV | SPP | 968 | | Supported-Format TLV | SPP | 969 | | Supported-Encoding TLV | SPP | 970 | | Token-Data TLV | Phase One | 971 | | Version TLV | Phase One | 972 +----------+--------------------------+------------------------+ 974 Table 2: EAP-CREDS Supported TLVs Types 976 TLV Value ( > 1 octet ) 978 This field carries data for the identified TLV. The internal 979 structure is determined by the TLV Type field. 981 The rest of this section describes the structure of the different 982 supported TLVs and their usage in the different messages. 984 4.2.1. EAP-CREDS defined TLVs 986 EAP-CREDS messages's payload comprieses zero, one, or more TLVs that 987 are encoded in a single EAP-CREDS message. The values for the TLV 988 Type that are supported by this specifications are listed in Table 2. 990 4.2.1.1. The Action TLV 991 0 1 2 3 992 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 993 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 994 | TLV Type | TLV Length | 995 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 996 | Flags | Action Type | 997 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 999 TLV Type (uint8) 1001 - Action TLV 1003 TLV Length (uint24) 1005 Fixed value (=2) 1007 Flags (uint8) 1009 Reserved 1011 4.2.1.2. The Certificate-Data TLV 1013 0 1 2 3 1014 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 1015 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1016 | TLV Type | TLV Length | 1017 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1018 | Flags | Format | Encoding | Value ... 1019 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1021 TLV Type (uint8) 1023 - Certificate-Data TLV 1025 Length (uint24) 1027 Provides the length of the TLV (> 3 octets) 1029 Flags (uint8) 1031 Provides a BITMASK that can be used to provide additional 1032 information related to the encapsulated certificate. The bits 1033 have the following meaning: 1035 Bit 0 - If set, the certificate is trusted (Trust Anchor) 1036 Bit 1 - If set, the certificate is a CA certificate 1038 Bit 2 - If set, the certificate is self-signed 1040 Bit 3 - If set, the certificate is a proxy certificate 1042 Bit 4 - If set, the certificate is an attribute certificate 1044 Bit 5 - Reserved 1046 Bit 6 - Reserved 1048 Bit 7 - Reserved 1050 For a Trusted Root CA, the value of the flags shall be 0x7 (0000 1051 0111). For an intermediate CA certificate that is not implicitly 1052 trusted, the value of the flags field should be set to 0x02 (0000 1053 0010). For an End-Entity certificate, the value of the Flags will be 1054 0x0 (0000 0000). 1056 Format (uint8) 1058 Provides the indication of the Format the certificate is in. The 1059 allowed values for this field are listed in Section 8.5. 1061 Encoding (uint8) 1063 Provides the indication of the Encoding the certificate is in. 1064 The allowed values for this field are listed in Table 12. 1066 Value (octet string) 1068 This field carries the data for the certificate. 1070 4.2.1.3. The Challenge-Data TLV 1072 0 1 2 3 1073 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 1074 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1075 | TLV Type | TLV Length | 1076 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1077 | Ch. Type | Challenge Data ... 1078 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1080 TLV Type (uint8) 1081 - Challenge-Data TLV 1083 Length (uint24) 1085 3 octets 1087 Challenge Type (uint8) 1089 This field carries the type of Challenge. In particular, the 1090 challenge type determines how the Peer MUST calculate the 1091 ('Challenge-Response'). The initial values for this fiel are 1092 listed in Section 8.6. Please refer to Section 3.4 for a detailed 1093 explanation of how to calculate the response to the challenge for 1094 the challenge types defined in this document. 1096 Challenge Data (> 1 octet) 1098 This field carries the data to be used as a challenge when 1099 validating newly deployed credentials. 1101 4.2.1.4. The Challenge-Response TLV 1103 0 1 2 3 1104 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1105 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1106 | TLV Type | TLV Length | 1107 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1108 | Challenge Response ... 1109 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1111 TLV Type (uint8) 1113 - Challenge-Response TLV 1115 Length (uint24) 1117 3 octets 1119 Challenge Response (> 1 octet) 1121 This field carries the data that resulted from the use of the 1122 credentials to be validated. 1124 4.2.1.5. The Credentials-Information TLV 1126 0 1 2 3 1127 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 1128 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1129 | TLV Type | TLV Length | 1130 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1131 | Flags | CredsType | ProtoID | 1132 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1133 | | 1134 | IssuedOn (GMT) | 1135 | | 1136 | | 1137 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1138 | | 1139 | Expires On (GMT) | 1140 | | 1141 | | 1142 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1143 | Credentials Length | 1144 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1145 | CredIDValue ... 1146 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1148 The Credential-Information TLV is used by the Peer to provide a 1149 description of the installed credentials that are relevant for the 1150 network that is being accessed. 1152 For example, when a set of credentials need to be renewed, the server 1153 checks the ('Credentials-Info') from the Peer and eventually selects 1154 the right one for renewal. The TLV structure is as follows: 1156 TLV Type (uint8) 1158 - Credentials-Information TLV 1160 Length (uint24) 1162 Provides the total length of the body of the Credential- 1163 Information TLV. 1165 Flags (uint8) 1167 Provides a BITMASK that can be used to provide information about 1168 the status of the credentials (e.g., if the use marks the 1169 credentials to be compromised). The bits have the following 1170 meaning: 1172 Bit 0 - If set, the credential is marked as compromised 1174 Bit 1 - If set, the credential is immutable and cannot be 1175 updated 1177 Bit 2 - Private Key or Secret Immutable, the public part of the 1178 credential (e.g., a certificate) can still be updated 1180 Bit 3 - If set, the credential cannot be updated (both public 1181 and private parts) 1183 Bit 4 - If set, the credential is ready to be used 1185 Bit 5 - If set, the credential was generated on the server 1187 Bit 6 - If set, the Peer would like to update the credential 1188 even if they are not expired 1190 Bit 7 - Reserved 1192 CredType (uint8) 1194 This field provides the description of the type of credential. 1195 The type of credentials are listed in Table 7 1197 ProtoID (uint16) 1199 This field indicates the protocol that was used to retrieve the 1200 target credential. When the TLV is used in a Request by the 1201 Server, this field is ignored. The values for this field are 1202 listed in Table 5. 1204 IssuedOn (16 octets) 1206 This field carries the GMT date for when this credential was 1207 issued. This field is 16 bytes long (the last byte must be set to 1208 '0x00') and contains the NULL-terminated ASCII string that 1209 represents the timestamp where the credential was issued. When 1210 the value is not set, the field should be set to { 0x00 }. The 1211 format of the string is as follows: 1213 YYYYMMDDHHmmssZ 1215 Where: 1217 YYYY - is the 4 digits representation of the year 1219 MM - is the 2 digits representation of the month 1221 DD - is the 2 digits representation of the day of the month 1223 HH - is the 2 digits representation of the hour of the day (24 1224 hour format) 1226 mm - is the 2 digits representation of the minutes of the hour 1228 ss - is the 2 digits representation of the seconds of the 1229 minute 1231 Z - is the character 'Z' 1233 ExpiresOn (16 octets) 1235 This field carries the GMT date for when this credential is to be 1236 considered expired. This field is 16 bytes long (the last byte 1237 must be set to '0x00') and contains the NULL-terminated ASCII 1238 string that represents the timestamp where the credential was 1239 issued. The format is the same as the ('IssuedOn') field. When 1240 the value is not set, the field should be set to { 0x00 }. 1242 Credentials Length (uint16) 1244 Length (in bytes) of the Credentials value. When used with a 1245 public-key type of credentials, this is the size of the key (e.g., 1246 for an RSA 2048 bit keys, this field should carry the value of 1247 256). When used with a symmetric secret, this field carries the 1248 size of the secred (in bytes). 1250 CredIDValue (> 1 octet) 1252 The binary value of the credentials' identifier. This identifier 1253 can be the binary value of the SHA-256 calculated over the 1254 certificate, a username, or it could be a random handle. As long 1255 as the ID allows the peer and the server to uniquely (in its 1256 context) identify the credentials, the value of this field can be 1257 calculated in any way. 1259 4.2.1.6. The Credentials-Data TLV 1261 0 1 2 3 1262 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 1263 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1264 | TLV Type | TLV Length | 1265 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1266 | Cred Type | Format | Encoding | Value ... 1267 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1269 TLV Type (uint8) 1271 - Credentials-Data TLV 1273 Length (uint24) 1275 Provides the length of the TLV (> 3 octets) 1277 Cred Type (uint8) 1279 Provides the indication of the type of credentials. The allowed 1280 values for this field are listed in Table 7. 1282 Format (uint8) 1284 Provides the indication of the Format the credentials are in. The 1285 allowed values for this field are listed in Section 8.5. 1287 Encoding (uint8) 1289 Provides the indication of the Encoding the credentials are in. 1290 The allowed values for this field are listed in Table 12. 1292 Value (octet string) 1294 This field carries the data for the credentials. 1296 4.2.1.7. The Error TLV 1297 0 1 2 3 1298 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 1299 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1300 | TLV Type | TLV Length | 1301 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1302 | EAP-CREDS Error Code | Secondary Error Code | 1303 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1304 | Description ... 1305 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1307 TLV Type (uint8) 1309 - Challenge-Response-Data TLV 1311 Length (uint24) 1313 3 octets 1315 EAP-CREDS Error Code (2 octets) 1317 This field carries the EAP-CREDS error code. These code are 1318 related to the EAP-CREDS operations only and it should not be used 1319 to carry the Provisioning-Protocol specific error codes. 1321 The error codes supported by this specifications are listed in 1322 Section 4.2.1.7. 1324 Secondary Error Code (2 octets) 1326 This field is used to convery an error at the encapsulation layer 1327 (i.e., the provisioning protocol error). For example, this field 1328 can be used to convey a transport protocol error code (e.g., HTTP 1329 status code). Do not use this field to convery EAP-CREDS specific 1330 errors. 1332 Description ( > 1 octet) 1334 The Description field is optional (i.e., when the Description Size 1335 is set to zero) and carries information about the error that 1336 occurred. The message may or may not be used by a user or an 1337 automated process for debugging purposes. 1339 4.2.1.8. The Network-Usage TLV 1340 0 1 2 3 1341 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 1342 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1343 | TLV Type | TLV Length | 1344 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1345 |U| Desc Format | Encoding | Network-Usage Data ... 1346 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1348 TLV Type (uint8) 1350 - Network-Usage TLV 1352 Length (uint24) 1354 Variable Length TLV (Value must be > 2 ) 1356 Description Format (uint8) 1358 The Type of data encoded in the Peer Description Data. The 1359 initial values for this field are listed in Section 8.10. 1361 Encoding (uint8) 1363 Provides the indication of the Encoding the network usage 1364 description data is in. The allowed values for this field are 1365 listed in Table 12. 1367 The 'U' field (1 bit) 1369 The 'URL' bit ('U') is used to indicate if the value of the 1370 Network-Usage Data field is to be interpreted as a URL or as the 1371 actual data. In particular, if the value in the 'URL' bit is '1', 1372 then the value in the Network-Usage Data field is to be 1373 interpreted as the URL where the actual data can be downloaded 1374 from. Otherwise, if the 'URL' bit is set to '0', then the value 1375 in the Netowrk-Usage Data field is to be interpreted as the actual 1376 data (not a URL referencing it). 1378 An example use of this bit is when the Peer wants to convey the 1379 URL of the MUD file [RFC8520]. In this case, the Peer can set the 1380 Network-Usage Data field to the Url of the MUD file related to the 1381 Peer. 1383 Desc Format (7 bits) 1385 This field provide the expected data format for the Network-Usage 1386 Data. For example, the value in this field could be set to 'MUD' 1387 and have the 'U' bit set to '1' to provide the MUD-related 1388 information at credentials management time instead of at network- 1389 provisioning time (DHCP option). This possibility could help the 1390 Network controller to decide if the device shall be allowed to 1391 register its credentials or not. 1393 The list of initial values for this field is provided in 1394 Section 8.7. 1396 Network-Usage Data (octet string) 1398 This is additional information related to the device. In 1399 particular, this TLV can be used by the Peer to provide the Server 1400 with the description of the intended network usage or a URL that 1401 points to the same information. 1403 For example, this field can be used to convey a MUD file 1404 (Manufacturer Usage Description) or the latest firmware-update 1405 manifest. 1407 4.2.1.9. The Profile TLV 1409 0 1 2 3 1410 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 1411 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1412 | TLV Type | TLV Length | 1413 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1414 | Profile Identifying Data ... 1415 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1417 TLV Type (uint8) 1419 - Profile Identifying Data TLV 1421 Length (uint24) 1423 Length value should be >= 1 1425 Profile Identifying Data (octet string) 1427 The Profile Identifying Data is used to provide indication to the 1428 other party about which profiles are supported when requesting 1429 credentials management. 1431 Also in this case, the data used in this field is left to be 1432 interpreted by the end-point and it is orthogonal to EAP-CREDS 1433 data types. 1435 An example of values for this field, an end-point could use the 1436 string representation (i.e., dotted representation) of the Object 1437 Identifier (OID) of the specific profile supported (e.g., could be 1438 defined in the Certificate Policy of the credentials' provider). 1440 4.2.1.10. The Protocol TLV 1442 0 1 2 3 1443 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 1444 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1445 | TLV Type | TLV Length | 1446 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1447 | Protocol ID | Version | 1448 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1450 TLV Type (uint8) 1452 - Protocol TLV 1454 TLV Length (uint24) 1456 Fixed TLV Length value of 4. 1458 Protocol ID (uint16) 1460 The Protocol ID value carries the id of a supported provisioning 1461 protocol. The initial list of values for the provisioning 1462 protocol identifiers can be found in Section 8.1. 1464 Version (uint16) 1466 The Version (Protocol Version) value represents the specific 1467 version of the identified provisioning protocol. When no version 1468 is specified for a protocol (i.e., either it does not support 1469 multiple versions or it does not matter), the value of this field 1470 should be set to '0x0'. 1472 4.2.1.11. The Provisioning-Data TLV 1473 0 1 2 3 1474 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 1475 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1476 | TLV Type | TLV Length | 1477 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1478 | Provisioning Data ... 1479 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1481 TLV Type (uint8) 1483 - Provisioning-Data TLV 1485 Length (uint24) 1487 3 octets 1489 Headers Data (> 1 octet) 1491 This field carries the provisioning protocol's messages. 1493 4.2.1.12. The Provisioning-Headers TLV 1495 0 1 2 3 1496 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 1497 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1498 | TLV Type | TLV Length | 1499 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1500 | Headers Data ... 1501 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1503 TLV Type (uint8) 1505 - Provisioning-Headers TLV 1507 Length (uint24) 1509 3 octets 1511 Headers Data (> 1 octet) 1513 This field carries the meta-data (if any) that might be associated 1514 with the transport-layer normally used with the provisioning 1515 protocol. For example, this TLV can carry the set of HTTP headers 1516 required by EST or ACME. 1518 4.2.1.13. The Provisioning-Params TLV 1520 0 1 2 3 1521 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 1522 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1523 | TLV Type | TLV Length | 1524 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1525 | Min Length | Max Length | 1526 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1527 | Algorithm | Flags | OBJECT IDENTIFIER (DER) ... 1528 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1530 TLV Type (uint8) 1532 - Provisioning-Params TLV 1534 Length (uint24) 1536 Provides the length of the TLV (>= 6 octets) 1538 Min Length (uint16) 1540 Provides the minimum allowed size size for the credentials. This 1541 value has meaning depending on the context of the credentials, 1542 however sizes are always expressed in bytes. 1544 For example, when used with a symmetric key or a password, the 1545 ('Min Length') and ('Max Length') refer to the minimum and maximum 1546 size of the password data. The ('Algor OID') field can be omitted 1547 in this case. 1549 On the other hand, when referring public-key credentials, this 1550 field should carry the size of the modulus of the key. For 1551 example, for an RSA 2048 bit keys, the field should carry the 1552 value of 256. For an ECDSA that uses the prime256r1 curve, this 1553 field should carry the value of 32 and the Algor OID should be the 1554 DER representation of the specific value of the curve (i.e., the 1555 DER representation of '1.2.840.10045.3.1.7'). 1557 Max Length (uint16) 1559 Provides the indication maximum size of the credentials. This 1560 value has meaning depending on the context of the credentials, 1561 however sizes are always expressed in bytes. 1563 The same considerations apply to this field as well as the ('Min 1564 Length') one discussed above. 1566 Flags (uint8) 1568 Provides a BITMASK that can be used to provide information about 1569 the status of the credentials (e.g., if the use marks the 1570 credentials to be compromised). The bits have the following 1571 meaning: 1573 Bit 0 - Credentials (or part of it) are to be generated on the 1574 server 1576 Bit 1 - Credentials (or part of it) are to be generated on the 1577 peer 1579 Bit 2 - Credentials are to be generated on dedicated hardware 1581 Bit 3 - Reserved 1583 Bit 4 - Reserved 1585 Bit 5 - Reserved 1587 Bit 6 - Reserved 1589 Bit 7 - Reserved 1591 When using public-key based credentials, the bits 0 and 1 are 1592 mutually exclusive. 1594 When using passwords or shared secrets, if bit 0 is set, then the 1595 secret is generated by the server and then sent to the client. On 1596 the other hand, if bit 1 is set, then the secret is generated by 1597 the peer and then sent to the server. Ultimately, if both bits 1598 are set, then the Server generates the first part of the password 1599 and sends it to the Peer, while the Peer generates the second part 1600 of the password and sends it to the Server. The password to be 1601 used for future authentication is the concatenation of the two 1602 shares of the password: first the one from the Server, then the 1603 one from the Client. 1605 NOTE WELL: Last but not least, since these passwords/secrets 1606 are meant to be used in a automated fashion, there is no 1607 restriction around the character set to use or their 1608 interpretation. Therefore,it is good practice to generate 1609 random passphrases that use the full 8-bit character set (on 1610 client and server) to maximize the secret's search space. 1612 Algorithm (uint8) 1614 Provides the indication of the algorithm used for the generation 1615 of the credentials. The allowed values for this field are listed 1616 in Table 8. 1618 Object Identifier (binary; > 1 octet) 1620 Provides the indication of additional parameters that are needed 1621 to be encoded for the credentials. This value is used only when 1622 the credentials use public-key cryptography - this field carries 1623 additional information about the generation algorithm to be used. 1624 We provide some useful values that can be used as reference: 1626 +----------------+----------------------+---------------------------+ 1627 | OID Name | Dotted | Binary Encoding | 1628 | | Representation | | 1629 +----------------+----------------------+---------------------------+ 1630 | secp256r1 | 1.2.840.10045.3.1.7 | 06 08 2A 86 48 CE 3D 03 | 1631 | curve | | 01 07 | 1632 | secp384r1 | 1.2.840.10045.3.1.34 | 06 08 2A 86 48 CE 3D 03 | 1633 | curve | | 01 22 | 1634 | secp521r1 | 1.2.840.10045.3.1.35 | 06 08 2A 86 48 CE 3D 03 | 1635 | curve | | 01 23 | 1636 | X25519 curve | 1.3.101.110 | 06 03 2B 65 6E | 1637 | X25519 curve | 1.3.101.110 | 06 03 2B 65 6E | 1638 | X448 curve | 1.3.101.111 | 06 03 2B 65 6F | 1639 | Ed25519 curve | 1.3.101.112 | 06 03 2B 65 70 | 1640 | Ed448 curve | 1.3.101.113 | 06 03 2B 65 71 | 1641 +----------------+----------------------+---------------------------+ 1643 Table 3: Object Identifiers Examples 1645 4.2.1.14. The Certificate-Request TLV 1647 0 1 2 3 1648 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 1649 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1650 | TLV Type | TLV Length | 1651 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1652 | Encoding | Format | Value ... 1653 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1655 TLV Type (uint8) 1657 - Token-Data TLV 1659 TLV Length (uint24) 1661 Provides the length of the TLV (> 3 octets) 1663 Encoding (uint8) 1665 Provides the indication of the Encoding the credentials are in. 1666 The allowed values for this field are listed in Table 12. 1668 Format (uint8) 1670 Provides the indication of the type of credentials. The allowed 1671 values for this field are listed in Table 9. 1673 Value (octet string) 1675 This field carries the data for the credentials. 1677 4.2.1.15. The Storage-Info TLV 1679 0 1 2 3 1680 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 1681 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1682 | TLV Type | Flags | Spare Slots | 1683 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1684 | Available Memory | 1685 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1687 TLV Type (uint8) 1689 - Store-Info TLV 1691 Flags (8 bits) 1693 Provides information about the status and type of store and 1694 limited information about its capabilities. The bits have the 1695 following meaning: 1697 Bit 0 - If set, the store supports RSA keys (software) 1699 Bit 1 - If set, the store supports RSA keys (hardware) 1700 Bit 2 - If set, the store supports ECDSA keys (software) 1702 Bit 3 - If set, the store supports ECDSA keys (hardware) 1704 Bit 4 - If set, the store supports symmetric keys 1706 Bit 5 - If set, the store supports generic tokens 1708 Bit 6 - If set, the store is immutable (no key generation or 1709 deletion) 1711 Bit 7 - Not Used 1713 Spare Slots (uint16) 1715 Provides the number of available slots where to store credentials. 1716 When no more slots are available, the value of '0' should be used 1717 to indicate to the Server that a credential must be deleted before 1718 a new one can be created. 1720 When the number of slots is not fixed or not known, the value of { 1721 0xFF, 0xFF } shall be used. 1723 Available Memory (uint32) 1725 This field carries the size (in bytes) of the spare memory on the 1726 Peer's secrets' store. 1728 4.2.1.16. The Supported-Formats TLV 1730 0 1 2 3 1731 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 1732 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1733 | TLV Type | TLV Length | 1734 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1735 | Format | 1736 +-+-+-+-+-+-+-+-+ 1738 TLV Type (uint8) 1740 - Supported-Format TLV 1742 TLV Length (uint24) 1744 Provides the length of the TLV. This field must be set to 1. 1746 Format (uint8) 1748 Provides the details about the supported format. Multiple formats 1749 TLVs can be used in the Peer's ('Init') message to provide the 1750 Server with the Peer's capabilities. 1752 4.2.1.17. The Supported-Encoding TLV 1754 0 1 2 3 1755 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 1756 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1757 | TLV Type | TLV Length | 1758 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1759 | Encoding | 1760 +-+-+-+-+-+-+-+-+ 1762 TLV Type (uint8) 1764 - Store-Info TLV 1766 TLV Length (uint24) 1768 Provides the length of the TLV. The field has a fixed value of 1. 1770 Encoding (uint8) 1772 Provides the indication of the supported Encoding by the End 1773 Point. This provides the indication to the Server of the 1774 capability of the Peer. The allowed values for this field are 1775 listed in Table 12. 1777 4.2.1.18. The Token-Data TLV 1779 0 1 2 3 1780 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 1781 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1782 | TLV Type | TLV Length | 1783 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1784 | Token Type | Encoding | Value ... 1785 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1787 TLV Type (uint8) 1789 - Token-Data TLV 1791 TLV Length (uint24) 1793 Provides the length of the TLV (> 3 octets) 1795 Token Type (uint8) 1797 Provides the indication of the type of credentials. The allowed 1798 values for this field are listed in Table 6. 1800 Encoding (uint8) 1802 Provides the indication of the Encoding the credentials are in. 1803 The allowed values for this field are listed in Table 12. 1805 Value (octet string) 1807 This field carries the data for the credentials. 1809 4.2.1.19. The Version TLV 1811 0 1 2 3 1812 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 1813 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1814 | TLV Type | TLV Length | 1815 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1816 | Version | 1817 +-+-+-+-+-+-+-+-+ 1819 TLV Type (uint8) 1821 - Version TLV 1823 TLV Length (uint24) 1825 Provides the length of the TLV. The field has a fixed value of 1. 1827 Version (uint8) 1829 The Version field represents the specific version of the EAP-CREDS 1830 protocol that are supported by the end point. When multiple 1831 versions of EAP-CREDS are supported, multiple ('Version') TLVs can 1832 be used. 1834 When no version is specified (i.e., either it does not support 1835 multiple versions or it does not matter), the value of this field 1836 should be set to '0x0' (any version). 1838 5. EAP-CREDS Messages 1840 This section describes each message and what TLVs are allowed or 1841 required. EAP-CREDS defines the following values for the Message 1842 Type (Type): 1844 +-----------+------------------------+------------------------------+ 1845 | Message | Name | Description | 1846 | Type | | | 1847 +-----------+------------------------+------------------------------+ 1848 | 0 | EAP-CREDS-Init | Initialization Phase | 1849 | 1 | EAP-CREDS-Provisioning | Carries Provisioning | 1850 | | | Protocol Messages | 1851 | 2 | EAP-CREDS-Validate | Validates newly installed | 1852 | | | credentials | 1853 +-----------+------------------------+------------------------------+ 1855 Table 4: EAP-CREDS Message Types 1857 5.1. The EAP-CREDS-Init Message 1859 The EAP-CREDS-Init message type is used in Phase One only of EAP- 1860 CREDS. The message flow is depicted in Section 3.2. This message 1861 supports the following TLVs: Version, Protocol, Credentials-Info, and 1862 Error. 1864 5.1.1. EAP Server's Init Message 1866 EAP-CREDS starts with an ('EAP-CREDS-Init') message from the server. 1867 This message MAY contain zero, one, or more ('Version') TLVs and, 1868 optionally, a ('Challenge-Data') TLV. 1870 The first message from the server is the one that starts Phase One, 1871 therefore the Server MUST set the headers' 'S' bit to '1' (Start) and 1872 the headers' 'Phase' value to '1' (Phase One). 1874 The Server uses one or more ('Version') TLVs in the EAP-Request/EAP- 1875 CREDS(Type=Init) message to provide the Peer with the list of EAP- 1876 CREDS versions supported. If omitted, the implict version of EAP- 1877 CREDS used in the session is one ('0x1'). If the Server detects 1878 multiple occurrences of this TLV in the reply from the Peer, an error 1879 shall be issued and the EAP-CREDS session should be terminated. 1881 In case Token-Based registration is enabled on the Server, the Server 1882 MUST include, in its Init message, a ('Challenge-Data') field that 1883 can be used by the client to provide challenge data for proof-of- 1884 possession of secrets. 1886 5.1.2. EAP Peer's Init Message 1888 The Peer MUST reply to the Server's ('EAP-CREDS-Init') message with 1889 its own ('EAP-CREDS-Init') one. The Peer SHOULD include one 1890 ('Version') TLV in its first message to indicate the version of EAP- 1891 CREDS that the client wants to use for the session. The Peer MUST 1892 also provide the list of supported provisioning protocols (via one or 1893 more the 'Protocol' TLV), the list and status of the installed 1894 credentials (via the 'Credentials-Info' TLV). The Peer MAY include 1895 authorization data when registering new credentials (e.g., an 1896 authorization token or a device certifcate) via the ('Token-Data') 1897 and ('Challenge-Response') TLV. 1899 The Peer MUST include one ('Credentials-Info') TLV for each 1900 credential the Network is authorized to manage. Typically, a Peer 1901 will include only one ('Credentials-Info') TLV in its ('EAP-CREDS- 1902 Init') message, but there might be cases where multiple types of 1903 credentials are available and selected depending on the location and 1904 other factors (e.g., X.509 certificate and username/password 1905 combination). 1907 In case the Peer does not have any credentials available yet, it does 1908 not add any ('Credentials-Info') TLV - leaving the Server with the 1909 only action possible: Registration. In this case, the Peer SHOULD 1910 include authorization information via the ('Token-Data') TLV as 1911 described in Section 5.1.2.1. Additionally, the Peer can add the 1912 ('Profile') TLV to indicate a preferred profile for the credentials. 1914 5.1.2.1. Bootstrapping Peer's Trustworthiness 1916 When the Peer does not have any valid credentials for the Network 1917 that it is authenticating to, it does not provide any ('Credentials- 1918 Info') TLV. This indicates to the Server that new credentials MUST 1919 be registered before the Peer is allowed on the network. 1921 The Registration process might rely on information exchanged during 1922 the Provisioning Process in Phase Two. However, if an authorization 1923 mechanism is not available from the supported provisioning protocol 1924 and no credentials are available on the Peer, EAP-CREDS provides a 1925 simple machanism for the Peer to leverage an out-of-band 1926 token/passphrase/ott that may be already available on the Peer (e.g., 1927 a device certificate or a 'spendable' credentials token like a 1928 kerberos ticket or a crypto-currency transaction) and that can be 1929 verified by the Server. 1931 In particular, when the Peer wants to register new credentials (and 1932 the Server requires the use of additional authorization data) it may 1933 need to provide (a) a Token, (b) a challenge value, and (c) a 1934 response to the challenge value. To do so, the Peer MUST encode the 1935 token in a ('Token-Data') TLV, the challenge value in a ('Challenge- 1936 Data') TLV, and, finally, the response to the challenge in the 1937 ('Challenge-Response') TLV. 1939 The use of ('Challenge-Data') and ('Challenge-Response') TLVs is 1940 optional, however it is suggested that if a token is used for 1941 bootstrapping the trust, it should provide a way to verify a secret 1942 associated with it. 1944 It is also very important that the authorization token is disclosed 1945 only to authorized servers - the Peer MUST NOT disclose authorization 1946 tokens that are not meant for the network that is being accessed. 1947 This can be done, usually, by verifying the identity of the Server 1948 first (in the outer mechanism) and then verify that the target of the 1949 Token is the Server the Client is talking to. 1951 5.2. The EAP-CREDS-Provisioning Message 1953 The EAP-CREDS-Provisioning message type is used in Phase Two only of 1954 EAP-CREDS. The message flow is depicted in Section 3.3. This 1955 message type supports the following TLVs: Protocol, Profile, 1956 Credentials-Info, Provisioning-Headers, Provisioning-Data, Token- 1957 Data, and Error. 1959 After the exchange of phase one messages, the Server MAY start phase 1960 two by issuing an ('EAP-CREDS-Provisioning') message for the Peer 1961 where it encodes all the required details for starting the 1962 provisioning process. In particular, the server sends the selected 1963 ('Action'), ('Protocol'), and metadata to the client in a EAP- 1964 Request/EAP-CREDS(Type=Provisioning) message. The header's 'S' bit 1965 MUST be set to '1' (Start) and the 'Phase' value set to '2' (Phase 1966 Two begins). 1968 NOTE WELL: After the initial message, the only TLVs that are 1969 allowed in messages coming from the server are the usual 1970 ('Provisioning-Headers') ('Provisioning-Data'), and ('Error'). 1972 The client checks that all the selected parameters are supported for 1973 the selected credentials and, if no errors are detected, it sends its 1974 first ('EAP-CREDS-Provisioning') message to the Server with the 1975 ('Provisioning-Headers') and ('Provisioning-Data') TLVs only. 1977 From now on, the conversation between the Peer and the Server 1978 continues until an error is detected or the provisioning protocol 1979 completes successfully. 1981 If no other actions, the server MAY continue with phase three or 1982 issue a success message and terminate the EAP session. 1984 NOTE WELL: When the SPP protocol is used, the protocol messages 1985 that are encoded inside the ('Protocol-Data') TLV are composed of 1986 sets of TLVs as defined in this document. The overall message 1987 size is provided by the size of the ('Protocol-Data') TLV that 1988 encapsulates the SPP-specific TLVs. This design choice provides 1989 symmetry in implementing support for SPP when compared to other 1990 provisioning protocols. 1992 5.3. The EAP-CREDS-Validate Message 1994 The EAP-CREDS-Validate message type is used in Phase Three only of 1995 EAP-CREDS. The message flow is depicted in Section 3.4. This 1996 message type supports the following TLVs: Protocol, Credentials-Info, 1997 Provisioning-Headers, Provisioning-Data, Token-Data, and Error. 1999 After Phase One (and/or Phase Two) ends, the Server MAY start phase 2000 three by issuing an ('EAP-CREDS-Validate') message for the Peer where 2001 it encodes all the required details for starting the validation 2002 process. In particular, the server sends the ('Credentials-Info'), a 2003 ('Challenge'), and the ('Phase-Control') TLVs in a EAP-Request/EAP- 2004 CREDS(Type=Validate) message. The ('Phase-Control') TLV should carry 2005 the '1' value for the 'S' bit (Start) and the number '3' for its 2006 value (Phase Three begins). 2008 The Peer generates the answer to the Challenge and sends back a EAP- 2009 Response/EAP-CREDS(Type=Validate) message with the ('Challenge- 2010 Response') and an optional ('Challenge') field (only for server-side 2011 validation of the symmetric credentials). If the Peer requested 2012 server-side validation of the credentials, the Server MUST include 2013 (if a symmetric secret) the response to the Peer-issued ('Challenge') 2014 TLV by computing the response and adding it to the ('Challenge- 2015 Response') TLV in its reply. 2017 Finally, in the last message, the Server (if Phase Three is to be 2018 ended) SHALL include the ('Phase-Control') TLV with the 'S' bit set 2019 to '0' (end of phase) and the value set to '3' (Phase Three ended). 2021 At this point, EAP-CREDS has terminated all possible operations and 2022 can be terminated. The Server can now terminate the EAP session 2023 successfully. In case the Peer was not authenticated during the 2024 tunnel establishment (i.e., no credentials were already available on 2025 the Peer), the Server should terminate the EAP session with a Failure 2026 (thus requiring the device to re-attach and authenticate to the 2027 network - phase two should have provided the Peer with the 2028 credentials to use for authenticating to the Network). 2030 6. Error Handling in EAP-CREDS 2032 This section provides a description of the error handling by using 2033 the CREDS-Error-TLV in a CREDS message. 2035 7. The Simple Provisioning Protocol (SPP) 2037 EAP-CREDS supports a Simple Provisioning Protocol (SPP) which 2038 comprises of a series of messages that enable the management not only 2039 of certificates, but also of other types of credentials like 2040 username/password pairs, asymmetric keys, and symmetric keys. 2042 The Simple Provisioning Protocol (SPP), described in this section, 2043 behaves as any other provisioning protocol: its messages are 2044 encapsulated in the ('Provisioning-Data') TLVs in the second phase of 2045 the protocol. SPP does not make use of any ('Provisioning-Headers') 2046 TLVs because its messages are all self-contained (no transport- 2047 protocol specific options are needed). 2049 When no ('Credentials-Info') TLVs have been provided by the client, 2050 the Server knows that the device does not have valid credentials it 2051 wants to use to access the Network. In this case, EAP-CREDS/SPP 2052 supports the use of Tokens to kick-off the registration process. The 2053 type, format, or encoding of the Token is orthogonal to EAP-CREDS/SPP 2054 which treats the token as a black-box field (i.e., it SHOULD NOT try 2055 to interpret or parse its contents). 2057 NOTE WELL: During Phase One, the Peer MAY include the ('Token- 2058 Data') TLV in its EAP-CREDS-Init message to provide the needed 2059 authorization to register a new set of credentials. The Server 2060 might not allow the registration of new credentials if the 2061 required authorization (i.e., the Token) was not provided during 2062 the initialization phase. 2064 In the case where an authorization token is used, different usage 2065 patterns are supported. For tokens that require an associated 2066 verifiable proof-of-possession, the Peer can include a ('Challenge- 2067 Response') TLVs. 2069 The ('Challenge-Data') TLV provided by the Server MUST be used to 2070 convey the challenge data (usually some random value) to compute the 2071 contents of the ('Challenge-Response') TLV. 2073 The ('Challenge-Response') TLV is used, instead, to encode the 2074 response to the challenge data. The ('Challenge-Response') TLV is 2075 generated by the Peer and verified by the Server. At minimum, the 2076 ('Challenge-Response') TLV SHOULD be calculated over the values of 2077 the ('Token-Data') and the ('Challenge-Data') TLVs to make sure that 2078 the authentication covers the token's data as well. 2080 NOTE WELL: The use of the ('Token-Data'), ('Challenge-Data'), and 2081 ('Challenge-Response') TLVs in the Peer's Init message is be used 2082 only to bootstrap trust between the Server and the Peer. If the 2083 Server accepts the authorization information as valid, the Peer is 2084 enabled for registering new credentials. This should happen only 2085 when the Peer does not have valid credentials or when the server 2086 wants to provision a different type of credentials (i.e., 2087 Action=(Register)). Other methods to provide authorization 2088 information might be provided by the selected provisioning 2089 protocol: in this case, the Server MAY enable registration of new 2090 credentials when no authorization data is provided in the 'Init' 2091 message from the client and delegate the validation of the 2092 authorization data during Phase Two. 2094 7.1. SPP Message Format 2096 The SPP Messages are constructed with zero, one, or more TLVs and 2097 encoded in the ('Provisioning-Data') TLV in EAP-CREDS/Provisioning 2098 message types. The size of the encpasulating ('Provisioning-Data') 2099 TLV provides the size of the whole message. 2101 7.2. SPP Message Flow 2103 ,--------. ,----------. 2104 |EAP Peer| |EAP Server| 2105 `---+----' `----+-----' 2106 | [1] EAP-Request/EAP-CREDS(Type=Provisioning) | 2107 | { Protocol(=SPP), Action, | 2108 | [ CredsInfo ] [ Params ], | 2109 | [ ProvData(=CredsData) ] } | 2110 | <------------------------------------------ 2111 | | 2112 | [2] EAP-Response/EAP-CREDS(Type=Provisioning)| 2113 | { [ ProvData(=CredsData) ] } | 2114 | ------------------------------------------> 2115 | | 2116 | [3] EAP-Response/EAP-CREDS(Type=Provisioning)| 2117 | { [ ProvData(=CredsData) ] } | 2118 | <------------------------------------------ 2119 | | 2120 | | 2122 SPP was designed to provide an easy alternative to more complex 2123 provisioning protocols. When no extra flexibility is needed, SPP 2124 provides an easy-to-implement alternative that can handle not only 2125 certificates, but also symmetric secrets and access tokens 2126 provisioning. In this section we provide the generic flow of 2127 messages for SPP and specific examples for certificates, username/ 2128 password, and token provisioning. 2130 EAP-CREDS defines several actions for a set of credentials and they 2131 are listed in Section 8.9. 2133 When a Peer wants to join a network it may or may not have have the 2134 needed credentials to do so. In case the Peer does not have valid 2135 credentials yet, the Server MAY start Phase Two with the intention of 2136 registering a new set of credentials. Alternatively, the Server MAY 2137 start Phase Two when the presented credentials information from the 2138 Peer triggers the Renew or the Remove action. 2140 [1] The Server sends EAP-Request/EAP-CREDS(Type=Provisioning) 2142 When registering new credentials, the first message from the 2143 Server, MUST not carry a ('Credentials-Info') TLV since there is 2144 no targeted credentials to apply the action on (i.e., for other 2145 actions - like 'renew' or 'remove' - the TLV would be required to 2146 identify the right set of credentials to renew or delete). 2148 In SPP, the Server sets the ('Protocol') TLV to SPP, the 2149 ('Action') TLV to 'Register', 'Renew', or 'Remove'. When 2150 provisioning (or registering) new credentials for the Peer, the 2151 Server also sets the ('Provisioning-Params') TLV (or Params) to 2152 the type of credentials to be provisioned. The Server also sets 2153 any relevant constraints, and, optionally, the ('Profile') TLV. 2155 NOTE WELL: If the Peer is authorized to register a new set of 2156 credentials, then the first message from the Server will have 2157 the ('Action') TLV set to 'register' and no ('Credentials- 2158 Info') TLV is present in the Server's message. In case server- 2159 side generation is used, an additional ('Credentials-Info') TLV 2160 MAY be encoded inside the ('Provisioning-Data') TLV. 2162 If the type of credentials is symmetric and the parameters call 2163 for server-side generation of a symmetric key share, the Server 2164 MUST also include its own generated share in a ('Credentials- 2165 Data') TLV inside the ('Provisioning-Data') one (the data for the 2166 provisioning protocol are encapsulated in the 'Provisioning-Data' 2167 TLV for any protocol used during Phase Two - SPP is no exception 2168 to this rule). 2170 In case Server-side only is selected, the Server MUST send the new 2171 credentials in its message and include the ('Credentials-Info') 2172 TLV. If no other credentials need to be managed, the Server MUST 2173 end Phase Two by setting the appropriate bits in the EAP-CREDS 2174 headers as well. 2176 [2] The Peer sends EAP-Response/EAP-CREDS(Type=Provisioning) 2178 When Peer-generation is selected (either Peer-only or combined 2179 Peer and Server side) and Phase Two has not terminated yet, the 2180 Peer MUST reply to the Server's message with its own 2181 'Provisioning' response. The response MUST carry either (a) its 2182 own generated share of the key in a ('Credentials-Data') TLV (if 2183 the credentials that are provisioned are symmetric and the 2184 configuration calls for a share of the key to be provided by the 2185 Peer) or (b) a PKCS#10 request in a ('Certificate-Request') TLV 2186 (also in this case, only if client-side generation was enabled by 2187 the Server) that is generated by using the parameters provided by 2188 the Server in the ('Provisioning-Params') TLV. 2190 [3] The Server sends EAP-Request/EAP-CREDS(Type=Provisioning) 2192 The last message of SPP is from the Server and it is used to 2193 deliver the finalized value of the credentials and/or associated 2194 metadata. In case the credentials being provisioned are 2195 Certificate-based, the Server MUST include the issued certificate 2196 in its reply. The issued credentials shall be encoded in a 2197 ('Credentials-Data') TLV inside the ('Provisioning-Data') one. In 2198 case that the selected format supported/selected by the Peer and 2199 the Server does not provide the possibility to encode the full 2200 chain (i.e., intermediate and Root CAs) in the response, the 2201 Server MUST add one ('Certificate-Data') TLV for each certificate 2202 in the chain (including the Root CA's certificate). 2204 The Server MUST include the ('Credentials-Info') TLV in its 2205 message. This provide the Peer with some additional data (e.g., 2206 the 'Profile' or the 'Identifier' associated with the credentials 2207 that were provisioned/managed). 2209 In the case where additional credentials need to be managed, the 2210 Server can continue Phase Two by issuing a new [1] message where 2211 the tuple Action/Credentials must be unique for the current EAP- 2212 CREDS session. 2214 The Server can now decide to start Phase Three (suggested if new 2215 credentials were provisioned or renewed) or to terminate the EAP 2216 session successfully. 2218 7.2.1. SPP Symmetric Secrets Management 2220 ,--------. ,----------. 2221 |EAP Peer| |EAP Server| 2222 `---+----' `----+-----' 2223 | [1] EAP-Request/EAP-CREDS(Type=Provisioning) | 2224 | { Protocol(=SPP), Action, [ Creds-Info ], | 2225 | [ Prov-Params ], [ Profile ] | 2226 | [ Prov-Data(=[Creds-Info],[Creds-Data]) ] }| 2227 | <----------------------------------------------- 2228 | | 2229 | [2] EAP-Response/EAP-CREDS(Type=Provisioning) | 2230 | { [ Prov-Data(=[Creds-Data]) ] } | 2231 | -----------------------------------------------> 2232 | | 2233 | [3] EAP-Response/EAP-CREDS(Type=Provisioning) | 2234 | { [ Prov-Data(=Creds-Info,[Creds-Data]) ] } | 2235 | <----------------------------------------------- 2236 | | 2237 | | 2239 EAP-CREDS/SPP can provision symmetric secrets (e.g, username/ 2240 password, API keys, or SIM-based keys), tokens (e.g., username/ 2241 password OAuth or Kerberos tokens), or asymmetric credentials (e.g., 2242 X.509 certificates or Key Pairs). This section focuses on 2243 provisioning symmetric secrets only. The message flow is provided in 2244 Section 7.2.1 2246 EAP-CREDS/SPP provides the possibility for shared secret to be 2247 generated in different ways: 2249 1. Server-Side Generated 2251 2. Client-Side Generated 2253 3. Both Client-Side and Server-Side Generated 2255 In particular, when initiating the second phase of the protocol, the 2256 ('Provisioning-Params') TLV is used to specify how to generate the 2257 secret (see Section 4.2.1.13). 2259 7.2.1.1. Server Side Only Generation 2261 [ TO BE EDITED ] 2263 Figure 1: SPP Message Flow for Server-Side only secrets provisioning 2265 The message flow for deploying a server-side only credential (i.e., 2266 during registration or renewal) consists of only one message from the 2267 server. The flow is depicted in Figure 1. 2269 In this case, the Server sends the first Provisioning message (which 2270 is also the last one), which MUST carry, the following data: 2272 o The ('Credentials-Info') TLV that specifies the info for the 2273 provisioned secret, and 2275 o The ('Protocol') TLV that specifies the provisioning protocol to 2276 be used, and 2278 o The ('Action') TLV that provides the action to be performed 2279 ('Registration') or ('Renew'), and 2281 o The ('Provisioning-Params') TLV that provides the generation 2282 parameters to the Peer, and 2284 The Server also includes, encoded in the ('Provisioning-Data') TLV, 2285 the following data: 2287 The ('Credentials-Info') TLV that provides the metadata associated 2288 with teh generated secret 2290 The ('Credentials-Data') TLV that provides the secret that is 2291 provisioned to the Peer 2293 Server-side secrets' generation can be used to generate username/ 2294 password combinations, API Keys, SIM-based credentials, or tokens. 2296 7.2.1.2. Client Side Only Generation 2298 [ TO BE EDITED ] 2300 Figure 2: SPP Message Flow for Client-Side only secrets provisioning 2302 The message flow for deploying a client-side only credential (i.e., 2303 during registration or renewal) consists of the full three messages 2304 exchange. The flow is depicted in Figure 2. 2306 In this case, the Server MUST include, in its first Provisioning 2307 message and encoded in the ('Provisioning-Data') TLV, the following 2308 data: 2310 o The ('Credentials-Info') TLV that specifies the target 2311 credentials, and 2313 o The ('Protocol') TLV that specifies the provisioning protocol to 2314 be used, and 2316 o The ('Action') TLV that provides the action to be performed 2317 ('Registration') or ('Renew'), and 2319 o The ('Provisioning-Params') TLV that provides the generation 2320 parameters to the Peer, and 2322 Notice that the Server does not include any ('Credentials-Data') TLV 2323 in its first message because the Server is not involved in the secret 2324 generation (client-side only). 2326 The Peer MUST reply with its own Provisioning message where the Peer 2327 MUST encode the following data in the ('Provisioning-Data') TLV: 2329 The ('Credentials-Data') TLV that provides the secret that is 2330 being registered 2332 The credentials data MUST conform to the specifications the Server 2333 provided in the ('Provisioning-Params') TLV. 2335 The final message is from the Server and it MUST contain (if no 2336 errors were detected), the following TLVs encoded, as usual, in the 2337 ('Provisioning-Data') TLV: 2339 The ('Credentials-Info') TLV that specifies the metadata 2340 associated with the generated secret, and 2342 The ('Credentials-Data') TLV that provides the secret that is 2343 provisioned to the Peer 2345 Client-side secrets' generation should be used with caution and an 2346 evaluation of the quality of the generated credentials MUST be 2347 performed to make sure that the security of the generated secret is 2348 adequate for accessing the network. Since evaluating the quality of 2349 a secret is quite a difficult tasks, the use of this generation mode 2350 MUST be evaluated carefully and selected accordingly to acceptable 2351 risk profiles. 2353 7.2.1.3. Client and Server Side Generation 2355 When registering or renewing credentials and the secret generation is 2356 split between the Server (1st share) and the Peer (2nd share), the 2357 message flow is the same as Section 7.2.1.2 with the following 2358 exceptions: 2360 o The Server MUST send its own share of the secret by including a 2361 ('Credentials-Data') TLV in its first message. 2363 All other parameters remain the same. 2365 Co-generation of the secret is the most secure option because both 2366 parties can provide the required randomness in their own share of the 2367 secret. 2369 7.2.2. SPP Key Pair Provisioning 2371 EAP-CREDS/SSP defines the following flow of messages for requesting 2372 the provisioning of key pairs (public and private keys). 2374 7.2.2.1. Server Side Only Generation 2376 [ This case covers the server-side generation of KeyPair and 2377 Certificate ] 2379 7.2.2.2. Client Side Only Generation 2381 [ This case covers the registration of a self-signed or already 2382 available (e.g., device) certificate ] 2384 7.2.2.3. Client and Server Side Generation 2386 This use-case is not supported. In other words, for the provisioning 2387 of Key Pairs, the ('Provisioning-Params') can not have both the peer- 2388 generation and server-generation bits set. 2390 7.2.3. SPP Certificate Provisioning 2392 EAP-CREDS/SSP defines the following flow of messages for requesting 2393 the provisioning of credentials. 2395 7.2.3.1. Server Side Only Generation 2397 [ This case covers the server-side generation of KeyPair and 2398 Certificate ] 2400 7.2.3.2. Client Side Only Generation 2402 [ This case covers the registration of a self-signed or already 2403 available (e.g., device) certificate ] 2405 7.2.3.3. Client and Server Side Generation 2407 [ This case covers the generation of the KeyPair on the Peer and the 2408 generation of the certificate on the Server ] 2410 7.2.4. SPP Token Provisioning 2412 EAP-CREDS/SSP defines the following flow of messages for requesting 2413 the provisioning of token-based credentials. 2415 7.2.4.1. Server Side Only Generation 2417 [ This case covers the server-side generation of the Token and 2418 possibly associated key ] 2420 7.2.4.2. Client Side Only Generation 2422 [ This case covers the registration of a self-signed or already 2423 available (e.g., device) certificate ] 2425 7.2.4.3. Client and Server Side Generation 2427 [ This case covers the generation of the KeyPair on the Peer and the 2428 generation of the Token that cointains the reference to the key on 2429 the Server ] 2431 8. IANA Considerations 2433 This document uses a new EAP type, EAP-CREDS, whose value (TBD) MUST 2434 be allocated by IANA from the EAP TYPEs subregistry of the RADIUS 2435 registry. This section provides guidance to the Internet Assigned 2436 Numbers Authority (IANA) regarding registration of values related to 2437 the EAP-CREDS protocol, in accordance with [RFC8126]. 2439 The EAP Method Type number for EAP-CREDS needs to be assigned. 2441 This document also requires IANA to create new registries as defined 2442 in the following subsections. 2444 8.1. Provisioning Protocols 2446 +-----------------+-------------------------------------------------+ 2447 | Message Type | Purpose | 2448 +-----------------+-------------------------------------------------+ 2449 | 0 | Unspecified | 2450 | 1 | Simple Provisioning Protocol (SPP) | 2451 | 2 | Basic Certificate Management Protocol (CMP-S) | 2452 | 3 | Full Certificate Management Protocol (CMP-F) | 2453 | 4 | Enrollment over Secure Transport (EST) | 2454 | 5 | Certificate Management over CMS (CMC) | 2455 | 6 | Automatic Certificate Management Environment | 2456 | | (ACME) | 2457 | ... | ... | 2458 | 49141 ... 65534 | Vendor Specific | 2459 +-----------------+-------------------------------------------------+ 2461 Table 5: EAP-CREDS Inner Protocol Identifiers 2463 Assignment of new values for new cryptosuites MUST be done through 2464 IANA with "Specification Required" and "IESG Approval" as defined in 2465 [RFC8126]. 2467 8.2. Token Types 2469 +------------+-----------------+ 2470 | Token Type | Description | 2471 +------------+-----------------+ 2472 | 0 | Unspecified | 2473 | 1 | JWT | 2474 | 2 | Kerberos | 2475 | 3 | OAuth | 2476 | 200..254 | Vendor Specific | 2477 +------------+-----------------+ 2479 Table 6: Token Types 2481 Assignment of new values for new Message Types MUST be done through 2482 IANA with "Expert Review" as defined in [RFC8126]. 2484 8.3. Credentials Types 2485 +------------------+-----------------------+ 2486 | Credentials Type | Description | 2487 +------------------+-----------------------+ 2488 | 0 | X.509 Certificate | 2489 | 1 | Public Key | 2490 | 2 | Symmetric Key | 2491 | 3 | Username and Password | 2492 | 4 | AKA Subscriber Key | 2493 | 5 | Bearer Token | 2494 | 6 | One-Time Token | 2495 | 7 | API Key | 2496 +------------------+-----------------------+ 2498 Table 7: Credentials Types 2500 Assignment of new values for new Message Types MUST be done through 2501 IANA with "Expert Review" as defined in [RFC8126]. 2503 8.4. Credentials Algorithms 2505 +---------+--------------------+ 2506 | ID | Algorithm | 2507 +---------+--------------------+ 2508 | 0 | None | 2509 | 1 | RSA | 2510 | 2 | ECDSA | 2511 | 3 | XMMS | 2512 | 4 | AKA Subscriber Key | 2513 | 5 | OAuth | 2514 | 6 | Kerberos4 | 2515 | 7 | Kerberos5 | 2516 | 200-254 | Reserved | 2517 +---------+--------------------+ 2519 Table 8: Credentials Algorithms 2521 Assignment of new values for new Message Types MUST be done through 2522 IANA with "Expert Review" as defined in [RFC8126]. 2524 8.5. Credentials Datatypes 2525 +---------+---------------+ 2526 | ID | Data Type | 2527 +---------+---------------+ 2528 | 0 | None (Binary) | 2529 | 1 | PKCS#8 | 2530 | 2 | PKCS#10 | 2531 | 3 | PKCS#12 | 2532 | 4 | PublicKeyInfo | 2533 | 200-254 | Reserved | 2534 +---------+---------------+ 2536 Table 9: Credentials Datatypes 2538 Assignment of new values for new Message Types MUST be done through 2539 IANA with "Expert Review" as defined in [RFC8126]. 2541 8.6. Challenge Types 2543 +----+----------------------+ 2544 | ID | Data Type | 2545 +----+----------------------+ 2546 | 0 | Not Specified | 2547 | 1 | EAP-CREDS-ASYMMETRIC | 2548 | 2 | EAP-CREDS-SYMMETRIC | 2549 +----+----------------------+ 2551 Table 10: Challenge Type 2553 Assignment of new values for new Message Types MUST be done through 2554 IANA with "Expert Review" as defined in [RFC8126]. 2556 8.7. Network Usage Datatypes 2558 +--------+------------------------------------------+ 2559 | ID | Data Type | 2560 +--------+------------------------------------------+ 2561 | 0 | Vendor-Specific | 2562 | 1 | Manufacturer Usage Description [RFC8520] | 2563 | 2 | Network Access Granting System | 2564 | 3 | Firmware Manifest | 2565 | 4..127 | Reserved for Future Use | 2566 +--------+------------------------------------------+ 2568 Table 11: Network Usage Datatypes 2570 Assignment of new values for new Message Types MUST be done through 2571 IANA with "Expert Review" as defined in [RFC8126]. 2573 8.8. Credentials Encoding 2575 +---------+------------+ 2576 | ID | Encoding | 2577 +---------+------------+ 2578 | 0 | None (Raw) | 2579 | 1 | DER | 2580 | 2 | PEM | 2581 | 3 | Base64 | 2582 | 4 | JSON | 2583 | 5 | XML | 2584 | 6 | ASCII | 2585 | 7 | UTF-8 | 2586 | 200-254 | Reserved | 2587 +---------+------------+ 2589 Table 12: Credentials Encoding 2591 Assignment of new values for new Message Types MUST be done through 2592 IANA with "Expert Review" as defined in [RFC8126]. 2594 8.9. Action Types 2596 +---------+--------------+--------------------------------+ 2597 | ID | Data Type | Description | 2598 +---------+--------------+--------------------------------+ 2599 | 0 | Registration | Registers New Credentials | 2600 | 1 | Renewal | Renew an Existing Credential | 2601 | 2 | Remove | Removes an Existing Credential | 2602 | 200-254 | n/a | Reserved | 2603 +---------+--------------+--------------------------------+ 2605 Table 13: Action Types 2607 Assignment of new values for new Message Types MUST be done through 2608 IANA with "Expert Review" as defined in [RFC8126]. 2610 8.10. Usage Metadata Types 2612 +------+----------------------+ 2613 | Type | Description | 2614 +------+----------------------+ 2615 | 0 | Binary (Unspecified) | 2616 | 1 | MUD File | 2617 | 2 | TEEP Manifest | 2618 +------+----------------------+ 2620 Table 14: Usage Metadata Types 2622 Assignment of new values for new Message Types MUST be done through 2623 IANA with "Expert Review" as defined in [RFC8126]. 2625 9. Security Considerations 2627 Several security considerations need to be explicitly considered for 2628 the system administrators and application developers to understand 2629 the weaknesses of the overall architecture. 2631 The most important security consideration when deploying EAP-CREDS is 2632 related to the security of the outer channel. In particular, EAP- 2633 CREDS assumes that the communication channel has been properly 2634 authenticated and that the information exchanged between the Peer and 2635 the Server are protected (i.e., confidentiality and integrity). 2637 For example, if certificate-based authentication is used, the server 2638 presents a certificate to the peer as part of the trust establishment 2639 (or negotiation). The peer SHOULD verify the validity of the EAP 2640 server certificate and SHOULD also examine the EAP server name 2641 presented in the certificate in order to determine whether the EAP 2642 server can be trusted. When performing server certificate 2643 validation, implementations MUST provide support for the rules in 2644 [RFC5280] for validating certificates against a known trust anchor. 2646 10. Acknowledgments 2648 The authors would like to thank everybody who provided insightful 2649 comments and helped in the definition of the deployment 2650 considerations. 2652 11. Normative References 2654 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2655 Requirement Levels", BCP 14, RFC 2119, 2656 DOI 10.17487/RFC2119, March 1997, 2657 . 2659 [RFC3748] Aboba, B., Blunk, L., Vollbrecht, J., Carlson, J., and H. 2660 Levkowetz, Ed., "Extensible Authentication Protocol 2661 (EAP)", RFC 3748, DOI 10.17487/RFC3748, June 2004, 2662 . 2664 [RFC4210] Adams, C., Farrell, S., Kause, T., and T. Mononen, 2665 "Internet X.509 Public Key Infrastructure Certificate 2666 Management Protocol (CMP)", RFC 4210, 2667 DOI 10.17487/RFC4210, September 2005, 2668 . 2670 [RFC5272] Schaad, J. and M. Myers, "Certificate Management over CMS 2671 (CMC)", RFC 5272, DOI 10.17487/RFC5272, June 2008, 2672 . 2674 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 2675 Housley, R., and W. Polk, "Internet X.509 Public Key 2676 Infrastructure Certificate and Certificate Revocation List 2677 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 2678 . 2680 [RFC6402] Schaad, J., "Certificate Management over CMS (CMC) 2681 Updates", RFC 6402, DOI 10.17487/RFC6402, November 2011, 2682 . 2684 [RFC7030] Pritikin, M., Ed., Yee, P., Ed., and D. Harkins, Ed., 2685 "Enrollment over Secure Transport", RFC 7030, 2686 DOI 10.17487/RFC7030, October 2013, 2687 . 2689 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 2690 Writing an IANA Considerations Section in RFCs", BCP 26, 2691 RFC 8126, DOI 10.17487/RFC8126, June 2017, 2692 . 2694 [RFC8520] Lear, E., Droms, R., and D. Romascanu, "Manufacturer Usage 2695 Description Specification", RFC 8520, 2696 DOI 10.17487/RFC8520, March 2019, 2697 . 2699 Author's Address 2701 Massimiliano Pala 2702 CableLabs 2703 858 Coal Creek Cir 2704 Louisville, CO 80027 2705 US 2707 Email: m.pala@openca.org 2708 URI: http://www.linkedin.com/in/mpala