idnits 2.17.1 draft-ietf-tram-turn-third-party-authz-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (January 20, 2015) is 3383 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 5766 (Obsoleted by RFC 8656) Summary: 1 error (**), 0 flaws (~~), 5 warnings (==), 2 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: July 24, 2015 Cisco 6 J. Uberti 7 Google 8 January 20, 2015 10 Session Traversal Utilities for NAT (STUN) Extension for Third Party 11 Authorization 12 draft-ietf-tram-turn-third-party-authz-06 14 Abstract 16 This document proposes the use of OAuth 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 ensure that 19 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 July 24, 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 . . . . . . . . . . . . . . . . 6 60 4.1. Key Establishment . . . . . . . . . . . . . . . . . . . . 7 61 4.1.1. DSKPP . . . . . . . . . . . . . . . . . . . . . . . . 8 62 4.1.2. HTTP interactions . . . . . . . . . . . . . . . . . . 8 63 4.1.3. Manual provisioning . . . . . . . . . . . . . . . . . 9 64 5. Forming a Request . . . . . . . . . . . . . . . . . . . . . . 9 65 6. STUN Attributes . . . . . . . . . . . . . . . . . . . . . . . 10 66 6.1. THIRD-PARTY-AUTHORIZATION . . . . . . . . . . . . . . . . 10 67 6.2. ACCESS-TOKEN . . . . . . . . . . . . . . . . . . . . . . 10 68 7. Receiving a request with ACCESS-TOKEN attribute . . . . . . . 12 69 8. Changes to STUN Client . . . . . . . . . . . . . . . . . . . 13 70 9. Usage with TURN . . . . . . . . . . . . . . . . . . . . . . . 13 71 10. Security Considerations . . . . . . . . . . . . . . . . . . . 15 72 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 73 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 16 74 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 16 75 13.1. Normative References . . . . . . . . . . . . . . . . . . 16 76 13.2. Informative References . . . . . . . . . . . . . . . . . 16 77 Appendix A. Sample tickets . . . . . . . . . . . . . . . . . . . 17 78 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19 80 1. Introduction 82 Session Traversal Utilities for NAT (STUN) [RFC5389] provides a 83 mechanism to control access via "long-term" username/ password 84 credentials that are provided as part of the STUN protocol. It is 85 expected that these credentials will be kept secret; if the 86 credentials are discovered, the STUN server could be used by 87 unauthorized users or applications. However, in web applications, 88 ensuring this secrecy is typically impossible. 90 To address this problem and the ones described in 91 [I-D.ietf-tram-auth-problems], this document proposes the use of 92 third party authorization using OAuth for STUN. Using OAuth, a 93 client obtains an ephemeral token from an authorization server e.g. 94 WebRTC server, and the token is presented to the STUN server instead 95 of the traditional mechanism of presenting username/password 96 credentials. The STUN server validates the authenticity of the token 97 and provides required services. 99 2. Terminology 101 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 102 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 103 document are to be interpreted as described in [RFC2119]. 105 o WebRTC Server: A web server that supports WebRTC 106 [I-D.ietf-rtcweb-overview]. 108 o Access Token: OAuth 2.0 access token. 110 o mac_key: The session key generated by the authorization server. 111 This session key has a lifetime that corresponds to the lifetime 112 of the access token, is generated by the authorization server and 113 bound to the access token. 115 o kid: An ephemeral and unique key identifier. The kid also allows 116 the resource server to select the appropriate keying material for 117 decryption. 119 3. Solution Overview 121 This specification uses the token type 'Assertion' (aka self- 122 contained token) described in [RFC6819] where all the information 123 necessary to authenticate the validity of the token is contained 124 within the token itself. This approach has the benefit of avoiding a 125 protocol between the STUN server and the authorization server for 126 token validation, thus reducing latency. The exact mechanism used by 127 a client to obtain a token from the OAuth authorization server is 128 outside the scope of this document. For example, a client could make 129 an HTTP request to an authorization server to obtain a token that can 130 be used to avail STUN services. The STUN token is returned in JSON, 131 along with other OAuth Parameters like token type, mac_key, kid, 132 token lifetime etc. The client is oblivious to the content of the 133 token. The token is embedded within a STUN request sent to the STUN 134 server. Once the STUN server has determined the token is valid, it's 135 services are offered for a determined period of time. 137 +-------------------+ +--------+ +---------+ 138 | ......... STUN | | STUN | | WebRTC | 139 | .WebRTC . Client | | | | | 140 | .Client . | | Server | | Server | 141 | ......... | | | | | 142 +-------------------+ +--------+ +---------+ 143 | | STUN request | | 144 | |------------------------------------------>| | 145 | | | | 146 | | STUN error response | | 147 | | (401 Unauthorized) | | 148 | |<------------------------------------------| | 149 | | THIRD-PARTY-AUTHORIZATION | | 150 | | | | 151 | | | | 152 | | HTTP Request for token | | 153 |------------------------------------------------------------>| 154 | | HTTP Response with token parameters | | 155 |<------------------------------------------------------------| 156 |OAuth | | | 157 Attributes | | 158 |------>| | | 159 | | STUN request with ACCESS-TOKEN | | 160 | |------------------------------------------>| | 161 | | | | 162 | | STUN success response | | 163 | |<------------------------------------------| | 164 | | STUN Messages | | 165 | | ////// integrity protected ////// | | 166 | | ////// integrity protected ////// | | 167 | | ////// integrity protected ////// | | 169 Figure 1: STUN Third Party Authorization 171 Note : An implementation may choose to contact the WebRTC server to 172 obtain a token even before it makes a STUN request, if it knows the 173 server details before hand. For example, once a client has learnt 174 that a STUN server supports Third Party authorization from a WebRTC 175 server, the client can obtain the token before making subsequent STUN 176 requests. 178 [I-D.ietf-oauth-pop-key-distribution] describes the interaction 179 between the client and the authorization server. For example, the 180 client learns the STUN server name "stun1@example.com" from THIRD- 181 PARTY-AUTHORIZATION attribute value and makes the following HTTP 182 request for the access token using transport-layer security (with 183 extra line breaks for display purposes only): 185 POST /o/oauth2/token HTTP/1.1 186 Host: server.example.com 187 Content-Type: application/x-www-form-urlencoded 188 aud=stun1@example.com 189 timestamp=1361471629 190 grant_type=implicit 191 token_type=pop 192 alg=HMAC-SHA-1 HMAC-SHA-256-128 194 Figure 2: Request 196 In the future STUNbis [I-D.ietf-tram-stunbis] will support hash 197 agility and accomplish this agility by conveying the HMAC algorithms 198 supported by the STUN server along with a STUN error message to the 199 client. The client then signals the intersection-set of algorithms 200 supported by it and the STUN server to the authorization server in 201 the 'alg' parameter defined in [I-D.ietf-oauth-pop-key-distribution]. 202 Authorization server selects an HMAC algorithm from the list of 203 algorithms client had provided and determines length of the mac_key 204 based on the selected HMAC algorithm. Note that until STUN supports 205 hash agility HMAC-SHA1 is the only valid hash algorithm that client 206 can signal to the authorization server and vice-versa. 208 If the client is authorized then the authorization server issues an 209 access token. An example of successful response: 211 HTTP/1.1 200 OK 212 Content-Type: application/json 213 Cache-Control: no-store 215 { 216 "access_token": 217 "U2FsdGVkX18qJK/kkWmRcnfHglrVTJSpS6yU32kmHmOrfGyI3m1gQj1jRPsr0uBb 218 HctuycAgsfRX7nJW2BdukGyKMXSiNGNnBzigkAofP6+Z3vkJ1Q5pWbfSRroOkWBn", 219 "token_type":"pop", 220 "expires_in":1800, 221 "kid":"22BIjxU93h/IgwEb", 222 "mac_key":"v51N62OM65kyMvfTI08O" 223 "alg":HMAC-SHA-256-128 224 } 226 Figure 3: Response 228 Access token and other attributes issued by the authorization server 229 are explained in Section 6.2. OAuth in [RFC6749] defines four grant 230 types. This specification uses the OAuth grant type "Implicit" 231 explained in section 1.3.2 of [RFC6749] where the WebRTC client is 232 issued an access token directly. The value of the scope parameter 233 explained in section 3.3 of [RFC6749] MUST be 'stun' string. 235 4. Obtaining a Token Using OAuth 237 A STUN client should know the authentication capability of the STUN 238 server before deciding to use third party authorization. A STUN 239 client initially makes a request without any authorization. If the 240 STUN server mandates third party authorization, it will return an 241 error message indicating that the client needs to be authorized to 242 use the STUN server. The STUN server includes an ERROR-CODE 243 attribute with a value of 401 (Unauthorized), a nonce value in a 244 NONCE attribute and a SOFTWARE attribute that gives information about 245 the STUN server's software. The STUN servers also includes 246 additional STUN attribute THIRD-PARTY-AUTHORIZATION signaling the 247 STUN client that the STUN server mandates third party authorization. 249 Consider the following example that illustrates the use of OAuth to 250 achieve third party authorization for TURN. In this example, a 251 resource owner i.e. WebRTC server, authorizes a TURN client to 252 access resources on a TURN server. 254 +----------------------+----------------------------+ 255 | OAuth | WebRTC | 256 +======================+============================+ 257 | Client | WebRTC client | 258 +----------------------+----------------------------+ 259 | Resource owner | WebRTC server | 260 +----------------------+----------------------------+ 261 | Authorization server | Authorization server | 262 +----------------------+----------------------------+ 263 | Resource server | TURN Server | 264 +----------------------+----------------------------+ 266 Figure 4: OAuth terminology mapped to WebRTC terminology 268 Using the OAuth 2.0 authorization framework, a WebRTC client (third- 269 party application) obtains limited access to a TURN (resource server) 270 on behalf of the WebRTC server (resource owner or authorization 271 server). The WebRTC client requests access to resources controlled 272 by the resource owner (WebRTC server) and hosted by the resource 273 server (TURN server). The WebRTC client obtains access token, 274 lifetime, session key (in the mac_key parameter) and kid. The TURN 275 client conveys the access token and other OAuth parameters learnt 276 from the authorization server to the resource server (TURN server). 277 The TURN server obtains the session key from the access token. The 278 TURN server validates the token, computes the message integrity of 279 the request and takes appropriate action i.e permits the TURN client 280 to create allocations. This is shown in an abstract way in Figure 5. 282 +---------------+ 283 | +<******+ 284 +------------->| Authorization | * 285 | | Server | * 286 | +----------|(WebRTC Server)| * AS-RS, 287 | | | | * AUTH keys 288 (2) | | +---------------+ * (1) 289 Access | | (3) * 290 Token | | Access Token * 291 Request | | + * 292 | | Session Key * 293 | | * 294 | V V 295 +-------+---+ +-+----=-----+ 296 | | (4) | | 297 | | TURN Request + Access | | 298 | WebRTC | Token | TURN | 299 | Client |---------------------->| Server | 300 | (Alice) | Allocate Response (5) | | 301 | |<----------------------| | 302 +-----------+ +------------+ 304 User : Alice 305 ****: Out-of-Band Long-Term Key Establishment 307 Figure 5: Interactions 309 4.1. Key Establishment 311 The authorization server shares a long-term secret (like asymmetric 312 credentials) with the resource server for mutual authentication. The 313 STUN server and authorization server MUST establish a symmetric key 314 (K), using an out of band mechanism. Symmetric key MUST be chosen to 315 ensure that the size of encrypted token is not large because usage of 316 asymmetric keys will result in large encrypted tokens which may not 317 fit into a single STUN message. The AS-RS, AUTH keys will be derived 318 from K. AS-RS key is used for encrypting the self-contained token 319 and message integrity of the encrypted token is calculated using the 320 AUTH key. The STUN and authorization servers MUST establish the 321 symmetric key over an authenticated secure channel. The 322 establishment of symmetric key is outside the scope of this 323 specification. For example, implementations could use one of the 324 following mechanisms to establish a symmetric key. 326 4.1.1. DSKPP 328 The two servers could choose to use Dynamic Symmetric Key 329 Provisioning Protocol (DSKPP) [RFC6063] to establish a symmetric key 330 (K). The encryption and MAC algorithms will be negotiated using the 331 KeyProvClientHello, KeyProvServerHello messages. A unique key 332 identifier (referred to as KeyID) for the symmetric key is generated 333 by the DSKPP server (i.e. Authorization server) and signalled to the 334 DSKPP client (i.e STUN server) which is equivalent to the kid defined 335 in this specification. The AS-RS, AUTH keys would be derived from 336 the symmetric key using (HMAC)-based key derivation function (HKDF) 337 [RFC5869] and the default hash function MUST be SHA-256. For example 338 if the input symmetric key (K) is 32 octets length, encryption 339 algorithm is AES_256_CBC and HMAC algorithm is HMAC-SHA-256-128 then 340 the secondary keys AS-RS, AUTH are generated from the input key K as 341 follows 343 1. HKDF-Extract(zero, K) -> PRK 345 2. HKDF-Expand(PRK, zero, 32) -> AS-RS key 347 3. HKDF-Expand(PRK, zero, 32) -> AUTH key 349 If Authenticated Encryption with Associated Data (AEAD) algorithm 350 defined in [RFC5116] is used then there is no need to generate the 351 AUTH key. 353 4.1.2. HTTP interactions 355 The two servers could choose to use REST API to establish a symmetric 356 key. To retrieve a new symmetric key, the STUN server makes an HTTP 357 GET request to the authorization server, specifying STUN as the 358 service to allocate the symmetric keys for, and specifying the name 359 of the STUN server. The response is returned with content-type 360 "application/json", and consists of a JSON object containing the 361 symmetric key. 363 Request 364 ------- 366 service - specifies the desired service (turn) 367 name - STUN server name be associated with the key 369 example: GET /?service=stun&name=turn1@example.com 371 Response 372 -------- 374 key - Long-term key (K) 375 ttl - the duration for which the key is valid, in seconds. 377 example: 378 { 379 "key" : 380 "ESIzRFVmd4iZABEiM0RVZgKn6WjLaTC1FXAghRMVTzkBGNaaN496523WIISKerLi", 381 "ttl" : 86400, 382 "kid" :"22BIjxU93h/IgwEb" 383 "enc" : A256CBC-HS512 384 } 386 The AS-RS, AUTH keys are derived from K using HKDF as discussed in 387 Section 4.1.1. Authorization server must also signal kid to the STUN 388 server which will be used to select the appropriate keying material 389 for decryption. A256CBC-HS512 and other encryption algorithms are 390 defined in [I-D.ietf-jose-json-web-algorithms]. In this case AS-RS 391 key length must be 256-bit, AUTH key length must be 256-bit (section 392 2.6 of [RFC4868]). 394 4.1.3. Manual provisioning 396 STUN and authorization servers could be manually configured with a 397 symmetric key (K) and kid. Mandatory to support authenticated 398 encryption algorithm MUST be AES_256_CBC_HMAC_SHA_512. 400 Note : The mechanism specified in Section 4.1.3 is easy to implement 401 and deploy compared to DSKPP, REST but lacks encryption and HMAC 402 algorithm agility. 404 5. Forming a Request 406 When a STUN server responds that third party authorization is 407 required, a STUN client re-attempts the request, this time including 408 access token and kid values in ACCESS-TOKEN and USERNAME STUN 409 attributes. The STUN client includes a MESSAGE-INTEGRITY attribute 410 as the last attribute in the message over the contents of the STUN 411 message. The HMAC for the MESSAGE-INTEGRITY attribute is computed as 412 described in section 15.4 of [RFC5389] where the mac_key is used as 413 the input key for the HMAC computation. The STUN client and server 414 will use the mac_key to compute the message integrity and doesn't 415 have to perform MD5 hash on the credentials. 417 6. STUN Attributes 419 The following new STUN attributes are introduced by this 420 specification to accomplish third party authorization. 422 6.1. THIRD-PARTY-AUTHORIZATION 424 This attribute is used by the STUN server to inform the client that 425 it supports third party authorization. This attribute value contains 426 the STUN server name. The STUN server may have tie-up with multiple 427 authorization servers and vice versa, so the client MUST provide the 428 STUN server name to the authorization server so that it can select 429 the appropriate keying material to generate the self-contained token. 430 The THIRD-PARTY-AUTHORIZATION attribute is a comprehension-optional 431 attribute (see Section 15 from [RFC5389]). 433 6.2. ACCESS-TOKEN 435 The access token is issued by the authorization server. OAuth does 436 not impose any limitation on the length of the access token but if 437 path MTU is unknown then STUN messages over IPv4 would need to be 438 less than 548 bytes (Section 7.1 of [RFC5389]), access token length 439 needs to be restricted to fit within the maximum STUN message size. 440 Note that the self-contained token is opaque to the client and it 441 MUST NOT examine the ticket. The ACCESS-TOKEN attribute is a 442 comprehension-required attribute (see Section 15 from [RFC5389]). 444 The token is structured as follows: 446 struct { 447 opaque { 448 uint16_t key_length; 449 opaque mac_key[key_length]; 450 uint64_t timestamp; 451 uint32_t lifetime; 452 } encrypted_block; 453 opaque mac[mac_length]; 454 } token; 456 Figure 6: Self-contained token format 458 Note: uintN_t means an unsigned integer of exactly N bits. Single- 459 byte entities containing uninterpreted data are of type opaque. All 460 values in the token are stored in network byte order. 462 The fields are described below: 464 key_length: Length of the session key in octets. Key length of 465 160-bits MUST be supported (i.e only 160-bit key is used by HMAC- 466 SHA-1 for message integrity of STUN message). The key length 467 facilitates the hash agility plan discussed in section 16.3 of 468 [RFC5389]. 470 mac_key: The session key generated by the authorization server. 472 timestamp: 64-bit unsigned integer field containing a timestamp. 473 The value indicates the time since January 1, 1970, 00:00 UTC, by 474 using a fixed point format. In this format, the integer number of 475 seconds is contained in the first 48 bits of the field, and the 476 remaining 16 bits indicate the number of 1/64K fractions of a 477 second (Native format - Unix). 479 lifetime: The lifetime of the access token, in seconds. For 480 example, the value 3600 indicates one hour. The lifetime value 481 SHOULD be greater than or equal to the "expires_in" parameter 482 defined in section 4.2.2 of [RFC6749], otherwise resource server 483 could revoke the token but the client assumes that the token has 484 not expired and would not refresh the token. 486 encrypted_block: The encrypted_block is encrypted using the 487 symmetric long-term key established between the resource server 488 and the authorization server. Shown in Figure 5 as AS-RS key. 490 mac: The Hashed Message Authentication Code (HMAC) is calculated 491 with the AUTH key over the 'encrypted_block' and the STUN server 492 name (N) conveyed in the THIRD-PARTY-AUTHORIZATION response. This 493 ensures that the client does not use the same token to gain 494 illegal access to other STUN servers provided by the same 495 administrative domain i.e., when multiple STUN servers in a single 496 administrative domain share the same symmetric key with an 497 authorization server. The length of the mac field is known to the 498 STUN and authorization server based on the negotiated MAC 499 algorithm. 501 An example encryption process is illustrated below. Here C, N denote 502 Ciphertext and STUN server name respectively. 504 o C = AES_256_CBC(AS-RS, encrypted_block) 505 o mac = HMAC-SHA-256-128(AUTH, C | | N) 507 Encryption is applied before message authentication on the sender 508 side and conversely on the receiver side. The entire token i.e., the 509 'encrypted_block' and 'mac' is base64 encoded (see section 4 of 510 [RFC4648]) and the resulting access token is signaled to the client. 511 If AEAD algorithm is used then there is no need to explicitly compute 512 HMAC, the associated data MUST be the STUN server name (N) and the 513 mac field MUST carry the nonce. The length of nonce MUST be 12 514 octets. 516 7. Receiving a request with ACCESS-TOKEN attribute 518 The STUN server, on receiving a request with ACCESS-TOKEN attribute, 519 performs checks listed in section 10.2.2 of [RFC5389] in addition to 520 the following steps to verify that the access token is valid: 522 o STUN server selects the keying material based on kid signalled in 523 the USERNAME attribute. 525 o It performs the verification of the token message integrity by 526 calculating HMAC over the encrypted portion in the self-contained 527 token and STUN server name using AUTH key and if the resulting 528 value does not match the mac field in the self-contained token 529 then it rejects the request with an error response 401 530 (Unauthorized). If AEAD algorithm is used then it has only a 531 single output, either a plaintext or a special symbol FAIL that 532 indicates that the inputs are not authentic. 534 o STUN server obtains the mac_key by retrieving the content of the 535 access token (which requires decryption of the self-contained 536 token using the AS-RS key). 538 o The STUN server verifies that no replay took place by performing 539 the following check: 541 * The access token is accepted if the timestamp field (TS) in the 542 self-contained token is recent enough to the reception time of 543 the STUN request (RDnew) using the following formula: Lifetime 544 + Delta > abs(RDnew - TS). The RECOMMENDED value for the 545 allowed Delta is 5 seconds. If the timestamp is NOT within the 546 boundaries then the STUN server discards the request with error 547 response 401 (Unauthorized). 549 o The STUN server uses the mac_key to compute the message integrity 550 over the request and if the resulting value does not match the 551 contents of the MESSAGE-INTEGRITY attribute then it rejects the 552 request with an error response 401 (Unauthorized). 554 o If all the checks pass, the STUN server continues to process the 555 request. Any response generated by the server MUST include the 556 MESSAGE-INTEGRITY attribute, computed using the mac_key. 558 8. Changes to STUN Client 560 o A STUN response is discarded by the client if the value computed 561 for message integrity using mac_key does not match the contents of 562 the MESSAGE-INTEGRITY attribute. 564 o If the access token expires then the client MUST obtain a new 565 token from the authorization server and use it for new STUN 566 requests. 568 9. Usage with TURN 570 Traversal Using Relay NAT (TURN) [RFC5766] an extension to the STUN 571 protocol is often used to improve the connectivity of P2P 572 applications. TURN ensures that a connection can be established even 573 when one or both sides is incapable of a direct P2P connection. 574 However, as a relay service, it imposes a nontrivial cost on the 575 service provider. Therefore, access to a TURN service is almost 576 always access-controlled. In order to achieve third party 577 authorization, a resource owner e.g. WebRTC server, authorizes a 578 TURN client to access resources on the TURN server. 580 +-------------------+ +--------+ +---------+ 581 | ......... TURN | | TURN | | WebRTC | 582 | .WebRTC . Client | | | | | 583 | .Client . | | Server | | Server | 584 | ......... | | | | | 585 +-------------------+ +--------+ +---------+ 586 | | Allocate request | | 587 | |------------------------------------------>| | 588 | | | | 589 | | Allocate error response | | 590 | | (401 Unauthorized) | | 591 | |<------------------------------------------| | 592 | | THIRD-PARTY-AUTHORIZATION | | 593 | | | | 594 | | | | 595 | | HTTP Request for token | | 596 |------------------------------------------------------------>| 597 | | HTTP Response with token parameters | | 598 |<------------------------------------------------------------| 599 |OAuth | | | 600 Attributes | | 601 |------>| | | 602 | | Allocate request ACCESS-TOKEN | | 603 | |------------------------------------------>| | 604 | | | | 605 | | Allocate success response | | 606 | |<------------------------------------------| | 607 | | TURN Messages | | 608 | | ////// integrity protected ////// | | 609 | | ////// integrity protected ////// | | 610 | | ////// integrity protected ////// | | 612 Figure 7: TURN Third Party Authorization 614 In the above figure, the client sends an Allocate request to the 615 server without credentials. Since the server requires that all 616 requests be authenticated using OAuth, the server rejects the request 617 with a 401 (Unauthorized) error code and STUN attribute THIRD-PARTY- 618 AUTHORIZATION. The WebRTC client obtains access token from the 619 WebRTC server and then tries again, this time including access token. 620 This time, the server validates the token, accepts the Allocate 621 request and returns an Allocate success response containing (amongst 622 other things) the relayed transport address assigned to the 623 allocation. 625 Changes specific to TURN are listed below: 627 o The access token can be reused for multiple Allocate requests to 628 the same TURN server. The TURN client MUST include the ACCESS- 629 TOKEN attribute only in Allocate and Refresh requests. Since the 630 access token is only valid for a specific period of time, the TURN 631 server MUST cache it so that it need not to be provided in every 632 request within an existing allocation. 634 o The lifetime provided by the TURN server in the Allocate and 635 Refresh responses MUST be less than or equal to the lifetime of 636 the token. It is RECOMMENDED that the TURN server calculate the 637 maximum allowed lifetime value using the formula: 639 lifetime + Delta - abs(RDnew - TS) 641 o If the access token expires then the client MUST obtain a new 642 token from the authorization server and use it for new 643 allocations. The client MUST use the new token to refresh 644 existing allocations. This way client has to maintain only one 645 token per TURN server. 647 10. Security Considerations 649 When OAuth is used the interaction between the client and the 650 authorization server requires Transport Layer Security (TLS) with a 651 ciphersuite offering confidentiality protection. The session key 652 MUST NOT be transmitted in clear since this would completely destroy 653 the security benefits of the proposed scheme. If an attacker tries 654 to replay message with ACCESS-TOKEN attribute then the server can 655 detect that the transaction ID as used for an old request and thus 656 prevent the replay attack. The client may know some (but not all) of 657 the token fields encrypted with a unknown secret key and the token 658 can be subjected to known-plaintext attack, but AES is secure against 659 this attack. 661 Threat mitigation discussed in section 5 of 662 [I-D.ietf-oauth-pop-architecture] and security considerations in 663 [RFC5389] are to be taken into account. 665 11. IANA Considerations 667 IANA is requested to add the following attributes to the STUN 668 attribute registry [iana-stun], 670 o THIRD-PARTY-AUTHORIZATION 672 o ACCESS-TOKEN 674 12. Acknowledgements 676 Authors would like to thank Dan Wing, Pal Martinsen, Oleg Moskalenko, 677 Charles Eckel, Spencer Dawkins and Hannes Tschofenig for comments and 678 review. The authors would like to give special thanks to Brandon 679 Williams for his help. 681 Thanks to Oleg Moskalenko for providing ticket samples in the 682 Appendix section. 684 13. References 686 13.1. Normative References 688 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 689 Requirement Levels", BCP 14, RFC 2119, March 1997. 691 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 692 Encodings", RFC 4648, October 2006. 694 [RFC4868] Kelly, S. and S. Frankel, "Using HMAC-SHA-256, HMAC-SHA- 695 384, and HMAC-SHA-512 with IPsec", RFC 4868, May 2007. 697 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 698 Encryption", RFC 5116, January 2008. 700 [RFC5389] Rosenberg, J., Mahy, R., Matthews, P., and D. Wing, 701 "Session Traversal Utilities for NAT (STUN)", RFC 5389, 702 October 2008. 704 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 705 6749, October 2012. 707 [iana-stun] 708 IANA, , "IANA: STUN Attributes", April 2011, 709 . 712 13.2. Informative References 714 [I-D.ietf-jose-json-web-algorithms] 715 Jones, M., "JSON Web Algorithms (JWA)", draft-ietf-jose- 716 json-web-algorithms-40 (work in progress), January 2015. 718 [I-D.ietf-oauth-pop-architecture] 719 Hunt, P., Richer, J., Mills, W., Mishra, P., and H. 720 Tschofenig, "OAuth 2.0 Proof-of-Possession (PoP) Security 721 Architecture", draft-ietf-oauth-pop-architecture-00 (work 722 in progress), July 2014. 724 [I-D.ietf-oauth-pop-key-distribution] 725 Bradley, J., Hunt, P., Jones, M., and H. Tschofenig, 726 "OAuth 2.0 Proof-of-Possession: Authorization Server to 727 Client Key Distribution", draft-ietf-oauth-pop-key- 728 distribution-00 (work in progress), July 2014. 730 [I-D.ietf-rtcweb-overview] 731 Alvestrand, H., "Overview: Real Time Protocols for 732 Browser-based Applications", draft-ietf-rtcweb-overview-13 733 (work in progress), November 2014. 735 [I-D.ietf-tram-auth-problems] 736 Reddy, T., R, R., Perumal, M., and A. Yegin, "Problems 737 with STUN long-term Authentication for TURN", draft-ietf- 738 tram-auth-problems-05 (work in progress), August 2014. 740 [I-D.ietf-tram-stunbis] 741 Petit-Huguenin, M., Salgueiro, G., Rosenberg, J., Wing, 742 D., Mahy, R., and P. Matthews, "Session Traversal 743 Utilities for NAT (STUN)", draft-ietf-tram-stunbis-00 744 (work in progress), November 2014. 746 [RFC5766] Mahy, R., Matthews, P., and J. Rosenberg, "Traversal Using 747 Relays around NAT (TURN): Relay Extensions to Session 748 Traversal Utilities for NAT (STUN)", RFC 5766, April 2010. 750 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 751 Key Derivation Function (HKDF)", RFC 5869, May 2010. 753 [RFC6063] Doherty, A., Pei, M., Machani, S., and M. Nystrom, 754 "Dynamic Symmetric Key Provisioning Protocol (DSKPP)", RFC 755 6063, December 2010. 757 [RFC6819] Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 758 Threat Model and Security Considerations", RFC 6819, 759 January 2013. 761 Appendix A. Sample tickets 763 Input data (same for all samples below): 765 //STUN SERVER NAME 766 server_name = "blackdow.carleon.gov"; 768 //Shared password between AS and RS 769 long_term_password = "HGkj32KJGiuy098sdfaqbNjOiaz71923"; 771 //MAC key of the session (included in the token) 772 mac_key = "ZksjpweoixXmvn67534m"; 774 //length of the MAC key 775 mac_key_length = 20; 777 //The timestamp field in the token 778 token_timestamp = 92470300704768; 780 //The lifetime of the token 781 token_lifetime = 3600; 783 //nonce for AEAD when AEAD is used 784 aead_nonce = "h4j3k2l2n4b5"; 786 Samples: 788 1) 789 hkdf hash function = SHA-256, 790 token encryption algorithm = AES-256-CBC 791 token auth algorithm = HMAC-SHA-256 793 Result: 794 AS_RS key (32 bytes) = \xd\x7e\x54\x5b\x7e\x15\xc9\x81\x8c\x81\x4b\x83 795 \xdc\x4e\xce\x24\x55\xde\x73\xe\xab\x8\x8a\x94 796 \xc4\x29\xab\x45\xfd\x61\xa\xb5 798 AUTH key (32 bytes) = \xd\x7e\x54\x5b\x7e\x15\xc9\x81\x8c\x81\x4b\x83 799 \xdc\x4e\xce\x24\x55\xde\x73\xe\xab\x8\x8a\x94 800 \xc4\x29\xab\x45\xfd\x61\xa\xb5 802 Encrypted token (80 bytes = 48+32) = 804 \x1b\xb6\x4b\x4f\xbf\x99\x6d\x60\x55\xda\xf3\x9f\xa1\xed\x3\x73\x4e 805 \x1c\x95\x64\x84\xc1\xeb\xc3\x63\x9b\x70\xe6\xb8\x21\x45\xe6\x45\xa0 806 \x23\xaf\xc1\xee\x87\x91\x7b\xea\xb8\x4a\x7f\x80\xb2\x0\xa5\xad\x14 807 \x97\x17\xf9\xbc\xfa\xa1\xc6\x2f\x4d\xfc\xaf\xc1\xc5\x11\xc5\x55\x7d 808 \xb0\x35\x58\xcf\xc6\xce\x6e\x10\x7\xd1\x98\xbd 810 2) 812 hkdf hash function = SHA-256, 813 token encryption algorithm = AEAD_AES_256_GCM 814 token auth algorithm = N/A 816 Result: 817 AS_RS key (32 bytes) = \xd\x7e\x54\x5b\x7e\x15\xc9\x81\x8c\x81\x4b\x83 818 \xdc\x4e\xce\x24\x55\xde\x73\xe\xab\x8\x8a\x94 819 \xc4\x29\xab\x45\xfd\x61\xa\xb5 820 AUTH key = N/A 822 Encrypted token (62 bytes = 34 + 16 + 12) = 824 \xa8\x52\x90\x64\xc7\xd9\x3b\x6c\xe\x9\xe\xcf\x9e\x7d\x0\x70\x47\xe2 825 \x99\x8d\xe3\x31\xe1\x39\x20\xed\x88\x90\x4\xd8\xcf\x82\x93\x3f\xc6\ 826 x4\xd1\xaa\xe6\xf5\x62\xea\x3c\x94\x45\x8\x3d\xfa\xe9\x5f\x68\x34\x6a 827 \x33\x6b\x32\x6c\x32\x6e\x34\x62\x35 829 3) 831 hkdf hash function = SHA-1, 832 token encryption algorithm = AES-128-CBC 833 token auth algorithm = HMAC-SHA-256-128 835 Result: 836 AS_RS key (16 bytes) = \x8c\x48\x5f\x1e\x1\x3a\xc6\x50\x36\x70\x84\x37 837 \xa5\x4e\xd7\x70 838 AUTH key (32 bytes) = \x8c\x48\x5f\x1e\x1\x3a\xc6\x50\x36\x70\x84\x37 839 \xa5\x4e\xd7\x70\x17\xcc\xcd\xa1\x7c\xd7\x8\x39 840 \xfa\xc8\xee\x14\xf9\x77\xb4\xcf 842 Encrypted token (64 bytes = 48+16) = 844 \x13\xcd\x17\x4a\xde\x54\xe1\xe6\x65\xe6\xbb\x3a\xb9\x4d\x1c\xf7\x3b 845 \x60\x31\x8b\xc4\x7\x4b\x3b\x5f\x1c\xda\xf4\x60\x4\x7\x88\x8e\xc9\xc7 846 \xd3\xf4\x71\x94\x87\x85\xd9\xad\xf7\x6a\xda\x77\x4e\x11\x13\x8d\x8e 847 \xe8\x93\x9\x76\xa3\x85\x96\x1f\x5e\xd3\xc4\x55 849 Figure 8: Sample tickets 851 Authors' Addresses 853 Tirumaleswar Reddy 854 Cisco Systems, Inc. 855 Cessna Business Park, Varthur Hobli 856 Sarjapur Marathalli Outer Ring Road 857 Bangalore, Karnataka 560103 858 India 860 Email: tireddy@cisco.com 861 Prashanth Patil 862 Cisco Systems, Inc. 863 Bangalore 864 India 866 Email: praspati@cisco.com 868 Ram Mohan Ravindranath 869 Cisco Systems, Inc. 870 Cessna Business Park, 871 Kadabeesanahalli Village, Varthur Hobli, 872 Sarjapur-Marathahalli Outer Ring Road 873 Bangalore, Karnataka 560103 874 India 876 Email: rmohanr@cisco.com 878 Justin Uberti 879 Google 880 747 6th Ave S 881 Kirkland, WA 882 98033 883 USA 885 Email: justin@uberti.name