idnits 2.17.1 draft-ietf-tram-turn-third-party-authz-13.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 13 instances of too long lines in the document, the longest one being 17 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (February 25, 2015) is 3346 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-01 -- 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: 2 errors (**), 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 29, 2015 Cisco 6 J. Uberti 7 Google 8 February 25, 2015 10 Session Traversal Utilities for NAT (STUN) Extension for Third Party 11 Authorization 12 draft-ietf-tram-turn-third-party-authz-13 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 29, 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 . . . . . . . . . . . . . . . . . . 16 77 14.2. Informative References . . . . . . . . . . . . . . . . . 16 78 Appendix A. Sample tickets . . . . . . . . . . . . . . . . . . . 18 79 Appendix B. Interaction between client and authorization server 20 80 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22 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 like WebRTC [I-D.ietf-rtcweb-overview] where JavaScript uses the 91 browser functionality to make real-time audio and/or video calls, Web 92 conferencing, and direct data transfer, ensuring this secrecy is 93 typically not possible. 95 To address this problem and the ones described in [RFC7376], this 96 document proposes the use of third party authorization using OAuth 97 2.0 [RFC6749] for STUN. Using OAuth 2.0, a client obtains an 98 ephemeral token from an authorization server e.g. WebRTC server, and 99 the token is presented to the STUN server instead of the traditional 100 mechanism of presenting username/password credentials. The STUN 101 server validates the authenticity of the token and provides required 102 services. Third party authorization using OAuth 2.0 for STUN 103 explained in this specification can also be used with Traversal Using 104 Relays around NAT (TURN) [RFC5766]. 106 2. Terminology 108 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 109 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 110 document are to be interpreted as described in [RFC2119]. 112 o WebRTC Server: A web server that supports WebRTC 113 [I-D.ietf-rtcweb-overview]. 115 o Access Token: OAuth 2.0 access token. 117 o mac_key: The session key generated by the authorization server. 118 This session key has a lifetime that corresponds to the lifetime 119 of the access token, is generated by the authorization server and 120 bound to the access token. 122 o kid: An ephemeral and unique key identifier. The kid also allows 123 the resource server to select the appropriate keying material for 124 decryption. 126 Some sections in this specification show WebRTC server as the 127 authorization server and client as the WebRTC client, however WebRTC 128 is intended to be used for illustrative purpose only. 130 3. Solution Overview 132 STUN client knows that it can use OAuth 2.0 with the target STUN 133 server either through configuration or when it receives the new STUN 134 attribute THIRD-PARTY-AUTHORIZATION in the error response with an 135 error code of 401(Unauthorized). 137 This specification uses the token type 'Assertion' (aka self- 138 contained token) described in [RFC6819] where all the information 139 necessary to authenticate the validity of the token is contained 140 within the token itself. This approach has the benefit of avoiding a 141 protocol between the STUN server and the authorization server for 142 token validation, thus reducing latency. The content of the token is 143 opaque to the client. The client embeds the token within a STUN 144 request sent to the STUN server. Once the STUN server has determined 145 the token is valid, its services are offered for a determined period 146 of time. Access token issued by the authorization server is 147 explained in Section 6.2. OAuth 2.0 in [RFC6749] defines four grant 148 types. This specification uses the OAuth 2.0 grant type "Implicit" 149 explained in section 1.3.2 of [RFC6749] where the client is issued an 150 access token directly. The string 'stun' is defined by this 151 specification for use as the OAuth scope parameter (see section 3.3 152 of [RFC6749]) for the OAuth token. 154 The exact mechanism used by a client to obtain a token from the OAuth 155 2.0 authorization server is outside the scope of this document. 156 Appendix B provides an example deployment scenario of interaction 157 between the client and authorization server to obtain a token. 159 4. Obtaining a Token Using OAuth 161 A STUN client needs to know the authentication capability of the STUN 162 server before deciding to use third party authorization. A STUN 163 client initially makes a request without any authorization. If the 164 STUN server supports third party authorization, it will return an 165 error message indicating that the client can authorize to the STUN 166 server using an OAuth 2.0 access token. The STUN server includes an 167 ERROR-CODE attribute with a value of 401 (Unauthorized), a nonce 168 value in a NONCE attribute and a SOFTWARE attribute that gives 169 information about the STUN server's software. The STUN server also 170 includes the additional STUN attribute THIRD-PARTY-AUTHORIZATION 171 signaling the STUN client that the STUN server supports third party 172 authorization. 174 Note: An implementation may choose to contact the authorization 175 server to obtain a token even before it makes a STUN request, if it 176 knows the server details before hand. For example, once a client has 177 learnt that a STUN server supports third party authorization from a 178 authorization server, the client can obtain the token before making 179 subsequent STUN requests. 181 4.1. Key Establishment 183 The authorization server shares a long-term secret (like asymmetric 184 credentials) with the STUN server for mutual authentication. 185 Symmetric-key algorithm with Hash based Message Authentication Codes 186 (HMACs) MUST be chosen to ensure that the size of encrypted token is 187 not large because usage of asymmetric keys will result in large 188 encrypted tokens which may not fit into a single STUN message. 190 The STUN server and authorization server can establish a symmetric 191 key (K), using an out of band mechanism. If symmetric key is used 192 then the AS-RS and AUTH keys will be derived from K. The AS-RS key 193 is used for encrypting the self-contained token and the message 194 integrity of the encrypted token is calculated using the AUTH key. 195 The STUN and authorization servers MUST establish the symmetric key 196 over an authenticated secure channel. 198 The procedure for establishment of the symmetric key is outside the 199 scope of this specification, and this specification does not mandate 200 support of any given mechanism. Section 4.1.1, Section 4.1.2 and 201 Section 4.1.3 show examples of mechanisms that can be used. 203 4.1.1. DSKPP 205 The STUN and AS servers could choose to use Dynamic Symmetric Key 206 Provisioning Protocol (DSKPP) [RFC6063] to establish a symmetric key 207 (K). The encryption and MAC algorithms will be negotiated using the 208 KeyProvClientHello, KeyProvServerHello messages. A unique key 209 identifier (referred to as KeyID) for the symmetric key is generated 210 by the DSKPP server (i.e., Authorization server) and signalled to the 211 DSKPP client (i.e., STUN server) which is equivalent to the kid 212 defined in this specification. The AS-RS, AUTH keys would be derived 213 from the symmetric key using (HMAC)-based key derivation function 214 (HKDF) [RFC5869] and the default hash function MUST be SHA-256. For 215 example if the input symmetric key (K) is 32 octets length, 216 encryption algorithm is AES_256_CBC and HMAC algorithm is HMAC-SHA1 217 [RFC2104] then the secondary keys AS-RS, AUTH are generated from the 218 input key K as follows 220 1. HKDF-Extract(zero, K) -> PRK 222 2. HKDF-Expand(PRK, "AUTH key", 20) -> AUTH key 224 3. HKDF-Expand(PRK, "AS-RS key", 32) -> AS-RS key 226 If Authenticated Encryption with Associated Data (AEAD) algorithm 227 defined in [RFC5116] is used then there is no need to generate the 228 AUTH key. AEAD simplifies implementation, since it involves only one 229 key, the user of AEAD need not consider relative order of encrypting 230 and authenticating the token and other benefits of AEAD are explained 231 in Section 1.3 of [RFC5116]. 233 4.1.2. HTTP interactions 235 The STUN and AS servers could choose to use REST API over HTTPS to 236 establish a symmetric key. HTTPS MUST be used for mutual 237 authentication and confidentiality. To retrieve a new symmetric key, 238 the STUN server makes an HTTP GET request to the authorization 239 server, specifying STUN as the service to allocate the symmetric keys 240 for, and specifying the name of the STUN server. The response is 241 returned with content-type "application/json", and consists of a 242 JavaScript Object Notation (JSON) [RFC7159] object containing the 243 symmetric key. 245 Request 246 ------- 248 service - specifies the desired service (turn) 249 name - STUN server name be associated with the key 251 example: GET /?service=stun&name=turn1@example.com 253 Response 254 -------- 256 k - Long-term key (K) 257 exp - identifies the time after which the key expires. 259 example: 260 { 261 "k" : 262 "ESIzRFVmd4iZABEiM0RVZgKn6WjLaTC1FXAghRMVTzkBGNaaN496523WIISKerLi", 263 "exp" : 1300819380, 264 "kid" :"22BIjxU93h/IgwEb" 265 "enc" : A256CBC-HS512 266 } 268 The AS-RS, AUTH keys are derived from K using HKDF as discussed in 269 Section 4.1.1. The authorization server must also signal kid to the 270 STUN server which will be used to select the appropriate keying 271 material for decryption. The parameter "k" is defined in 272 Section 6.4.1 of [I-D.ietf-jose-json-web-algorithms], "enc" is 273 defined in Section 4.1.2 of [I-D.ietf-jose-json-web-encryption], 274 "kid" is defined in Section 4.1.4 of 275 [I-D.ietf-jose-json-web-signature] and "exp" is defined in 276 Section 4.1.4 of [I-D.ietf-oauth-json-web-token]. A256CBC-HS512 and 277 other authenticated encryption algorithms are defined in 278 [I-D.ietf-jose-json-web-algorithms]. In this case AS-RS key length 279 must be 256-bit, AUTH key length must be 256-bit (section 2.6 of 280 [RFC4868]). 282 4.1.3. Manual provisioning 284 The STUN and AS servers could be manually configured with a symmetric 285 key (K) and kid. If manual provisioning is supported, support MUST 286 also be provided for AES_256_CBC_HMAC_SHA_512 (explained in 288 [I-D.ietf-jose-json-web-algorithms]) as the authenticated encryption 289 algorithm. 291 Note : The mechanism specified in Section 4.1.3 compared to DSKPP and 292 REST lacks encryption and HMAC algorithm agility. 294 5. Forming a Request 296 When a STUN server responds that third party authorization is 297 required, a STUN client re-attempts the request, this time including 298 access token and kid values in ACCESS-TOKEN and USERNAME STUN 299 attributes. The STUN client includes a MESSAGE-INTEGRITY attribute 300 as the last attribute in the message over the contents of the STUN 301 message. The HMAC for the MESSAGE-INTEGRITY attribute is computed as 302 described in section 15.4 of [RFC5389] where the mac_key is used as 303 the input key for the HMAC computation. The STUN client and server 304 will use the mac_key to compute the message integrity and do not 305 perform MD5 hash on the credentials. 307 6. STUN Attributes 309 The following new STUN attributes are introduced by this 310 specification to accomplish third party authorization. 312 6.1. THIRD-PARTY-AUTHORIZATION 314 This attribute is used by the STUN server to inform the client that 315 it supports third party authorization. This attribute value contains 316 the STUN server name. The STUN server may have tie-ups with multiple 317 authorization servers and vice versa, so the client MUST provide the 318 STUN server name to the authorization server so that it can select 319 the appropriate keying material to generate the self-contained token. 320 The THIRD-PARTY-AUTHORIZATION attribute is a comprehension-optional 321 attribute (see Section 15 from [RFC5389]). If the client is able to 322 comprehend THIRD-PARTY-AUTHORIZATION it MUST ensure that third party 323 authorization takes precedence over first party authentication 324 (explained in section 10 of [RFC5389]). If the client does not 325 support or is not capable of doing third party authorization then it 326 defaults to first party authentication. 328 6.2. ACCESS-TOKEN 330 The access token is issued by the authorization server. OAuth 2.0 331 does not impose any limitation on the length of the access token but 332 if path MTU is unknown then STUN messages over IPv4 would need to be 333 less than 548 bytes (Section 7.1 of [RFC5389]). The access token 334 length needs to be restricted to fit within the maximum STUN message 335 size. Note that the self-contained token is opaque to the client and 336 the client MUST NOT examine the token. The ACCESS-TOKEN attribute is 337 a comprehension-required attribute (see Section 15 from [RFC5389]). 339 The token is structured as follows: 341 struct { 342 opaque { 343 uint16_t key_length; 344 opaque mac_key[key_length]; 345 uint64_t timestamp; 346 uint32_t lifetime; 347 uint8_t padding_length; 348 uint8_t padding[padding_length]; 349 } encrypted_block; 350 opaque mac[mac_length]; 351 uint8_t mac_length; 352 } token; 354 Figure 1: Self-contained token format 356 Note: uintN_t means an unsigned integer of exactly N bits. Single- 357 byte entities containing uninterpreted data are of type opaque. All 358 values in the token are stored in network byte order. 360 The fields are described below: 362 key_length: Length of the session key in octets. Key length of 363 160-bits MUST be supported (i.e., only 160-bit key is used by 364 HMAC-SHA-1 for message integrity of STUN message). The key length 365 facilitates the hash agility plan discussed in section 16.3 of 366 [RFC5389]. 368 mac_key: The session key generated by the authorization server. 370 timestamp: 64-bit unsigned integer field containing a timestamp. 371 The value indicates the time since January 1, 1970, 00:00 UTC, by 372 using a fixed point format. In this format, the integer number of 373 seconds is contained in the first 48 bits of the field, and the 374 remaining 16 bits indicate the number of 1/64K fractions of a 375 second (Native format - Unix). 377 lifetime: The lifetime of the access token, in seconds. For 378 example, the value 3600 indicates one hour. The lifetime value 379 MUST be greater than or equal to the "expires_in" parameter 380 defined in section 4.2.2 of [RFC6749], otherwise resource server 381 could revoke the token but the client would assume that the token 382 has not expired and would not refresh the token. 384 padding_length: The padding length MUST be such that the total size 385 of the encrypted_block structure is a multiple of the cipher's 386 block length. 388 padding: Padding that is added to force the length of the plaintext 389 to be an integral multiple of the block cipher's block length. 391 encrypted_block: The encrypted_block is encrypted using the 392 symmetric long-term key established between the STUN server and 393 the authorization server. Shown in Figure 3 as AS-RS key. 395 mac: The Hashed Message Authentication Code (HMAC) is calculated 396 with the AUTH key over the 'encrypted_block' and the STUN server 397 name (N) conveyed in the THIRD-PARTY-AUTHORIZATION response. This 398 ensures that the client does not use the same token to gain 399 illegal access to other STUN servers provided by the same 400 administrative domain i.e., when multiple STUN servers in a single 401 administrative domain share the same symmetric key with an 402 authorization server. 404 mac_length: Length of the mac field. 406 An example encryption process is illustrated below. Here C, N denote 407 Ciphertext and STUN server name respectively. 409 o C = AES_256_CBC(AS-RS, encrypted_block) 411 * Initialization vector can be set to zero because the 412 encrypted_block in each access token will not be identical and 413 hence will not result in generation of identical ciphertext. 415 o mac = HMAC-SHA-256-128(AUTH, C | | N) 417 Encryption is applied before message authentication on the sender 418 side and conversely on the receiver side. The entire token i.e., the 419 'encrypted_block' and 'mac' is base64 encoded (see section 4 of 420 [RFC4648]) and the resulting access token is signaled to the client. 421 If AEAD algorithm is used then there is no need to explicitly compute 422 HMAC, the associated data MUST be the STUN server name (N) and the 423 mac field MUST carry the nonce. The length of nonce for AEAD 424 algorithms is explained in [RFC5116]. 426 7. STUN Server Behaviour 428 The STUN server, on receiving a request with ACCESS-TOKEN attribute, 429 performs checks listed in section 10.2.2 of [RFC5389] in addition to 430 the following steps to verify that the access token is valid: 432 o STUN server selects the keying material based on kid signalled in 433 the USERNAME attribute. 435 o It performs the verification of the token message integrity by 436 calculating HMAC over the encrypted portion in the self-contained 437 token and STUN server name using AUTH key and if the resulting 438 value does not match the mac field in the self-contained token 439 then it rejects the request with an error response 401 440 (Unauthorized). If AEAD algorithm is used then it has only a 441 single output, either a plaintext or a special symbol FAIL that 442 indicates that the inputs are not authentic. 444 o STUN server obtains the mac_key by retrieving the content of the 445 access token (which requires decryption of the self-contained 446 token using the AS-RS key). 448 o The STUN server verifies that no replay took place by performing 449 the following check: 451 * The access token is accepted if the timestamp field (TS) in the 452 self-contained token is recent enough to the reception time of 453 the STUN request (RDnew) using the following formula: Lifetime 454 + Delta > abs(RDnew - TS). The RECOMMENDED value for the 455 allowed Delta is 5 seconds. If the timestamp is NOT within the 456 boundaries then the STUN server discards the request with error 457 response 401 (Unauthorized). 459 o The STUN server uses the mac_key to compute the message integrity 460 over the request and if the resulting value does not match the 461 contents of the MESSAGE-INTEGRITY attribute then it rejects the 462 request with an error response 401 (Unauthorized). 464 o If all the checks pass, the STUN server continues to process the 465 request. Any response generated by the server MUST include the 466 MESSAGE-INTEGRITY attribute, computed using the mac_key. 468 If a STUN server receives an ACCESS-TOKEN attribute unexpectedly 469 (because it had not previously sent out a THIRD-PARTY-AUTHORIZATION), 470 it will respond with an error code of 420 (Unknown Attribute) as 471 specified in Section 7.3.1 of [RFC5389]. 473 8. STUN Client Behaviour 475 o The client looks for the MESSAGE-INTEGRITY attribute in the 476 response. If MESSAGE-INTEGRITY is absent or the value computed 477 for message integrity using mac_key does not match the contents of 478 the MESSAGE-INTEGRITY attribute then the response MUST be 479 discarded. 481 o If the access token expires then the client MUST obtain a new 482 token from the authorization server and use it for new STUN 483 requests. 485 9. Usage with TURN 487 Traversal Using Relay NAT (TURN) [RFC5766] an extension to the STUN 488 protocol is often used to improve the connectivity of P2P 489 applications. TURN ensures that a connection can be established even 490 when one or both sides is incapable of a direct P2P connection. 491 However, as a relay service, it imposes a nontrivial cost on the 492 service provider. Therefore, access to a TURN service is almost 493 always access-controlled. In order to achieve third party 494 authorization, a resource owner e.g. WebRTC server, authorizes a 495 TURN client to access resources on the TURN server. 497 Consider the following example that illustrates the use of OAuth 2.0 498 to achieve third party authorization for TURN. In this example, a 499 resource owner i.e., WebRTC server, authorizes a TURN client to 500 access resources on a TURN server. 502 +----------------------+----------------------------+ 503 | OAuth 2.0 | WebRTC | 504 +======================+============================+ 505 | Client | WebRTC client | 506 +----------------------+----------------------------+ 507 | Resource owner | WebRTC server | 508 +----------------------+----------------------------+ 509 | Authorization server | Authorization server | 510 +----------------------+----------------------------+ 511 | Resource server | TURN Server | 512 +----------------------+----------------------------+ 514 Figure 2: OAuth terminology mapped to WebRTC terminology 516 Using the OAuth 2.0 authorization framework, a WebRTC client (third- 517 party application) obtains limited access to a TURN (resource server) 518 on behalf of the WebRTC server (resource owner or authorization 519 server). The WebRTC client requests access to resources controlled 520 by the resource owner (WebRTC server) and hosted by the resource 521 server (TURN server). The WebRTC client obtains access token, 522 lifetime, session key and kid. The TURN client conveys the access 523 token and other OAuth 2.0 parameters learnt from the authorization 524 server to the TURN server. The TURN server obtains the session key 525 from the access token. The TURN server validates the token, computes 526 the message integrity of the request and takes appropriate action 527 i.e, permits the TURN client to create allocations. This is shown in 528 an abstract way in Figure 3. 530 +---------------+ 531 | +<******+ 532 +------------->| Authorization | * 533 | | Server | * 534 | +----------|(WebRTC Server)| * AS-RS, 535 | | | | * AUTH keys 536 (2) | | +---------------+ * (1) 537 Access | | (3) * 538 Token | | Access Token * 539 Request | | + * 540 | | Session Key * 541 | | * 542 | V V 543 +-------+---+ +-+----=-----+ 544 | | (4) | | 545 | | TURN Request + Access | | 546 | WebRTC | Token | TURN | 547 | Client |---------------------->| Server | 548 | (Alice) | Allocate Response (5) | | 549 | |<----------------------| | 550 +-----------+ +------------+ 552 User : Alice 553 ****: Out-of-Band Long-Term Key Establishment 555 Figure 3: Interactions 557 In the below figure, the client sends an Allocate request to the 558 server without credentials. Since the server requires that all 559 requests be authenticated using OAuth 2.0, the server rejects the 560 request with a 401 (Unauthorized) error code and STUN attribute 561 THIRD-PARTY-AUTHORIZATION. The WebRTC client obtains access token 562 from the WebRTC server and then tries again, this time including 563 access token. This time, the server validates the token, accepts the 564 Allocate request and returns an Allocate success response containing 565 (amongst other things) the relayed transport address assigned to the 566 allocation. 568 +-------------------+ +--------+ +---------+ 569 | ......... TURN | | TURN | | WebRTC | 570 | .WebRTC . Client | | | | | 571 | .Client . | | Server | | Server | 572 | ......... | | | | | 573 +-------------------+ +--------+ +---------+ 574 | | Allocate request | | 575 | |------------------------------------------>| | 576 | | | | 577 | | Allocate error response | | 578 | | (401 Unauthorized) | | 579 | |<------------------------------------------| | 580 | | THIRD-PARTY-AUTHORIZATION | | 581 | | | | 582 | | | | 583 | | HTTP Request for token | | 584 |------------------------------------------------------------>| 585 | | HTTP Response with token parameters | | 586 |<------------------------------------------------------------| 587 |OAuth 2.0 | | 588 Attributes | | 589 |------>| | | 590 | | Allocate request ACCESS-TOKEN | | 591 | |------------------------------------------>| | 592 | | | | 593 | | Allocate success response | | 594 | |<------------------------------------------| | 595 | | TURN Messages | | 596 | | ////// integrity protected ////// | | 597 | | ////// integrity protected ////// | | 598 | | ////// integrity protected ////// | | 600 Figure 4: TURN Third Party Authorization 602 Changes specific to TURN are listed below: 604 o The access token can be reused for multiple Allocate requests to 605 the same TURN server. The TURN client MUST include the ACCESS- 606 TOKEN attribute only in Allocate and Refresh requests. Since the 607 access token is valid for a specific period of time, the TURN 608 server can cache it so that it can check if the access token in a 609 new allocation request matches one of the cached tokens and avoids 610 the need to decrypt the token. 612 o The lifetime provided by the TURN server in the Allocate and 613 Refresh responses MUST be less than or equal to the lifetime of 614 the token. It is RECOMMENDED that the TURN server calculate the 615 maximum allowed lifetime value using the formula: 617 lifetime + Delta - abs(RDnew - TS) 619 The RECOMMENDED value for the allowed Delta is 5 seconds. 621 o If the access token expires then the client MUST obtain a new 622 token from the authorization server and use it for new 623 allocations. The client MUST use the new token to refresh 624 existing allocations. This way client has to maintain only one 625 token per TURN server. 627 10. Operational Considerations 629 The following operational considerations should be taken into 630 account: 632 o Each authorization server should maintain the list of STUN servers 633 for which it will grant tokens, and the long-term secret shared 634 with each of those STUN servers. 636 o If manual configuration (Section 4.1.3) is used to establish 637 symmetric keys, the necessary information which includes long-term 638 key (K), encryption and HMAC algorithms have to be configured on 639 each authorization server and STUN server for each kid. The 640 client obtains the session key and HMAC algorithm from the 641 authorization server in company with the token. 643 o When a STUN client sends a request to get access to a particular 644 STUN server (S) the authorization server must ensure that it 645 selects the appropriate kid, access-token depending on the server 646 S. 648 11. Security Considerations 650 When OAuth 2.0 is used the interaction between the client and the 651 authorization server requires Transport Layer Security (TLS) with a 652 ciphersuite offering confidentiality protection and the guidance 653 given in [I-D.ietf-uta-tls-bcp] must be followed to avoid attacks on 654 TLS. The session key MUST NOT be transmitted in clear since this 655 would completely destroy the security benefits of the proposed 656 scheme. An attacker trying to replay message with ACCESS-TOKEN 657 attribute can be mitigated by frequent changes of nonce value as 658 discussed in section 10.2 of [RFC5389]. The client may know some 659 (but not all) of the token fields encrypted with a unknown secret key 660 and the token can be subjected to known-plaintext attack, but AES is 661 secure against this attack. 663 An attacker may remove the THIRD-PARTY-AUTHORIZATION STUN attribute 664 from the error message forcing the client to pick first party 665 authentication, this attack may be mitigated by opting for Transport 666 Layer Security (TLS) [RFC5246] or Datagram Transport Layer Security 667 (DTLS) [RFC6347] as a transport protocol for Session Traversal 668 Utilities for NAT (STUN), as defined in [RFC5389]and [RFC7350]. 670 Threat mitigation discussed in section 5 of 671 [I-D.ietf-oauth-pop-architecture] and security considerations in 672 [RFC5389] are to be taken into account. 674 12. IANA Considerations 676 [Paragraphs below in braces should be removed by the RFC Editor upon 677 publication] 679 [IANA is requested to add the following attributes to the STUN 680 attribute registry [iana-stun], The THIRD-PARTY-AUTHORIZATION 681 attribute requires that IANA allocate a value in the "STUN attributes 682 Registry" from the comprehension-optional range (0x8000-0xBFFF)] 684 This document defines the THIRD-PARTY-AUTHORIZATION STUN attribute, 685 described in Section 6. IANA has allocated the comprehension- 686 optional codepoint TBD for this attribute. 688 [The ACCESS-TOKEN attribute requires that IANA allocate a value in 689 the "STUN attributes Registry" from the comprehension-required range 690 (0x0000-0x3FFF)] 692 This document defines the ACCESS-TOKEN STUN attribute, described in 693 Section 6. IANA has allocated the comprehension-required codepoint 694 TBD for this attribute. 696 13. Acknowledgements 698 Authors would like to thank Dan Wing, Pal Martinsen, Oleg Moskalenko, 699 Charles Eckel, Spencer Dawkins, Hannes Tschofenig, Yaron Sheffer, Tom 700 Taylor, Christer Holmberg, Pete Resnick, Kathleen Moriarty, Richard 701 Barnes, Stephen Farrell and Alissa Cooper for comments and review. 702 The authors would like to give special thanks to Brandon Williams for 703 his help. 705 Thanks to Oleg Moskalenko for providing token samples in the 706 Appendix section. 708 14. References 709 14.1. Normative References 711 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 712 Requirement Levels", BCP 14, RFC 2119, March 1997. 714 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 715 Encodings", RFC 4648, October 2006. 717 [RFC4868] Kelly, S. and S. Frankel, "Using HMAC-SHA-256, HMAC-SHA- 718 384, and HMAC-SHA-512 with IPsec", RFC 4868, May 2007. 720 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 721 Encryption", RFC 5116, January 2008. 723 [RFC5389] Rosenberg, J., Mahy, R., Matthews, P., and D. Wing, 724 "Session Traversal Utilities for NAT (STUN)", RFC 5389, 725 October 2008. 727 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 728 6749, October 2012. 730 [iana-stun] 731 IANA, , "IANA: STUN Attributes", April 2011, 732 . 735 14.2. Informative References 737 [I-D.ietf-jose-json-web-algorithms] 738 Jones, M., "JSON Web Algorithms (JWA)", draft-ietf-jose- 739 json-web-algorithms-40 (work in progress), January 2015. 741 [I-D.ietf-jose-json-web-encryption] 742 Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 743 draft-ietf-jose-json-web-encryption-40 (work in progress), 744 January 2015. 746 [I-D.ietf-jose-json-web-signature] 747 Jones, M., Bradley, J., and N. Sakimura, "JSON Web 748 Signature (JWS)", draft-ietf-jose-json-web-signature-41 749 (work in progress), January 2015. 751 [I-D.ietf-oauth-json-web-token] 752 Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 753 (JWT)", draft-ietf-oauth-json-web-token-32 (work in 754 progress), December 2014. 756 [I-D.ietf-oauth-pop-architecture] 757 Hunt, P., Richer, J., Mills, W., Mishra, P., and H. 758 Tschofenig, "OAuth 2.0 Proof-of-Possession (PoP) Security 759 Architecture", draft-ietf-oauth-pop-architecture-00 (work 760 in progress), July 2014. 762 [I-D.ietf-oauth-pop-key-distribution] 763 Bradley, J., Hunt, P., Jones, M., and H. Tschofenig, 764 "OAuth 2.0 Proof-of-Possession: Authorization Server to 765 Client Key Distribution", draft-ietf-oauth-pop-key- 766 distribution-00 (work in progress), July 2014. 768 [I-D.ietf-rtcweb-overview] 769 Alvestrand, H., "Overview: Real Time Protocols for 770 Browser-based Applications", draft-ietf-rtcweb-overview-13 771 (work in progress), November 2014. 773 [I-D.ietf-tram-stunbis] 774 Petit-Huguenin, M., Salgueiro, G., Rosenberg, J., Wing, 775 D., Mahy, R., and P. Matthews, "Session Traversal 776 Utilities for NAT (STUN)", draft-ietf-tram-stunbis-01 777 (work in progress), February 2015. 779 [I-D.ietf-uta-tls-bcp] 780 Sheffer, Y., Holz, R., and P. Saint-Andre, 781 "Recommendations for Secure Use of TLS and DTLS", draft- 782 ietf-uta-tls-bcp-11 (work in progress), February 2015. 784 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 785 Hashing for Message Authentication", RFC 2104, February 786 1997. 788 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 789 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 791 [RFC5766] Mahy, R., Matthews, P., and J. Rosenberg, "Traversal Using 792 Relays around NAT (TURN): Relay Extensions to Session 793 Traversal Utilities for NAT (STUN)", RFC 5766, April 2010. 795 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 796 Key Derivation Function (HKDF)", RFC 5869, May 2010. 798 [RFC6063] Doherty, A., Pei, M., Machani, S., and M. Nystrom, 799 "Dynamic Symmetric Key Provisioning Protocol (DSKPP)", RFC 800 6063, December 2010. 802 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 803 Security Version 1.2", RFC 6347, January 2012. 805 [RFC6819] Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 806 Threat Model and Security Considerations", RFC 6819, 807 January 2013. 809 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 810 Interchange Format", RFC 7159, March 2014. 812 [RFC7350] Petit-Huguenin, M. and G. Salgueiro, "Datagram Transport 813 Layer Security (DTLS) as Transport for Session Traversal 814 Utilities for NAT (STUN)", RFC 7350, August 2014. 816 [RFC7376] Reddy, T., Ravindranath, R., Perumal, M., and A. Yegin, 817 "Problems with Session Traversal Utilities for NAT (STUN) 818 Long-Term Authentication for Traversal Using Relays around 819 NAT (TURN)", RFC 7376, September 2014. 821 Appendix A. Sample tickets 823 Input data (same for all samples below): 825 //STUN SERVER NAME 826 server_name = "blackdow.carleon.gov"; 828 //Shared key between AS and RS 830 long_term_key = \x48\x47\x6b\x6a\x33\x32\x4b\x4a\x47\x69\x75\x79 831 \x30\x39\x38\x73\x64\x66\x61\x71\x62\x4e\x6a\x4f 832 \x69\x61\x7a\x37\x31\x39\x32\x33; 834 //MAC key of the session (included in the token) 835 mac_key = \x5a\x6b\x73\x6a\x70\x77\x65\x6f\x69\x78\x58\x6d\x76\x6e 836 \x36\x37\x35\x33\x34\x6d; 838 //length of the MAC key 839 mac_key_length = 20; 841 //The timestamp field in the token 842 token_timestamp = 92470300704768; 844 //The lifetime of the token 845 token_lifetime = 3600; 847 //nonce for AEAD when AEAD is used 848 aead_nonce = \x68\x34\x6a\x33\x6b\x32\x6c\x32\x6e\x34\x62\x35; 850 Samples: 852 1) 853 hkdf hash function = SHA-256, 854 token encryption algorithm = AES-256-CBC 855 token auth algorithm = HMAC-SHA-256 857 Result: 858 AS_RS key (32 bytes) = \xd8\xa4\x54\x1\x68\xb\xb8\x7c\x6c\x86 859 \xc5\x29\x3e\x35\x33\x91\x9b\x51\xfc\xf9 860 \xde\x25\x19\xa9\xa3\x56\x2b\x51\x7b\xe2\x76\x4f 862 AUTH key (32 bytes) = \x72\xe1\xf9\xc9\xfe\xb9\xe7\xd8\x2a\xcc\x2d 863 \xc3\x33\xd4\x2f\xc1\x7f\x3e\x36\x29\xfa\xf8\x50 864 \x16\x5c\xcf\x60\xd1\x67\xb9\x8f\x76 866 Encrypted token (80 bytes = 48+32) = 868 \x26\x6\x38\x82\xfa\x74\xa6\x2\x6a\xa6\xa4\x37\x30\xac\x83\xc6\x45\x51 869 \x5c\x9e\x3e\xea\x86\x11\xb9\x4e\x8c\x27\x38\x8a\x51\xa7\xd\xc\x74\x72 870 \xdf\xb8\x12\x6a\x8e\x17\xb3\x50\x16\x10\xee\x7e\x53\xe1\x90\x6e\x3b\x37 871 \xda\x17\x57\xb1\xa2\x6\x64\x5c\x63\x79\x33\x34\x7d\xab\x71\x56\x98\x2b 872 \x1\xa6\x66\x29\xce\xb1\xa5\xb4 874 2) 876 hkdf hash function = SHA-256, 877 token encryption algorithm = AEAD_AES_256_GCM 878 token auth algorithm = N/A 880 Result: 881 AS_RS key (32 bytes) = \xd8\xa4\x54\x1\x68\xb\xb8\x7c\x6c\x86\xc5\x29\x3e 882 \x35\x33\x91\x9b\x51\xfc\xf9\xde\x25\x19\xa9\xa3\x56 883 \x2b\x51\x7b\xe2\x76\x4f 884 AUTH key = N/A 886 Encrypted token (62 bytes = 34 + 16 + 12) = 888 \xd4\x86\x5c\x5d\x59\xfb\x3f\xe3\xf6\xf1\xd8\xc3\x22\xc2\x22\x26\x8d\x2e\xf0 889 \xbe\x2\x5b\xbd\x13\x49\x89\x6e\xa5\xc5\x51\xee\xee\x7f\xd9\xe4\x41\xd7\xcb 890 \x51\x20\x40\xcc\xc5\x53\x90\x2f\xdc\xbb\x8d\x53\x68\x34\x6a\x33\x6b\x32\x6c 891 \x32\x6e\x34\x62\x35 893 3) 895 hkdf hash function = SHA-1, 896 token encryption algorithm = AES-128-CBC 897 token auth algorithm = HMAC-SHA-256-128 899 Result: 901 AS_RS key (16 bytes) = \x22\x93\xd1\x4\xae\x29\x73\x3e\xcd\x1a\x18\xbd\x56\x45\x63\x67 902 AUTH key (32 bytes) = \x00\xd2\x70\x78\x60\xc7\x54\xbb\x34\x3e\x4c\xd0\xcc\x03\x66\x9c 903 \x2e\x1a\x89\xe0\xee\x97\xb7\x8e\x36\x4b\x76\xb0\x39\x46\x19\x4a 905 Encrypted token (64 bytes = 48+16) = 907 \xf8\xef\x95\xdc\x6b\x35\x50\x8a\x6a\x36\x8f\xd9\xdc\x51\x92\x0c\x39\x2f\xcb\xf0\x1e 908 \x2f\x66\x8d\xbc\x50\xb8\x30\x7c\xd9\x04\xf6\x27\xb0\x9e\x73\xdc\x15\xc8\x96\xfb\x4e 909 \x3b\x5b\xe3\xc7\x54\x20\xc0\xd2\x90\x88\x08\x3d\x72\x9c\xd2\x17\x65\x43\x8f\xaa 910 \x41\x48 912 Figure 5: Sample tickets 914 Appendix B. Interaction between client and authorization server 916 Client makes an HTTP request to an authorization server to obtain a 917 token that can be used to avail itself of STUN services. The STUN 918 token is returned in JSON syntax [RFC7159], along with other OAuth 919 2.0 parameters like token type, key, token lifetime and kid defined 920 in [I-D.ietf-oauth-pop-key-distribution]. 922 +-------------------+ +--------+ +---------+ 923 | ......... STUN | | STUN | | WebRTC | 924 | .WebRTC . Client | | | | | 925 | .Client . | | Server | | Server | 926 | ......... | | | | | 927 +-------------------+ +--------+ +---------+ 928 | | STUN request | | 929 | |------------------------------------------>| | 930 | | | | 931 | | STUN error response | | 932 | | (401 Unauthorized) | | 933 | |<------------------------------------------| | 934 | | THIRD-PARTY-AUTHORIZATION | | 935 | | | | 936 | | | | 937 | | HTTP Request for token | | 938 |------------------------------------------------------------>| 939 | | HTTP Response with token parameters | | 940 |<------------------------------------------------------------| 941 |OAuth 2.0 | | 942 Attributes | | 943 |------>| | | 944 | | STUN request with ACCESS-TOKEN | | 945 | |------------------------------------------>| | 946 | | | | 947 | | STUN success response | | 948 | |<------------------------------------------| | 949 | | STUN Messages | | 950 | | ////// integrity protected ////// | | 951 | | ////// integrity protected ////// | | 952 | | ////// integrity protected ////// | | 954 Figure 6: STUN Third Party Authorization 956 [I-D.ietf-oauth-pop-key-distribution] describes the interaction 957 between the client and the authorization server. For example, the 958 client learns the STUN server name "stun1@example.com" from THIRD- 959 PARTY-AUTHORIZATION attribute value and makes the following HTTP 960 request for the access token using transport-layer security (with 961 extra line breaks for display purposes only): 963 HTTP/1.1 964 Host: server.example.com 965 Content-Type: application/x-www-form-urlencoded 966 aud=stun1@example.com 967 timestamp=1361471629 968 grant_type=implicit 969 token_type=pop 970 alg=HMAC-SHA-1 HMAC-SHA-256-128 972 Figure 7: Request 974 [I-D.ietf-tram-stunbis] will support hash agility and accomplish this 975 agility by conveying the HMAC algorithms supported by the STUN server 976 along with a STUN error message to the client. The client then 977 signals the intersection-set of algorithms supported by it and the 978 STUN server to the authorization server in the 'alg' parameter 979 defined in [I-D.ietf-oauth-pop-key-distribution]. The authorization 980 server selects an HMAC algorithm from the list of algorithms the 981 client provided and determines length of the mac_key based on the 982 selected HMAC algorithm. Note that until STUN supports hash agility 983 HMAC-SHA1 is the only valid hash algorithm that the client can signal 984 to the authorization server and vice-versa. 986 If the client is authorized then the authorization server issues an 987 access token. An example of successful response: 989 HTTP/1.1 200 OK 990 Content-Type: application/json 991 Cache-Control: no-store 993 { 994 "access_token": 995 "U2FsdGVkX18qJK/kkWmRcnfHglrVTJSpS6yU32kmHmOrfGyI3m1gQj1jRPsr0uBb 996 HctuycAgsfRX7nJW2BdukGyKMXSiNGNnBzigkAofP6+Z3vkJ1Q5pWbfSRroOkWBn", 997 "token_type":"pop", 998 "expires_in":1800, 999 "kid":"22BIjxU93h/IgwEb", 1000 "key":"v51N62OM65kyMvfTI08O" 1001 "alg":HMAC-SHA-256-128 1002 } 1004 Figure 8: Response 1006 Authors' Addresses 1007 Tirumaleswar Reddy 1008 Cisco Systems, Inc. 1009 Cessna Business Park, Varthur Hobli 1010 Sarjapur Marathalli Outer Ring Road 1011 Bangalore, Karnataka 560103 1012 India 1014 Email: tireddy@cisco.com 1016 Prashanth Patil 1017 Cisco Systems, Inc. 1018 Bangalore 1019 India 1021 Email: praspati@cisco.com 1023 Ram Mohan Ravindranath 1024 Cisco Systems, Inc. 1025 Cessna Business Park, 1026 Kadabeesanahalli Village, Varthur Hobli, 1027 Sarjapur-Marathahalli Outer Ring Road 1028 Bangalore, Karnataka 560103 1029 India 1031 Email: rmohanr@cisco.com 1033 Justin Uberti 1034 Google 1035 747 6th Ave S 1036 Kirkland, WA 1037 98033 1038 USA 1040 Email: justin@uberti.name