idnits 2.17.1 draft-pala-eap-creds-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 10 instances of too long lines in the document, the longest one being 2 characters in excess of 72. == There are 5 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == 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 (October 28, 2019) is 1632 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 2068 -- Looks like a reference, but probably isn't: '2' on line 2074 == Missing Reference: 'N' is mentioned on line 543, but not defined -- Looks like a reference, but probably isn't: '3' on line 2078 == Missing Reference: 'RFC3279' is mentioned on line 635, but not defined == Missing Reference: 'RFC4055' is mentioned on line 635, but not defined == Missing Reference: 'RFC4491' is mentioned on line 636, but not defined Summary: 1 error (**), 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 October 28, 2019 5 Expires: April 30, 2020 7 Credentials Provisioning and Management via EAP (EAP-CREDS) 8 draft-pala-eap-creds-05 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 April 30, 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 . . . . . . . . . . . . . . . . . . 5 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.2. Phase Transitioning Rules . . . . . . . . . . . . . . . . 8 86 3.3. Phase One: Initialization . . . . . . . . . . . . . . . . 9 87 3.4. Phase Two: Provisioning . . . . . . . . . . . . . . . . . 11 88 3.5. Phase Three: Validation . . . . . . . . . . . . . . . . . 13 89 4. EAP-CREDS Message Format . . . . . . . . . . . . . . . . . . 15 90 4.1. Message Header . . . . . . . . . . . . . . . . . . . . . 15 91 4.2. Message Payload . . . . . . . . . . . . . . . . . . . . . 17 92 4.3. EAP-CREDS defined TLVs . . . . . . . . . . . . . . . . . 18 93 4.3.1. The Action TLV . . . . . . . . . . . . . . . . . . . 18 94 4.3.2. The Certificate-Data TLV . . . . . . . . . . . . . . 19 95 4.3.3. The Challenge-Data TLV . . . . . . . . . . . . . . . 20 96 4.3.4. The Challenge-Response TLV . . . . . . . . . . . . . 21 97 4.3.5. The Credentials-Information TLV . . . . . . . . . . . 22 98 4.3.6. The Credentials-Data TLV . . . . . . . . . . . . . . 25 99 4.3.7. The Error TLV . . . . . . . . . . . . . . . . . . . . 25 100 4.3.8. The Network-Usage TLV . . . . . . . . . . . . . . . . 26 101 4.3.9. The Profile TLV . . . . . . . . . . . . . . . . . . . 28 102 4.3.10. The Protocol TLV . . . . . . . . . . . . . . . . . . 29 103 4.3.11. The Provisioning-Data TLV . . . . . . . . . . . . . . 29 104 4.3.12. The Provisioning-Headers TLV . . . . . . . . . . . . 30 105 4.3.13. The Provisioning-Params TLV . . . . . . . . . . . . . 31 106 4.3.14. The Certificate-Request TLV . . . . . . . . . . . . . 33 107 4.3.15. The Storage-Info TLV . . . . . . . . . . . . . . . . 34 108 4.3.16. The Supported-Formats TLV . . . . . . . . . . . . . . 35 109 4.3.17. The Supported-Encoding TLV . . . . . . . . . . . . . 36 110 4.3.18. The Token-Data TLV . . . . . . . . . . . . . . . . . 36 111 4.3.19. The Version TLV . . . . . . . . . . . . . . . . . . . 37 112 5. EAP-CREDS Messages . . . . . . . . . . . . . . . . . . . . . 38 113 5.1. The EAP-CREDS-Init Message . . . . . . . . . . . . . . . 38 114 5.1.1. EAP Server's Init Message . . . . . . . . . . . . . . 38 115 5.1.2. EAP Peer's Init Message . . . . . . . . . . . . . . . 39 116 5.1.2.1. Bootstrapping Peer's Trustworthiness . . . . . . 39 117 5.1.3. The EAP-CREDS-Provisioning Message . . . . . . . . . 40 118 5.1.4. The EAP-CREDS-Validate Message . . . . . . . . . . . 41 119 6. Error Handling in EAP-CREDS . . . . . . . . . . . . . . . . . 42 120 7. The Simple Provisioning Protocol (SPP) . . . . . . . . . . . 42 121 7.1. SPP Message Format . . . . . . . . . . . . . . . . . . . 43 122 7.2. SPP Message Flow . . . . . . . . . . . . . . . . . . . . 43 123 7.2.1. SPP Symmetric Secrets Management . . . . . . . . . . 46 124 7.2.1.1. Server Side Only Generation . . . . . . . . . . . 47 125 7.2.1.2. Client Side Only Generation . . . . . . . . . . . 47 126 7.2.1.3. Client and Server Side Generation . . . . . . . . 49 127 7.2.2. SPP Key Pair Provisioning . . . . . . . . . . . . . . 49 128 7.2.2.1. Server Side Only Generation . . . . . . . . . . . 49 129 7.2.2.2. Client Side Only Generation . . . . . . . . . . . 49 130 7.2.2.3. Client and Server Side Generation . . . . . . . . 49 131 7.2.3. SPP Certificate Provisioning . . . . . . . . . . . . 49 132 7.2.3.1. Server Side Only Generation . . . . . . . . . . . 49 133 7.2.3.2. Client Side Only Generation . . . . . . . . . . . 50 134 7.2.3.3. Client and Server Side Generation . . . . . . . . 50 135 7.2.4. SPP Token Provisioning . . . . . . . . . . . . . . . 50 136 7.2.4.1. Server Side Only Generation . . . . . . . . . . . 50 137 7.2.4.2. Client Side Only Generation . . . . . . . . . . . 50 138 7.2.4.3. Client and Server Side Generation . . . . . . . . 50 139 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 50 140 8.1. Provisioning Protocols . . . . . . . . . . . . . . . . . 51 141 8.2. Token Types . . . . . . . . . . . . . . . . . . . . . . . 51 142 8.3. Credentials Types . . . . . . . . . . . . . . . . . . . . 51 143 8.4. Credentials Algorithms . . . . . . . . . . . . . . . . . 52 144 8.5. Credentials Datatypes . . . . . . . . . . . . . . . . . . 52 145 8.6. Challenge Types . . . . . . . . . . . . . . . . . . . . . 53 146 8.7. Network Usage Datatypes . . . . . . . . . . . . . . . . . 53 147 8.8. Credentials Encoding . . . . . . . . . . . . . . . . . . 54 148 8.9. Action Types . . . . . . . . . . . . . . . . . . . . . . 54 149 8.10. Usage Metadata Types . . . . . . . . . . . . . . . . . . 54 150 9. Security Considerations . . . . . . . . . . . . . . . . . . . 55 151 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 55 152 11. Normative References . . . . . . . . . . . . . . . . . . . . 55 153 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 56 155 1. Requirements notation 157 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 158 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 159 document are to be interpreted as described in [RFC2119]. 161 2. Introduction 163 Many environments are, today, moving towards requiring strong 164 authentication when it comes to gain access to networks. The 802.1x 165 architecture provides network administrators with the possibility to 166 check credentials presented by a device even before providing any 167 connectivity or IP services to it. 169 However, the provisioning and management of these credentials is a 170 hard problem to solve and many vendors opt for long-lived credentials 171 that can not be easily revoked, replaced, or simply renewed. 173 This specification addresses the problem of providing a simple-to-use 174 and simple-to-deploy conduit for credentials management by extending 175 the EAP protocol to support credentials provisioning and management 176 functionality. In particular, the EAP-CREDS method defined here 177 provides a generic framework that can carry the messages for 178 provisioning different types of credentials. EAP-CREDS cannot be 179 used as a stand-alone method, it is required that EAP-CREDS is used 180 as an inner method of EAP-TLS, EAP-TEAP, or any other tunnelling 181 method that can provide the required secrecy and (at minimum) server- 182 side authentication to make sure that the communication is protected 183 and with the right server. 185 2.1. Overview of existing solutions 187 Currently there are many protocols that address credentials lifecycle 188 management. In particular, when it comes to digital certificates, 189 some of the most deployed management protocols are: Certificate 190 Management Protocol (CMP) [RFC4210], Certificate Management over CMS 191 (CMC) [RFC5272][RFC6402], Enrollment over Secure Transport (EST) 192 [RFC7030], and Automated Certificate Management Environment (ACME) . 193 However, none of these protocols provide native support for client 194 that do not have IP connectivity yet (e.g., because they do not have 195 network-access credentials, yet). EAP-CREDS provides the possibility 196 to use such protocols (i.e., message-based) by defining a series of 197 messages that can be used to encapsulate the provisioning messages 198 for the selected provisioning protocol. 200 In addition to these protocols, EAP-CREDS also defines a series of 201 simple messages that provide a generic enrollment protocol that 202 allows not only certificates but also other types of credentials 203 (e.g., username/password pairs, tokens, or symmetric secrets) to be 204 delivered to the client as part of the provisioning and/or renewal 205 process. The set of messages that make up the generic provisioning 206 protocol is referred to as the Simple Provisioning Protocol protocol 207 or SPP. 209 2.2. Scope Statement 211 This document focuses on the definition of the EAP-CREDS method to 212 convey credentials provisioning and managing messages between the 213 client and the AAA server. Moreover, the document defines how to 214 encode messages for the main IETF provisioning protocols. 216 This document, however, does not provide specifications for how and 217 where the credentials are generated. In particular, the credentials 218 could be generated directly within the AAA server or at a different 219 location (i.e., the Certificate Service Provider or CSP) site. 220 Different authentication mechanisms (e.g., TLS, etc.) can be used to 221 secure the communication between the server's endpoint and the CSP. 223 2.3. EAP-CREDS as tunneled mechanism only 225 EAP-CREDS requires that an outer mechanism is in place between the 226 Peer and the Server in order to provide authentication and 227 confidentiality of the messages exchanged via EAP-CREDS. In other 228 words, EAP-CREDS assumes that an appropriatly encrypted and 229 authenticated channel has been established to prevent the possibility 230 to leak information or to allow man-in-the-middle attacks. 232 This choice was taken to simplify the message flow between Peer and 233 Server, and to abstract EAP-CREDS from the secure-channel 234 establishment mechanism. EAP-TLS, or EAP-TEAP are examples of such 235 mechanisms.s 237 2.4. Fragmentation Support 239 EAP does not directly support handling fragmented packets and it 240 requires the outer method to provide fragmentation support. 242 Because of the outer method requirements in particular, removing any 243 support for fragmented messages in EAP-CREDS removes the duplication 244 of packets (e.g., Acknowledgment Packets) sent across the Peer and 245 the Server, thus resulting in a smaller number of exchanged messages 247 2.5. Encapsulating Provisioning Protocols in EAP-CREDS 249 In order to use EAP-CREDS together with your favorite provisioning 250 protocol, the messages from the provisioning protcol need to be sent 251 to the other party. In EAP-CREDS, this is done by encoding the 252 provisioning protocol messages inside the ('Provisioning-Data') TLV. 253 In case the provisioning protocol uses additional data for its 254 operations (e.g., uses HTTP Headers), this data can be encoded in a 255 separate ('Provisioning-Headers') TLV. 257 Since the implementation of the provisioning endpoint could happen in 258 a (logically or physically) different component, a method is needed 259 to identify when a provisioning protocol has actually ended. In EAP- 260 CREDS, the 'D' bit in the message headers is used for this purpose. 262 In the first message of Phase Two, the Server provides the client 263 with all the selected parameters for one specific credential that 264 needs attention (or for a new credential) to be managed by the 265 network. In particular, the server provides, at minimum, the 266 ('Protocol') TLV, the ('Action') TLV, and the ('Provisioning-Params') 267 or the ('Credentials-Info') TLV. 269 After checking the parameters sent by the Server, if the Peer does 270 not support any of the proposed ones, it MUST send a message with one 271 single ('Error') TLV with the appropriate error code(s). The server, 272 can then decide if to manage a different set of credentials (if more 273 where reported by the Peer in its Phase One message) or if to 274 terminate the EAP session with an error. 276 The Peer and the Server exchange Provisioning messages until an error 277 is detected (and the appropriate error message is sent to the other 278 party) or until Phase Two is successfully completed. 280 2.6. Algorithm Requirements 282 EAP-CREDS uses the SHA-256 hashing algorithm to verify credentials in 283 phase three of the protocol. Peers and Servers MUST support SHA-256 284 for this purpose. 286 2.7. Notation 288 In this document we use the following notation in the diagrams to 289 provide information about the cardinality of the data structures 290 (TLVs) within EAP-CREDS messages: 292 +--------+------------+---------------------------------------------+ 293 | Symbol | Example | Usage | 294 +--------+------------+---------------------------------------------+ 295 | { } | {TLV1} | Curly Brackets are used to indicate a set | 296 | [ ] | {[TLV2]} | Square Brackets are used to indicate that a | 297 | | | field is optional | 298 | ( ) | {TLV1(=V)} | Round Squares are used to specify a value | 299 | + | {TLV_2+} | The Plus character indicates that one or | 300 | | | more instances are allowed | 301 +--------+------------+---------------------------------------------+ 303 Table 1: EAP-CREDS Notation 305 3. EAP-CREDS Protocol 307 In a nutshell, EAP-CREDS provides the abstraction layer on top of 308 which credentials provisioning/managing protocols can be deployed 309 thus enabling their use even before provisioning IP services. 311 This section outlines the operation of the protocol and message 312 flows. The format of the CREDS messages is given in Section 4. 314 3.1. Message Flow 316 EAP-CREDS message flow is logically subdivided into three different 317 phases: Initialization, Provisioning, and Validation. EAP-CREDS 318 enforces the order of phases, i.e. it is not possible to move to an 319 earlier phase. 321 Phase transitioning is controlled by the Server. In particular, the 322 server, after the last message of a phase, it can decide to either 323 (a) start the next phase by sending the first message of the next 324 phase, or (b) continue the same phase by sending another "first" 325 message of the phase (e.g., managing a second set of credentials) - 326 this is allowed only in Phase Two and Phase Three but NOT in Phase 327 One, or (c) terminate the EAP session. 329 Phase One (Required). Initialization. During this phase the Peer 330 and the Server exchange the information needed to select the 331 appropriate credentials management protocol. Phase One flow is 332 composed by only messages. In particular, the Sever sends its 333 initial message of type ('EAP-CREDS-Init'). The Peer replies with 334 the details about which provisioning protocols are supported, and 335 additional information such as the list of installed credentials 336 and, optionally, authorization data (for new credentials 337 registration). 339 Phase Two (Optional). Provisioning Protocol Flow. In this phase, 340 the Peer and the Server exchange the provisioning protocol's 341 messages encapsulated in a EAP-CREDS message of type Provisioning. 342 The messages use two main TLVs. The first one is the 343 ('Provisioning-Headers') TLV which is optional and carries 344 information that might be normally coveyed via the transport 345 protocol (e.g., HTTP headers). The second one is the 346 ('Provisioning-Data'), which is required and carries the 347 provisioning protocol's messages. The server can decide to repeat 348 phase two again to register new credentials or to renew a separate 349 set of credentials by issuing a new ('Provisioning') message for 350 the new target. When no more credentials have to be managed, the 351 Server can start phase three or simply terminate the EAP session. 353 Phase Three (Optional). Credentials Validation. This optional phase 354 can be initiated by the server and it is used to validate that the 355 Peer has properly installed the credentials and can use them to 356 authenticate itself. Depending on the credentials' type, the 357 messages can carry a challenge/nonce, the value of the secret/ 358 token, or other information. The format of the credentials is 359 supposed to be known by the provider and the device. 361 3.2. Phase Transitioning Rules 363 In order to keep track of starting and ending a phase, EAP-CREDS 364 defines several bits and fields in the EAP-CREDS message headers. In 365 particular, as described in Section 4.1, the 'S' bit is used to 366 indicate the beginning (or Start) of a phase, while the 'Phase' field 367 (4 bits) is used to indicate the phase for this message. 369 In EAP-CREDS, phase transitioning is under the sole control of the 370 Server, therefore the value of the 'S' bit is meaningful only in 371 messages sent by the Server. The value of the 'S' bit in Peer's 372 messages SHALL be set to '0x0' and SHALL be ignored by the server. 374 When starting a new phase, the Server MUST set the 'S' bit to '1' and 375 the 'Phase' field to the current phase number (e.g., one, two, or 376 three). 378 In case the first message of a phase is to be repeated (e.g., because 379 of processing multiple credentials), the 'S' bit SHALL be set to '0' 380 (i.e., it should be set to '1' only on the first occurrency and set 381 to '0' in subsequent messages). 383 3.3. Phase One: Initialization 385 The following figure provides the message flow for Phase One: 387 ,--------. ,----------. 388 |EAP Peer| |EAP Server| 389 `---+----' `----+-----' 390 | Outer Tunnel Established | 391 | <--------------------------------------> 392 | | 393 | [1] EAP-Request/EAP-CREDS(Type=Init) | ,---------!. 394 | { [ Version+ ], [ Challenge ] } | |Phase One|_\ 395 | <--------------------------------------- |Begins | 396 | | `-----------' 397 | [2] EAP-Response/EAP-CREDS(Type=Init) | 398 | { Protocol+, [ Encoding+ ], | 399 | [ Format+ ] , [ Version ] | ,---------!. 400 | [ Creds-Info+ ], [ Storage-Info ]| |Phase One|_\ 401 | [ Net-Usage], [ Token ], | |Ends | 402 | [ Challenge-Rsp ], [ Profile+ ] }| `-----------' 403 | ---------------------------------------> 404 | | 405 | | 407 EAP-CREDS Phase One Message Flow 409 [1] Server sends EAP-Request/EAP-CREDS(Type=Init): 411 After the establishment of the outer mechanism (e.g., EAP-TLS, 412 EAP-TEAP, EAP-TTLS, etc.), the server MAY decide to start a 413 credentials management session. In order to do that, the Server 414 sends an EAP-Request/EAP-CREDS(Type=Init) message to the Peer with 415 one ('Phase-Control') TLV with the 'S' bit set to '1' and the 416 value set to '1' (thus indicating the beginning of Phase One). 417 Also, the Server MAY use one or more ('Version') TLVs to indicate 418 the supported versions. 420 The Server MAY also specify which versions of EAP-CREDS are 421 supported by adding one or more ('Version') TLVs. If no 422 ('Version') TLV is added to the message, the Peer SHOULD assume 423 the supported version is 1 ('0x1'). 425 [2] The Peer sends EAP-Response/EAP-CREDS(Type=Init) 427 The Peer, sends back a message that carries one ('Version') TLV to 428 indicate the selected version of EAP-CREDS (i.e. from the list 429 provided by the server) (optional). If the client does not 430 include the ('Version') TLV, the Server MUST use the most recent 431 supported version of EAP-CREDS. Moreover, the Server includes one 432 or more ('Protocol') TLVs to indicate the list of supported 433 provisioning protocols, followed by one ('Credentials-Info') TLVs 434 for each installed credentials to provide their status to the 435 server (i.e., if multiple credentials are configured on the Peer 436 for this Network, then the Peer MUST include one ('Credentials- 437 Info') TLV for each of them). 439 The Peer also provides the list of supported Encodings and Formats 440 by adding one or more ('Supported-Encodings') and ('Supported- 441 Formats') TLVs. The Peer MAY also provide the Server with 442 information about the Peer's credentials storage by using the 443 'Storage-Status' TLV. 445 When there are no abailable credentials, the Peer MAY include an 446 authorization token that can be consumed by the Server for 447 registering new credentials. In particular, the Peer can include 448 the ('Token-Data') TLV to convey the value of the token. The 449 ('Challenge-Data') and ('Challenge-Response') TLVs, instead, can 450 be used to convey a challenge and its response based on the 451 authorization information (e.g., maybe a public key hash is 452 present in the Token, then the peer can generate some random data 453 - or use the one from the Server - and generate a signature on 454 that value: the signature SHALL be encoded in the ('Challenge- 455 Response') TLV and it should be calculated over the concatenation 456 of values inside the ('Challenge-Data') TLV and the ('Token-Data') 457 TLV. 459 Also, the Peer MAY add one or more ('Profile') TLVs to indicate to 460 the Server which profiles are requested/supported (e.g., a pre- 461 configuration MAY exist on the Peer with these ecosystem-specific 462 identifiers). 464 Ultimately, the Peer MAY include additional metadata regarding the 465 status of the Peer. To this end, the Peer can use a ('Storage- 466 Info') TLV to provide the server with additional data about the 467 Peer's capabilities and resources. Also, the ('Network-Usage') 468 TLV can be used to provide the Server with the indication of which 469 network resources are needed by the Peer and what is its intended 470 utilization pattern(s). 472 The server checks that the Peer's selected protocol, version, and 473 parameters are supported and, if not (or if the server detects an 474 error), it can (a) send a non-recoverable error message to the 475 peer, notify the outer (tunneling) layer, and terminate the EAP- 476 CREDS session, or (b) start phase one again by sending a new 477 ('EAP-CREDS-Init') message that will also carry an ERROR TLV that 478 provides the Peer with the reason the initial response was not 479 acceptable. In this case, the ('Phase-Control') TLV MUST be 480 omitted since it is not the first message of phase one. The 481 server and the peer can repeat phase one until they reach an 482 agreement or the session is terminated by the Server. 484 NOTE WELL: The determination of the need to start phase two or not 485 is based on the contents of the ('Credentials-Info') TLV sent by 486 the Peer (e.g., a credential is about to expire or a credential is 487 simply missing). 489 3.4. Phase Two: Provisioning 491 The following figure provides the message flow for Phase 2: 493 ,--------. ,----------. 494 |EAP Peer| |EAP Server| 495 `---+----' `----+-----' 496 | [1] EAP-Request/EAP-CREDS(Type=Provisioning) | 497 | { Protocol, Action, | ,---------!. 498 | [ CredInfo ], [ Params ], | |Phase Two|_\ 499 | [ ProtoData ], [ ProtoHeaders ] } | |Begins | 500 | <---------------------------------------------- `-----------' 501 | | 502 | [2] EAP-Response/EAP-CREDS(Type=Provisioning) | 503 | { ProtoData, [ ProtoHeaders ] } | 504 | ----------------------------------------------> 505 | | 506 . . 507 . . 508 . . 509 . . 510 | [N] EAP-Response/EAP-CREDS(Type=Provisioning) | 511 | { [ CredInfo ], [ ProtoData ], | 512 | [ ProtoHeaders ] } | 513 | <---------------------------------------------- 514 | | 515 | [N+1] EAP-Request/EAP-CREDS(Type=Provisioning)| ,---------!. 516 | { [ ProtoData ], [ ProtoHeaders ] } | |Phase Two|_\ 517 | ----------------------------------------------> |Ends | 518 | | `-----------' 519 | | 521 EAP-CREDS Phase Two Message Flow 523 [1] The Server sends EAP-Request/EAP-CREDS(Type=Init) 525 The first message of Phase Two indicates that the Server is ready 526 to initiate the selected provisioning protocol. 528 [2] The Peer sends EAP-Response/EAP-CREDS(Type=Init) 530 After that, the Peer sends its first message to the Server by 531 sending the EAP-Response/EAP-CREDS(Type=Provisioning) message. 532 This message contains the selected provisioning protocol's message 533 data and some extra fields (e.g., transport-protocol headers) in 534 the ('Provisioning-Data') and ('Protocol-Headers') TLVs 535 respectively. 537 [3] The Server sends EAP-Request/EAP-CREDS(Type=Init) 539 The Server replies to the Peer's message with EAP-Request/EAP- 540 CREDS(Type=Provisioning) messages until the provisioning protocol 541 reaches an end or an error condition arise (non-recoverable). 543 [N] The Server sends EAP-Request/EAP-CREDS(Type=Provisioning) 545 When the provisioning protocol has been executed for the specific 546 set of credentials, the server sends a last message that MUST 547 include the description of the provisioned credentials in a 548 ('Credentials-Info') TLV and MUST set the 'D' bit in the EAP-CREDS 549 message header to '1' to indicates that the server does not have 550 any more ('Provisioning') messages for this credenital. The final 551 message does not need to be an empty one, i.e. other TLVs are 552 still allowed in the same message (e.g., the 'Provisioning-Data' 553 and the 'Provisioning-Headers' ones). 555 [N+1] The Peer sends EAP-Request/EAP-CREDS(Type=Provisioning) 557 The Peer MUST reply to the server with a ('Provisioning') message 558 that MUST have the 'D' bit in the EAP-CREDS message header set to 559 '1', thus indicating that the credentials have been installed 560 correctly. In case of errors, the Peer MUST include the 561 appropriate ('Error') TLV. Also in this case, the final message 562 does not need to be an empty one, i.e. other TLVs are still 563 allowed in the same message (e.g., the 'Provisioning-Data' and the 564 'Provisioning-Headers' ones). 566 At this point, the Server can decide to provision (or manage) another 567 set of credentials by issuing a new ('Provisioning') message, or it 568 can decide to start Phase Three by sending its first ('Validate') 569 message, or it can terminate the EAP session. 571 3.5. Phase Three: Validation 573 The following figure provides the message flow for Phase 3: 575 ,--------. ,----------. 576 |EAP Peer| |EAP Server| 577 `---+----' `----+-----' 578 | [1] EAP-Request/EAP-CREDS(Type=Validate) | ,-----------!. 579 | { Cred-Info, Challenge } | |Phase Three|_\ 580 | <----------------------------------------- |Begins | 581 | | `-------------' 582 | [2] EAP-Response/EAP-CREDS(Type=Validate)| ,-----------!. 583 | { Challenge-Response } | |Phase Three|_\ 584 | -----------------------------------------> |Ends | 585 | | `-------------' 586 | | 588 EAP-CREDS Phase Three Message Flow 590 Phase three is optional and it is used by the server to request the 591 client to validate (proof) that the new credentials have been 592 installed correctly before issuing the final Success message. 594 NOTE WELL: Phase Three introduces a dependency on the selected 595 hashing algorithm to provide common and easy way to check the 596 integrity and functionality of a newly installed set of 597 credentials. 599 [1] The Server sends EAP-Request/EAP-CREDS(Type=Validate) 601 In order to start Phase Three, the Server sends an EAP-Request/ 602 EAP-CREDS(Type=Validate) message to the Peer. The Server MUST 603 include the ('Credentials-Info') TLV to provide the indication 604 about which set of credentials the Server intends to validate. 605 The Server MUST also include a randomly generated challenge in the 606 message to the client. The type of challenge determines how the 607 ('Challenge-Response') is calculated. EAP-CREDS defines the 608 asymmetric and symmetric challenges in Section 8.6 and others can 609 be defined according to the specified rules. 611 As usual, the Server MUST set, in the headers, the 'S' bit to '1' 612 in its first message of Phase Three and the 'Phase' value shall be 613 set to '3' (beginning of Phase Three). 615 [2] The Peer sends EAP-Response/EAP-CREDS(Type=Validate) 616 When the client receives the Validate message from the server, it 617 calculates the response to the challenge and sends the response 618 back to the server in a EAP-Response/EAP-CREDS(Type=Validate) 619 message. When the EAP-CREDS-ASYMMETRIC-CHALLENGE and EAP-CREDS- 620 SYMMETRIC-CHALLENGE values are used in the Challenge type, the 621 Peer MUST calculate the response as follows: 623 Public-Key 625 For any public-key based credentials (e.g., certificates or 626 raw key pairs), the response to the challenge is calculated 627 by generating a signature over the hashed value of the 628 challenge. The hashing algorithm to be used for this 629 purpose is specified in Section 2.6. The format of the 630 signature in the ('Challenge-Response') TLV is the 631 concatenation of: 633 - The signatureAlgorithm (DER encoded) which contains the 634 identifier for the cryptographic algorithm used by the 635 Peer to generate the signature. [RFC3279], [RFC4055], 636 and [RFC4491] list supported signature algorithms, but 637 other signature algorithms MAY also be supported. The 638 definition of the signatureAlgorithm is provided in 639 Section 4.1.1.2 of [RFC5280]. 641 - The signatureValue (DER encoded) which contains the 642 digital signature itself. The signature value is encoded 643 as a BIT STRING and the details of how to generate the 644 signatures' structures can be found in Section 4.1.1.3 of 645 [RFC5280] and referenced material. 647 Symmetric Secret 649 For any symmetric based credentials (e.g., password or Key), 650 the response to the challenge is calculated by using the 651 selected hash function (see Section 2.6) on the 652 concatenation of (a) the value carried in the server- 653 provided ('Challenge-Data') TLV, and (b) the secret value 654 itself (salted hash). 656 The initial values for the type of challenges are described in the 657 Section 8.6. Other types of challenges MAY be defined according 658 to the specified procedures. 660 In case of issues with the validation of newly deployed 661 credentials, both the Server and the Peer should consider those 662 credentials invalid (or unusable) and should issue the required 663 failure message(s). 665 4. EAP-CREDS Message Format 667 The EAP-CREDS defines the following message types: 669 1. EAP-CREDS/Init 671 2. EAP-CREDS/Provisioning 673 3. EAP-CREDS/Validate 675 Each of these message types have the basic structure as identified in 676 Section 4.1. EAP-CREDS messages contain zero, one, or more TLVs. 677 The internal structure of the different types of TLVs is described in 678 Section 4.2, while a detailed description of the EAP-CREDS message 679 types is provided in Section 5. 681 4.1. Message Header 683 The EAP-CREDS messages consist of the standard EAP header (see 684 Section 4 of [RFC3748]), followed by the version of the EAP-CREDS (4 685 bits) and a field (4 bits) reserved for future use. The header has 686 the following structure: 688 0 1 2 3 689 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 690 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 691 | Code | Identifier | Length | 692 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 693 | Type |J|S|F|D| Phase | Message Length | 694 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 695 | Message Length | Data ... 696 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-. 698 Where the Code, Identifier, Length, and Type fields are all part of 699 the EAP header as defined in [RFC3748]. Since EAP-CREDS can only be 700 used as a tunneled mechanism, the presence of these fields is only 701 for backward compatibility with existing parsers. In particular, the 702 'Length' field is not used (can be ignored): the message length is 703 carried in the 'Message Length' field instead. 705 The Type field in the EAP header is for EAP-CREDS. 707 The Flags bitfield is used to convey status information (e.g., extra 708 long message, phase number, phase transitioning state). The 709 transition-control bit (i.e., the 'S' bit) are set in Server's 710 messages and are ignored in Peer's messages (the Server is the entity 711 that unilaterally controls the phase transition process). The 712 meanins of the bits in the 'Flags' field are as follows: 714 Bit 'J' (Jumbo Message) - If set, it idicates the presence of the 715 'Message Length' field. This bit SHALL be used only when the size 716 of the message exceeds the maximum value allowed in the 'Length' 717 field. In this case, the 'Message Length' field is added to the 718 message and set to the whole message size and the 'Length' field 719 is used for the current fragment length. If not set, the 'Message 720 Length' field is not present in the Message and the 'Length' field 721 is used for the message size (and the 'F' bit MUST be set to '0'). 723 Bit 'S' (Start) - If set, this message is the first one of a new 724 EAP-CREDS phase. The value of the new phase is encoded in the 725 'Phase' field. 727 Bit 'F' - If set, this message is a fragment of a message. In 728 this case, the 'Data' field is to be concatenated with all 729 messages with the 'F' bit set to '1' until the message with the 730 'F' bit set to '0' that indicates the end of the message. If the 731 message is not fragmented, the 'F' bit MUST be set to '0'. The 732 use of this bit is required when the tunneling method does not 733 provide support for messages up to 2^32 bits in size. 735 Bit 'D' - This bit is used in Phase Two and Phase Three to 736 indicate that the specific operation for the identified credential 737 is over. For example, when multiple credentials exist on the Peer 738 and the Server needs to manage and validate one of them. In its 739 last message, when the provisioning protocol is done, the server 740 sets the 'D' (Done) bit to indicate that it is done. The Peer, in 741 its reply, sets the bit to indicate the end of provisioning for 742 this credentials is also over. After that, the Server can 743 continue Phase Two, transition to Phase Three, or terminate the 744 EAP session. 746 The Phase field is a 4-bits value and identifies the EAP-CREDS phase 747 for the current message. The version of EAP-CREDS described in this 748 document supports three values for this field: 750 0x01 - Phase One 752 0x02 - Phase Two 754 0x03 - Phase Three 756 A detailed explanation of the 'Phase' and 'Flags' fields of the 757 message headers is provided in Section 3.2. 759 The Data field is the message payload. The full description of this 760 field is provided in the next section. 762 4.2. Message Payload 764 The Data part of the message is organized as zero, one, or more TLV 765 objects whose structure is defined in this section. 767 Each TLV object has the same basic structure that is defined as 768 follows: 770 0 1 2 3 771 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 772 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 773 | TLV Type | TLV Length | 774 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 775 | TLV Value ... 776 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 778 Where: 780 TLV-Type (uint8) 782 This field is used to indicate the type of data that the TLV 783 carries. The type of TLV determines its internal structure. The 784 supported values for this fields are provided in the following 785 table: 787 Length (uint24) 789 This field carries the size of the value of the TLV. In 790 particular, the overall size of a TLV (i.e., the header plus the 791 value) can be calculated by adding the size of the header (6 792 octects) to the value of the Length field (i.e., the size of the 793 TLV's value). 795 +----------+--------------------------+------------------------+ 796 | TLV Name | TLV Type | Scope/Usage | 797 +----------+--------------------------+------------------------+ 798 | | Action TLV | Phase Two | 799 | | Certificate-Data TLV | Phase Two/SPP | 800 | | Challenge-Data TLV | Phase Two, Phase Three | 801 | | Challenge-Response TLV | Phase Two, Phase Three | 802 | | Credentials-Data TLV | Phase Two/SPP | 803 | | Credentials-Info TLV | Phase Two, Phase Three | 804 | | Error TLV | All Phases | 805 | | Network-Usage TLV | Phase One | 806 | | Profile TLV | Phase Two | 807 | | Protocol TLV | Phase One, Phase Two | 808 | | Provisioning-Data TLV | Phase Two | 809 | | Provisioning-Headers TLV | Phase Two | 810 | | Provisioning-Params TLV | Phase Two | 811 | | Certificate-Request TLV | SPP | 812 | | Storage-Info TLV | SPP | 813 | | Supported-Format TLV | SPP | 814 | | Supported-Encoding TLV | SPP | 815 | | Token-Data TLV | Phase One | 816 | | Version TLV | Phase One | 817 +----------+--------------------------+------------------------+ 819 Table 2: EAP-CREDS Supported TLVs Types 821 TLV Value ( > 1 octet ) 823 This field carries data for the identified TLV. The internal 824 structure is determined by the TLV Type field. 826 The rest of this section describes the structure of the different 827 supported TLVs and their usage in the different messages. 829 4.3. EAP-CREDS defined TLVs 831 EAP-CREDS messages's payload comprieses zero, one, or more TLVs that 832 are encoded in a single EAP-CREDS message. The values for the TLV 833 Type that are supported by this specifications are listed in Table 2. 835 4.3.1. The Action TLV 836 0 1 2 3 837 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 838 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 839 | TLV Type | TLV Length | 840 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 841 | Flags | Action Type | 842 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 844 TLV Type (uint8) 846 - Action TLV 848 TLV Length (uint24) 850 Fixed value (=2) 852 Flags (uint8) 854 Reserved 856 4.3.2. The Certificate-Data TLV 858 0 1 2 3 859 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 860 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 861 | TLV Type | TLV Length | 862 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 863 | Flags | Encoding | Value ... 864 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 866 TLV Type (uint8) 868 - Certificate-Data TLV 870 Length (uint24) 872 Provides the length of the TLV (> 3 octets) 874 Flags (uint8) 876 Provides a BITMASK that can be used to provide additional 877 information related to the encapsulated certificate. The bits 878 have the following meaning: 880 Bit 0 - If set, the certificate is trusted (Trust Anchor) 881 Bit 1 - If set, the certificate is a CA certificate 883 Bit 2 - If set, the certificate is self-signed 885 Bit 3 - If set, the certificate is a proxy certificate 887 Bit 4 - If set, the certificate is an attribute certificate 889 Bit 5 - Reserved 891 Bit 6 - Reserved 893 Bit 7 - Reserved 895 For a Trusted Root CA, the value of the flags shall be 0x7 (0000 896 0111). For an intermediate CA certificate that is not implicitly 897 trusted, the value of the flags field should be set to 0x02 (0000 898 0010). For an End-Entity certificate, the value of the Flags will be 899 0x0 (0000 0000). 901 Format (uint8) 903 Provides the indication of the Format the certificate is in. The 904 allowed values for this field are listed in Section 8.5. 906 Encoding (uint8) 908 Provides the indication of the Encoding the certificate is in. 909 The allowed values for this field are listed in Section 8.8. 911 Value (octet string) 913 This field carries the data for the certificate. 915 4.3.3. The Challenge-Data TLV 917 0 1 2 3 918 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 919 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 920 | TLV Type | TLV Length | 921 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 922 | Ch. Type | Challenge Data ... 923 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 925 TLV Type (uint8) 926 - Challenge-Data TLV 928 Length (uint24) 930 3 octets 932 Challenge Type (uint8) 934 This field carries the type of Challenge. In particular, the 935 challenge type determines how the Peer MUST calculate the 936 ('Challenge-Response'). The initial values for this fiel are 937 listed in Section 8.6. Please refer to Section 3.5 for a detailed 938 explanation of how to calculate the response to the challenge for 939 the challenge types defined in this document. 941 Challenge Data (> 1 octet) 943 This field carries the data to be used as a challenge when 944 validating newly deployed credentials. 946 4.3.4. The Challenge-Response TLV 948 0 1 2 3 949 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 950 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 951 | TLV Type | TLV Length | 952 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 953 | Challenge Response ... 954 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 956 TLV Type (uint8) 958 - Challenge-Response TLV 960 Length (uint24) 962 3 octets 964 Challenge Response (> 1 octet) 966 This field carries the data that resulted from the use of the 967 credentials to be validated. 969 4.3.5. The Credentials-Information TLV 971 0 1 2 3 972 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 973 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 974 | TLV Type | TLV Length | 975 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 976 | Flags | CredsType | ProtoID | 977 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 978 | | 979 | IssuedOn (GMT) | 980 | | 981 | | 982 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 983 | | 984 | Expires On (GMT) | 985 | | 986 | | 987 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 988 | Credentials Length | 989 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 990 | CredIDValue ... 991 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 993 The Credential-Information TLV is used by the Peer to provide a 994 description of the installed credentials that are relevant for the 995 network that is being accessed. 997 For example, when a set of credentials need to be renewed, the server 998 checks the ('Credentials-Info') from the Peer and eventually selects 999 the right one for renewal. The TLV structure is as follows: 1001 TLV Type (uint8) 1003 - Credentials-Information TLV 1005 Length (uint24) 1007 Provides the total length of the body of the Credential- 1008 Information TLV. 1010 Flags (uint8) 1012 Provides a BITMASK that can be used to provide information about 1013 the status of the credentials (e.g., if the use marks the 1014 credentials to be compromised). The bits have the following 1015 meaning: 1017 Bit 0 - If set, the credential is marked as compromised 1019 Bit 1 - If set, the credential is immutable and cannot be 1020 updated 1022 Bit 2 - Private Key or Secret Immutable, the public part of the 1023 credential (e.g., a certificate) can still be updated 1025 Bit 3 - If set, the credential cannot be updated (both public 1026 and private parts) 1028 Bit 4 - If set, the credential is ready to be used 1030 Bit 5 - If set, the credential was generated on the server 1032 Bit 6 - If set, the Peer would like to update the credential 1033 even if they are not expired 1035 Bit 7 - Reserved 1037 CredType (uint8) 1039 This field provides the description of the type of credential. 1040 The type of credentials are listed in Section 8.3 1042 ProtoID (uint16) 1044 This field indicates the protocol that was used to retrieve the 1045 target credential. When the TLV is used in a Request by the 1046 Server, this field is ignored. The values for this field are 1047 listed in Section 8.1. 1049 IssuedOn (16 octets) 1051 This field carries the GMT date for when this credential was 1052 issued. This field is 16 bytes long (the last byte must be set to 1053 '0x00') and contains the NULL-terminated ASCII string that 1054 represents the timestamp where the credential was issued. When 1055 the value is not set, the field should be set to { 0x00 }. The 1056 format of the string is as follows: 1058 YYYYMMDDHHmmssZ 1060 Where: 1062 YYYY - is the 4 digits representation of the year 1064 MM - is the 2 digits representation of the month 1066 DD - is the 2 digits representation of the day of the month 1068 HH - is the 2 digits representation of the hour of the day (24 1069 hour format) 1071 mm - is the 2 digits representation of the minutes of the hour 1073 ss - is the 2 digits representation of the seconds of the 1074 minute 1076 Z - is the character 'Z' 1078 ExpiresOn (16 octets) 1080 This field carries the GMT date for when this credential is to be 1081 considered expired. This field is 16 bytes long (the last byte 1082 must be set to '0x00') and contains the NULL-terminated ASCII 1083 string that represents the timestamp where the credential was 1084 issued. The format is the same as the ('IssuedOn') field. When 1085 the value is not set, the field should be set to { 0x00 }. 1087 Credentials Length (uint16) 1089 Length (in bytes) of the Credentials value. When used with a 1090 public-key type of credentials, this is the size of the key (e.g., 1091 for an RSA 2048 bit keys, this field should carry the value of 1092 256). When used with a symmetric secret, this field carries the 1093 size of the secred (in bytes). 1095 CredIDValue (> 1 octet) 1097 The binary value of the credentials' identifier. This identifier 1098 can be the binary value of the SHA-256 calculated over the 1099 certificate, a username, or it could be a random handle. As long 1100 as the ID allows the peer and the server to uniquely (in its 1101 context) identify the credentials, the value of this field can be 1102 calculated in any way. 1104 4.3.6. The Credentials-Data TLV 1106 0 1 2 3 1107 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 1108 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1109 | TLV Type | TLV Length | 1110 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1111 | Cred Type | Format | Encoding | Value ... 1112 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1114 TLV Type (uint8) 1116 - Credentials-Data TLV 1118 Length (uint24) 1120 Provides the length of the TLV (> 3 octets) 1122 Cred Type (uint8) 1124 Provides the indication of the type of credentials. The allowed 1125 values for this field are listed in Section 8.3. 1127 Format (uint8) 1129 Provides the indication of the Format the credentials are in. The 1130 allowed values for this field are listed in Section 8.5. 1132 Encoding (uint8) 1134 Provides the indication of the Encoding the credentials are in. 1135 The allowed values for this field are listed in Section 8.8. 1137 Value (octet string) 1139 This field carries the data for the credentials. 1141 4.3.7. The Error TLV 1142 0 1 2 3 1143 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 1144 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1145 | TLV Type | TLV Length | 1146 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1147 | EAP-CREDS Error Code | Secondary Error Code | 1148 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1149 | Description ... 1150 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1152 TLV Type (uint8) 1154 - Challenge-Response-Data TLV 1156 Length (uint24) 1158 3 octets 1160 EAP-CREDS Error Code (2 octets) 1162 This field carries the EAP-CREDS error code. These code are 1163 related to the EAP-CREDS operations only and it should not be used 1164 to carry the Provisioning-Protocol specific error codes. 1166 The error codes supported by this specifications are listed in 1167 Section 4.3.7. 1169 Secondary Error Code (2 octets) 1171 This field is used to convery an error at the encapsulation layer 1172 (i.e., the provisioning protocol error). For example, this field 1173 can be used to convey a transport protocol error code (e.g., HTTP 1174 status code). Do not use this field to convery EAP-CREDS specific 1175 errors. 1177 Description ( > 1 octet) 1179 The Description field is optional (i.e., when the Description Size 1180 is set to zero) and carries information about the error that 1181 occurred. The message may or may not be used by a user or an 1182 automated process for debugging purposes. 1184 4.3.8. The Network-Usage TLV 1185 0 1 2 3 1186 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 1187 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1188 | TLV Type | TLV Length | 1189 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1190 |U| Desc Format | Encoding | Network-Usage Data ... 1191 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1193 TLV Type (uint8) 1195 - Network-Usage TLV 1197 Length (uint24) 1199 Variable Length TLV (Value must be > 2 ) 1201 Description Format (uint8) 1203 The Type of data encoded in the Peer Description Data. The 1204 initial values for this field are listed in Section 8.10. 1206 Encoding (uint8) 1208 Provides the indication of the Encoding the network usage 1209 description data is in. The allowed values for this field are 1210 listed in Section 8.8. 1212 The 'U' field (1 bit) 1214 The 'URL' bit ('U') is used to indicate if the value of the 1215 Network-Usage Data field is to be interpreted as a URL or as the 1216 actual data. In particular, if the value in the 'URL' bit is '1', 1217 then the value in the Network-Usage Data field is to be 1218 interpreted as the URL where the actual data can be downloaded 1219 from. Otherwise, if the 'URL' bit is set to '0', then the value 1220 in the Netowrk-Usage Data field is to be interpreted as the actual 1221 data (not a URL referencing it). 1223 An example use of this bit is when the Peer wants to convey the 1224 URL of the MUD file [RFC8520]. In this case, the Peer can set the 1225 Network-Usage Data field to the Url of the MUD file related to the 1226 Peer. 1228 Desc Format (7 bits) 1230 This field provide the expected data format for the Network-Usage 1231 Data. For example, the value in this field could be set to 'MUD' 1232 and have the 'U' bit set to '1' to provide the MUD-related 1233 information at credentials management time instead of at network- 1234 provisioning time (DHCP option). This possibility could help the 1235 Network controller to decide if the device shall be allowed to 1236 register its credentials or not. 1238 The list of initial values for this field is provided in 1239 Section 8.7. 1241 Network-Usage Data (octet string) 1243 This is additional information related to the device. In 1244 particular, this TLV can be used by the Peer to provide the Server 1245 with the description of the intended network usage or a URL that 1246 points to the same information. 1248 For example, this field can be used to convey a MUD file 1249 (Manufacturer Usage Description) or the latest firmware-update 1250 manifest. 1252 4.3.9. The Profile TLV 1254 0 1 2 3 1255 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 1256 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1257 | TLV Type | TLV Length | 1258 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1259 | Profile Identifying Data ... 1260 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1262 TLV Type (uint8) 1264 - Profile Identifying Data TLV 1266 Length (uint24) 1268 Length value should be >= 1 1270 Profile Identifying Data (octet string) 1272 The Profile Identifying Data is used to provide indication to the 1273 other party about which profiles are supported when requesting 1274 credentials management. 1276 Also in this case, the data used in this field is left to be 1277 interpreted by the end-point and it is orthogonal to EAP-CREDS 1278 data types. 1280 An example of values for this field, an end-point could use the 1281 string representation (i.e., dotted representation) of the Object 1282 Identifier (OID) of the specific profile supported (e.g., could be 1283 defined in the Certificate Policy of the credentials' provider). 1285 4.3.10. The Protocol TLV 1287 0 1 2 3 1288 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 1289 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1290 | TLV Type | TLV Length | 1291 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1292 | Protocol ID | Version | 1293 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1295 TLV Type (uint8) 1297 - Protocol TLV 1299 TLV Length (uint24) 1301 Fixed TLV Length value of 4. 1303 Protocol ID (uint16) 1305 The Protocol ID value carries the id of a supported provisioning 1306 protocol. The initial list of values for the provisioning 1307 protocol identifiers can be found in Section 8.1. 1309 Version (uint16) 1311 The Version (Protocol Version) value represents the specific 1312 version of the identified provisioning protocol. When no version 1313 is specified for a protocol (i.e., either it does not support 1314 multiple versions or it does not matter), the value of this field 1315 should be set to '0x0'. 1317 4.3.11. The Provisioning-Data TLV 1318 0 1 2 3 1319 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 1320 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1321 | TLV Type | TLV Length | 1322 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1323 | Provisioning Data ... 1324 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1326 TLV Type (uint8) 1328 - Provisioning-Data TLV 1330 Length (uint24) 1332 3 octets 1334 Headers Data (> 1 octet) 1336 This field carries the provisioning protocol's messages. 1338 4.3.12. The Provisioning-Headers 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 | Headers Data ... 1346 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1348 TLV Type (uint8) 1350 - Provisioning-Headers TLV 1352 Length (uint24) 1354 3 octets 1356 Headers Data (> 1 octet) 1358 This field carries the meta-data (if any) that might be associated 1359 with the transport-layer normally used with the provisioning 1360 protocol. For example, this TLV can carry the set of HTTP headers 1361 required by EST or ACME. 1363 4.3.13. The Provisioning-Params TLV 1365 0 1 2 3 1366 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 1367 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1368 | TLV Type | TLV Length | 1369 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1370 | Min Length | Max Length | 1371 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1372 | Algorithm | Flags | OBJECT IDENTIFIER (DER) ... 1373 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1375 TLV Type (uint8) 1377 - Provisioning-Params TLV 1379 Length (uint24) 1381 Provides the length of the TLV (>= 6 octets) 1383 Min Length (uint16) 1385 Provides the minimum allowed size size for the credentials. This 1386 value has meaning depending on the context of the credentials, 1387 however sizes are always expressed in bytes. 1389 For example, when used with a symmetric key or a password, the 1390 ('Min Length') and ('Max Length') refer to the minimum and maximum 1391 size of the password data. The ('Algor OID') field can be omitted 1392 in this case. 1394 On the other hand, when referring public-key credentials, this 1395 field should carry the size of the modulus of the key. For 1396 example, for an RSA 2048 bit keys, the field should carry the 1397 value of 256. For an ECDSA that uses the prime256r1 curve, this 1398 field should carry the value of 32 and the Algor OID should be the 1399 DER representation of the specific value of the curve (i.e., the 1400 DER representation of '1.2.840.10045.3.1.7'). 1402 Max Length (uint16) 1404 Provides the indication maximum size of the credentials. This 1405 value has meaning depending on the context of the credentials, 1406 however sizes are always expressed in bytes. 1408 The same considerations apply to this field as well as the ('Min 1409 Length') one discussed above. 1411 Flags (uint8) 1413 Provides a BITMASK that can be used to provide information about 1414 the status of the credentials (e.g., if the use marks the 1415 credentials to be compromised). The bits have the following 1416 meaning: 1418 Bit 0 - Credentials (or part of it) are to be generated on the 1419 server 1421 Bit 1 - Credentials (or part of it) are to be generated on the 1422 peer 1424 Bit 2 - Credentials are to be generated on dedicated hardware 1426 Bit 3 - Reserved 1428 Bit 4 - Reserved 1430 Bit 5 - Reserved 1432 Bit 6 - Reserved 1434 Bit 7 - Reserved 1436 When using public-key based credentials, the bits 0 and 1 are 1437 mutually exclusive. 1439 When using passwords or shared secrets, if bit 0 is set, then the 1440 secret is generated by the server and then sent to the client. On 1441 the other hand, if bit 1 is set, then the secret is generated by 1442 the peer and then sent to the server. Ultimately, if both bits 1443 are set, then the Server generates the first part of the password 1444 and sends it to the Peer, while the Peer generates the second part 1445 of the password and sends it to the Server. The password to be 1446 used for future authentication is the concatenation of the two 1447 shares of the password: first the one from the Server, then the 1448 one from the Client. 1450 NOTE WELL: Last but not least, since these passwords/secrets 1451 are meant to be used in a automated fashion, there is no 1452 restriction around the character set to use or their 1453 interpretation. Therefore,it is good practice to generate 1454 random passphrases that use the full 8-bit character set (on 1455 client and server) to maximize the secret's search space. 1457 Algorithm (uint8) 1459 Provides the indication of the algorithm used for the generation 1460 of the credentials. The allowed values for this field are listed 1461 in Section 8.4. 1463 Object Identifier (binary; > 1 octet) 1465 Provides the indication of additional parameters that are needed 1466 to be encoded for the credentials. This value is used only when 1467 the credentials use public-key cryptography - this field carries 1468 additional information about the generation algorithm to be used. 1469 We provide some useful values that can be used as reference: 1471 +----------------+----------------------+---------------------------+ 1472 | OID Name | Dotted | Binary Encoding | 1473 | | Representation | | 1474 +----------------+----------------------+---------------------------+ 1475 | secp256r1 | 1.2.840.10045.3.1.7 | 06 08 2A 86 48 CE 3D 03 | 1476 | curve | | 01 07 | 1477 | secp384r1 | 1.2.840.10045.3.1.34 | 06 08 2A 86 48 CE 3D 03 | 1478 | curve | | 01 22 | 1479 | secp521r1 | 1.2.840.10045.3.1.35 | 06 08 2A 86 48 CE 3D 03 | 1480 | curve | | 01 23 | 1481 | X25519 curve | 1.3.101.110 | 06 03 2B 65 6E | 1482 | X25519 curve | 1.3.101.110 | 06 03 2B 65 6E | 1483 | X448 curve | 1.3.101.111 | 06 03 2B 65 6F | 1484 | Ed25519 curve | 1.3.101.112 | 06 03 2B 65 70 | 1485 | Ed448 curve | 1.3.101.113 | 06 03 2B 65 71 | 1486 +----------------+----------------------+---------------------------+ 1488 Table 3: Object Identifiers Examples 1490 4.3.14. The Certificate-Request TLV 1492 0 1 2 3 1493 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 1494 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1495 | TLV Type | TLV Length | 1496 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1497 | Encoding | Format | Value ... 1498 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1500 TLV Type (uint8) 1502 - Token-Data TLV 1504 TLV Length (uint24) 1506 Provides the length of the TLV (> 3 octets) 1508 Encoding (uint8) 1510 Provides the indication of the Encoding the credentials are in. 1511 The allowed values for this field are listed in Section 8.8. 1513 Format (uint8) 1515 Provides the indication of the type of credentials. The allowed 1516 values for this field are listed in Section 8.5. 1518 Value (octet string) 1520 This field carries the data for the credentials. 1522 4.3.15. The Storage-Info TLV 1524 0 1 2 3 1525 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 1526 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1527 | TLV Type | Flags | Spare Slots | 1528 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1529 | Available Memory | 1530 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1532 TLV Type (uint8) 1534 - Store-Info TLV 1536 Flags (8 bits) 1538 Provides information about the status and type of store and 1539 limited information about its capabilities. The bits have the 1540 following meaning: 1542 Bit 0 - If set, the store supports RSA keys (software) 1544 Bit 1 - If set, the store supports RSA keys (hardware) 1545 Bit 2 - If set, the store supports ECDSA keys (software) 1547 Bit 3 - If set, the store supports ECDSA keys (hardware) 1549 Bit 4 - If set, the store supports symmetric keys 1551 Bit 5 - If set, the store supports generic tokens 1553 Bit 6 - If set, the store is immutable (no key generation or 1554 deletion) 1556 Bit 7 - Not Used 1558 Spare Slots (uint16) 1560 Provides the number of available slots where to store credentials. 1561 When no more slots are available, the value of '0' should be used 1562 to indicate to the Server that a credential must be deleted before 1563 a new one can be created. 1565 When the number of slots is not fixed or not known, the value of { 1566 0xFF, 0xFF } shall be used. 1568 Available Memory (uint32) 1570 This field carries the size (in bytes) of the spare memory on the 1571 Peer's secrets' store. 1573 4.3.16. The Supported-Formats TLV 1575 0 1 2 3 1576 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 1577 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1578 | TLV Type | TLV Length | 1579 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1580 | Format | 1581 +-+-+-+-+-+-+-+-+ 1583 TLV Type (uint8) 1585 - Supported-Format TLV 1587 TLV Length (uint24) 1589 Provides the length of the TLV. This field must be set to 1. 1591 Format (uint8) 1593 Provides the details about the supported format. Multiple formats 1594 TLVs can be used in the Peer's ('Init') message to provide the 1595 Server with the Peer's capabilities. 1597 4.3.17. The Supported-Encoding TLV 1599 0 1 2 3 1600 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 1601 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1602 | TLV Type | TLV Length | 1603 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1604 | Encoding | 1605 +-+-+-+-+-+-+-+-+ 1607 TLV Type (uint8) 1609 - Store-Info TLV 1611 TLV Length (uint24) 1613 Provides the length of the TLV. The field has a fixed value of 1. 1615 Encoding (uint8) 1617 Provides the indication of the supported Encoding by the End 1618 Point. This provides the indication to the Server of the 1619 capability of the Peer. The allowed values for this field are 1620 listed in Section 8.8. 1622 4.3.18. The Token-Data TLV 1624 0 1 2 3 1625 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 1626 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1627 | TLV Type | TLV Length | 1628 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1629 | Token Type | Encoding | Value ... 1630 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1632 TLV Type (uint8) 1634 - Token-Data TLV 1636 TLV Length (uint24) 1638 Provides the length of the TLV (> 3 octets) 1640 Token Type (uint8) 1642 Provides the indication of the type of credentials. The allowed 1643 values for this field are listed in Section 8.2. 1645 Encoding (uint8) 1647 Provides the indication of the Encoding the credentials are in. 1648 The allowed values for this field are listed in Section 8.8. 1650 Value (octet string) 1652 This field carries the data for the credentials. 1654 4.3.19. The Version TLV 1656 0 1 2 3 1657 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 1658 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1659 | TLV Type | TLV Length | 1660 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1661 | Version | 1662 +-+-+-+-+-+-+-+-+ 1664 TLV Type (uint8) 1666 - Version TLV 1668 TLV Length (uint24) 1670 Provides the length of the TLV. The field has a fixed value of 1. 1672 Version (uint8) 1674 The Version field represents the specific version of the EAP-CREDS 1675 protocol that are supported by the end point. When multiple 1676 versions of EAP-CREDS are supported, multiple ('Version') TLVs can 1677 be used. 1679 When no version is specified (i.e., either it does not support 1680 multiple versions or it does not matter), the value of this field 1681 should be set to '0x0' (any version). 1683 5. EAP-CREDS Messages 1685 This section describes each message and what TLVs are allowed or 1686 required. EAP-CREDS defines the following values for the Message 1687 Type (Type): 1689 +-----------+------------------------+------------------------------+ 1690 | Message | Name | Description | 1691 | Type | | | 1692 +-----------+------------------------+------------------------------+ 1693 | 0 | EAP-CREDS-Init | Initialization Phase | 1694 | 1 | EAP-CREDS-Provisioning | Carries Provisioning | 1695 | | | Protocol Messages | 1696 | 2 | EAP-CREDS-Validate | Validates newly installed | 1697 | | | credentials | 1698 +-----------+------------------------+------------------------------+ 1700 Table 4: EAP-CREDS Message Types 1702 5.1. The EAP-CREDS-Init Message 1704 The EAP-CREDS-Init message type is used in Phase One only of EAP- 1705 CREDS. The message flow is depicted in Section 3.3. This message 1706 supports the following TLVs: Version, Protocol, Credentials-Info, and 1707 Error. 1709 5.1.1. EAP Server's Init Message 1711 EAP-CREDS starts with an ('EAP-CREDS-Init') message from the server. 1712 This message MAY contain zero, one, or more ('Version') TLVs and, 1713 optionally, a ('Challenge-Data') TLV. 1715 The first message from the server is the one that starts Phase One, 1716 therefore the Server MUST set the headers' 'S' bit to '1' (Start) and 1717 the headers' 'Phase' value to '1' (Phase One). 1719 The Server uses one or more ('Version') TLVs in the EAP-Request/EAP- 1720 CREDS(Type=Init) message to provide the Peer with the list of EAP- 1721 CREDS versions supported. If omitted, the implict version of EAP- 1722 CREDS used in the session is one ('0x1'). If the Server detects 1723 multiple occurrences of this TLV in the reply from the Peer, an error 1724 shall be issued and the EAP-CREDS session should be terminated. 1726 In case Token-Based registration is enabled on the Server, the Server 1727 MUST include, in its Init message, a ('Challenge-Data') field that 1728 can be used by the client to provide challenge data for proof-of- 1729 possession of secrets. 1731 5.1.2. EAP Peer's Init Message 1733 The Peer MUST reply to the Server's ('EAP-CREDS-Init') message with 1734 its own ('EAP-CREDS-Init') one. The Peer SHOULD include one 1735 ('Version') TLV in its first message to indicate the version of EAP- 1736 CREDS that the client wants to use for the session. The Peer MUST 1737 also provide the list of supported provisioning protocols (via one or 1738 more the 'Protocol' TLV), the list and status of the installed 1739 credentials (via the 'Credentials-Info' TLV). The Peer MAY include 1740 authorization data when registering new credentials (e.g., an 1741 authorization token or a device certifcate) via the ('Token-Data') 1742 and ('Challenge-Response') TLV. 1744 The Peer MUST include one ('Credentials-Info') TLV for each 1745 credential the Network is authorized to manage. Typically, a Peer 1746 will include only one ('Credentials-Info') TLV in its ('EAP-CREDS- 1747 Init') message, but there might be cases where multiple types of 1748 credentials are available and selected depending on the location and 1749 other factors (e.g., X.509 certificate and username/password 1750 combination). 1752 In case the Peer does not have any credentials available yet, it does 1753 not add any ('Credentials-Info') TLV - leaving the Server with the 1754 only action possible: Registration. In this case, the Peer SHOULD 1755 include authorization information via the ('Token-Data') TLV as 1756 described in Section 5.1.2.1. Additionally, the Peer can add the 1757 ('Profile') TLV to indicate a preferred profile for the credentials. 1759 5.1.2.1. Bootstrapping Peer's Trustworthiness 1761 When the Peer does not have any valid credentials for the Network 1762 that it is authenticating to, it does not provide any ('Credentials- 1763 Info') TLV. This indicates to the Server that new credentials MUST 1764 be registered before the Peer is allowed on the network. 1766 The Registration process might rely on information exchanged during 1767 the Provisioning Process in Phase Two. However, if an authorization 1768 mechanism is not available from the supported provisioning protocol 1769 and no credentials are available on the Peer, EAP-CREDS provides a 1770 simple machanism for the Peer to leverage an out-of-band 1771 token/passphrase/ott that may be already available on the Peer (e.g., 1772 a device certificate or a 'spendable' credentials token like a 1773 kerberos ticket or a crypto-currency transaction) and that can be 1774 verified by the Server. 1776 In particular, when the Peer wants to register new credentials (and 1777 the Server requires the use of additional authorization data) it may 1778 need to provide (a) a Token, (b) a challenge value, and (c) a 1779 response to the challenge value. To do so, the Peer MUST encode the 1780 token in a ('Token-Data') TLV, the challenge value in a ('Challenge- 1781 Data') TLV, and, finally, the response to the challenge in the 1782 ('Challenge-Response') TLV. 1784 The use of ('Challenge-Data') and ('Challenge-Response') TLVs is 1785 optional, however it is suggested that if a token is used for 1786 bootstrapping the trust, it should provide a way to verify a secret 1787 associated with it. 1789 It is also very important that the authorization token is disclosed 1790 only to authorized servers - the Peer MUST NOT disclose authorization 1791 tokens that are not meant for the network that is being accessed. 1792 This can be done, usually, by verifying the identity of the Server 1793 first (in the outer mechanism) and then verify that the target of the 1794 Token is the Server the Client is talking to. 1796 5.1.3. The EAP-CREDS-Provisioning Message 1798 The EAP-CREDS-Provisioning message type is used in Phase Two only of 1799 EAP-CREDS. The message flow is depicted in Section 3.4. This 1800 message type supports the following TLVs: Protocol, Profile, 1801 Credentials-Info, Provisioning-Headers, Provisioning-Data, Token- 1802 Data, and Error. 1804 After the exchange of phase one messages, the Server MAY start phase 1805 two by issuing an ('EAP-CREDS-Provisioning') message for the Peer 1806 where it encodes all the required details for starting the 1807 provisioning process. In particular, the server sends the selected 1808 ('Action'), ('Protocol'), and metadata to the client in a EAP- 1809 Request/EAP-CREDS(Type=Provisioning) message. The header's 'S' bit 1810 MUST be set to '1' (Start) and the 'Phase' value set to '2' (Phase 1811 Two begins). 1813 NOTE WELL: After the initial message, the only TLVs that are 1814 allowed in messages coming from the server are the usual 1815 ('Provisioning-Headers') ('Provisioning-Data'), and ('Error'). 1817 The client checks that all the selected parameters are supported for 1818 the selected credentials and, if no errors are detected, it sends its 1819 first ('EAP-CREDS-Provisioning') message to the Server with the 1820 ('Provisioning-Headers') and ('Provisioning-Data') TLVs only. 1822 From now on, the conversation between the Peer and the Server 1823 continues until an error is detected or the provisioning protocol 1824 completes successfully. 1826 If no other actions, the server MAY continue with phase three or 1827 issue a success message and terminate the EAP session. 1829 NOTE WELL: When the SPP protocol is used, the protocol messages 1830 that are encoded inside the ('Protocol-Data') TLV are composed of 1831 sets of TLVs as defined in this document. The overall message 1832 size is provided by the size of the ('Protocol-Data') TLV that 1833 encapsulates the SPP-specific TLVs. This design choice provides 1834 symmetry in implementing support for SPP when compared to other 1835 provisioning protocols. 1837 5.1.4. The EAP-CREDS-Validate Message 1839 The EAP-CREDS-Validate message type is used in Phase Three only of 1840 EAP-CREDS. The message flow is depicted in Section 3.5. This 1841 message type supports the following TLVs: Protocol, Credentials-Info, 1842 Provisioning-Headers, Provisioning-Data, Token-Data, and Error. 1844 After Phase One (and/or Phase Two) ends, the Server MAY start phase 1845 three by issuing an ('EAP-CREDS-Validate') message for the Peer where 1846 it encodes all the required details for starting the validation 1847 process. In particular, the server sends the ('Credentials-Info'), a 1848 ('Challenge'), and the ('Phase-Control') TLVs in a EAP-Request/EAP- 1849 CREDS(Type=Validate) message. The ('Phase-Control') TLV should carry 1850 the '1' value for the 'S' bit (Start) and the number '3' for its 1851 value (Phase Three begins). 1853 The Peer generates the answer to the Challenge and sends back a EAP- 1854 Response/EAP-CREDS(Type=Validate) message with the ('Challenge- 1855 Response') and an optional ('Challenge') field (only for server-side 1856 validation of the symmetric credentials). If the Peer requested 1857 server-side validation of the credentials, the Server MUST include 1858 (if a symmetric secret) the response to the Peer-issued ('Challenge') 1859 TLV by computing the response and adding it to the ('Challenge- 1860 Response') TLV in its reply. 1862 Finally, in the last message, the Server (if Phase Three is to be 1863 ended) SHALL include the ('Phase-Control') TLV with the 'S' bit set 1864 to '0' (end of phase) and the value set to '3' (Phase Three ended). 1866 At this point, EAP-CREDS has terminated all possible operations and 1867 can be terminated. The Server can now terminate the EAP session 1868 successfully. In case the Peer was not authenticated during the 1869 tunnel establishment (i.e., no credentials were already available on 1870 the Peer), the Server should terminate the EAP session with a Failure 1871 (thus requiring the device to re-attach and authenticate to the 1872 network - phase two should have provided the Peer with the 1873 credentials to use for authenticating to the Network). 1875 6. Error Handling in EAP-CREDS 1877 This section provides a description of the error handling by using 1878 the CREDS-Error-TLV in a CREDS message. 1880 7. The Simple Provisioning Protocol (SPP) 1882 EAP-CREDS supports a Simple Provisioning Protocol (SPP) which 1883 comprises of a series of messages that enable the management not only 1884 of certificates, but also of other types of credentials like 1885 username/password pairs, asymmetric keys, and symmetric keys. 1887 The Simple Provisioning Protocol (SPP), described in this section, 1888 behaves as any other provisioning protocol: its messages are 1889 encapsulated in the ('Provisioning-Data') TLVs in the second phase of 1890 the protocol. SPP does not make use of any ('Provisioning-Headers') 1891 TLVs because its messages are all self-contained (no transport- 1892 protocol specific options are needed). 1894 When no ('Credentials-Info') TLVs have been provided by the client, 1895 the Server knows that the device does not have valid credentials it 1896 wants to use to access the Network. In this case, EAP-CREDS/SPP 1897 supports the use of Tokens to kick-off the registration process. The 1898 type, format, or encoding of the Token is orthogonal to EAP-CREDS/SPP 1899 which treats the token as a black-box field (i.e., it SHOULD NOT try 1900 to interpret or parse its contents). 1902 NOTE WELL: During Phase One, the Peer MAY include the ('Token- 1903 Data') TLV in its EAP-CREDS-Init message to provide the needed 1904 authorization to register a new set of credentials. The Server 1905 might not allow the registration of new credentials if the 1906 required authorization (i.e., the Token) was not provided during 1907 the initialization phase. 1909 In the case where an authorization token is used, different usage 1910 patterns are supported. For tokens that require an associated 1911 verifiable proof-of-possession, the Peer can include a ('Challenge- 1912 Response') TLVs. 1914 The ('Challenge-Data') TLV provided by the Server MUST be used to 1915 convey the challenge data (usually some random value) to compute the 1916 contents of the ('Challenge-Response') TLV. 1918 The ('Challenge-Response') TLV is used, instead, to encode the 1919 response to the challenge data. The ('Challenge-Response') TLV is 1920 generated by the Peer and verified by the Server. At minimum, the 1921 ('Challenge-Response') TLV SHOULD be calculated over the values of 1922 the ('Token-Data') and the ('Challenge-Data') TLVs to make sure that 1923 the authentication covers the token's data as well. 1925 NOTE WELL: The use of the ('Token-Data'), ('Challenge-Data'), and 1926 ('Challenge-Response') TLVs in the Peer's Init message is be used 1927 only to bootstrap trust between the Server and the Peer. If the 1928 Server accepts the authorization information as valid, the Peer is 1929 enabled for registering new credentials. This should happen only 1930 when the Peer does not have valid credentials or when the server 1931 wants to provision a different type of credentials (i.e., 1932 Action=(Register)). Other methods to provide authorization 1933 information might be provided by the selected provisioning 1934 protocol: in this case, the Server MAY enable registration of new 1935 credentials when no authorization data is provided in the 'Init' 1936 message from the client and delegate the validation of the 1937 authorization data during Phase Two. 1939 7.1. SPP Message Format 1941 The SPP Messages are constructed with zero, one, or more TLVs and 1942 encoded in the ('Provisioning-Data') TLV in EAP-CREDS/Provisioning 1943 message types. The size of the encpasulating ('Provisioning-Data') 1944 TLV provides the size of the whole message. 1946 7.2. SPP Message Flow 1948 ,--------. ,----------. 1949 |EAP Peer| |EAP Server| 1950 `---+----' `----+-----' 1951 | [1] EAP-Request/EAP-CREDS(Type=Provisioning) | 1952 | { Protocol(=SPP), Action, | 1953 | [ CredsInfo ] [ Params ], | 1954 | [ ProvData(=CredsData) ] } | 1955 | <------------------------------------------ 1956 | | 1957 | [2] EAP-Response/EAP-CREDS(Type=Provisioning)| 1958 | { [ ProvData(=CredsData) ] } | 1959 | ------------------------------------------> 1960 | | 1961 | [3] EAP-Response/EAP-CREDS(Type=Provisioning)| 1962 | { [ ProvData(=CredsData) ] } | 1963 | <------------------------------------------ 1964 | | 1965 | | 1967 SPP was designed to provide an easy alternative to more complex 1968 provisioning protocols. When no extra flexibility is needed, SPP 1969 provides an easy-to-implement alternative that can handle not only 1970 certificates, but also symmetric secrets and access tokens 1971 provisioning. In this section we provide the generic flow of 1972 messages for SPP and specific examples for certificates, username/ 1973 password, and token provisioning. 1975 EAP-CREDS defines several actions for a set of credentials and they 1976 are listed in Section 8.9. 1978 When a Peer wants to join a network it may or may not have have the 1979 needed credentials to do so. In case the Peer does not have valid 1980 credentials yet, the Server MAY start Phase Two with the intention of 1981 registering a new set of credentials. Alternatively, the Server MAY 1982 start Phase Two when the presented credentials information from the 1983 Peer triggers the Renew or the Remove action. 1985 [1] The Server sends EAP-Request/EAP-CREDS(Type=Provisioning) 1987 When registering new credentials, the first message from the 1988 Server, MUST not carry a ('Credentials-Info') TLV since there is 1989 no targeted credentials to apply the action on (i.e., for other 1990 actions - like 'renew' or 'remove' - the TLV would be required to 1991 identify the right set of credentials to renew or delete). 1993 In SPP, the Server sets the ('Protocol') TLV to SPP, the 1994 ('Action') TLV to 'Register', 'Renew', or 'Remove'. When 1995 provisioning (or registering) new credentials for the Peer, the 1996 Server also sets the ('Provisioning-Params') TLV (or Params) to 1997 the type of credentials to be provisioned. The Server also sets 1998 any relevant constraints, and, optionally, the ('Profile') TLV. 2000 NOTE WELL: If the Peer is authorized to register a new set of 2001 credentials, then the first message from the Server will have 2002 the ('Action') TLV set to 'register' and no ('Credentials- 2003 Info') TLV is present in the Server's message. In case server- 2004 side generation is used, an additional ('Credentials-Info') TLV 2005 MAY be encoded inside the ('Provisioning-Data') TLV. 2007 If the type of credentials is symmetric and the parameters call 2008 for server-side generation of a symmetric key share, the Server 2009 MUST also include its own generated share in a ('Credentials- 2010 Data') TLV inside the ('Provisioning-Data') one (the data for the 2011 provisioning protocol are encapsulated in the 'Provisioning-Data' 2012 TLV for any protocol used during Phase Two - SPP is no exception 2013 to this rule). 2015 In case Server-side only is selected, the Server MUST send the new 2016 credentials in its message and include the ('Credentials-Info') 2017 TLV. If no other credentials need to be managed, the Server MUST 2018 end Phase Two by setting the appropriate bits in the EAP-CREDS 2019 headers as well. 2021 [2] The Peer sends EAP-Response/EAP-CREDS(Type=Provisioning) 2023 When Peer-generation is selected (either Peer-only or combined 2024 Peer and Server side) and Phase Two has not terminated yet, the 2025 Peer MUST reply to the Server's message with its own 2026 'Provisioning' response. The response MUST carry either (a) its 2027 own generated share of the key in a ('Credentials-Data') TLV (if 2028 the credentials that are provisioned are symmetric and the 2029 configuration calls for a share of the key to be provided by the 2030 Peer) or (b) a PKCS#10 request in a ('Certificate-Request') TLV 2031 (also in this case, only if client-side generation was enabled by 2032 the Server) that is generated by using the parameters provided by 2033 the Server in the ('Provisioning-Params') TLV. 2035 [3] The Server sends EAP-Request/EAP-CREDS(Type=Provisioning) 2037 The last message of SPP is from the Server and it is used to 2038 deliver the finalized value of the credentials and/or associated 2039 metadata. In case the credentials being provisioned are 2040 Certificate-based, the Server MUST include the issued certificate 2041 in its reply. The issued credentials shall be encoded in a 2042 ('Credentials-Data') TLV inside the ('Provisioning-Data') one. In 2043 case that the selected format supported/selected by the Peer and 2044 the Server does not provide the possibility to encode the full 2045 chain (i.e., intermediate and Root CAs) in the response, the 2046 Server MUST add one ('Certificate-Data') TLV for each certificate 2047 in the chain (including the Root CA's certificate). 2049 The Server MUST include the ('Credentials-Info') TLV in its 2050 message. This provide the Peer with some additional data (e.g., 2051 the 'Profile' or the 'Identifier' associated with the credentials 2052 that were provisioned/managed). 2054 In the case where additional credentials need to be managed, the 2055 Server can continue Phase Two by issuing a new [1] message where 2056 the tuple Action/Credentials must be unique for the current EAP- 2057 CREDS session. 2059 The Server can now decide to start Phase Three (suggested if new 2060 credentials were provisioned or renewed) or to terminate the EAP 2061 session successfully. 2063 7.2.1. SPP Symmetric Secrets Management 2065 ,--------. ,----------. 2066 |EAP Peer| |EAP Server| 2067 `---+----' `----+-----' 2068 | [1] EAP-Request/EAP-CREDS(Type=Provisioning) | 2069 | { Protocol(=SPP), Action, [ Creds-Info ], | 2070 | [ Prov-Params ], [ Profile ] | 2071 | [ Prov-Data(=[Creds-Info],[Creds-Data]) ] }| 2072 | <----------------------------------------------- 2073 | | 2074 | [2] EAP-Response/EAP-CREDS(Type=Provisioning) | 2075 | { [ Prov-Data(=[Creds-Data]) ] } | 2076 | -----------------------------------------------> 2077 | | 2078 | [3] EAP-Response/EAP-CREDS(Type=Provisioning) | 2079 | { [ Prov-Data(=Creds-Info,[Creds-Data]) ] } | 2080 | <----------------------------------------------- 2081 | | 2082 | | 2084 EAP-CREDS/SPP can provision symmetric secrets (e.g, username/ 2085 password, API keys, or SIM-based keys), tokens (e.g., username/ 2086 password OAuth or Kerberos tokens), or asymmetric credentials (e.g., 2087 X.509 certificates or Key Pairs). This section focuses on 2088 provisioning symmetric secrets only. The message flow is provided in 2089 Section 7.2.1 2091 EAP-CREDS/SPP provides the possibility for shared secret to be 2092 generated in different ways: 2094 1. Server-Side Generated 2096 2. Client-Side Generated 2098 3. Both Client-Side and Server-Side Generated 2100 In particular, when initiating the second phase of the protocol, the 2101 ('Provisioning-Params') TLV is used to specify how to generate the 2102 secret (see Section 4.3.13). 2104 7.2.1.1. Server Side Only Generation 2106 [ TO BE EDITED ] 2108 Figure 1: SPP Message Flow for Server-Side only secrets provisioning 2110 The message flow for deploying a server-side only credential (i.e., 2111 during registration or renewal) consists of only one message from the 2112 server. The flow is depicted in Figure 1. 2114 In this case, the Server sends the first Provisioning message (which 2115 is also the last one), which MUST carry, the following data: 2117 o The ('Credentials-Info') TLV that specifies the info for the 2118 provisioned secret, and 2120 o The ('Protocol') TLV that specifies the provisioning protocol to 2121 be used, and 2123 o The ('Action') TLV that provides the action to be performed 2124 ('Registration') or ('Renew'), and 2126 o The ('Provisioning-Params') TLV that provides the generation 2127 parameters to the Peer, and 2129 The Server also includes, encoded in the ('Provisioning-Data') TLV, 2130 the following data: 2132 The ('Credentials-Info') TLV that provides the metadata associated 2133 with teh generated secret 2135 The ('Credentials-Data') TLV that provides the secret that is 2136 provisioned to the Peer 2138 Server-side secrets' generation can be used to generate username/ 2139 password combinations, API Keys, SIM-based credentials, or tokens. 2141 7.2.1.2. Client Side Only Generation 2143 [ TO BE EDITED ] 2145 Figure 2: SPP Message Flow for Client-Side only secrets provisioning 2147 The message flow for deploying a client-side only credential (i.e., 2148 during registration or renewal) consists of the full three messages 2149 exchange. The flow is depicted in Figure 2. 2151 In this case, the Server MUST include, in its first Provisioning 2152 message and encoded in the ('Provisioning-Data') TLV, the following 2153 data: 2155 o The ('Credentials-Info') TLV that specifies the target 2156 credentials, and 2158 o The ('Protocol') TLV that specifies the provisioning protocol to 2159 be used, and 2161 o The ('Action') TLV that provides the action to be performed 2162 ('Registration') or ('Renew'), and 2164 o The ('Provisioning-Params') TLV that provides the generation 2165 parameters to the Peer, and 2167 Notice that the Server does not include any ('Credentials-Data') TLV 2168 in its first message because the Server is not involved in the secret 2169 generation (client-side only). 2171 The Peer MUST reply with its own Provisioning message where the Peer 2172 MUST encode the following data in the ('Provisioning-Data') TLV: 2174 The ('Credentials-Data') TLV that provides the secret that is 2175 being registered 2177 The credentials data MUST conform to the specifications the Server 2178 provided in the ('Provisioning-Params') TLV. 2180 The final message is from the Server and it MUST contain (if no 2181 errors were detected), the following TLVs encoded, as usual, in the 2182 ('Provisioning-Data') TLV: 2184 The ('Credentials-Info') TLV that specifies the metadata 2185 associated with the generated secret, and 2187 The ('Credentials-Data') TLV that provides the secret that is 2188 provisioned to the Peer 2190 Client-side secrets' generation should be used with caution and an 2191 evaluation of the quality of the generated credentials MUST be 2192 performed to make sure that the security of the generated secret is 2193 adequate for accessing the network. Since evaluating the quality of 2194 a secret is quite a difficult tasks, the use of this generation mode 2195 MUST be evaluated carefully and selected accordingly to acceptable 2196 risk profiles. 2198 7.2.1.3. Client and Server Side Generation 2200 When registering or renewing credentials and the secret generation is 2201 split between the Server (1st share) and the Peer (2nd share), the 2202 message flow is the same as Section 7.2.1.2 with the following 2203 exceptions: 2205 o The Server MUST send its own share of the secret by including a 2206 ('Credentials-Data') TLV in its first message. 2208 All other parameters remain the same. 2210 Co-generation of the secret is the most secure option because both 2211 parties can provide the required randomness in their own share of the 2212 secret. 2214 7.2.2. SPP Key Pair Provisioning 2216 EAP-CREDS/SSP defines the following flow of messages for requesting 2217 the provisioning of key pairs (public and private keys). 2219 7.2.2.1. Server Side Only Generation 2221 [ This case covers the server-side generation of KeyPair and 2222 Certificate ] 2224 7.2.2.2. Client Side Only Generation 2226 [ This case covers the registration of a self-signed or already 2227 available (e.g., device) certificate ] 2229 7.2.2.3. Client and Server Side Generation 2231 This use-case is not supported. In other words, for the provisioning 2232 of Key Pairs, the ('Provisioning-Params') can not have both the peer- 2233 generation and server-generation bits set. 2235 7.2.3. SPP Certificate Provisioning 2237 EAP-CREDS/SSP defines the following flow of messages for requesting 2238 the provisioning of credentials. 2240 7.2.3.1. Server Side Only Generation 2242 [ This case covers the server-side generation of KeyPair and 2243 Certificate ] 2245 7.2.3.2. Client Side Only Generation 2247 [ This case covers the registration of a self-signed or already 2248 available (e.g., device) certificate ] 2250 7.2.3.3. Client and Server Side Generation 2252 [ This case covers the generation of the KeyPair on the Peer and the 2253 generation of the certificate on the Server ] 2255 7.2.4. SPP Token Provisioning 2257 EAP-CREDS/SSP defines the following flow of messages for requesting 2258 the provisioning of token-based credentials. 2260 7.2.4.1. Server Side Only Generation 2262 [ This case covers the server-side generation of the Token and 2263 possibly associated key ] 2265 7.2.4.2. Client Side Only Generation 2267 [ This case covers the registration of a self-signed or already 2268 available (e.g., device) certificate ] 2270 7.2.4.3. Client and Server Side Generation 2272 [ This case covers the generation of the KeyPair on the Peer and the 2273 generation of the Token that cointains the reference to the key on 2274 the Server ] 2276 8. IANA Considerations 2278 This document uses a new EAP type, EAP-CREDS, whose value (TBD) MUST 2279 be allocated by IANA from the EAP TYPEs subregistry of the RADIUS 2280 registry. This section provides guidance to the Internet Assigned 2281 Numbers Authority (IANA) regarding registration of values related to 2282 the EAP-CREDS protocol, in accordance with [RFC8126]. 2284 The EAP Method Type number for EAP-CREDS needs to be assigned. 2286 This document also requires IANA to create new registries as defined 2287 in the following subsections. 2289 8.1. Provisioning Protocols 2291 +-----------------+-------------------------------------------------+ 2292 | Message Type | Purpose | 2293 +-----------------+-------------------------------------------------+ 2294 | 0 | Unspecified | 2295 | 1 | Simple Provisioning Protocol (SPP) | 2296 | 2 | Basic Certificate Management Protocol (CMP-S) | 2297 | 3 | Full Certificate Management Protocol (CMP-F) | 2298 | 4 | Enrollment over Secure Transport (EST) | 2299 | 5 | Certificate Management over CMS (CMC) | 2300 | 6 | Automatic Certificate Management Environment | 2301 | | (ACME) | 2302 | ... | ... | 2303 | 49141 ... 65534 | Vendor Specific | 2304 +-----------------+-------------------------------------------------+ 2306 Table 5: EAP-CREDS Inner Protocol Identifiers 2308 Assignment of new values for new cryptosuites MUST be done through 2309 IANA with "Specification Required" and "IESG Approval" as defined in 2310 [RFC8126]. 2312 8.2. Token Types 2314 +------------+-----------------+ 2315 | Token Type | Description | 2316 +------------+-----------------+ 2317 | 0 | Unspecified | 2318 | 1 | JWT | 2319 | 2 | Kerberos | 2320 | 3 | OAuth | 2321 | 4 | Certificate | 2322 | 200..254 | Vendor Specific | 2323 +------------+-----------------+ 2325 Table 6: Token Types 2327 Assignment of new values for new Message Types MUST be done through 2328 IANA with "Expert Review" as defined in [RFC8126]. 2330 8.3. Credentials Types 2331 +------------------+-----------------------+ 2332 | Credentials Type | Description | 2333 +------------------+-----------------------+ 2334 | 0 | X.509 Certificate | 2335 | 1 | Public Key | 2336 | 2 | Symmetric Key | 2337 | 3 | Username and Password | 2338 | 4 | AKA Subscriber Key | 2339 | 5 | Bearer Token | 2340 | 6 | One-Time Token | 2341 | 7 | API Key | 2342 +------------------+-----------------------+ 2344 Table 7: Credentials Types 2346 Assignment of new values for new Message Types MUST be done through 2347 IANA with "Expert Review" as defined in [RFC8126]. 2349 8.4. Credentials Algorithms 2351 +---------+--------------------+ 2352 | ID | Algorithm | 2353 +---------+--------------------+ 2354 | 0 | None | 2355 | 1 | RSA | 2356 | 2 | ECDSA | 2357 | 3 | XMMS | 2358 | 4 | AKA Subscriber Key | 2359 | 5 | OAuth | 2360 | 6 | Kerberos4 | 2361 | 7 | Kerberos5 | 2362 | 200-254 | Reserved | 2363 +---------+--------------------+ 2365 Table 8: Credentials Algorithms 2367 Assignment of new values for new Message Types MUST be done through 2368 IANA with "Expert Review" as defined in [RFC8126]. 2370 8.5. Credentials Datatypes 2371 +---------+---------------+ 2372 | ID | Data Type | 2373 +---------+---------------+ 2374 | 0 | None (Binary) | 2375 | 1 | PKCS#8 | 2376 | 2 | PKCS#10 | 2377 | 3 | PKCS#12 | 2378 | 4 | PublicKeyInfo | 2379 | 200-254 | Reserved | 2380 +---------+---------------+ 2382 Table 9: Credentials Datatypes 2384 Assignment of new values for new Message Types MUST be done through 2385 IANA with "Expert Review" as defined in [RFC8126]. 2387 8.6. Challenge Types 2389 +----+----------------------+ 2390 | ID | Data Type | 2391 +----+----------------------+ 2392 | 0 | Not Specified | 2393 | 1 | EAP-CREDS-ASYMMETRIC | 2394 | 2 | EAP-CREDS-SYMMETRIC | 2395 +----+----------------------+ 2397 Table 10: Challenge Type 2399 Assignment of new values for new Message Types MUST be done through 2400 IANA with "Expert Review" as defined in [RFC8126]. 2402 8.7. Network Usage Datatypes 2404 +--------+------------------------------------------+ 2405 | ID | Data Type | 2406 +--------+------------------------------------------+ 2407 | 0 | Vendor-Specific | 2408 | 1 | Manufacturer Usage Description [RFC8520] | 2409 | 2 | Network Access Granting System | 2410 | 3 | Firmware Manifest | 2411 | 4..127 | Reserved for Future Use | 2412 +--------+------------------------------------------+ 2414 Table 11: Network Usage Datatypes 2416 Assignment of new values for new Message Types MUST be done through 2417 IANA with "Expert Review" as defined in [RFC8126]. 2419 8.8. Credentials Encoding 2421 +---------+------------+ 2422 | ID | Encoding | 2423 +---------+------------+ 2424 | 0 | None (Raw) | 2425 | 1 | DER | 2426 | 2 | PEM | 2427 | 3 | Base64 | 2428 | 4 | JSON | 2429 | 5 | XML | 2430 | 6 | ASCII | 2431 | 7 | UTF-8 | 2432 | 200-254 | Reserved | 2433 +---------+------------+ 2435 Table 12: Credentials Encoding 2437 Assignment of new values for new Message Types MUST be done through 2438 IANA with "Expert Review" as defined in [RFC8126]. 2440 8.9. Action Types 2442 +---------+--------------+--------------------------------+ 2443 | ID | Data Type | Description | 2444 +---------+--------------+--------------------------------+ 2445 | 0 | Registration | Registers New Credentials | 2446 | 1 | Renewal | Renew an Existing Credential | 2447 | 2 | Remove | Removes an Existing Credential | 2448 | 200-254 | n/a | Reserved | 2449 +---------+--------------+--------------------------------+ 2451 Table 13: Action Types 2453 Assignment of new values for new Message Types MUST be done through 2454 IANA with "Expert Review" as defined in [RFC8126]. 2456 8.10. Usage Metadata Types 2458 +------+----------------------+ 2459 | Type | Description | 2460 +------+----------------------+ 2461 | 0 | Binary (Unspecified) | 2462 | 1 | MUD File | 2463 | 2 | TEEP Manifest | 2464 +------+----------------------+ 2466 Table 14: Usage Metadata Types 2468 Assignment of new values for new Message Types MUST be done through 2469 IANA with "Expert Review" as defined in [RFC8126]. 2471 9. Security Considerations 2473 Several security considerations need to be explicitly considered for 2474 the system administrators and application developers to understand 2475 the weaknesses of the overall architecture. 2477 The most important security consideration when deploying EAP-CREDS is 2478 related to the security of the outer channel. In particular, EAP- 2479 CREDS assumes that the communication channel has been properly 2480 authenticated and that the information exchanged between the Peer and 2481 the Server are protected (i.e., confidentiality and integrity). 2483 For example, if certificate-based authentication is used, the server 2484 presents a certificate to the peer as part of the trust establishment 2485 (or negotiation). The peer SHOULD verify the validity of the EAP 2486 server certificate and SHOULD also examine the EAP server name 2487 presented in the certificate in order to determine whether the EAP 2488 server can be trusted. When performing server certificate 2489 validation, implementations MUST provide support for the rules in 2490 [RFC5280] for validating certificates against a known trust anchor. 2492 10. Acknowledgments 2494 The authors would like to thank everybody who provided insightful 2495 comments and helped in the definition of the deployment 2496 considerations. 2498 11. Normative References 2500 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2501 Requirement Levels", BCP 14, RFC 2119, 2502 DOI 10.17487/RFC2119, March 1997, 2503 . 2505 [RFC3748] Aboba, B., Blunk, L., Vollbrecht, J., Carlson, J., and H. 2506 Levkowetz, Ed., "Extensible Authentication Protocol 2507 (EAP)", RFC 3748, DOI 10.17487/RFC3748, June 2004, 2508 . 2510 [RFC4210] Adams, C., Farrell, S., Kause, T., and T. Mononen, 2511 "Internet X.509 Public Key Infrastructure Certificate 2512 Management Protocol (CMP)", RFC 4210, 2513 DOI 10.17487/RFC4210, September 2005, 2514 . 2516 [RFC5272] Schaad, J. and M. Myers, "Certificate Management over CMS 2517 (CMC)", RFC 5272, DOI 10.17487/RFC5272, June 2008, 2518 . 2520 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 2521 Housley, R., and W. Polk, "Internet X.509 Public Key 2522 Infrastructure Certificate and Certificate Revocation List 2523 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 2524 . 2526 [RFC6402] Schaad, J., "Certificate Management over CMS (CMC) 2527 Updates", RFC 6402, DOI 10.17487/RFC6402, November 2011, 2528 . 2530 [RFC7030] Pritikin, M., Ed., Yee, P., Ed., and D. Harkins, Ed., 2531 "Enrollment over Secure Transport", RFC 7030, 2532 DOI 10.17487/RFC7030, October 2013, 2533 . 2535 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 2536 Writing an IANA Considerations Section in RFCs", BCP 26, 2537 RFC 8126, DOI 10.17487/RFC8126, June 2017, 2538 . 2540 [RFC8520] Lear, E., Droms, R., and D. Romascanu, "Manufacturer Usage 2541 Description Specification", RFC 8520, 2542 DOI 10.17487/RFC8520, March 2019, 2543 . 2545 Author's Address 2547 Massimiliano Pala 2548 CableLabs 2549 858 Coal Creek Cir 2550 Louisville, CO 80027 2551 US 2553 Email: m.pala@openca.org 2554 URI: http://www.linkedin.com/in/mpala