idnits 2.17.1 draft-cuellar-ace-pat-priv-enhanced-authz-tokens-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (January 2, 2018) is 2306 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFC6749' is mentioned on line 456, but not defined == Missing Reference: 'Resource-REQ' is mentioned on line 259, but not defined == Missing Reference: 'RFC7049' is mentioned on line 381, but not defined ** Obsolete undefined reference: RFC 7049 (Obsoleted by RFC 8949) == Unused Reference: 'RFC6347' is defined on line 987, but no explicit reference was found in the text == Unused Reference: 'I-D.ietf-cose-msg' is defined on line 1008, but no explicit reference was found in the text == Unused Reference: 'I-D.ietf-ace-cbor-web-token' is defined on line 1036, but no explicit reference was found in the text ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) ** Obsolete normative reference: RFC 7539 (Obsoleted by RFC 8439) -- No information found for draft-ietf-ace-actors-0 - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-ace-actors' ** Downref: Normative reference to an Informational draft: draft-ietf-oauth-pop-architecture (ref. 'I-D.ietf-oauth-pop-architecture') == Outdated reference: A later version (-46) exists of draft-ietf-ace-oauth-authz-06 == Outdated reference: A later version (-15) exists of draft-ietf-ace-cbor-web-token-05 Summary: 4 errors (**), 0 flaws (~~), 9 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ACE Working Group J. Cuellar 3 Internet-Draft P. Kasinathan 4 Intended status: Standards Track Siemens AG 5 Expires: July 6, 2018 D. Calvo 6 Atos Research and Innovation 7 January 2, 2018 9 Privacy-Enhanced-Tokens (PAT) profile for ACE 10 draft-cuellar-ace-pat-priv-enhanced-authz-tokens-06 12 Abstract 14 This specification defines PAT, "Privacy-Enhanced-Authorization- 15 Tokens", an efficient protocol and an unlinkable-token construction 16 procedure for client authorization in a constrained environment. 17 This memo also specifies a profile for ACE framework for 18 Authentication and Authorization. The PAT draft uses symmetric 19 cryptography, proof-of-possession (PoP) for a key owned by the client 20 that is bound to an OAuth 2.0 access-token. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on July 6, 2018. 39 Copyright Notice 41 Copyright (c) 2018 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 57 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 58 3. PAT Overview and Features . . . . . . . . . . . . . . . . . . 4 59 4. PAT Protocol . . . . . . . . . . . . . . . . . . . . . . . . 6 60 4.1. RS<->AS: Security-association-Setup . . . . . . . . . . . 7 61 4.2. [C->RS : Resource-Request] . . . . . . . . . . . . . . . 7 62 4.3. [RS->C : Un-Authorized-Request(AS-Info)] . . . . . . . . 7 63 4.4. C<->AS : Security-Association-Setup . . . . . . . . . . . 9 64 4.5. C->AS : Access-Request . . . . . . . . . . . . . . . . . 9 65 4.6. C<-AS : Access-Response . . . . . . . . . . . . . . . . . 11 66 4.6.1. Access-Token construction: . . . . . . . . . . . . . 12 67 4.6.2. Verifier or PoP key construction: . . . . . . . . . . 13 68 4.7. C->RS : Resource-Request . . . . . . . . . . . . . . . . 14 69 4.8. RS->C : Resource-Response . . . . . . . . . . . . . . . . 17 70 4.8.1. RS Response-codes to C RES-REQ: . . . . . . . . . . . 19 71 4.9. Construction of Derived-Tokens (DT) . . . . . . . . . . . 19 72 4.9.1. C->RS: Resource-Request via DT . . . . . . . . . . . 19 73 4.9.2. RS->C : Resource-Response to DT . . . . . . . . . . . 21 74 5. Security Considerations . . . . . . . . . . . . . . . . . . . 21 75 5.1. Privacy Considerations . . . . . . . . . . . . . . . . . 22 76 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 77 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 22 78 7.1. Normative References . . . . . . . . . . . . . . . . . . 22 79 7.2. Informative References . . . . . . . . . . . . . . . . . 23 80 8. Acknowledgement . . . . . . . . . . . . . . . . . . . . . . . 23 81 8.1. Copyright Statement . . . . . . . . . . . . . . . . . . . 23 82 Appendix A. ACE profile Registration . . . . . . . . . . . . . . 23 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24 85 1. Introduction 87 Three well-known problems in constrained environments are the 88 authorization of clients to access resources on servers, the 89 realization of secure communication between nodes, and the 90 preservation of privacy. The reader is referred for instance to [I- 91 D.ietf-ace-actors], [I-D.ietf-ace-oauth-authz] and [KoMa2014]. This 92 memo describes a way of constructing Tokens from an initial secret 93 that can be used by clients and resource servers (or in some cases, 94 more generally by arbitrary nodes) to delegate client authentication 95 and authorization in a constrained environment to trusted and 96 unconstrained authorization servers. 98 This draft uses the architecture of [draft-ietf-ace-actors] and [I- 99 D.ietf-ace-oauth-authz], designed to help constrained nodes in 100 authorization-related tasks via less-constrained nodes. Terminology 101 for constrained nodes is described in [RFC7228]. A device (Client) 102 that wants to access a protected resource on a constrained node 103 (Resource Server) first has to gain permission in the form of a token 104 from the Authorization Server. This memo also specifies a profile of 105 the ACE framework [I-D.ietf-ace-oauth-authz]. 107 The main goal of the PAT is to present methods for constructing 108 authorization tokens efficiently with privacy features such as 109 unlinkability. The CoAP protocol [RFC7252] MAY be used as the 110 application layer protocol. The draft uses symmetric Proof-of- 111 Possession keys [I-D.ietf-oauth-pop-architecture], CBOR web tokens 112 (CWT) [draft-ietf-ace-cbor-web-token-05] claims to represent security 113 claims together with CBOR Object Signing and Encryption (COSE) [I- 114 D.ietf-cose-msg] and Concise Binary Object Representation (CBOR) [RFC 115 7049]. 117 2. Terminology 119 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 120 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 121 document are to be interpreted as described in [RFC2119]. 123 In this document, these words will appear with that interpretation 124 only when in ALL CAPS. Lower case uses of these words are not to be 125 interpreted as carrying [RFC2119] significance. 127 Terminology for entities in the architecture is defined in OAuth 2.0 128 [RFC6749] and [I-D.ietf-ace-actors], such as client (C), resource 129 server (RS), resource owner (RO), resources (R) and the authorization 130 server (AS). 132 o Access-Token (AT): the access token is a token prepared by the AS 133 for C. It represents the privileges granted by the RO to the C to 134 perform actions over the Resources (R) on an RS. 136 o Token (Tk): this token is prepared by the C, presented to the RS 137 to access the resources (R) on RS. The Tk contains all 138 information needed by the RS to verify that it was granted by AS. 139 The Client derives Tk from the AT. 141 In version-5 of PAT draft the token names -- AT and Tk -- and their 142 purposes were harmonized with [I-D.ietf-ace-oauth-authz]. 144 3. PAT Overview and Features 146 The PAT protocol is designed to work with ACE framework [I-D.ietf- 147 ace-oauth-authz] and ACE actors [I-D.ietf-ace-actors]. In this 148 specification we assume the following: 150 o A Resource Server (RS) has one or more resources (R) and it is 151 registered with an Authorization Server (AS) 153 o The Authorization Server (AS) provides access-tokens for the 154 clients to access resources of RS. The corresponding Resource 155 Owner (RO) of the RS MAY assign allowed-permissions for the 156 Clients in the AS. 158 o The RS is offline after commissioning, i.e., RS cannot make any 159 introspective queries to the AS to verify the authorization 160 information provided by the C. 162 o A Client (C) is either registered with an AS or it knows how to 163 reach the RS for accessing the required resources. 165 * To access a resource on a Resource Server (RS), a Client (C) 166 should request an access-token (AT) from AS, either directly or 167 using its Client Authorization Server (CAS). For the sake of 168 simplicity, this memo does not include the actor CAS. 170 Based on the above assumptions, a simple PAT message flow can be 171 described as follows: a C may perform a resource-request to RS 172 without a valid access-token, the RS will reject and it may provide 173 AS information to the C in the response. The C performs an Access- 174 Request to AS to ask for an AT that allows accessing the required 175 resource (R) on RS. The AS checks if C is allowed to access the 176 resource (R) on RS or not, based on permissions assigned by the RO. 177 If C has sufficient permissions, then AS generates an Access-Token 178 (AT) plus proof-of-possession (PoP) key bounded to the access-token 179 and a common secret (K) between AS and RS. AS sends both the AT and 180 the PoP key to C via a secure channel. How this secure channel is 181 created between AS and C is out of the scope of this draft. After 182 receiving AT and PoP key, C performs a resource-request to RS by 183 constructing token (Tk) from AT or by deriving Token. The RS can 184 construct its own version of the PoP key from the AT and verifies the 185 received AT. If it is valid, RS encrypts the response with the PoP 186 key. At the end of this phase, both C and RS has established a 187 common derived secret, the PoP key. Later, C can generate unlinkable 188 tokens (Tk) from the initial AT as described in Section 4.9. 190 In particular, PAT is designed to be used in contexts where 191 unlinkability (privacy) and efficiency are the main goals: the tokens 192 (Tk) convey only the assurance of the authorization claims of the 193 clients. In particular, the procedure described in Section 4.9 194 enables the Tokens (Tk) to be constructed in such a way that they do 195 not leak information about the correspondence of messages to the same 196 Client or from the same access-token (AT). For example, if an 197 eavesdropper observes the messages from different Clients to and from 198 the Resource Servers, the protocol does not give him information 199 about which messages correspond to the same Client. Of course, other 200 information like the IP-addresses or the contents themselves of the 201 requests/responses from lower-layer protocols may leak some 202 information, and this can be treated separately via other methods. 204 The main features of PAT protocol are described below: 206 o The PAT method allows a RO, or an Authorization Server (AS) on its 207 behalf, to authorize one or several clients (C) to access 208 resources (R) on a constrained Resource Server (RS). The C can 209 also be constrained devices. The Access-Token (AT) response from 210 AS to C MUST be performed via secure channels. 212 o The RO is able to decide (if he wishes: in a fine-grained way) 213 which client under which circumstances may access the resources 214 exposed by the RS. This can be used to provide consent (in terms 215 of privacy) from RO. 217 o The Access-Tokens (AT) are crafted in such a way that the client 218 can derive Tokens (Tk) that allow demonstrating to RS its 219 authorization claims. The message exchange between C and RS for 220 the presentation of the tokens MAY be performed via insecure 221 channels to enforce efficiency. But the payload content -- if the 222 Client is performing a POST/PUT/DELETE request -- from C to RS or 223 the response payload from RS to C MUST be encrypted. 225 o The RS can derive the PoP key from the AT, which is received 226 attached to the Resource Request message, and it encrypts the 227 response using it. 229 o The tokens (Tk) do not provide any information about any 230 associated identities such as identifiers of the clients, of 231 access-tokens (AT) and of the resource-server. 233 o The tokens (Tk) are supported by a "proof-of-possession" (PoP) key 234 and the initial access-token (AT). The PoP key allows an 235 authorized entity (a client) to prove to the verifier (here, the 236 RS), that C is indeed the intended authorized owner of the token 237 and not simply the bearer of the token. 239 To be coherent with ACE Authorization framework [I-D.ietf-ace-oauth- 240 authz], this draft also specifies an ACE profile to use PAT and for 241 efficient encoding it uses CWT and COSE. The PAT profile is signaled 242 when the C requests token from the AS or via RS in response to 243 unauthorized request response. The PAT profile will cover all the 244 requirements described in [I-D.ietf-ace-oauth-authz]. 246 4. PAT Protocol 248 The detailed description of PAT protocol is presented in this 249 Section 4. The PAT protocol includes three actors: the RS, the C, 250 and the AS. PAT message flow is shown in Figure 1. Messages in 251 [square brackets] mean they are optional. 253 ,-. ,--. ,--. 254 |C| |RS| |AS| 255 `+' `+-' `+-' 256 | | 1 Security-Association-Setup| 257 | | <---------------------------> 258 | | | 259 | 2 [Resource-REQ] | | 260 |------------------------> | 261 | | | 262 |3 [Un-Auth-REQ(AS-Info)]| | 263 |<------------------------ | 264 | | | 265 | 4 Security-Association-Setup | 266 |<-----------------------------------------------------> 267 | | | 268 | 5 Access-REQ | 269 |------------------------------------------------------> 270 | | | 271 | 6 Access-RSP | 272 |<------------------------------------------------------ 273 | | | 274 | 7 Resource-REQ | | 275 |------------------------> | 276 | | | 277 | 8 Resource-RSP | | 278 |<------------------------ | 279 ,+. ,+-. ,+-. 280 |C| |RS| |AS| 281 `-' `--' `--' 283 Figure 1: PAT protocol message flow 285 The following subsections describe the message flow in more detail, 286 especially how the messages and tokens with PoP are constructed. 288 A PAT message sent from actor A to actor B is represented using the 289 following notation: "A -> B : Message Name" 291 4.1. RS<->AS: Security-association-Setup 293 This memo assumes that the Resource Server (RS) and its 294 Authentication Server (AS) share a long term shared secret (K), i.e., 295 a shared key which MAY be implemented via USB (out of band methods) 296 when device commissioning -- out of scope --. The shared secret (K) 297 is used both by the AS and the RS to create proof-of-possession keys 298 (PoP keys or verifiers). 300 We can also assume that the CAS and AS share a secure connection if 301 CAS exist as an actor, e.g., DTLS. During the commissioning phase, 302 RS registers the cryptographic algorithms and the parameters it 303 supports. The internal clock of RS can be synchronized with the AS 304 during the commissioning phase. Also, PAT supports the use of 305 Lightweight Authenticated Time (LATe) Synchronization Protocol [I.D- 306 draft-navas-ace-secure-time-synchronization]. 308 4.2. [C->RS : Resource-Request] 310 Initially, a C may not have a valid access-token (AT) to access a 311 protected resource (R) hosted in RS. The C might not also know the 312 corresponding AS-information to request AT from AS. In this 313 scenario, C may send a Resource-Request message to RS without a valid 314 Token (Tk). 316 To enable resource discovery, RS may expose the URI "/.well-known/ 317 core" as described in [RFC6690], but this resource itself MAY be 318 protected. Thus, C can optionally make a CoAP GET request to the URI 319 "/.well-known/core". 321 4.3. [RS->C : Un-Authorized-Request(AS-Info)] 323 Once RS receives a resource request from a C, it checks: 325 o If C has attached a valid token (Tk) or not to the request. If C 326 does not have a valid token (Tk), then RS MUST respond to C with 327 4.01 (Unauthorized request). Optionally, RS may include 328 information about AS (AS-Info) which includes additional 329 parameters (AS address) to reach the /token endpoint exposed by 330 the AS. Note: this message is sent to any unauthorized Client, 331 therefore it is recommended to include as less information as 332 possible to identify AS. 334 o If C has a valid access token, but not for the requested resource 335 then RS MUST respond with 4.03 (Forbidden) 337 o If C has a valid access token, but not for the method requested 338 then RS MUST respond with 4.05 (Method Not Allowed) 340 o If C has a valid access token, then RS must follow the procedure 341 described in Section 4.8 to create a valid response to C. 343 Figure 2 shows the sequence of messages with detailed CoAP types 344 between C and RS for the above Un-Authorized-Request: 346 ,-. ,--. 347 |C| |RS| 348 `+' `+-' 349 | | ,---------------------------. 350 | 1 Res-REQ | |Header:GET | 351 |----------->| |Type:Confirmable | 352 | | |URI-Path:.well-known/core | 353 | | `---------------------------' 354 | | ,---------------------------. 355 | | |Header: 4.01 Unauthorized | 356 | 2 Res-RSP | |Type: Acknowledgement | 357 |<-----------| |content-type: | 358 | | |application/cbor | 359 | | |Payload:{AS-Info,params} | 360 ,+. ,+-.`---------------------------' 361 |C| |RS| 362 `-' `--' 363 Figure 2: C<->RS Resource-Request and Unauthorized as response 365 The RS MAY send an Unauthorized response with additional information 366 such as AS-Info and parameters (params). To mitigate attacks based 367 on time synchronization, the Lightweight Authenticated Time (LATe) 368 synchronization protocol [I.D-draft-navas-ace-secure-time- 369 synchronization] MAY be used. In section 6.2 of [I.D-draft-navas- 370 ace-secure-time-synchronization] Possible Scenarios, the scenario 1.2 371 of suits PAT protocol, an example of it is shown in figure 3. 373 The response payload MAY include AS information (AS-info) and LATe 374 time synchronization's TIC information object such as key-reference 375 ID (kid) shared secret between RS and AS, a nonce to prevent replay 376 attacks and the message authentication codes (MAC) algorithm 377 [optional] used for producing the MAC. It is recommended for RS to 378 create a MAC tag for TIC parameters. 380 Figure 3 shows RS example response message to C encoded using CBOR 381 [RFC7049] with pat-type="UnAuthReq". 383 Header: 4.01 (Unauthorized) 384 Content-Type: application/cbor+pat; 385 pat-type="UnAuthReq" 386 Payload: 387 { 388 AS-Info: "coaps://as.example.com/token", 389 #protected 390 TIC params: 391 { 392 nonce: 'rs-nonce..', 393 kid: '..', 394 [alg]: '..' 395 TAG: '..' 396 } 397 } 399 Figure 3: AS information + LATe time synchronization payload 401 4.4. C<->AS : Security-Association-Setup 403 Before sending an access-request message, C must establish a secure 404 channel with the AS. The C may be registered with the AS, as 405 described in [I-D.ietf.ace-oauth-authz] or the C MAY have received 406 AS-Info from RS as the answer to a previous Un-Authorized-Request. 408 The AS may have an access-control list defined by the RO for the 409 authorized clients. With this access-control list, AS can verify if 410 the client is allowed to establish a secure connection or not. If RO 411 granted enough privileges to the client to access the requested 412 resource (R) in RS, then AS establishes a confidential channel with 413 C. How this secure connection (e.g., a DTLS channel) should be 414 established is out of the scope of this memo. 416 Notice that, it is important to ensure that the connection between AS 417 and C MUST be reliable and secure since the PAT protocol relies on 418 the fact that the messages exchanged between C and AS are protected 419 and confidential. If the Client is also a constrained device, then C 420 may use DTLS-profile as described in [I.D-draft-gerdes-ace-dtls- 421 authorize] to create the secure channel with the AS. 423 4.5. C->AS : Access-Request 425 Once C establishes a secure communication channel with AS, C sends an 426 access-request (ACC-REQ) message to AS to the endpoint /token 427 requesting an access token for RS as described in [I-D.ietf.ace- 428 oauth-authz]. 430 Optionally, the C includes as part of the Access-Request Message the 431 details about the resources (R) or their corresponding URI with the 432 operations it needs to access or perform on RS. If not AS should 433 prepare an access token with default permissions. Fine grained 434 access to resources (R) of RS depends on the infrastructure or 435 services the RS offers. For example, if RS exposes different 436 resources such as temperature and humidity, a generic access token 437 may be granted by AS to C to access both resources on RS. On the 438 other hand, the application developer or administrator may decide the 439 access-rights based on application requirements. 441 Figure 4 shows an access-request message sent from C to AS to get an 442 access token. The "aud" represents a specific resource R 443 ("tempSensor") and "scope" represents the allowed actions that C aims 444 to perform as described in [I-D.ietf-ace-oauth-authz] using CWT [I- 445 D.ietf-ace-cbor-web-token]. The Scope parameter can be designed 446 based on application requirements i.e., it can be "read" or "write" 447 or methods such as "GET|POST" etc. If RS has included TIC 448 information for time synchronization, then the C MUST include TIC 449 object, including the MAC -- if included -- without any changes in 450 the payload for access request. 452 How the client authenticates itself against the AS is out of the 453 scope of this draft. Nevertheless, in the following example, the 454 client presents the Client_Credentials i.e., password based 455 authentication by presenting its client_secret (see section 2.3.1. of 456 [RFC6749]). 458 Header: POST (Code=0.02) 459 Uri-Host: "coaps://as.example.com" 460 Uri-Path: "token" 461 Content-Type: "application/cbor+cwt+late ; 462 late-type=tic" 463 Payload: 464 { 465 "grant_type" : "client_credentials", 466 "client_id": "client123", 467 "client_secret": "Secret123", 468 "aud" : "tempSensor", 469 "scope": "GET|POST", 470 ... omitted for brevity ... 471 TIC params: 472 {.. [if exist] .. 473 nonce:'rs-nonce..', # same rs-nonce sent by RS 474 kid: '..' 475 } 476 TAG: .. # TIC MAC tag produced by RS 477 using the shared key k with AS. 478 } 479 Figure 4: Example Client Access-Request message to AS 481 4.6. C<-AS : Access-Response 483 When AS receives an access-request message from a C, AS validates it 484 and performs the following actions: 486 o If the access request from C is valid (i.e., operations are 487 covered by the privileges defined by the RO), then AS prepares the 488 Access-Token (AT) and sends it with COAP response code 2.01 489 (Created). 491 o If the Access-Request from C contains LATe time synchronization 492 TIC information object, then an appropriate response with TOC 493 information object is included in the response as described in 494 [I.D-draft-navas-ace-secure-time-synchronization]. 496 o If the client request is invalid then AS MUST send appropriate 497 COAP error response code as specified in [I-D.ietf-ace-oauth- 498 authz]. 500 The Figure 5 shows the Access-Request from C to AS and the Access- 501 Response from AS to C. 503 ,-. ,--. 504 |C| |AS| 505 `+' `+-' 506 | 1 DTLS | 507 |<-----------> 508 | | 509 | | ,------------------------. 510 | | |Header:POST(code=0.02) | 511 |2 Access-REQ| |content-type: | 512 |------------> |application/cbor | 513 | | |URI-Path: token | 514 | | |Payload:{ACC-REQ} | 515 | | `------------------------' 516 | | ,-----------------------------. 517 |3 Access-RSP| |Header: Created (code=2.01) | 518 |<------------ |content-type: | 519 | | |application/cbor | 520 | | |Payload:{ACC-RSP} | 521 ,+. ,+-.`-----------------------------' 522 |C| |AS| 523 `-' `--' 525 Figure 5: Access-Request and Access-Response 527 The AS constructs the Access-Token (AT) and the verifier (the 528 symmetric PoP key) as the answer for a valid access request from C. 529 The contents of the access-response (ACC-RSP) payload are logically 530 split into two parts: the Access-Token (AT) and the Verifier 531 (Symmetric PoP key). 533 4.6.1. Access-Token construction: 535 o The Access-Token is constructed by AS using the CWT claim 536 parameters. It represents the permissions granted to the Client. 538 * "iss" (issuer): AS identity 540 * "aud" (audience): resource server URI or specific resource URI 541 for a fine-grained procedure. 543 * "exp" (Expiration Time): token expiration time 545 * "iat" (Issued At): token issued at time by AS 547 * "cti" CWT ID should be unique for every Access-Token. 549 * "scp" (Scope): Note that scp is not a CWT claim. It can 550 specify allowed methods such as GET, POST, PUT or DELETE. 552 Other CWT claims are optional. It is recommended to avoid the CWT 553 claim "sub" (subject) as it exposes client identity. 555 4.6.2. Verifier or PoP key construction: 557 o Verifier (Symmetric PoP key): G (K, Access-Token). The Client 558 will use the Verifier as the key material to communicate with the 559 RS, i.e., if C wants to encrypt its payload, it uses the verifier 560 as the key. 562 * G: the MAC algorithm which is used to create the verifier, we 563 propose Poly1305 [RFC7539]. Notice that G is a function which 564 takes two parameters (key, data) as input and it produces a 565 keyed digest as the output 567 * K: the shared key between AS and RS 569 * Access-Token: constructed using CWT claims as explained before 571 It is of special importance that the Access-Response message with the 572 access token and the verifier MUST be sent to C through a secure 573 channel -- in our example we considered a DTLS channel between C and 574 AS --. 576 The time-synchronization between AS and RS MAY be implemented based 577 on the application requirements using [I.D-draft-navas-ace-secure- 578 time-synchronization]. 580 The AS should specify required parameters as described in [I-D.ietf- 581 ace-oauth-authz] such as the type of token, etc. Also, if the 582 Access-Request from C does not include any profile, AS MUST signal 583 the C to use appropriate or default profile that is supported by RS. 585 If the access-request message includes LATe TIC information, then AS 586 MUST prepare TOC information and included it in the response. A MAC 587 tag for TOC is created and appended in the response to prevent the 588 client from tampering TOC information. 590 Figure 6 shows the example of an Access-Response sent from AS to C 591 after successful validation of C's credentials which were presented 592 using an Access-Request message. 594 Header: 2.01 (Created) 595 Content-Type: application/cbor+cwt+pat; pat-type="tk" 596 Location-Path: token/... 597 Payload: 598 { 599 "access token": b64'SlAV32hkKG ... 600 { 601 "iss": https://as.example.com 602 "aud": "tempSensor", 603 "scp": "read", 604 "iat": 1..., 605 "cti": "..", # Unique can be a Sequence Number 606 "exp": 5..., 607 "alg": "chacha20/poly1305", 608 "profile": "ace_pat" 609 } 610 "cnf": 611 { 612 COSE_Key: { 613 "kty": "symmetric", 614 "kid": h'... 615 "k": b64'jb3yjn... #[verifier] 616 } 617 } 618 TOC:{ 619 as_time: '..', 620 nonce: 'rs-nonce..', 621 } 622 tag: '..' #TOC tag 623 } 625 Figure 6: Example Access-Response message sent from AS to C 626 with detailed CWT params and payload info 628 4.7. C->RS : Resource-Request 630 Once C receives the Access-Response from AS, C can construct a token 631 (Tk) which will demonstrate that C has got the sufficient 632 authorization to access resources (R) in RS. 634 A new Token (Tk) MUST be attached to each RES-REQ sent to RS by C. 635 If payload data are included, then C should encrypt them using the 636 verifier as key and optionally it can include an Authentication Hash 637 (AuthHash= Hash(verifier+C_nonce)). PAT profile provides necessary 638 recommendations by using AEAD (e.g., chach20/poly1305) algorithm. 640 o As an example if C performs: 642 * A CoAP GET() without payload. In this case, the request from C 643 MAY be sent un-encrypted since it does not include confidential 644 data, but the response from RS with payload MUST be always 645 encrypted and only the valid C MUST be able to decrypt it. 647 * A CoAP POST(), a CoAP PUT() or a CoAP DELETE() request with 648 payload MUST be protected and encrypted by using the AEAD 649 algorithm specified in the Access Token (AT). PAT profile 650 proposes to use ChaCha20-Poly1305-AEAD authenticated encryption 651 mechanism, while using the Verifier (PoP key) as the key and a 652 nonce. The AuthHash MAY be protected by using it as Additional 653 Authentication Data (AAD) in the AEAD algorithm. 655 The RS MUST implement /authz-info endpoint to allow any Client to 656 transfer the token (Tk) as described in [I-D.ietf-ace-oauth-authz]. 657 The Resource-Request message with valid Token (Tk) shall be 658 constructed from AT by C and it should be sent to RS in the following 659 way: 661 o Figure 7 shows the example of Client Resource-Request: 663 Request: 664 Content-Type: application/cose+cbor+pat; 665 pat-type="AuthReq"; 666 Message: 667 { CoAP request: GET/POST/PUT/DELETE 668 Uri-Host "coap://rs.example.com" 669 uri-path: /authz-info 670 payload: 671 { 672 Token: 673 { 674 Access Token(AT), # Tk encapsulates the AT from AS 675 AuthHash=Hash(verifier+nonce), #optional for GET 676 nonce, 677 #Chach20/Poly1305(Verifier,nonce, 678 AAD=AuthHash, payload) 679 Payload:{ 680 # if exist 681 } 682 } 683 } 684 } 686 Figure 7: RES-REQ from C using /authz-info implemented at RS 688 Figure 7 shows the detailed example of GET RES-REQ to the endpoint 689 /authz-info implemented at RS as described in [I-D.ietf-ace-oauth- 690 authz]. This option enables the C to transport the token (Tk) to the 691 RS. After receiving the request, RS verifies the token (Tk): RS can 692 construct its own version of verifier or PoP-key by performing 693 G(K,AT) from the access-token (AT); and RS checks whether 694 AuthHash=Hash(verifier+nonce) is valid or not. If Tk and AuthHash 695 are valid, then RS sends an encrypted response using the verifier 696 (PoP key). 698 o Figure 8 shows the GET request from C to RS described in [I- 699 D.ietf-ace-oauth-authz], with pat-type="AuthReq". 701 Header: GET 702 Content-Type: application/cose+cbor+pat; 703 pat-type="AuthReq"; 704 Uri-Host: "coap://rs.example.com" 705 Uri-Path: /authz-info 706 Payload: 707 { token: { 708 "access token": .. { 709 "aud": "tempSensor" 710 "scp": "read" 711 ... #CWT omitted for brevity. 712 } 713 "nonce": .. 714 "AuthHash": .. #[AuthHash=hash(verifier+nonce)] 715 } 716 TOC:{ 717 time:'as-time', 718 nonce:'rs-nonce',# rs-nonce from RS TOC object 719 } tag: '..' #TOC tag 720 } 722 Figure 8: Example of valid GET RES-REQ from C to RS 723 including time-sync using endpoint /authz-info. 725 The C performs a GET request to "tempSensor" using CWT claim "aud", 726 and together C also transfers the Token (Tk) to the RS. PAT allows 727 performing both RES-REQ and transferring authorization information in 728 RES-REQ. In the next example we show how to perform a resource 729 request if the C performs a POST request with encrypted payload 730 information. 732 o Figure 9 shows an example of POST Resource-Request from C to RS 733 described in [I-D.ietf-ace-oauth-authz], with pat-type="AuthReq". 735 Header: POST (Code=0.02) 736 Content-Type: application/cose+cbor+pat; 737 cose-type="encrypt0"; 738 "pat-type="AuthReq"; 739 Uri-Host: "coap://rs.example" 740 Uri-Path: /authz-info 741 Payload: 742 {# COSE 743 token: { 744 "access token": .. { 745 "aud": "firmwareUpd" 746 "scp": "write" 747 ... CWT omitted for brevity, 748 } 749 "nonce": .. # nonce 750 "AuthHash": .. #[AuthHash=hash(verifier+nonce)] 751 TOC:{ 752 time:'as-time', 753 nonce:'rs-nonce', # rs-nonce from RS TIC 754 } tag: '..' #TOC tag 755 } 756 # COSE_Encrypt0 + COSE_MAC0 Protected 757 ciphertext:{ 758 #Chacha20/Poly1305 AEAD payload using 759 # key=verifier, 760 # nonce=.., 761 # AAD=AuthHash 762 }, 763 tag: .. 764 } 766 Figure 9: Example of valid POST request from C to RS 768 Figure 9 shows the POST Resource-Request from C to RS where the Uri- 769 Path "/authz-info" allows the authorized client to perform firmware 770 upgrade on the RS using the CWT claim "aud:firmwareUpd". PAT 771 recommends protecting sensitive information such as the payload using 772 AEAD algorithm (chacha20/poly1305). The client should use Verifier 773 or PoP key as the key, a nonce, and AuthHash as AAD. 775 4.8. RS->C : Resource-Response 777 When the RES-REQ with a token (Tk) arrives from C to RS, RS MUST 778 evaluate the resource request and the token (Tk) in the following 779 order: 781 o Step 0: Check whether the contents of Tk are derived from an 782 access-token (AT) or not. 784 o Step1: If Tk contains the access-token (AT) from AS, extract AT. 785 Extract nonce and Authentication Hash (AuthHash) from the request 786 message. 788 * Step1.1: (If available) Verify the freshness of the sequence 789 number (cti) in the access token presented by AS. 791 * Step1.2: Generate the verifier by computing G(K, access token) 792 where K is the shared key between AS and RS. 794 * Step1.3: Compute a verification hash as Hash(verifier+nonce) 795 and compare the result with AuthHash for correctness. 797 * Step1.4: Check if the access token has valid CWT parameters 798 such as "aud", "scp", "exp", "nbf", etc for the requested 799 resource or action to be performed. 801 * Step1.5: (IF available) Synchronize RS internal clock using TOC 802 object as described in [I.D-draft-navas-ace-secure-time- 803 synchronization]. 805 o Step2: If the token is valid, RS should create a temporary 806 internal state as shown in table 1 below with details of CWT 807 claims "cti","exp","scp"", and the verifier (PoP key). 809 The RS internal state table which is shown in Table1 also includes 810 "next cti". The next cti (cti x) value is computed as the Hash of 811 previous cti (cti x-1) and the verifier. The purpose of this is 812 explained in the section Section 4.9. 814 |------------+-----------+-------+-------+-----------------------| 815 | Verifier | cti_x-1 | exp | scp | next cti (cti_x) | 816 |------------+-----------+-------+-------+-----------------------| 817 | G(k,AT) | cti_x0= | of AT | of AT | cti_x1= | 818 | | cti of AT | | | hash(cti_x0,Verifier) | 819 |------------+-----------+-------+-------+-----------------------| 820 Table 1: RS Internal state table of access-tokens and RS_nonce 822 o Step 3: If the token is valid, then RS decrypts the payload from 823 the client (if exist) Verifier (PoP key). 825 o Step 4: After that, RS prepares the response and encrypts the 826 payload with a fresh nonce, PoP key. Only the Client (C) with a 827 valid key (the Verifier) can decrypt the payload: 829 4.8.1. RS Response-codes to C RES-REQ: 831 o If the token (Tk) is valid -- as discussed above --, then RS MUST 832 respond with payload-data as described above with the appropriate 833 response code as described in [RFC7252]. For example, to a POST 834 request with 2.01 (created) or 2.04 (changed). 836 o If the token (Tk) is invalid, then RS MUST respond with code 4.01 837 (Unauthorized) 839 o If the token (Tk) is valid but does not match the "aud" or 840 resource C is requesting for then RS MUST respond with code 4.03 841 (Forbidden) 843 4.9. Construction of Derived-Tokens (DT) 845 The objectives to create Derived-Tokens (DT) are: 847 o To produce Unlinkable Tokens (Tk). It is not efficient for the 848 client to request a new access-token (AT) from AS everytime. 849 Also, if C uses the same access-token (AT) from AS, the identity 850 of the client can be identified via the AT CWT claim "cti" (token 851 identity). 853 o To reduce token (Tk) size (efficiency in transport) that the 854 client must send to RS /authz-info in every resource request. 856 o To create tokens (Tk) that may have limited access to protected- 857 resources -- fine-grained resource access tokens -- from the 858 original access-tokens (AT) that could grant more privileges to 859 protected-resources on RS. For example, an access-token (AT) 860 could provide permissions to access all protected-resources on RS 861 via CWT claims audience "aud" and scope "scp". The client could 862 derive a Token (Tk) providing access to a reduced set of 863 protected-resources available on RS from the initial AT. 865 4.9.1. C->RS: Resource-Request via DT 867 The Client receives an encrypted response from RS after its first 868 RES-REQ with the access-token (AT) from AS. 870 The Client creates a new Derived-Token(DT) using CWT claims as 871 described below. In order to minimize the data size, we use only the 872 claims which are required. 874 o Client MAY prepare a DT with a subset of scope "scp" operations 875 that the client received from the initial Access-Token (AT). It 876 creates the first derived "cti_x1" by Hash("cti_x0 + verifier") 877 from the CWT claim "cti" of the original access-token (AT). The 878 subsequent derivation of "cti_x" can be performed by a generic 879 function "cti_x = Hash(cti_x-1 + verifier)". Note that the 880 derived-token (DT) MUST include all the necessary CWT claims such 881 as "cti_x", "aud", "exp", "scp". All other CWT claims are 882 optional. 884 o Client creates the AuthHash=(verifer+nonce). 886 o Client prepares encrypted content using verifier as the key -- if 887 there is any payload --. 889 o Note: in the Additional Authenticated data (AAD), the C includes 890 AuthHash and the derived-token (DT), so that the payload cannot be 891 misused/exchanged with another RES-REQ or nonce. 893 Header: POST (Code=0.02) 894 Content-Type: application/cbor+cwt+cose++pat; 895 cose-type="encrypt0"; 896 "pat-type="AuthReq"; 897 Uri-Host: "coap://rs.example" 898 Uri-Path: /firmware 899 Payload: 900 {# COSE 901 token: {derived-token(DT): 902 "aud": "firmwareUpd", 903 "exp": .. 904 "scp": "write", 905 "cti": Hash(cti_x+verifier) 906 # cti_x=Hash(cti_x-1+verifier). 907 } 908 "nonce": .. # new nonce 909 "AuthHash": h'bfa03.. #[Hash=(verifier+nonce)] 910 # COSE_Encrypt0 + COSE_MAC0 Protected 911 ciphertext:{ 912 #Chacha20/Poly1305 AEAD payload using 913 # key=verifier, 914 # nonce=.., 915 # AAD=AuthHash,DT 916 h'....omitted for brevity 917 }, 918 tag: h'... omitted for brevity 919 } 921 Figure 12: Example of valid Resource-Request 922 from C to RS using a derived-token(DT) 924 4.9.2. RS->C : Resource-Response to DT 926 After receiving the Token (Tk) which encapsulates the derived Token 927 (DT) from C, RS performs the following Steps. If any of them fails, 928 then RS must send an UnAuthorized response to C, and C must use the 929 first AT, which was received from the AS, or request a new AT based 930 on the resource owner (RO) configuration: 932 o RS extracts CWT claim cti (cti_x) from the Derived-Token (DT) and 933 checks if it exists in its internal state table. If RS finds the 934 cti_x, then RS uses the corresponding verifier, "cti_x-1, "exp", 935 and "scp" to perform the validation of next steps. 937 o RS checks that cti_x= Hash (cti_x-1+verifier) 939 o RS checks that AuthHash == Hash(verifier+nonce) 941 o RS checks that the permissions are valid using "scp" and 942 expiration time "exp" 944 o RS updates the new cti_x-1, cti_x in its internal state table 946 o RS creates an encrypted response to be sent to C with a payload 947 including payload-data. 949 |---------+--------------+---------+-------+-------+-----------------| 950 | msg# | Verifier (V) | cti_x-1 | exp | scp | cti_x= | 951 | | | | | | Hash(cti_x-1+V) | 952 |---------+--------------+---------+-------+-------+-----------------| 953 | 0 | G(K,AT) | 0x00 | of AT | of AT | 0xAB = | 954 | | | | | | Hash(0x00+V) | 955 |---------+--------------+---------+-------+-------+-----------------| 956 | 1 (upd) | G(k,AT) | 0xAB | of AT | of AT | 0xFF = | 957 | | | | | | Hash(0xAB+V) | 958 |---------+--------------+---------+-------+-------+-----------------| 959 Table 2: RS updating only two parameters in its 960 internal stating table 1 962 The Table 2 shows the RS internal state table with an example. 964 5. Security Considerations 966 TBD 968 5.1. Privacy Considerations 970 The CoAP messaging layer parameters such as token and message-id can 971 be used for matching a specific request and response. TBD 973 6. IANA Considerations 975 TBD 977 7. References 979 7.1. Normative References 981 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 982 Requirement Levels", BCP 14, RFC 2119, March 1997. 984 [RFC7252] Shelby, Z., Hartke, K. and Borman, C., "The Constrained 985 Application Protocol (CoAP)", RFC 7252, June 2014. 987 [RFC6347] Rescorla E. and Modadugu N., "Datagram Transport Layer 988 Security Version 1.2", RFC 6347, January 2012. 990 [RFC7539] Y. Nir and A. Langley: ChaCha20 and Poly1305 for IETF 991 Protocols, RFC7539, May 2015 993 [I-D.ietf-ace-actors] Gerdes, S., Seitz, L., Selander, G., and C. 994 Bormann, "An architecture for authorization in constrained 995 environments", draft-ietf-ace-actors-0 (work in progress), March 996 2017. 998 [I-D.ietf-oauth-pop-architecture] Hunt, P., Richer, J., Mills, W., 999 Mishra, P., and H. Tschofenig, "OAuth 2.0 Proof-of-Possession (PoP) 1000 Security Architecture", draft-ietf-oauth-pop-architecture-08 (work in 1001 progress), July 2016. 1003 [I-D.ietf-ace-oauth-authz] Seitz, L., Selander, G., Wahlstroem, E., 1004 Erdtman, S., and H. Tschofenig, "Authorization for the Internet of 1005 Things using OAuth 2.0", draft-ietf-ace-oauth-authz-06 (work in 1006 progress), March 2017. 1008 [I-D.ietf-cose-msg] Schaad, J., "CBOR Object Signing and Encryption 1009 (COSE)", draft-ietf-cose-msg-24 (work in progress), November 2016. 1011 [I.D-draft-navas-ace-secure-time-synchronization] Navas, G., 1012 Selander, G., Seitz, L., "Lightweight Authenticated Time (LATe) 1013 Synchronization Protocol", draft-navas-ace-secure-time- 1014 synchronization-00 (work in progress), October 2016. 1016 7.2. Informative References 1018 [KoMa2014] Kohnstamm, J. and Madhub, D., "Mauritius Declaration on 1019 the Internet of Things", 36th International Conference of Data 1020 Protection and Privacy Comissioners, October 2014. 1022 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1023 Constrained-Node Networks", RFC 7228, DOI 10.17487/RFC7228, May 2014, 1024 1026 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1027 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1028 . 1030 [I.D-draft-gerdes-ace-dtls-authorize] Gerdes, S., Begmann, O., 1031 Bormann, C., Selander, G., Seitz, L. Datagram Transport Layer 1032 Security (DTLS) Profile for Authentication and Authorization for 1033 Constrained Environments (ACE), draft-gerdes-ace-dtls-authorize-01, 1034 March 2017. 1036 [I-D.ietf-ace-cbor-web-token] Jones, M., Tschofenig, H., Erdtman, S., 1037 CBOR Web Token (CWT), draft-ietf-ace-cbor-web-token-05 (work in 1038 progress), June 2017.. 1040 8. Acknowledgement 1042 This draft is the result of collaborative research in the RERUM EU 1043 funded project and has been partly funded by the European Commission 1044 (Contract No. 609094). The authors thank Ludwig Seitz for reviewing 1045 the previous version of the draft. 1047 8.1. Copyright Statement 1049 Copyright (c) 2015 IETF Trust and the persons identified as authors 1050 of the code. All rights reserved. 1052 Redistribution and use in source and binary forms, with or without 1053 modification, is permitted pursuant to, and subject to the license 1054 terms contained in, the Simplified BSD License set forth in 1055 Section 4.c of the IETF Trust's Legal Provisions Relating to IETF 1056 Documents . 1058 Appendix A. ACE profile Registration 1060 TBD 1061 |----------------------+-----| 1062 | ACE profile template | PAT | 1063 |----------------------+-----| 1064 | Profile name | TBD | 1065 | Profile Description | TBD | 1066 | Profile ID | TBD | 1067 |----------------------+-----| 1068 Table2: ACE profile registration template 1070 Authors' Addresses 1072 Jorge Cuellar 1073 Siemens AG 1074 Otto-Hahn-Ring 6 1075 Munich, Germany 81739 1077 Email: jorge.cuellar@siemens.com 1079 Prabhakaran Kasinathan 1080 Siemens AG 1081 Otto-Hahn-Ring 6 1082 Munich, Germany 81739 1084 Email: prabhakaran.kasinathan@siemens.com 1086 Daniel Calvo 1087 Atos Research and Innovation 1088 Poligono Industrial Candina 1089 Santander, Spain 39011 1091 Email: daniel.calvo@atos.net