idnits 2.17.1 draft-ietf-tram-turn-third-party-authz-14.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 == Line 327 has weird spacing: '... opaque nonce...' -- The document date (April 15, 2015) is 3292 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-01 == Outdated reference: A later version (-07) exists of draft-ietf-oauth-pop-key-distribution-01 == 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-04 -- 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 (~~), 6 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: October 17, 2015 Cisco 6 J. Uberti 7 Google 8 April 15, 2015 10 Session Traversal Utilities for NAT (STUN) Extension for Third Party 11 Authorization 12 draft-ietf-tram-turn-third-party-authz-14 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 October 17, 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. HTTP interactions . . . . . . . . . . . . . . . . . . 5 62 4.1.2. Manual provisioning . . . . . . . . . . . . . . . . . 7 63 5. Forming a Request . . . . . . . . . . . . . . . . . . . . . . 7 64 6. STUN Attributes . . . . . . . . . . . . . . . . . . . . . . . 7 65 6.1. THIRD-PARTY-AUTHORIZATION . . . . . . . . . . . . . . . . 7 66 6.2. ACCESS-TOKEN . . . . . . . . . . . . . . . . . . . . . . 8 67 7. STUN Server Behaviour . . . . . . . . . . . . . . . . . . . . 10 68 8. STUN Client Behaviour . . . . . . . . . . . . . . . . . . . . 11 69 9. Usage with TURN . . . . . . . . . . . . . . . . . . . . . . . 11 70 10. Operational Considerations . . . . . . . . . . . . . . . . . 15 71 11. Security Considerations . . . . . . . . . . . . . . . . . . . 15 72 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 73 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 16 74 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 16 75 14.1. Normative References . . . . . . . . . . . . . . . . . . 17 76 14.2. Informative References . . . . . . . . . . . . . . . . . 17 77 Appendix A. Sample tickets . . . . . . . . . . . . . . . . . . . 19 78 Appendix B. Interaction between client and authorization server 20 79 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22 81 1. Introduction 83 Session Traversal Utilities for NAT (STUN) [RFC5389] provides a 84 mechanism to control access via "long-term" username/ password 85 credentials that are provided as part of the STUN protocol. It is 86 expected that these credentials will be kept secret; if the 87 credentials are discovered, the STUN server could be used by 88 unauthorized users or applications. However, in web applications 89 like WebRTC [I-D.ietf-rtcweb-overview] where JavaScript uses the 90 browser functionality to make real-time audio and/or video calls, Web 91 conferencing, and direct data transfer, ensuring this secrecy is 92 typically not possible. 94 To address this problem and the ones described in [RFC7376], this 95 document proposes the use of third party authorization using OAuth 96 2.0 [RFC6749] for STUN. Using OAuth 2.0, a client obtains an 97 ephemeral token from an authorization server e.g. WebRTC server, and 98 the token is presented to the STUN server instead of the traditional 99 mechanism of presenting username/password credentials. The STUN 100 server validates the authenticity of the token and provides required 101 services. Third party authorization using OAuth 2.0 for STUN 102 explained in this specification can also be used with Traversal Using 103 Relays around NAT (TURN) [RFC5766]. 105 2. Terminology 107 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 108 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 109 document are to be interpreted as described in [RFC2119]. 111 o WebRTC Server: A web server that supports WebRTC 112 [I-D.ietf-rtcweb-overview]. 114 o Access Token: OAuth 2.0 access token. 116 o mac_key: The session key generated by the authorization server. 117 This session key has a lifetime that corresponds to the lifetime 118 of the access token, is generated by the authorization server and 119 bound to the access token. 121 o kid: An ephemeral and unique key identifier. The kid also allows 122 the resource server to select the appropriate keying material for 123 decryption. 125 Some sections in this specification show WebRTC server as the 126 authorization server and client as the WebRTC client, however WebRTC 127 is intended to be used for illustrative purpose only. 129 3. Solution Overview 131 STUN client knows that it can use OAuth 2.0 with the target STUN 132 server either through configuration or when it receives the new STUN 133 attribute THIRD-PARTY-AUTHORIZATION in the error response with an 134 error code of 401(Unauthorized). 136 This specification uses the token type 'Assertion' (aka self- 137 contained token) described in [RFC6819] where all the information 138 necessary to authenticate the validity of the token is contained 139 within the token itself. This approach has the benefit of avoiding a 140 protocol between the STUN server and the authorization server for 141 token validation, thus reducing latency. The content of the token is 142 opaque to the client. The client embeds the token within a STUN 143 request sent to the STUN server. Once the STUN server has determined 144 the token is valid, its services are offered for a determined period 145 of time. Access token issued by the authorization server is 146 explained in Section 6.2. OAuth 2.0 in [RFC6749] defines four grant 147 types. This specification uses the OAuth 2.0 grant type "Implicit" 148 explained in section 1.3.2 of [RFC6749] where the client is issued an 149 access token directly. The string 'stun' is defined by this 150 specification for use as the OAuth scope parameter (see section 3.3 151 of [RFC6749]) for the OAuth token. 153 The exact mechanism used by a client to obtain a token from the OAuth 154 2.0 authorization server is outside the scope of this document. 155 Appendix B provides an example deployment scenario of interaction 156 between the client and authorization server to obtain a token. 158 4. Obtaining a Token Using OAuth 160 A STUN client needs to know the authentication capability of the STUN 161 server before deciding to use third party authorization. A STUN 162 client initially makes a request without any authorization. If the 163 STUN server supports third party authorization, it will return an 164 error message indicating that the client can authorize to the STUN 165 server using an OAuth 2.0 access token. The STUN server includes an 166 ERROR-CODE attribute with a value of 401 (Unauthorized), a nonce 167 value in a NONCE attribute and a SOFTWARE attribute that gives 168 information about the STUN server's software. The STUN server also 169 includes the additional STUN attribute THIRD-PARTY-AUTHORIZATION 170 signaling the STUN client that the STUN server supports third party 171 authorization. 173 Note: An implementation may choose to contact the authorization 174 server to obtain a token even before it makes a STUN request, if it 175 knows the server details before hand. For example, once a client has 176 learnt that a STUN server supports third party authorization from a 177 authorization server, the client can obtain the token before making 178 subsequent STUN requests. 180 4.1. Key Establishment 182 In this model the STUN server would not authenticate the client 183 itself but would rather verify whether the client knows the session 184 key associated with a specific access token. Example of this 185 approach can be found with the OAuth 2.0 Proof-of-Possession (PoP) 186 Security Architecture [I-D.ietf-oauth-pop-architecture]. The 187 authorization server shares a long-term secret (K) with the STUN 188 server. When the client requests an access token the authorization 189 server creates a fresh and unique session key (mac_key) and places it 190 into the token encrypted with the long term secret. Symmetric 191 cryptography MUST be chosen to ensure that the size of encrypted 192 token is not large because usage of asymmetric cryptography will 193 result in large encrypted tokens which may not fit into a single STUN 194 message. 196 The STUN server and authorization server can establish a symmetric 197 key (K) and certain authenticated encryption algorithm, using an out 198 of band mechanism. The STUN and authorization servers MUST establish 199 K over an authenticated secure channel. If Authenticated Encryption 200 with AES-CBC and HMAC-SHA (defined in 201 [I-D.mcgrew-aead-aes-cbc-hmac-sha2]) is used then the AS-RS and AUTH 202 keys will be derived from K. The AS-RS key is used for encrypting 203 the self-contained token and the message integrity of the encrypted 204 token is calculated using the AUTH key. If Authenticated Encryption 205 with Associated Data (AEAD) algorithm defined in [RFC5116] is used 206 then there is no need to generate the AUTH key and AS-RS key will 207 have the same value as K. 209 The procedure for establishment of the symmetric key is outside the 210 scope of this specification, and this specification does not mandate 211 support of any given mechanism. Section 4.1.1 and Section 4.1.2 show 212 examples of mechanisms that can be used. 214 4.1.1. HTTP interactions 216 The STUN and AS servers could choose to use REST API over HTTPS to 217 establish a symmetric key. HTTPS MUST be used for mutual 218 authentication and confidentiality. To retrieve a new symmetric key, 219 the STUN server makes an HTTP GET request to the authorization 220 server, specifying STUN as the service to allocate the symmetric keys 221 for, and specifying the name of the STUN server. The response is 222 returned with content-type "application/json", and consists of a 223 JavaScript Object Notation (JSON) [RFC7159] object containing the 224 symmetric key. 226 Request 227 ------- 229 service - specifies the desired service (turn) 230 name - STUN server name be associated with the key 232 example: GET /?service=stun&name=turn1@example.com 234 Response 235 -------- 237 k - Long-term key (K) 238 exp - identifies the time after which the key expires. 240 example: 241 { 242 "k" : 243 "ESIzRFVmd4iZABEiM0RVZgKn6WjLaTC1FXAghRMVTzkBGNaaN496523WIISKerLi", 244 "exp" : 1300819380, 245 "kid" :"22BIjxU93h/IgwEb" 246 "enc" : A256GCMKW 247 } 249 The authorization server must also signal kid to the STUN server 250 which will be used to select the appropriate keying material for 251 decryption. The parameter "k" is defined in Section 6.4.1 of 252 [I-D.ietf-jose-json-web-algorithms], "enc" is defined in 253 Section 4.1.2 of [I-D.ietf-jose-json-web-encryption], "kid" is 254 defined in Section 4.1.4 of [I-D.ietf-jose-json-web-signature] and 255 "exp" is defined in Section 4.1.4 of [I-D.ietf-oauth-json-web-token]. 256 A256GCMKW and other authenticated encryption algorithms are defined 257 in [I-D.ietf-jose-json-web-algorithms]. A STUN server and 258 authorization server implementation MUST support A256GCMKW as the 259 authenticated encryption algorithm. 261 If A256CBC-HS512 defined in [I-D.ietf-jose-json-web-algorithms] is 262 used then the AS-RS and AUTH keys are derived from K using the 263 mechanism explained in section 5.2.2.1 of 264 [I-D.ietf-jose-json-web-algorithms]. In this case AS-RS key length 265 must be 256-bit, AUTH key length must be 256-bit (section 2.6 of 266 [RFC4868]). 268 4.1.2. Manual provisioning 270 The STUN and AS servers could be manually configured with a symmetric 271 key (K), authenticated encryption algorithm and kid. 273 Note : The mechanism specified in Section 4.1.2 requires 274 configuration to change the symmetric key (K) and/or authenticated 275 encryption algorithm. Hence a STUN server and authorization server 276 implementation SHOULD support REST explained in Section 4.1.1. 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 token. The ACCESS-TOKEN attribute is 321 a comprehension-required attribute (see Section 15 from [RFC5389]). 323 The token is structured as follows: 325 struct { 326 uint16_t nonce_length; 327 opaque nonce[nonce_length]; 328 opaque { 329 uint16_t key_length; 330 opaque mac_key[key_length]; 331 uint64_t timestamp; 332 uint32_t lifetime; 333 } encrypted_block; 334 } token; 336 Figure 1: Self-contained token format 338 Note: uintN_t means an unsigned integer of exactly N bits. Single- 339 byte entities containing uninterpreted data are of type opaque. All 340 values in the token are stored in network byte order. 342 The associated data (A) MUST be the STUN server name. This ensures 343 that the client does not use the same token to gain illegal access to 344 other STUN servers provided by the same administrative domain i.e., 345 when multiple STUN servers in a single administrative domain share 346 the same symmetric key with an authorization server. 348 The fields are described below: 350 nonce_length: Length of the nonce field. The length of nonce for 351 authenticated encryption with additional data (AEAD) algorithms is 352 explained in [RFC5116]. 354 Nonce: Nonce (N) formation is explained in section 3.2 of [RFC5116]. 356 key_length: Length of the session key in octets. Key length of 357 160-bits MUST be supported (i.e., only 160-bit key is used by 358 HMAC-SHA-1 for message integrity of STUN message). The key length 359 facilitates the hash agility plan discussed in section 16.3 of 360 [RFC5389]. 362 mac_key: The session key generated by the authorization server. 364 timestamp: 64-bit unsigned integer field containing a timestamp. 365 The value indicates the time since January 1, 1970, 00:00 UTC, by 366 using a fixed point format. In this format, the integer number of 367 seconds is contained in the first 48 bits of the field, and the 368 remaining 16 bits indicate the number of 1/64K fractions of a 369 second (Native format - Unix). 371 lifetime: The lifetime of the access token, in seconds. For 372 example, the value 3600 indicates one hour. The lifetime value 373 MUST be greater than or equal to the "expires_in" parameter 374 defined in section 4.2.2 of [RFC6749], otherwise resource server 375 could revoke the token but the client would assume that the token 376 has not expired and would not refresh the token. 378 encrypted_block: The encrypted_block (P) is encrypted and 379 authenticated using the symmetric long-term key established 380 between the STUN server and the authorization server. 382 The AEAD encryption operation has four inputs: K , N, A, and P, as 383 defined in section 2.1 of [RFC5116] and there is a single output a 384 ciphertext C or an indication that the requested encryption operation 385 could not be performed. 387 If AES_CBC_HMAC_SHA2 (explained in section 2.1 of 388 [I-D.mcgrew-aead-aes-cbc-hmac-sha2])) is used then the encryption 389 process is illustrated below. The ciphertext consists of the string 390 S, with the string T appended to it. Here C and A denote Ciphertext 391 and STUN server name respectively. The octet string AL (section 2.1 392 of [I-D.mcgrew-aead-aes-cbc-hmac-sha2]) is equal to the number of 393 bits in A expressed as a 64-bit unsigned big endian integer. 395 o AUTH = initial authentication key length octets of K, 397 o AS-RS = final encryption key length octets of K, 399 o S = CBC-PKCS5-ENC(AS-RS, encrypted_block), 401 * Initialization vector is set to zero because the 402 encrypted_block in each access token will not be identical and 403 hence will not result in generation of identical ciphertext. 405 o mac = MAC(AUTH, A || S || AL), 406 o T = initial T_LEN octets of mac, 408 o C = S || T. 410 The entire token i.e., the 'encrypted_block' is base64 encoded (see 411 section 4 of [RFC4648]) and the resulting access token is signaled to 412 the client. 414 7. STUN Server Behaviour 416 The STUN server, on receiving a request with ACCESS-TOKEN attribute, 417 performs checks listed in section 10.2.2 of [RFC5389] in addition to 418 the following steps to verify that the access token is valid: 420 o STUN server selects the keying material based on kid signalled in 421 the USERNAME attribute. 423 o The AEAD decryption operation has four inputs: K, N, A, and C, as 424 defined in section 2.2 of [RFC5116]. AEAD decryption algorithm 425 has only a single output, either a plaintext or a special symbol 426 FAIL that indicates that the inputs are not authentic. If 427 authenticated decrypt operation returns FAIL then the STUN server 428 rejects the request with an error response 401 (Unauthorized). 430 o If AES_CBC_HMAC_SHA2 is used then the final T_LEN octets are 431 stripped from C. It performs the verification of the token 432 message integrity by calculating HMAC over the the STUN server 433 name, the encrypted portion in the self-contained token and the AL 434 using AUTH key and if the resulting value does not match the mac 435 field in the self-contained token then it rejects the request with 436 an error response 401 (Unauthorized). 438 o STUN server obtains the mac_key by retrieving the content of the 439 access token (which requires decryption of the self-contained 440 token using the AS-RS key). 442 o The STUN server verifies that no replay took place by performing 443 the following check: 445 * The access token is accepted if the timestamp field (TS) in the 446 self-contained token is recent enough to the reception time of 447 the STUN request (RDnew) using the following formula: Lifetime 448 + Delta > abs(RDnew - TS). The RECOMMENDED value for the 449 allowed Delta is 5 seconds. If the timestamp is NOT within the 450 boundaries then the STUN server discards the request with error 451 response 401 (Unauthorized). 453 o The STUN server uses the mac_key to compute the message integrity 454 over the request and if the resulting value does not match the 455 contents of the MESSAGE-INTEGRITY attribute then it rejects the 456 request with an error response 401 (Unauthorized). 458 o If all the checks pass, the STUN server continues to process the 459 request. Any response generated by the server MUST include the 460 MESSAGE-INTEGRITY attribute, computed using the mac_key. 462 If a STUN server receives an ACCESS-TOKEN attribute unexpectedly 463 (because it had not previously sent out a THIRD-PARTY-AUTHORIZATION), 464 it will respond with an error code of 420 (Unknown Attribute) as 465 specified in Section 7.3.1 of [RFC5389]. 467 8. STUN Client Behaviour 469 o The client looks for the MESSAGE-INTEGRITY attribute in the 470 response. If MESSAGE-INTEGRITY is absent or the value computed 471 for message integrity using mac_key does not match the contents of 472 the MESSAGE-INTEGRITY attribute then the response MUST be 473 discarded. 475 o If the access token expires then the client MUST obtain a new 476 token from the authorization server and use it for new STUN 477 requests. 479 9. Usage with TURN 481 Traversal Using Relay NAT (TURN) [RFC5766] an extension to the STUN 482 protocol is often used to improve the connectivity of P2P 483 applications. TURN ensures that a connection can be established even 484 when one or both sides is incapable of a direct P2P connection. 485 However, as a relay service, it imposes a nontrivial cost on the 486 service provider. Therefore, access to a TURN service is almost 487 always access-controlled. In order to achieve third party 488 authorization, a resource owner e.g. WebRTC server, authorizes a 489 TURN client to access resources on the TURN server. 491 Consider the following example that illustrates the use of OAuth 2.0 492 to achieve third party authorization for TURN. In this example, a 493 resource owner i.e., WebRTC server, authorizes a TURN client to 494 access resources on a TURN server. 496 +----------------------+----------------------------+ 497 | OAuth 2.0 | WebRTC | 498 +======================+============================+ 499 | Client | WebRTC client | 500 +----------------------+----------------------------+ 501 | Resource owner | WebRTC server | 502 +----------------------+----------------------------+ 503 | Authorization server | Authorization server | 504 +----------------------+----------------------------+ 505 | Resource server | TURN Server | 506 +----------------------+----------------------------+ 508 Figure 2: OAuth terminology mapped to WebRTC terminology 510 Using the OAuth 2.0 authorization framework, a WebRTC client (third- 511 party application) obtains limited access to a TURN (resource server) 512 on behalf of the WebRTC server (resource owner or authorization 513 server). The WebRTC client requests access to resources controlled 514 by the resource owner (WebRTC server) and hosted by the resource 515 server (TURN server). The WebRTC client obtains access token, 516 lifetime, session key and kid. The TURN client conveys the access 517 token and other OAuth 2.0 parameters learnt from the authorization 518 server to the TURN server. The TURN server obtains the session key 519 from the access token. The TURN server validates the token, computes 520 the message integrity of the request and takes appropriate action 521 i.e, permits the TURN client to create allocations. This is shown in 522 an abstract way in Figure 3. 524 +---------------+ 525 | +<******+ 526 +------------->| Authorization | * 527 | | Server | * 528 | +----------|(WebRTC Server)| * AS-RS, 529 | | | | * AUTH keys 530 (2) | | +---------------+ * (1) 531 Access | | (3) * 532 Token | | Access Token * 533 Request | | + * 534 | | Session Key * 535 | | * 536 | V V 537 +-------+---+ +-+----=-----+ 538 | | (4) | | 539 | | TURN Request + Access | | 540 | WebRTC | Token | TURN | 541 | Client |---------------------->| Server | 542 | (Alice) | Allocate Response (5) | | 543 | |<----------------------| | 544 +-----------+ +------------+ 546 User : Alice 547 ****: Out-of-Band Long-Term Key Establishment 549 Figure 3: Interactions 551 In the below figure, the client sends an Allocate request to the 552 server without credentials. Since the server requires that all 553 requests be authenticated using OAuth 2.0, the server rejects the 554 request with a 401 (Unauthorized) error code and STUN attribute 555 THIRD-PARTY-AUTHORIZATION. The WebRTC client obtains access token 556 from the WebRTC server and then tries again, this time including 557 access token. This time, the server validates the token, accepts the 558 Allocate request and returns an Allocate success response containing 559 (amongst other things) the relayed transport address assigned to the 560 allocation. 562 +-------------------+ +--------+ +---------+ 563 | ......... TURN | | TURN | | WebRTC | 564 | .WebRTC . Client | | | | | 565 | .Client . | | Server | | Server | 566 | ......... | | | | | 567 +-------------------+ +--------+ +---------+ 568 | | Allocate request | | 569 | |------------------------------------------>| | 570 | | | | 571 | | Allocate error response | | 572 | | (401 Unauthorized) | | 573 | |<------------------------------------------| | 574 | | THIRD-PARTY-AUTHORIZATION | | 575 | | | | 576 | | | | 577 | | HTTP Request for token | | 578 |------------------------------------------------------------>| 579 | | HTTP Response with token parameters | | 580 |<------------------------------------------------------------| 581 |OAuth 2.0 | | 582 Attributes | | 583 |------>| | | 584 | | Allocate request ACCESS-TOKEN | | 585 | |------------------------------------------>| | 586 | | | | 587 | | Allocate success response | | 588 | |<------------------------------------------| | 589 | | TURN Messages | | 590 | | ////// integrity protected ////// | | 591 | | ////// integrity protected ////// | | 592 | | ////// integrity protected ////// | | 594 Figure 4: TURN Third Party Authorization 596 Changes specific to TURN are listed below: 598 o The access token can be reused for multiple Allocate requests to 599 the same TURN server. The TURN client MUST include the ACCESS- 600 TOKEN attribute only in Allocate and Refresh requests. Since the 601 access token is valid for a specific period of time, the TURN 602 server can cache it so that it can check if the access token in a 603 new allocation request matches one of the cached tokens and avoids 604 the need to decrypt the token. 606 o The lifetime provided by the TURN server in the Allocate and 607 Refresh responses MUST be less than or equal to the lifetime of 608 the token. It is RECOMMENDED that the TURN server calculate the 609 maximum allowed lifetime value using the formula: 611 lifetime + Delta - abs(RDnew - TS) 613 The RECOMMENDED value for the allowed Delta is 5 seconds. 615 o If the access token expires then the client MUST obtain a new 616 token from the authorization server and use it for new 617 allocations. The client MUST use the new token to refresh 618 existing allocations. This way client has to maintain only one 619 token per TURN server. 621 10. Operational Considerations 623 The following operational considerations should be taken into 624 account: 626 o Each authorization server should maintain the list of STUN servers 627 for which it will grant tokens, and the long-term secret shared 628 with each of those STUN servers. 630 o If manual configuration (Section 4.1.2) is used to establish 631 symmetric keys, the necessary information which includes long-term 632 secret (K) and authenticated encryption algorithm have to be 633 configured on each authorization server and STUN server for each 634 kid. The client obtains the session key and HMAC algorithm from 635 the authorization server in company with the token. 637 o When a STUN client sends a request to get access to a particular 638 STUN server (S) the authorization server must ensure that it 639 selects the appropriate kid, access-token depending on the server 640 S. 642 11. Security Considerations 644 When OAuth 2.0 is used the interaction between the client and the 645 authorization server requires Transport Layer Security (TLS) with a 646 ciphersuite offering confidentiality protection and the guidance 647 given in [I-D.ietf-uta-tls-bcp] must be followed to avoid attacks on 648 TLS. The session key MUST NOT be transmitted in clear since this 649 would completely destroy the security benefits of the proposed 650 scheme. An attacker trying to replay message with ACCESS-TOKEN 651 attribute can be mitigated by frequent changes of nonce value as 652 discussed in section 10.2 of [RFC5389]. The client may know some 653 (but not all) of the token fields encrypted with a unknown secret key 654 and the token can be subjected to known-plaintext attack, but AES is 655 secure against this attack. 657 An attacker may remove the THIRD-PARTY-AUTHORIZATION STUN attribute 658 from the error message forcing the client to pick first party 659 authentication, this attack may be mitigated by opting for Transport 660 Layer Security (TLS) [RFC5246] or Datagram Transport Layer Security 661 (DTLS) [RFC6347] as a transport protocol for Session Traversal 662 Utilities for NAT (STUN), as defined in [RFC5389]and [RFC7350]. 664 Threat mitigation discussed in section 5 of 665 [I-D.ietf-oauth-pop-architecture] and security considerations in 666 [RFC5389] are to be taken into account. 668 12. IANA Considerations 670 [Paragraphs below in braces should be removed by the RFC Editor upon 671 publication] 673 [IANA is requested to add the following attributes to the STUN 674 attribute registry [iana-stun], The THIRD-PARTY-AUTHORIZATION 675 attribute requires that IANA allocate a value in the "STUN attributes 676 Registry" from the comprehension-optional range (0x8000-0xBFFF)] 678 This document defines the THIRD-PARTY-AUTHORIZATION STUN attribute, 679 described in Section 6. IANA has allocated the comprehension- 680 optional codepoint TBD for this attribute. 682 [The ACCESS-TOKEN attribute requires that IANA allocate a value in 683 the "STUN attributes Registry" from the comprehension-required range 684 (0x0000-0x3FFF)] 686 This document defines the ACCESS-TOKEN STUN attribute, described in 687 Section 6. IANA has allocated the comprehension-required codepoint 688 TBD for this attribute. 690 13. Acknowledgements 692 Authors would like to thank Dan Wing, Pal Martinsen, Oleg Moskalenko, 693 Charles Eckel, Spencer Dawkins, Hannes Tschofenig, Yaron Sheffer, Tom 694 Taylor, Christer Holmberg, Pete Resnick, Kathleen Moriarty, Richard 695 Barnes, Stephen Farrell and Alissa Cooper for comments and review. 696 The authors would like to give special thanks to Brandon Williams for 697 his help. 699 Thanks to Oleg Moskalenko for providing token samples in the 700 Appendix section. 702 14. References 703 14.1. Normative References 705 [I-D.ietf-jose-json-web-algorithms] 706 Jones, M., "JSON Web Algorithms (JWA)", draft-ietf-jose- 707 json-web-algorithms-40 (work in progress), January 2015. 709 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 710 Requirement Levels", BCP 14, RFC 2119, March 1997. 712 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 713 Encodings", RFC 4648, October 2006. 715 [RFC4868] Kelly, S. and S. Frankel, "Using HMAC-SHA-256, HMAC-SHA- 716 384, and HMAC-SHA-512 with IPsec", RFC 4868, May 2007. 718 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 719 Encryption", RFC 5116, January 2008. 721 [RFC5389] Rosenberg, J., Mahy, R., Matthews, P., and D. Wing, 722 "Session Traversal Utilities for NAT (STUN)", RFC 5389, 723 October 2008. 725 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 726 6749, October 2012. 728 [iana-stun] 729 IANA, , "IANA: STUN Attributes", April 2011, 730 . 733 14.2. Informative References 735 [I-D.ietf-jose-json-web-encryption] 736 Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 737 draft-ietf-jose-json-web-encryption-40 (work in progress), 738 January 2015. 740 [I-D.ietf-jose-json-web-signature] 741 Jones, M., Bradley, J., and N. Sakimura, "JSON Web 742 Signature (JWS)", draft-ietf-jose-json-web-signature-41 743 (work in progress), January 2015. 745 [I-D.ietf-oauth-json-web-token] 746 Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 747 (JWT)", draft-ietf-oauth-json-web-token-32 (work in 748 progress), December 2014. 750 [I-D.ietf-oauth-pop-architecture] 751 Hunt, P., Richer, J., Mills, W., Mishra, P., and H. 752 Tschofenig, "OAuth 2.0 Proof-of-Possession (PoP) Security 753 Architecture", draft-ietf-oauth-pop-architecture-01 (work 754 in progress), March 2015. 756 [I-D.ietf-oauth-pop-key-distribution] 757 Bradley, J., Hunt, P., Jones, M., and H. Tschofenig, 758 "OAuth 2.0 Proof-of-Possession: Authorization Server to 759 Client Key Distribution", draft-ietf-oauth-pop-key- 760 distribution-01 (work in progress), March 2015. 762 [I-D.ietf-rtcweb-overview] 763 Alvestrand, H., "Overview: Real Time Protocols for 764 Browser-based Applications", draft-ietf-rtcweb-overview-13 765 (work in progress), November 2014. 767 [I-D.ietf-tram-stunbis] 768 Petit-Huguenin, M., Salgueiro, G., Rosenberg, J., Wing, 769 D., Mahy, R., and P. Matthews, "Session Traversal 770 Utilities for NAT (STUN)", draft-ietf-tram-stunbis-04 771 (work in progress), March 2015. 773 [I-D.ietf-uta-tls-bcp] 774 Sheffer, Y., Holz, R., and P. Saint-Andre, 775 "Recommendations for Secure Use of TLS and DTLS", draft- 776 ietf-uta-tls-bcp-11 (work in progress), February 2015. 778 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] 779 McGrew, D., Foley, J., and K. Paterson, "Authenticated 780 Encryption with AES-CBC and HMAC-SHA", draft-mcgrew-aead- 781 aes-cbc-hmac-sha2-05 (work in progress), July 2014. 783 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 784 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 786 [RFC5766] Mahy, R., Matthews, P., and J. Rosenberg, "Traversal Using 787 Relays around NAT (TURN): Relay Extensions to Session 788 Traversal Utilities for NAT (STUN)", RFC 5766, April 2010. 790 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 791 Security Version 1.2", RFC 6347, January 2012. 793 [RFC6819] Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 794 Threat Model and Security Considerations", RFC 6819, 795 January 2013. 797 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 798 Interchange Format", RFC 7159, March 2014. 800 [RFC7350] Petit-Huguenin, M. and G. Salgueiro, "Datagram Transport 801 Layer Security (DTLS) as Transport for Session Traversal 802 Utilities for NAT (STUN)", RFC 7350, August 2014. 804 [RFC7376] Reddy, T., Ravindranath, R., Perumal, M., and A. Yegin, 805 "Problems with Session Traversal Utilities for NAT (STUN) 806 Long-Term Authentication for Traversal Using Relays around 807 NAT (TURN)", RFC 7376, September 2014. 809 Appendix A. Sample tickets 811 Input data (same for all samples below): 813 //STUN SERVER NAME 814 server_name = "blackdow.carleon.gov"; 816 //Shared key between AS and RS 818 long_term_key = \x48\x47\x6b\x6a\x33\x32\x4b\x4a\x47\x69\x75\x79 819 \x30\x39\x38\x73\x64\x66\x61\x71\x62\x4e\x6a\x4f 820 \x69\x61\x7a\x37\x31\x39\x32\x33 822 //MAC key of the session (included in the token) 823 mac_key = \x5a\x6b\x73\x6a\x70\x77\x65\x6f\x69\x78\x58\x6d\x76\x6e 824 \x36\x37\x35\x33\x34\x6d; 826 //length of the MAC key 827 mac_key_length = 20; 829 //The timestamp field in the token 830 token_timestamp = 92470300704768; 832 //The lifetime of the token 833 token_lifetime = 3600; 835 //nonce for AEAD when AEAD is used 836 aead_nonce = \x68\x34\x6a\x33\x6b\x32\x6c\x32\x6e\x34\x62\x35; 838 Sample: 840 1) 842 token encryption algorithm = AEAD_AES_256_GCM 843 token auth algorithm = N/A 844 Result: 845 AS_RS key (32 bytes) = 846 \x48\x47\x6b\x6a\x33\x32\x4b\x4a\x47\x69\x75\x79 847 \x30\x39\x38\x73\x64\x66\x61\x71\x62\x4e\x6a\x4f 848 \x69\x61\x7a\x37\x31\x39\x32\x33 850 AUTH key = N/A 852 Encrypted token (62 bytes = 34 + 16 + 12) = 854 \xd4\x86\x5c\x5d\x59\xfb\x3f\xe3\xf6\xf1\xd8\xc3\x22\xc2\x22\x26\x8d 855 \x2e\xf0\xbe\x2\x5b\xbd\x13\x49\x89\x6e\xa5\xc5\x51\xee\xee\x7f\xd9 856 \xe4\x41\xd7\xcb\x51\x20\x40\xcc\xc5\x53\x90\x2f\xdc\xbb\x8d\x53\x68 857 \x34\x6a\x33\x6b\x32\x6c\x32\x6e\x34\x62\x35 859 Figure 5: Sample tickets 861 Appendix B. Interaction between client and authorization server 863 Client makes an HTTP request to an authorization server to obtain a 864 token that can be used to avail itself of STUN services. The STUN 865 token is returned in JSON syntax [RFC7159], along with other OAuth 866 2.0 parameters like token type, key, token lifetime and kid defined 867 in [I-D.ietf-oauth-pop-key-distribution]. 869 +-------------------+ +--------+ +---------+ 870 | ......... STUN | | STUN | | WebRTC | 871 | .WebRTC . Client | | | | | 872 | .Client . | | Server | | Server | 873 | ......... | | | | | 874 +-------------------+ +--------+ +---------+ 875 | | STUN request | | 876 | |------------------------------------------>| | 877 | | | | 878 | | STUN error response | | 879 | | (401 Unauthorized) | | 880 | |<------------------------------------------| | 881 | | THIRD-PARTY-AUTHORIZATION | | 882 | | | | 883 | | | | 884 | | HTTP Request for token | | 885 |------------------------------------------------------------>| 886 | | HTTP Response with token parameters | | 887 |<------------------------------------------------------------| 888 |OAuth 2.0 | | 889 Attributes | | 890 |------>| | | 891 | | STUN request with ACCESS-TOKEN | | 892 | |------------------------------------------>| | 893 | | | | 894 | | STUN success response | | 895 | |<------------------------------------------| | 896 | | STUN Messages | | 897 | | ////// integrity protected ////// | | 898 | | ////// integrity protected ////// | | 899 | | ////// integrity protected ////// | | 901 Figure 6: STUN Third Party Authorization 903 [I-D.ietf-oauth-pop-key-distribution] describes the interaction 904 between the client and the authorization server. For example, the 905 client learns the STUN server name "stun1@example.com" from THIRD- 906 PARTY-AUTHORIZATION attribute value and makes the following HTTP 907 request for the access token using transport-layer security (with 908 extra line breaks for display purposes only): 910 HTTP/1.1 911 Host: server.example.com 912 Content-Type: application/x-www-form-urlencoded 913 aud=stun1@example.com 914 timestamp=1361471629 915 grant_type=implicit 916 token_type=pop 917 alg=HMAC-SHA-1 HMAC-SHA-256-128 919 Figure 7: Request 921 [I-D.ietf-tram-stunbis] will support hash agility and accomplish this 922 agility by conveying the HMAC algorithms supported by the STUN server 923 along with a STUN error message to the client. The client then 924 signals the intersection-set of algorithms supported by it and the 925 STUN server to the authorization server in the 'alg' parameter 926 defined in [I-D.ietf-oauth-pop-key-distribution]. The authorization 927 server selects an HMAC algorithm from the list of algorithms the 928 client provided and determines length of the mac_key based on the 929 selected HMAC algorithm. Note that until STUN supports hash agility 930 HMAC-SHA1 is the only valid hash algorithm that the client can signal 931 to the authorization server and vice-versa. 933 If the client is authorized then the authorization server issues an 934 access token. An example of successful response: 936 HTTP/1.1 200 OK 937 Content-Type: application/json 938 Cache-Control: no-store 940 { 941 "access_token": 942 "U2FsdGVkX18qJK/kkWmRcnfHglrVTJSpS6yU32kmHmOrfGyI3m1gQj1jRPsr0uBb 943 HctuycAgsfRX7nJW2BdukGyKMXSiNGNnBzigkAofP6+Z3vkJ1Q5pWbfSRroOkWBn", 944 "token_type":"pop", 945 "expires_in":1800, 946 "kid":"22BIjxU93h/IgwEb", 947 "key":"v51N62OM65kyMvfTI08O" 948 "alg":HMAC-SHA-256-128 949 } 951 Figure 8: Response 953 Authors' Addresses 954 Tirumaleswar Reddy 955 Cisco Systems, Inc. 956 Cessna Business Park, Varthur Hobli 957 Sarjapur Marathalli Outer Ring Road 958 Bangalore, Karnataka 560103 959 India 961 Email: tireddy@cisco.com 963 Prashanth Patil 964 Cisco Systems, Inc. 965 Bangalore 966 India 968 Email: praspati@cisco.com 970 Ram Mohan Ravindranath 971 Cisco Systems, Inc. 972 Cessna Business Park, 973 Kadabeesanahalli Village, Varthur Hobli, 974 Sarjapur-Marathahalli Outer Ring Road 975 Bangalore, Karnataka 560103 976 India 978 Email: rmohanr@cisco.com 980 Justin Uberti 981 Google 982 747 6th Ave S 983 Kirkland, WA 984 98033 985 USA 987 Email: justin@uberti.name