idnits 2.17.1 draft-ietf-tram-turn-third-party-authz-10.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 (February 6, 2015) is 3367 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) ** Obsolete normative reference: RFC 5389 (Obsoleted by RFC 8489) == Outdated reference: A later version (-08) exists of draft-ietf-oauth-pop-architecture-00 == Outdated reference: A later version (-07) exists of draft-ietf-oauth-pop-key-distribution-00 == Outdated reference: A later version (-19) exists of draft-ietf-rtcweb-overview-13 == Outdated reference: A later version (-21) exists of draft-ietf-tram-stunbis-00 -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 5766 (Obsoleted by RFC 8656) -- Obsolete informational reference (is this intentional?): RFC 6347 (Obsoleted by RFC 9147) -- Obsolete informational reference (is this intentional?): RFC 7159 (Obsoleted by RFC 8259) Summary: 1 error (**), 0 flaws (~~), 5 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 TRAM T. Reddy 3 Internet-Draft P. Patil 4 Intended status: Standards Track R. Ravindranath 5 Expires: August 10, 2015 Cisco 6 J. Uberti 7 Google 8 February 6, 2015 10 Session Traversal Utilities for NAT (STUN) Extension for Third Party 11 Authorization 12 draft-ietf-tram-turn-third-party-authz-10 14 Abstract 16 This document proposes the use of OAuth 2.0 to obtain and validate 17 ephemeral tokens that can be used for Session Traversal Utilities for 18 NAT (STUN) authentication. The usage of ephemeral tokens ensures 19 that access to a STUN server can be controlled even if the tokens are 20 compromised. 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 August 10, 2015. 39 Copyright Notice 41 Copyright (c) 2015 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. Solution Overview . . . . . . . . . . . . . . . . . . . . . . 3 59 4. Obtaining a Token Using OAuth . . . . . . . . . . . . . . . . 4 60 4.1. Key Establishment . . . . . . . . . . . . . . . . . . . . 4 61 4.1.1. DSKPP . . . . . . . . . . . . . . . . . . . . . . . . 5 62 4.1.2. HTTP interactions . . . . . . . . . . . . . . . . . . 5 63 4.1.3. Manual provisioning . . . . . . . . . . . . . . . . . 6 64 5. Forming a Request . . . . . . . . . . . . . . . . . . . . . . 7 65 6. STUN Attributes . . . . . . . . . . . . . . . . . . . . . . . 7 66 6.1. THIRD-PARTY-AUTHORIZATION . . . . . . . . . . . . . . . . 7 67 6.2. ACCESS-TOKEN . . . . . . . . . . . . . . . . . . . . . . 7 68 7. STUN Server Behaviour . . . . . . . . . . . . . . . . . . . . 9 69 8. STUN Client Behaviour . . . . . . . . . . . . . . . . . . . . 10 70 9. Usage with TURN . . . . . . . . . . . . . . . . . . . . . . . 11 71 10. Operational Considerations . . . . . . . . . . . . . . . . . 14 72 11. Security Considerations . . . . . . . . . . . . . . . . . . . 14 73 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 74 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 15 75 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 76 14.1. Normative References . . . . . . . . . . . . . . . . . . 15 77 14.2. Informative References . . . . . . . . . . . . . . . . . 16 78 Appendix A. Sample tickets . . . . . . . . . . . . . . . . . . . 17 79 Appendix B. Interaction between client and authorization server 19 80 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21 82 1. Introduction 84 Session Traversal Utilities for NAT (STUN) [RFC5389] provides a 85 mechanism to control access via "long-term" username/ password 86 credentials that are provided as part of the STUN protocol. It is 87 expected that these credentials will be kept secret; if the 88 credentials are discovered, the STUN server could be used by 89 unauthorized users or applications. However, in web applications, 90 ensuring this secrecy is typically impossible. 92 To address this problem and the ones described in [RFC7376], this 93 document proposes the use of third party authorization using OAuth 94 2.0 [RFC6749] for STUN. Using OAuth 2.0, a client obtains an 95 ephemeral token from an authorization server e.g. WebRTC server, and 96 the token is presented to the STUN server instead of the traditional 97 mechanism of presenting username/password credentials. The STUN 98 server validates the authenticity of the token and provides required 99 services. Third party authorization using OAuth 2.0 for STUN 100 explained in this specification can also be used with Traversal Using 101 Relays around NAT (TURN) [RFC5766]. 103 2. Terminology 105 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 106 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 107 document are to be interpreted as described in [RFC2119]. 109 o WebRTC Server: A web server that supports WebRTC 110 [I-D.ietf-rtcweb-overview]. 112 o Access Token: OAuth 2.0 access token. 114 o mac_key: The session key generated by the authorization server. 115 This session key has a lifetime that corresponds to the lifetime 116 of the access token, is generated by the authorization server and 117 bound to the access token. 119 o kid: An ephemeral and unique key identifier. The kid also allows 120 the resource server to select the appropriate keying material for 121 decryption. 123 Some sections in this specification show WebRTC server as the 124 authorization server and client as the WebRTC client, however WebRTC 125 is intended to be used for illustrative purpose only. 127 3. Solution Overview 129 STUN client knows that it can use OAuth 2.0 with the target STUN 130 server either through configuration or when it receives the new STUN 131 attribute THIRD-PARTY-AUTHORIZATION in the error response with an 132 error code of 401(Unauthorized). 134 This specification uses the token type 'Assertion' (aka self- 135 contained token) described in [RFC6819] where all the information 136 necessary to authenticate the validity of the token is contained 137 within the token itself. This approach has the benefit of avoiding a 138 protocol between the STUN server and the authorization server for 139 token validation, thus reducing latency. The content of the token is 140 opaque to the client. The client embeds the token within a STUN 141 request sent to the STUN server. Once the STUN server has determined 142 the token is valid, its services are offered for a determined period 143 of time. Access token issued by the authorization server is 144 explained in Section 6.2. OAuth 2.0 in [RFC6749] defines four grant 145 types. This specification uses the OAuth 2.0 grant type "Implicit" 146 explained in section 1.3.2 of [RFC6749] where the client is issued an 147 access token directly. The value of the scope parameter explained in 148 section 3.3 of [RFC6749] MUST be string 'stun'. 150 The exact mechanism used by a client to obtain a token from the OAuth 151 2.0 authorization server is outside the scope of this document. 152 Appendix B provides an example deployment scenario of interaction 153 between the client and authorization server to obtain a token. 155 4. Obtaining a Token Using OAuth 157 A STUN client MUST know the authentication capability of the STUN 158 server before deciding to use third party authorization. A STUN 159 client initially makes a request without any authorization. If the 160 STUN server supports third party authorization, it will return an 161 error message indicating that the client can authorize to the STUN 162 server using an OAuth 2.0 access token. The STUN server includes an 163 ERROR-CODE attribute with a value of 401 (Unauthorized), a nonce 164 value in a NONCE attribute and a SOFTWARE attribute that gives 165 information about the STUN server's software. The STUN server also 166 includes the additional STUN attribute THIRD-PARTY-AUTHORIZATION 167 signaling the STUN client that the STUN server supports third party 168 authorization. 170 Note: An implementation may choose to contact the authorization 171 server to obtain a token even before it makes a STUN request, if it 172 knows the server details before hand. For example, once a client has 173 learnt that a STUN server supports third party authorization from a 174 authorization server, the client can obtain the token before making 175 subsequent STUN requests. 177 4.1. Key Establishment 179 The authorization server shares a long-term secret (like asymmetric 180 credentials) with the STUN server for mutual authentication. 181 Symmetric-key algorithm with Hash based Message Authentication Codes 182 (HMACs) MUST be chosen to ensure that the size of encrypted token is 183 not large because usage of asymmetric keys will result in large 184 encrypted tokens which may not fit into a single STUN message. 186 The STUN server and authorization server can establish a symmetric 187 key (K), using an out of band mechanism. If symmetric key is used 188 then the AS-RS and AUTH keys will be derived from K. The AS-RS key 189 is used for encrypting the self-contained token and the message 190 integrity of the encrypted token is calculated using the AUTH key. 191 The STUN and authorization servers MUST establish the symmetric key 192 over an authenticated secure channel. The procedure for 193 establishment of the symmetric key is outside the scope of this 194 specification. For example, implementations could use one of the 195 following mechanisms to establish a symmetric key. 197 4.1.1. DSKPP 199 The two servers could choose to use Dynamic Symmetric Key 200 Provisioning Protocol (DSKPP) [RFC6063] to establish a symmetric key 201 (K). The encryption and MAC algorithms will be negotiated using the 202 KeyProvClientHello, KeyProvServerHello messages. A unique key 203 identifier (referred to as KeyID) for the symmetric key is generated 204 by the DSKPP server (i.e., Authorization server) and signalled to the 205 DSKPP client (i.e., STUN server) which is equivalent to the kid 206 defined in this specification. The AS-RS, AUTH keys would be derived 207 from the symmetric key using (HMAC)-based key derivation function 208 (HKDF) [RFC5869] and the default hash function MUST be SHA-256. For 209 example if the input symmetric key (K) is 32 octets length, 210 encryption algorithm is AES_256_CBC and HMAC algorithm is HMAC-SHA1 211 [RFC2104] then the secondary keys AS-RS, AUTH are generated from the 212 input key K as follows 214 1. HKDF-Extract(zero, K) -> PRK 216 2. HKDF-Expand(PRK, "AUTH key", 20) -> AUTH key 218 3. HKDF-Expand(PRK, "AS-RS key", 32) -> AS-RS key 220 If Authenticated Encryption with Associated Data (AEAD) algorithm 221 defined in [RFC5116] is used then there is no need to generate the 222 AUTH key. 224 4.1.2. HTTP interactions 226 The two servers could choose to use REST API over HTTPS to establish 227 a symmetric key. HTTPS MUST be used for mutual authentication and 228 confidentiality. To retrieve a new symmetric key, the STUN server 229 makes an HTTP GET request to the authorization server, specifying 230 STUN as the service to allocate the symmetric keys for, and 231 specifying the name of the STUN server. The response is returned 232 with content-type "application/json", and consists of a JSON object 233 containing the symmetric key. 235 Request 236 ------- 238 service - specifies the desired service (turn) 239 name - STUN server name be associated with the key 241 example: GET /?service=stun&name=turn1@example.com 243 Response 244 -------- 246 key - Long-term key (K) 247 ttl - the duration for which the key is valid, in seconds. 249 example: 250 { 251 "key" : 252 "ESIzRFVmd4iZABEiM0RVZgKn6WjLaTC1FXAghRMVTzkBGNaaN496523WIISKerLi", 253 "ttl" : 86400, 254 "kid" :"22BIjxU93h/IgwEb" 255 "enc" : A256CBC-HS512 256 } 258 The AS-RS, AUTH keys are derived from K using HKDF as discussed in 259 Section 4.1.1. The authorization server must also signal kid to the 260 STUN server which will be used to select the appropriate keying 261 material for decryption. A256CBC-HS512 and other encryption 262 algorithms are defined in [I-D.ietf-jose-json-web-algorithms]. In 263 this case AS-RS key length must be 256-bit, AUTH key length must be 264 256-bit (section 2.6 of [RFC4868]). 266 4.1.3. Manual provisioning 268 The STUN and authorization servers could be manually configured with 269 a symmetric key (K) and kid. If manual provisioning is supported, 270 support MUST also be provided for AES_256_CBC_HMAC_SHA_512 (explained 271 in [I-D.ietf-jose-json-web-algorithms]) as the authenticated 272 encryption algorithm . 274 Note : The mechanism specified in Section 4.1.3 is easy to implement 275 and deploy compared to DSKPP, REST but lacks encryption and HMAC 276 algorithm agility. 278 5. Forming a Request 280 When a STUN server responds that third party authorization is 281 required, a STUN client re-attempts the request, this time including 282 access token and kid values in ACCESS-TOKEN and USERNAME STUN 283 attributes. The STUN client includes a MESSAGE-INTEGRITY attribute 284 as the last attribute in the message over the contents of the STUN 285 message. The HMAC for the MESSAGE-INTEGRITY attribute is computed as 286 described in section 15.4 of [RFC5389] where the mac_key is used as 287 the input key for the HMAC computation. The STUN client and server 288 will use the mac_key to compute the message integrity and do not 289 perform MD5 hash on the credentials. 291 6. STUN Attributes 293 The following new STUN attributes are introduced by this 294 specification to accomplish third party authorization. 296 6.1. THIRD-PARTY-AUTHORIZATION 298 This attribute is used by the STUN server to inform the client that 299 it supports third party authorization. This attribute value contains 300 the STUN server name. The STUN server may have tie-ups with multiple 301 authorization servers and vice versa, so the client MUST provide the 302 STUN server name to the authorization server so that it can select 303 the appropriate keying material to generate the self-contained token. 304 The THIRD-PARTY-AUTHORIZATION attribute is a comprehension-optional 305 attribute (see Section 15 from [RFC5389]). If the client is able to 306 comprehend THIRD-PARTY-AUTHORIZATION it MUST ensure that third party 307 authorization takes precedence over first party authentication 308 (explained in section 10 of [RFC5389]). If the client does not 309 support or is not capable of doing third party authorization then it 310 defaults to first party authentication. 312 6.2. ACCESS-TOKEN 314 The access token is issued by the authorization server. OAuth 2.0 315 does not impose any limitation on the length of the access token but 316 if path MTU is unknown then STUN messages over IPv4 would need to be 317 less than 548 bytes (Section 7.1 of [RFC5389]). The access token 318 length needs to be restricted to fit within the maximum STUN message 319 size. Note that the self-contained token is opaque to the client and 320 the client MUST NOT examine the ticket. The ACCESS-TOKEN attribute 321 is a comprehension-required attribute (see Section 15 from 322 [RFC5389]). 324 The token is structured as follows: 326 struct { 327 opaque { 328 uint16_t key_length; 329 opaque mac_key[key_length]; 330 uint64_t timestamp; 331 uint32_t lifetime; 332 uint8_t padding_length; 333 uint8_t padding[padding_length]; 334 } encrypted_block; 335 opaque mac[mac_length]; 336 uint8_t mac_length; 337 } token; 339 Figure 1: Self-contained token format 341 Note: uintN_t means an unsigned integer of exactly N bits. Single- 342 byte entities containing uninterpreted data are of type opaque. All 343 values in the token are stored in network byte order. 345 The fields are described below: 347 key_length: Length of the session key in octets. Key length of 348 160-bits MUST be supported (i.e., only 160-bit key is used by 349 HMAC-SHA-1 for message integrity of STUN message). The key length 350 facilitates the hash agility plan discussed in section 16.3 of 351 [RFC5389]. 353 mac_key: The session key generated by the authorization server. 355 timestamp: 64-bit unsigned integer field containing a timestamp. 356 The value indicates the time since January 1, 1970, 00:00 UTC, by 357 using a fixed point format. In this format, the integer number of 358 seconds is contained in the first 48 bits of the field, and the 359 remaining 16 bits indicate the number of 1/64K fractions of a 360 second (Native format - Unix). 362 lifetime: The lifetime of the access token, in seconds. For 363 example, the value 3600 indicates one hour. The lifetime value 364 MUST be greater than or equal to the "expires_in" parameter 365 defined in section 4.2.2 of [RFC6749], otherwise resource server 366 could revoke the token but the client would assume that the token 367 has not expired and would not refresh the token. 369 padding_length: The padding length MUST be such that the total size 370 of the encrypted_block structure is a multiple of the cipher's 371 block length. 373 padding: Padding that is added to force the length of the plaintext 374 to be an integral multiple of the block cipher's block length. 376 encrypted_block: The encrypted_block is encrypted using the 377 symmetric long-term key established between the STUN server and 378 the authorization server. Shown in Figure 3 as AS-RS key. 380 mac: The Hashed Message Authentication Code (HMAC) is calculated 381 with the AUTH key over the 'encrypted_block' and the STUN server 382 name (N) conveyed in the THIRD-PARTY-AUTHORIZATION response. This 383 ensures that the client does not use the same token to gain 384 illegal access to other STUN servers provided by the same 385 administrative domain i.e., when multiple STUN servers in a single 386 administrative domain share the same symmetric key with an 387 authorization server. 389 mac_length: Length of the mac field. 391 An example encryption process is illustrated below. Here C, N denote 392 Ciphertext and STUN server name respectively. 394 o C = AES_256_CBC(AS-RS, encrypted_block) 396 * Initialization vector can be set to zero because the 397 encrypted_block in each access token will not be identical and 398 hence will not result in generation of identical ciphertext. 400 o mac = HMAC-SHA-256-128(AUTH, C | | N) 402 Encryption is applied before message authentication on the sender 403 side and conversely on the receiver side. The entire token i.e., the 404 'encrypted_block' and 'mac' is base64 encoded (see section 4 of 405 [RFC4648]) and the resulting access token is signaled to the client. 406 If AEAD algorithm is used then there is no need to explicitly compute 407 HMAC, the associated data MUST be the STUN server name (N) and the 408 mac field MUST carry the nonce. The length of nonce for AEAD 409 algorithms is explained in [RFC5116]. 411 7. STUN Server Behaviour 413 The STUN server, on receiving a request with ACCESS-TOKEN attribute, 414 performs checks listed in section 10.2.2 of [RFC5389] in addition to 415 the following steps to verify that the access token is valid: 417 o STUN server selects the keying material based on kid signalled in 418 the USERNAME attribute. 420 o It performs the verification of the token message integrity by 421 calculating HMAC over the encrypted portion in the self-contained 422 token and STUN server name using AUTH key and if the resulting 423 value does not match the mac field in the self-contained token 424 then it rejects the request with an error response 401 425 (Unauthorized). If AEAD algorithm is used then it has only a 426 single output, either a plaintext or a special symbol FAIL that 427 indicates that the inputs are not authentic. 429 o STUN server obtains the mac_key by retrieving the content of the 430 access token (which requires decryption of the self-contained 431 token using the AS-RS key). 433 o The STUN server verifies that no replay took place by performing 434 the following check: 436 * The access token is accepted if the timestamp field (TS) in the 437 self-contained token is recent enough to the reception time of 438 the STUN request (RDnew) using the following formula: Lifetime 439 + Delta > abs(RDnew - TS). The RECOMMENDED value for the 440 allowed Delta is 5 seconds. If the timestamp is NOT within the 441 boundaries then the STUN server discards the request with error 442 response 401 (Unauthorized). 444 o The STUN server uses the mac_key to compute the message integrity 445 over the request and if the resulting value does not match the 446 contents of the MESSAGE-INTEGRITY attribute then it rejects the 447 request with an error response 401 (Unauthorized). 449 o If all the checks pass, the STUN server continues to process the 450 request. Any response generated by the server MUST include the 451 MESSAGE-INTEGRITY attribute, computed using the mac_key. 453 If a STUN server receives an ACCESS-TOKEN attribute unexpectedly 454 (because it had not previously sent out a THIRD-PARTY-AUTHORIZATION), 455 it will respond with an error code of 420 (Unknown Attribute) as 456 specified in Section 7.3.1 of [RFC5389]. 458 8. STUN Client Behaviour 460 o The client looks for the MESSAGE-INTEGRITY attribute in the 461 response. If MESSAGE-INTEGRITY is absent or the value computed 462 for message integrity using mac_key does not match the contents of 463 the MESSAGE-INTEGRITY attribute then the response MUST be 464 discarded. 466 o If the access token expires then the client MUST obtain a new 467 token from the authorization server and use it for new STUN 468 requests. 470 9. Usage with TURN 472 Traversal Using Relay NAT (TURN) [RFC5766] an extension to the STUN 473 protocol is often used to improve the connectivity of P2P 474 applications. TURN ensures that a connection can be established even 475 when one or both sides is incapable of a direct P2P connection. 476 However, as a relay service, it imposes a nontrivial cost on the 477 service provider. Therefore, access to a TURN service is almost 478 always access-controlled. In order to achieve third party 479 authorization, a resource owner e.g. WebRTC server, authorizes a 480 TURN client to access resources on the TURN server. 482 Consider the following example that illustrates the use of OAuth 2.0 483 to achieve third party authorization for TURN. In this example, a 484 resource owner i.e., WebRTC server, authorizes a TURN client to 485 access resources on a TURN server. 487 +----------------------+----------------------------+ 488 | OAuth 2.0 | WebRTC | 489 +======================+============================+ 490 | Client | WebRTC client | 491 +----------------------+----------------------------+ 492 | Resource owner | WebRTC server | 493 +----------------------+----------------------------+ 494 | Authorization server | Authorization server | 495 +----------------------+----------------------------+ 496 | Resource server | TURN Server | 497 +----------------------+----------------------------+ 499 Figure 2: OAuth terminology mapped to WebRTC terminology 501 Using the OAuth 2.0 authorization framework, a WebRTC client (third- 502 party application) obtains limited access to a TURN (resource server) 503 on behalf of the WebRTC server (resource owner or authorization 504 server). The WebRTC client requests access to resources controlled 505 by the resource owner (WebRTC server) and hosted by the resource 506 server (TURN server). The WebRTC client obtains access token, 507 lifetime, session key and kid. The TURN client conveys the access 508 token and other OAuth 2.0 parameters learnt from the authorization 509 server to the TURN server. The TURN server obtains the session key 510 from the access token. The TURN server validates the token, computes 511 the message integrity of the request and takes appropriate action 512 i.e, permits the TURN client to create allocations. This is shown in 513 an abstract way in Figure 3. 515 +---------------+ 516 | +<******+ 517 +------------->| Authorization | * 518 | | Server | * 519 | +----------|(WebRTC Server)| * AS-RS, 520 | | | | * AUTH keys 521 (2) | | +---------------+ * (1) 522 Access | | (3) * 523 Token | | Access Token * 524 Request | | + * 525 | | Session Key * 526 | | * 527 | V V 528 +-------+---+ +-+----=-----+ 529 | | (4) | | 530 | | TURN Request + Access | | 531 | WebRTC | Token | TURN | 532 | Client |---------------------->| Server | 533 | (Alice) | Allocate Response (5) | | 534 | |<----------------------| | 535 +-----------+ +------------+ 537 User : Alice 538 ****: Out-of-Band Long-Term Key Establishment 540 Figure 3: Interactions 542 In the below figure, the client sends an Allocate request to the 543 server without credentials. Since the server requires that all 544 requests be authenticated using OAuth 2.0, the server rejects the 545 request with a 401 (Unauthorized) error code and STUN attribute 546 THIRD-PARTY-AUTHORIZATION. The WebRTC client obtains access token 547 from the WebRTC server and then tries again, this time including 548 access token. This time, the server validates the token, accepts the 549 Allocate request and returns an Allocate success response containing 550 (amongst other things) the relayed transport address assigned to the 551 allocation. 553 +-------------------+ +--------+ +---------+ 554 | ......... TURN | | TURN | | WebRTC | 555 | .WebRTC . Client | | | | | 556 | .Client . | | Server | | Server | 557 | ......... | | | | | 558 +-------------------+ +--------+ +---------+ 559 | | Allocate request | | 560 | |------------------------------------------>| | 561 | | | | 562 | | Allocate error response | | 563 | | (401 Unauthorized) | | 564 | |<------------------------------------------| | 565 | | THIRD-PARTY-AUTHORIZATION | | 566 | | | | 567 | | | | 568 | | HTTP Request for token | | 569 |------------------------------------------------------------>| 570 | | HTTP Response with token parameters | | 571 |<------------------------------------------------------------| 572 |OAuth 2.0 | | 573 Attributes | | 574 |------>| | | 575 | | Allocate request ACCESS-TOKEN | | 576 | |------------------------------------------>| | 577 | | | | 578 | | Allocate success response | | 579 | |<------------------------------------------| | 580 | | TURN Messages | | 581 | | ////// integrity protected ////// | | 582 | | ////// integrity protected ////// | | 583 | | ////// integrity protected ////// | | 585 Figure 4: TURN Third Party Authorization 587 Changes specific to TURN are listed below: 589 o The access token can be reused for multiple Allocate requests to 590 the same TURN server. The TURN client MUST include the ACCESS- 591 TOKEN attribute only in Allocate and Refresh requests. Since the 592 access token is valid for a specific period of time, the TURN 593 server can cache it so that it can check if the access token in a 594 new allocation request matches one of the cached tokens and avoids 595 the need to decrypt the token. 597 o The lifetime provided by the TURN server in the Allocate and 598 Refresh responses MUST be less than or equal to the lifetime of 599 the token. It is RECOMMENDED that the TURN server calculate the 600 maximum allowed lifetime value using the formula: 602 lifetime + Delta - abs(RDnew - TS) 604 The RECOMMENDED value for the allowed Delta is 5 seconds. 606 o If the access token expires then the client MUST obtain a new 607 token from the authorization server and use it for new 608 allocations. The client MUST use the new token to refresh 609 existing allocations. This way client has to maintain only one 610 token per TURN server. 612 10. Operational Considerations 614 The following operational considerations should be taken into 615 account: 617 o Each authorization server should maintain the list of STUN servers 618 for which it will grant tokens, and the long-term secret shared 619 with each of those STUN servers. 621 o If manual configuration (Section 4.1.3) is used to establish 622 symmetric keys, the necessary information which includes long-term 623 key (K), encryption and HMAC algorithms have to be configured on 624 each authorization server and STUN server for each kid. The 625 client obtains the session key and HMAC algorithm from the 626 authorization server in company with the token. 628 o When a STUN client sends a request to get access to a particular 629 STUN server (S) the authorization server must ensure that it 630 selects the appropriate kid, access-token depending on the server 631 S. 633 11. Security Considerations 635 When OAuth 2.0 is used the interaction between the client and the 636 authorization server requires Transport Layer Security (TLS) with a 637 ciphersuite offering confidentiality protection. The session key 638 MUST NOT be transmitted in clear since this would completely destroy 639 the security benefits of the proposed scheme. An attacker trying to 640 replay message with ACCESS-TOKEN attribute can be mitigated by 641 frequent changes of nonce value as discussed in section 10.2 of 642 [RFC5389]. The client may know some (but not all) of the token 643 fields encrypted with a unknown secret key and the token can be 644 subjected to known-plaintext attack, but AES is secure against this 645 attack. 647 An attacker may remove the THIRD-PARTY-AUTHORIZATION STUN attribute 648 from the error message forcing the client to pick first party 649 authentication, this attack may be mitigated by opting for Transport 650 Layer Security (TLS) [RFC5246] or Datagram Transport Layer Security 651 (DTLS) [RFC6347] as a transport protocol for Session Traversal 652 Utilities for NAT (STUN), as defined in [RFC5389]and [RFC7350]. 654 Threat mitigation discussed in section 5 of 655 [I-D.ietf-oauth-pop-architecture] and security considerations in 656 [RFC5389] are to be taken into account. 658 12. IANA Considerations 660 [Paragraphs below in braces should be removed by the RFC Editor upon 661 publication] 663 [IANA is requested to add the following attributes to the STUN 664 attribute registry [iana-stun], The THIRD-PARTY-AUTHORIZATION 665 attribute requires that IANA allocate a value in the "STUN attributes 666 Registry" from the comprehension-optional range (0x8000-0xBFFF)] 668 This document defines the THIRD-PARTY-AUTHORIZATION STUN attribute, 669 described in Section 6. IANA has allocated the comprehension- 670 optional codepoint TBD for this attribute. 672 [The ACCESS-TOKEN attribute requires that IANA allocate a value in 673 the "STUN attributes Registry" from the comprehension-required range 674 (0x0000-0x3FFF)] 676 This document defines the ACCESS-TOKEN STUN attribute, described in 677 Section 6. IANA has allocated the comprehension-required codepoint 678 TBD for this attribute. 680 13. Acknowledgements 682 Authors would like to thank Dan Wing, Pal Martinsen, Oleg Moskalenko, 683 Charles Eckel, Spencer Dawkins, Hannes Tschofenig, Yaron Sheffer and 684 Tom Taylor for comments and review. The authors would like to give 685 special thanks to Brandon Williams for his help. 687 Thanks to Oleg Moskalenko for providing ticket samples in the 688 Appendix section. 690 14. References 692 14.1. Normative References 694 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 695 Requirement Levels", BCP 14, RFC 2119, March 1997. 697 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 698 Encodings", RFC 4648, October 2006. 700 [RFC4868] Kelly, S. and S. Frankel, "Using HMAC-SHA-256, HMAC-SHA- 701 384, and HMAC-SHA-512 with IPsec", RFC 4868, May 2007. 703 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 704 Encryption", RFC 5116, January 2008. 706 [RFC5389] Rosenberg, J., Mahy, R., Matthews, P., and D. Wing, 707 "Session Traversal Utilities for NAT (STUN)", RFC 5389, 708 October 2008. 710 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 711 6749, October 2012. 713 [iana-stun] 714 IANA, , "IANA: STUN Attributes", April 2011, 715 . 718 14.2. Informative References 720 [I-D.ietf-jose-json-web-algorithms] 721 Jones, M., "JSON Web Algorithms (JWA)", draft-ietf-jose- 722 json-web-algorithms-40 (work in progress), January 2015. 724 [I-D.ietf-oauth-pop-architecture] 725 Hunt, P., Richer, J., Mills, W., Mishra, P., and H. 726 Tschofenig, "OAuth 2.0 Proof-of-Possession (PoP) Security 727 Architecture", draft-ietf-oauth-pop-architecture-00 (work 728 in progress), July 2014. 730 [I-D.ietf-oauth-pop-key-distribution] 731 Bradley, J., Hunt, P., Jones, M., and H. Tschofenig, 732 "OAuth 2.0 Proof-of-Possession: Authorization Server to 733 Client Key Distribution", draft-ietf-oauth-pop-key- 734 distribution-00 (work in progress), July 2014. 736 [I-D.ietf-rtcweb-overview] 737 Alvestrand, H., "Overview: Real Time Protocols for 738 Browser-based Applications", draft-ietf-rtcweb-overview-13 739 (work in progress), November 2014. 741 [I-D.ietf-tram-stunbis] 742 Petit-Huguenin, M., Salgueiro, G., Rosenberg, J., Wing, 743 D., Mahy, R., and P. Matthews, "Session Traversal 744 Utilities for NAT (STUN)", draft-ietf-tram-stunbis-00 745 (work in progress), November 2014. 747 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 748 Hashing for Message Authentication", RFC 2104, February 749 1997. 751 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 752 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 754 [RFC5766] Mahy, R., Matthews, P., and J. Rosenberg, "Traversal Using 755 Relays around NAT (TURN): Relay Extensions to Session 756 Traversal Utilities for NAT (STUN)", RFC 5766, April 2010. 758 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 759 Key Derivation Function (HKDF)", RFC 5869, May 2010. 761 [RFC6063] Doherty, A., Pei, M., Machani, S., and M. Nystrom, 762 "Dynamic Symmetric Key Provisioning Protocol (DSKPP)", RFC 763 6063, December 2010. 765 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 766 Security Version 1.2", RFC 6347, January 2012. 768 [RFC6819] Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 769 Threat Model and Security Considerations", RFC 6819, 770 January 2013. 772 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 773 Interchange Format", RFC 7159, March 2014. 775 [RFC7350] Petit-Huguenin, M. and G. Salgueiro, "Datagram Transport 776 Layer Security (DTLS) as Transport for Session Traversal 777 Utilities for NAT (STUN)", RFC 7350, August 2014. 779 [RFC7376] Reddy, T., Ravindranath, R., Perumal, M., and A. Yegin, 780 "Problems with Session Traversal Utilities for NAT (STUN) 781 Long-Term Authentication for Traversal Using Relays around 782 NAT (TURN)", RFC 7376, September 2014. 784 Appendix A. Sample tickets 786 Input data (same for all samples below): 788 //STUN SERVER NAME 789 server_name = "blackdow.carleon.gov"; 791 //Shared key between AS and RS 793 long_term_key = \x48\x47\x6b\x6a\x33\x32\x4b\x4a\x47\x69\x75\x79 794 \x30\x39\x38\x73\x64\x66\x61\x71\x62\x4e\x6a\x4f 795 \x69\x61\x7a\x37\x31\x39\x32\x33; 797 //MAC key of the session (included in the token) 798 mac_key = \x5a\x6b\x73\x6a\x70\x77\x65\x6f\x69\x78\x58\x6d\x76\x6e 799 \x36\x37\x35\x33\x34\x6d; 801 //length of the MAC key 802 mac_key_length = 20; 804 //The timestamp field in the token 805 token_timestamp = 92470300704768; 807 //The lifetime of the token 808 token_lifetime = 3600; 810 //nonce for AEAD when AEAD is used 811 aead_nonce = \x68\x34\x6a\x03\x6b\x32\x6c\x32\6E\0x4\0x62\0x05; 813 Samples: 815 1) 816 hkdf hash function = SHA-256, 817 token encryption algorithm = AES-256-CBC 818 token auth algorithm = HMAC-SHA-256 820 Result: 821 AS_RS key (32 bytes) = \xd\x7e\x54\x5b\x7e\x15\xc9\x81\x8c\x81\x4b\x83 822 \xdc\x4e\xce\x24\x55\xde\x73\xe\xab\x8\x8a\x94 823 \xc4\x29\xab\x45\xfd\x61\xa\xb5 825 AUTH key (32 bytes) = \xd\x7e\x54\x5b\x7e\x15\xc9\x81\x8c\x81\x4b\x83 826 \xdc\x4e\xce\x24\x55\xde\x73\xe\xab\x8\x8a\x94 827 \xc4\x29\xab\x45\xfd\x61\xa\xb5 829 Encrypted token (80 bytes = 48+32) = 831 \x1b\xb6\x4b\x4f\xbf\x99\x6d\x60\x55\xda\xf3\x9f\xa1\xed\x3\x73\x4e 832 \x1c\x95\x64\x84\xc1\xeb\xc3\x63\x9b\x70\xe6\xb8\x21\x45\xe6\x45\xa0 833 \x23\xaf\xc1\xee\x87\x91\x7b\xea\xb8\x4a\x7f\x80\xb2\x0\xa5\xad\x14 834 \x97\x17\xf9\xbc\xfa\xa1\xc6\x2f\x4d\xfc\xaf\xc1\xc5\x11\xc5\x55\x7d 835 \xb0\x35\x58\xcf\xc6\xce\x6e\x10\x7\xd1\x98\xbd 836 2) 838 hkdf hash function = SHA-256, 839 token encryption algorithm = AEAD_AES_256_GCM 840 token auth algorithm = N/A 842 Result: 843 AS_RS key (32 bytes) = \xd\x7e\x54\x5b\x7e\x15\xc9\x81\x8c\x81\x4b\x83 844 \xdc\x4e\xce\x24\x55\xde\x73\xe\xab\x8\x8a\x94 845 \xc4\x29\xab\x45\xfd\x61\xa\xb5 846 AUTH key = N/A 848 Encrypted token (62 bytes = 34 + 16 + 12) = 850 \xa8\x52\x90\x64\xc7\xd9\x3b\x6c\xe\x9\xe\xcf\x9e\x7d\x0\x70\x47\xe2 851 \x99\x8d\xe3\x31\xe1\x39\x20\xed\x88\x90\x4\xd8\xcf\x82\x93\x3f\xc6\ 852 x4\xd1\xaa\xe6\xf5\x62\xea\x3c\x94\x45\x8\x3d\xfa\xe9\x5f\x68\x34\x6a 853 \x33\x6b\x32\x6c\x32\x6e\x34\x62\x35 855 3) 857 hkdf hash function = SHA-1, 858 token encryption algorithm = AES-128-CBC 859 token auth algorithm = HMAC-SHA-256-128 861 Result: 862 AS_RS key (16 bytes) = \x8c\x48\x5f\x1e\x1\x3a\xc6\x50\x36\x70\x84\x37 863 \xa5\x4e\xd7\x70 864 AUTH key (32 bytes) = \x8c\x48\x5f\x1e\x1\x3a\xc6\x50\x36\x70\x84\x37 865 \xa5\x4e\xd7\x70\x17\xcc\xcd\xa1\x7c\xd7\x8\x39 866 \xfa\xc8\xee\x14\xf9\x77\xb4\xcf 868 Encrypted token (64 bytes = 48+16) = 870 \x13\xcd\x17\x4a\xde\x54\xe1\xe6\x65\xe6\xbb\x3a\xb9\x4d\x1c\xf7\x3b 871 \x60\x31\x8b\xc4\x7\x4b\x3b\x5f\x1c\xda\xf4\x60\x4\x7\x88\x8e\xc9\xc7 872 \xd3\xf4\x71\x94\x87\x85\xd9\xad\xf7\x6a\xda\x77\x4e\x11\x13\x8d\x8e 873 \xe8\x93\x9\x76\xa3\x85\x96\x1f\x5e\xd3\xc4\x55 875 Figure 5: Sample tickets 877 Appendix B. Interaction between client and authorization server 879 Client could make an HTTP request to an authorization server to 880 obtain a token that can be used to avail itself of STUN services. 881 The STUN token is returned in JSON syntax [RFC7159], along with other 882 OAuth 2.0 parameters like token type, key, token lifetime and kid 883 defined in [I-D.ietf-oauth-pop-key-distribution]. 885 +-------------------+ +--------+ +---------+ 886 | ......... STUN | | STUN | | WebRTC | 887 | .WebRTC . Client | | | | | 888 | .Client . | | Server | | Server | 889 | ......... | | | | | 890 +-------------------+ +--------+ +---------+ 891 | | STUN request | | 892 | |------------------------------------------>| | 893 | | | | 894 | | STUN error response | | 895 | | (401 Unauthorized) | | 896 | |<------------------------------------------| | 897 | | THIRD-PARTY-AUTHORIZATION | | 898 | | | | 899 | | | | 900 | | HTTP Request for token | | 901 |------------------------------------------------------------>| 902 | | HTTP Response with token parameters | | 903 |<------------------------------------------------------------| 904 |OAuth 2.0 | | 905 Attributes | | 906 |------>| | | 907 | | STUN request with ACCESS-TOKEN | | 908 | |------------------------------------------>| | 909 | | | | 910 | | STUN success response | | 911 | |<------------------------------------------| | 912 | | STUN Messages | | 913 | | ////// integrity protected ////// | | 914 | | ////// integrity protected ////// | | 915 | | ////// integrity protected ////// | | 917 Figure 6: STUN Third Party Authorization 919 [I-D.ietf-oauth-pop-key-distribution] describes the interaction 920 between the client and the authorization server. For example, the 921 client learns the STUN server name "stun1@example.com" from THIRD- 922 PARTY-AUTHORIZATION attribute value and makes the following HTTP 923 request for the access token using transport-layer security (with 924 extra line breaks for display purposes only): 926 HTTP/1.1 927 Host: server.example.com 928 Content-Type: application/x-www-form-urlencoded 929 aud=stun1@example.com 930 timestamp=1361471629 931 grant_type=implicit 932 token_type=pop 933 alg=HMAC-SHA-1 HMAC-SHA-256-128 935 Figure 7: Request 937 [I-D.ietf-tram-stunbis] will support hash agility and accomplish this 938 agility by conveying the HMAC algorithms supported by the STUN server 939 along with a STUN error message to the client. The client then 940 signals the intersection-set of algorithms supported by it and the 941 STUN server to the authorization server in the 'alg' parameter 942 defined in [I-D.ietf-oauth-pop-key-distribution]. The authorization 943 server selects an HMAC algorithm from the list of algorithms the 944 client provided and determines length of the mac_key based on the 945 selected HMAC algorithm. Note that until STUN supports hash agility 946 HMAC-SHA1 is the only valid hash algorithm that the client can signal 947 to the authorization server and vice-versa. 949 If the client is authorized then the authorization server issues an 950 access token. An example of successful response: 952 HTTP/1.1 200 OK 953 Content-Type: application/json 954 Cache-Control: no-store 956 { 957 "access_token": 958 "U2FsdGVkX18qJK/kkWmRcnfHglrVTJSpS6yU32kmHmOrfGyI3m1gQj1jRPsr0uBb 959 HctuycAgsfRX7nJW2BdukGyKMXSiNGNnBzigkAofP6+Z3vkJ1Q5pWbfSRroOkWBn", 960 "token_type":"pop", 961 "expires_in":1800, 962 "kid":"22BIjxU93h/IgwEb", 963 "key":"v51N62OM65kyMvfTI08O" 964 "alg":HMAC-SHA-256-128 965 } 967 Figure 8: Response 969 Authors' Addresses 970 Tirumaleswar Reddy 971 Cisco Systems, Inc. 972 Cessna Business Park, Varthur Hobli 973 Sarjapur Marathalli Outer Ring Road 974 Bangalore, Karnataka 560103 975 India 977 Email: tireddy@cisco.com 979 Prashanth Patil 980 Cisco Systems, Inc. 981 Bangalore 982 India 984 Email: praspati@cisco.com 986 Ram Mohan Ravindranath 987 Cisco Systems, Inc. 988 Cessna Business Park, 989 Kadabeesanahalli Village, Varthur Hobli, 990 Sarjapur-Marathahalli Outer Ring Road 991 Bangalore, Karnataka 560103 992 India 994 Email: rmohanr@cisco.com 996 Justin Uberti 997 Google 998 747 6th Ave S 999 Kirkland, WA 1000 98033 1001 USA 1003 Email: justin@uberti.name