idnits 2.17.00 (12 Aug 2021) /tmp/idnits41614/draft-ietf-tram-turn-third-party-authz-16.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 (May 13, 2015) is 2558 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) -- Looks like a reference, but probably isn't: '1' on line 898 -- Looks like a reference, but probably isn't: '2' on line 903 == Outdated reference: draft-ietf-jose-json-web-algorithms has been published as RFC 7518 ** Obsolete normative reference: RFC 5389 (Obsoleted by RFC 8489) == Outdated reference: draft-ietf-jose-json-web-encryption has been published as RFC 7516 == Outdated reference: draft-ietf-jose-json-web-signature has been published as RFC 7515 == Outdated reference: draft-ietf-oauth-json-web-token has been published as RFC 7519 == 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: draft-ietf-rtcweb-overview has been published as RFC 8825 == Outdated reference: draft-ietf-tram-stunbis has been published as RFC 8489 -- 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 5785 (Obsoleted by RFC 8615) -- 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 (~~), 9 warnings (==), 8 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: November 14, 2015 Cisco 6 J. Uberti 7 Google 8 May 13, 2015 10 Session Traversal Utilities for NAT (STUN) Extension for Third Party 11 Authorization 12 draft-ietf-tram-turn-third-party-authz-16 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 November 14, 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 3.1. Usage with TURN . . . . . . . . . . . . . . . . . . . . . 4 60 4. Obtaining a Token Using OAuth . . . . . . . . . . . . . . . . 7 61 4.1. Key Establishment . . . . . . . . . . . . . . . . . . . . 8 62 4.1.1. HTTP interactions . . . . . . . . . . . . . . . . . . 8 63 4.1.2. Manual provisioning . . . . . . . . . . . . . . . . . 10 64 5. Forming a Request . . . . . . . . . . . . . . . . . . . . . . 10 65 6. STUN Attributes . . . . . . . . . . . . . . . . . . . . . . . 10 66 6.1. THIRD-PARTY-AUTHORIZATION . . . . . . . . . . . . . . . . 10 67 6.2. ACCESS-TOKEN . . . . . . . . . . . . . . . . . . . . . . 11 68 7. STUN server behaviour . . . . . . . . . . . . . . . . . . . . 13 69 8. STUN client behaviour . . . . . . . . . . . . . . . . . . . . 14 70 9. TURN client and server behaviour . . . . . . . . . . . . . . 14 71 10. Operational Considerations . . . . . . . . . . . . . . . . . 15 72 11. Security Considerations . . . . . . . . . . . . . . . . . . . 15 73 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 74 12.1. Well-Known 'stun-key' URI . . . . . . . . . . . . . . . 16 75 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 16 76 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 17 77 14.1. Normative References . . . . . . . . . . . . . . . . . . 17 78 14.2. Informative References . . . . . . . . . . . . . . . . . 17 79 Appendix A. Sample tickets . . . . . . . . . . . . . . . . . . . 19 80 Appendix B. Interaction between client and authorization server 20 81 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22 83 1. Introduction 85 Session Traversal Utilities for NAT (STUN) [RFC5389] provides a 86 mechanism to control access via "long-term" username/ password 87 credentials that are provided as part of the STUN protocol. It is 88 expected that these credentials will be kept secret; if the 89 credentials are discovered, the STUN server could be used by 90 unauthorized users or applications. However, in web applications 91 like WebRTC [I-D.ietf-rtcweb-overview] where JavaScript uses the 92 browser functionality to make real-time audio and/or video calls, Web 93 conferencing, and direct data transfer, ensuring this secrecy is 94 typically not possible. 96 To address this problem and the ones described in [RFC7376], this 97 document proposes the use of third party authorization using OAuth 98 2.0 [RFC6749] for STUN. Using OAuth 2.0, a client obtains an 99 ephemeral token from an authorization server e.g. WebRTC server, and 100 the token is presented to the STUN server instead of the traditional 101 mechanism of presenting username/password credentials. The STUN 102 server validates the authenticity of the token and provides required 103 services. Third party authorization using OAuth 2.0 for STUN 104 explained in this specification can also be used with Traversal Using 105 Relays around NAT (TURN) [RFC5766]. 107 2. Terminology 109 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 110 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 111 document are to be interpreted as described in [RFC2119]. 113 This document uses the following abbreviations: 115 o WebRTC Server: A web server that supports WebRTC 116 [I-D.ietf-rtcweb-overview]. 118 o Access Token: OAuth 2.0 access token. 120 o mac_key: The session key generated by the authorization server. 121 This session key has a lifetime that corresponds to the lifetime 122 of the access token, is generated by the authorization server and 123 bound to the access token. 125 o kid: An ephemeral and unique key identifier. The kid also allows 126 the resource server to select the appropriate keying material for 127 decryption. 129 o AS: Authorization server 131 Some sections in this specification show WebRTC server as the 132 authorization server and client as the WebRTC client, however WebRTC 133 is intended to be used for illustrative purpose only. 135 3. Solution Overview 137 STUN client knows that it can use OAuth 2.0 with the target STUN 138 server either through configuration or when it receives the new STUN 139 attribute THIRD-PARTY-AUTHORIZATION in the error response with an 140 error code of 401(Unauthorized). 142 This specification uses the token type 'Assertion' (aka self- 143 contained token) described in [RFC6819] where all the information 144 necessary to authenticate the validity of the token is contained 145 within the token itself. This approach has the benefit of avoiding a 146 protocol between the STUN server and the authorization server for 147 token validation, thus reducing latency. The content of the token is 148 opaque to the client. The client embeds the token within a STUN 149 request sent to the STUN server. Once the STUN server has determined 150 the token is valid, its services are offered for a determined period 151 of time. Access token issued by the authorization server is 152 explained in Section 6.2. OAuth 2.0 in [RFC6749] defines four grant 153 types. This specification uses the OAuth 2.0 grant type "Implicit" 154 explained in section 1.3.2 of [RFC6749] where the client is issued an 155 access token directly. The string 'stun' is defined by this 156 specification for use as the OAuth scope parameter (see section 3.3 157 of [RFC6749]) for the OAuth token. 159 The exact mechanism used by a client to obtain a token and other 160 OAuth 2.0 parameters like token type, mac_key, token lifetime and kid 161 is outside the scope of this document. Appendix B provides an 162 example deployment scenario of interaction between the client and 163 authorization server to obtain a token and other OAuth 2.0 164 parameters. 166 Section 3.1 illustrates the use of OAuth 2.0 to achieve third party 167 authorization for TURN. 169 3.1. Usage with TURN 171 TURN, an extension to the STUN protocol, is often used to improve the 172 connectivity of P2P applications. TURN ensures that a connection can 173 be established even when one or both sides is incapable of a direct 174 P2P connection. However, as a relay service, it imposes a nontrivial 175 cost on the service provider. Therefore, access to a TURN service is 176 almost always access-controlled. In order to achieve third party 177 authorization, a resource owner e.g. WebRTC server, authorizes a 178 TURN client to access resources on the TURN server. 180 In this example, a resource owner i.e., WebRTC server, authorizes a 181 TURN client to access resources on a TURN server. 183 +----------------------+----------------------------+ 184 | OAuth 2.0 | WebRTC | 185 +======================+============================+ 186 | Client | WebRTC client | 187 +----------------------+----------------------------+ 188 | Resource owner | WebRTC server | 189 +----------------------+----------------------------+ 190 | Authorization server | Authorization server | 191 +----------------------+----------------------------+ 192 | Resource server | TURN Server | 193 +----------------------+----------------------------+ 195 Figure 1: OAuth terminology mapped to WebRTC terminology 197 Using the OAuth 2.0 authorization framework, a WebRTC client (third- 198 party application) obtains limited access to a TURN server (resource 199 server) on behalf of the WebRTC server (resource owner or 200 authorization server). The WebRTC client requests access to 201 resources controlled by the resource owner (WebRTC server) and hosted 202 by the resource server (TURN server). The WebRTC client obtains 203 access token, lifetime, session key and kid. The TURN client conveys 204 the access token and other OAuth 2.0 parameters learnt from the 205 authorization server to the TURN server. The TURN server obtains the 206 session key from the access token. The TURN server validates the 207 token, computes the message integrity of the request and takes 208 appropriate action i.e, permits the TURN client to create 209 allocations. This is shown in an abstract way in Figure 2. 211 +---------------+ 212 | +<******+ 213 +------------->| Authorization | * 214 | | Server | * 215 | +----------|(WebRTC Server)| * AS-RS, 216 | | | | * AUTH keys 217 (1) | | +---------------+ * (0) 218 Access | | (2) * 219 Token | | Access Token * 220 Request | | + * 221 | | Session Key * 222 | | * 223 | V V 224 +-------+---+ +-+----=-----+ 225 | | (3) | | 226 | | TURN Request + Access | | 227 | WebRTC | Token | TURN | 228 | Client |---------------------->| Server | 229 | (Alice) | Allocate Response (4) | | 230 | |<----------------------| | 231 +-----------+ +------------+ 233 User : Alice 234 ****: Out-of-Band Long-Term Key Establishment 236 Figure 2: Interactions 238 In the below figure, the TURN client sends an Allocate request to the 239 TURN server without credentials. Since the TURN server requires that 240 all requests be authenticated using OAuth 2.0, the TURN server 241 rejects the request with a 401 (Unauthorized) error code and STUN 242 attribute THIRD-PARTY-AUTHORIZATION. The WebRTC client obtains 243 access token from the WebRTC server, provides the access token to the 244 TURN client and it tries again, this time including access token in 245 the allocate request. This time, the TURN server validates the 246 token, accepts the Allocate request and returns an Allocate success 247 response containing (amongst other things) the relayed transport 248 address assigned to the allocation. 250 +-------------------+ +--------+ +---------+ 251 | ......... TURN | | TURN | | WebRTC | 252 | .WebRTC . Client | | | | | 253 | .Client . | | Server | | Server | 254 | ......... | | | | | 255 +-------------------+ +--------+ +---------+ 256 | | Allocate request | | 257 | |------------------------------------------>| | 258 | | | | 259 | | Allocate error response | | 260 | | (401 Unauthorized) | | 261 | |<------------------------------------------| | 262 | | THIRD-PARTY-AUTHORIZATION | | 263 | | | | 264 | | | | 265 | | HTTP Request for token | | 266 |------------------------------------------------------------>| 267 | | HTTP Response with token parameters | | 268 |<------------------------------------------------------------| 269 |OAuth 2.0 | | 270 Attributes | | 271 |------>| | | 272 | | Allocate request ACCESS-TOKEN | | 273 | |------------------------------------------>| | 274 | | | | 275 | | Allocate success response | | 276 | |<------------------------------------------| | 277 | | TURN Messages | | 278 | | ////// integrity protected ////// | | 279 | | ////// integrity protected ////// | | 280 | | ////// integrity protected ////// | | 282 Figure 3: TURN Third Party Authorization 284 4. Obtaining a Token Using OAuth 286 A STUN client needs to know the authentication capability of the STUN 287 server before deciding to use third party authorization. A STUN 288 client initially makes a request without any authorization. If the 289 STUN server supports third party authorization, it will return an 290 error message indicating that the client can authorize to the STUN 291 server using an OAuth 2.0 access token. The STUN server includes an 292 ERROR-CODE attribute with a value of 401 (Unauthorized), a nonce 293 value in a NONCE attribute and a SOFTWARE attribute that gives 294 information about the STUN server's software. The STUN server also 295 includes the additional STUN attribute THIRD-PARTY-AUTHORIZATION 296 signaling the STUN client that the STUN server supports third party 297 authorization. 299 Note: An implementation may choose to contact the authorization 300 server to obtain a token even before it makes a STUN request, if it 301 knows the server details before hand. For example, once a client has 302 learnt that a STUN server supports third party authorization from a 303 authorization server, the client can obtain the token before making 304 subsequent STUN requests. 306 4.1. Key Establishment 308 In this model the STUN server would not authenticate the client 309 itself but would rather verify whether the client knows the session 310 key associated with a specific access token. Example of this 311 approach can be found with the OAuth 2.0 Proof-of-Possession (PoP) 312 Security Architecture [I-D.ietf-oauth-pop-architecture]. The 313 authorization server shares a long-term secret (K) with the STUN 314 server. When the client requests an access token the authorization 315 server creates a fresh and unique session key (mac_key) and places it 316 into the token encrypted with the long term secret. Symmetric 317 cryptography MUST be chosen to ensure that the size of encrypted 318 token is not large because usage of asymmetric cryptography will 319 result in large encrypted tokens which may not fit into a single STUN 320 message. 322 The STUN server and authorization server can establish a symmetric 323 key (K) and certain authenticated encryption algorithm, using an out 324 of band mechanism. The STUN and authorization servers MUST establish 325 K over an authenticated secure channel. If Authenticated Encryption 326 with AES-CBC and HMAC-SHA (defined in 327 [I-D.mcgrew-aead-aes-cbc-hmac-sha2]) is used then the AS-RS and AUTH 328 keys will be derived from K. The AS-RS key is used for encrypting 329 the self-contained token and the message integrity of the encrypted 330 token is calculated using the AUTH key. If Authenticated Encryption 331 with Associated Data (AEAD) algorithm defined in [RFC5116] is used 332 then there is no need to generate the AUTH key and AS-RS key will 333 have the same value as K. 335 The procedure for establishment of the symmetric key is outside the 336 scope of this specification, and this specification does not mandate 337 support of any given mechanism. Section 4.1.1 and Section 4.1.2 show 338 examples of mechanisms that can be used. 340 4.1.1. HTTP interactions 342 The STUN and AS servers could choose to use REST API over HTTPS to 343 establish a symmetric key. HTTPS MUST be used for data 344 confidentiality and TLS based on client certificate MUST be used for 345 mutual authentication. To retrieve a new symmetric key, the STUN 346 server makes an HTTP GET request to the authorization server, 347 specifying STUN as the service to allocate the symmetric keys for, 348 and specifying the name of the STUN server. The response is returned 349 with content-type "application/json", and consists of a JavaScript 350 Object Notation (JSON) [RFC7159] object containing the symmetric key. 352 Request 353 ------- 355 service - specifies the desired service (turn) 356 name - STUN server name be associated with the key 358 example: 359 GET https://www.example.com/.well-known/stun-key?service=stun 360 &name=turn1@example.com 362 Response 363 -------- 365 k - Long-term key (K) 366 exp - identifies the time after which the key expires. 368 example: 369 { 370 "k" : 371 "ESIzRFVmd4iZABEiM0RVZgKn6WjLaTC1FXAghRMVTzkBGNaaN496523WIISKerLi", 372 "exp" : 1300819380, 373 "kid" :"22BIjxU93h/IgwEb" 374 "enc" : A256GCM 375 } 377 The authorization server must also signal kid to the STUN server 378 which will be used to select the appropriate keying material for 379 decryption. The parameter "k" is defined in Section 6.4.1 of 380 [I-D.ietf-jose-json-web-algorithms], "enc" is defined in 381 Section 4.1.2 of [I-D.ietf-jose-json-web-encryption], "kid" is 382 defined in Section 4.1.4 of [I-D.ietf-jose-json-web-signature] and 383 "exp" is defined in Section 4.1.4 of [I-D.ietf-oauth-json-web-token]. 384 A256GCM and other authenticated encryption algorithms are defined in 385 section 5.1 of [I-D.ietf-jose-json-web-algorithms]. A STUN server 386 and authorization server implementation MUST support A256GCM as the 387 authenticated encryption algorithm. 389 If A256CBC-HS512 defined in [I-D.ietf-jose-json-web-algorithms] is 390 used then the AS-RS and AUTH keys are derived from K using the 391 mechanism explained in section 5.2.2.1 of 392 [I-D.ietf-jose-json-web-algorithms]. In this case AS-RS key length 393 must be 256-bit, AUTH key length must be 256-bit (section 2.6 of 394 [RFC4868]). 396 4.1.2. Manual provisioning 398 The STUN and AS servers could be manually configured with a symmetric 399 key (K), authenticated encryption algorithm and kid. 401 Note : The mechanism specified in this section requires configuration 402 to change the symmetric key (K) and/or authenticated encryption 403 algorithm. Hence a STUN server and authorization server 404 implementation SHOULD support REST explained in Section 4.1.1. 406 5. Forming a Request 408 When a STUN server responds that third party authorization is 409 required, a STUN client re-attempts the request, this time including 410 access token and kid values in ACCESS-TOKEN and USERNAME STUN 411 attributes. The STUN client includes a MESSAGE-INTEGRITY attribute 412 as the last attribute in the message over the contents of the STUN 413 message. The HMAC for the MESSAGE-INTEGRITY attribute is computed as 414 described in section 15.4 of [RFC5389] where the mac_key is used as 415 the input key for the HMAC computation. The STUN client and server 416 will use the mac_key to compute the message integrity and do not 417 perform MD5 hash on the credentials. 419 6. STUN Attributes 421 The following new STUN attributes are introduced by this 422 specification to accomplish third party authorization. 424 6.1. THIRD-PARTY-AUTHORIZATION 426 This attribute is used by the STUN server to inform the client that 427 it supports third party authorization. This attribute value contains 428 the STUN server name. The authorization server may have tie-ups with 429 multiple STUN servers and vice versa, so the client MUST provide the 430 STUN server name to the authorization server so that it can select 431 the appropriate keying material to generate the self-contained token. 432 If the authorization server does not have tie-up with the STUN server 433 then it returns error to the client. If the client does not support 434 or is not capable of doing third party authorization then it defaults 435 to first party authentication. The THIRD-PARTY-AUTHORIZATION 436 attribute is a comprehension-optional attribute (see Section 15 from 437 [RFC5389]). If the client is able to comprehend THIRD-PARTY- 438 AUTHORIZATION it MUST ensure that third party authorization takes 439 precedence over first party authentication (explained in section 10 440 of [RFC5389]). 442 6.2. ACCESS-TOKEN 444 The access token is issued by the authorization server. OAuth 2.0 445 does not impose any limitation on the length of the access token but 446 if path MTU is unknown then STUN messages over IPv4 would need to be 447 less than 548 bytes (Section 7.1 of [RFC5389]). The access token 448 length needs to be restricted to fit within the maximum STUN message 449 size. Note that the self-contained token is opaque to the client and 450 the client MUST NOT examine the token. The ACCESS-TOKEN attribute is 451 a comprehension-required attribute (see Section 15 from [RFC5389]). 453 The token is structured as follows: 455 struct { 456 uint16_t nonce_length; 457 opaque nonce[nonce_length]; 458 opaque { 459 uint16_t key_length; 460 opaque mac_key[key_length]; 461 uint64_t timestamp; 462 uint32_t lifetime; 463 } encrypted_block; 464 } token; 466 Figure 4: Self-contained token format 468 Note: uintN_t means an unsigned integer of exactly N bits. Single- 469 byte entities containing uninterpreted data are of type opaque. All 470 values in the token are stored in network byte order. 472 The fields are described below: 474 nonce_length: Length of the nonce field. The length of nonce for 475 authenticated encryption with additional data (AEAD) algorithms is 476 explained in [RFC5116]. 478 Nonce: Nonce (N) formation is explained in section 3.2 of [RFC5116]. 480 key_length: Length of the session key in octets. Key length of 481 160-bits MUST be supported (i.e., only 160-bit key is used by 482 HMAC-SHA-1 for message integrity of STUN message). The key length 483 facilitates the hash agility plan discussed in section 16.3 of 484 [RFC5389]. 486 mac_key: The session key generated by the authorization server. 488 timestamp: 64-bit unsigned integer field containing a timestamp. 489 The value indicates the time since January 1, 1970, 00:00 UTC, by 490 using a fixed point format. In this format, the integer number of 491 seconds is contained in the first 48 bits of the field, and the 492 remaining 16 bits indicate the number of 1/64K fractions of a 493 second (Native format - Unix). 495 lifetime: The lifetime of the access token, in seconds. For 496 example, the value 3600 indicates one hour. The lifetime value 497 MUST be greater than or equal to the "expires_in" parameter 498 defined in section 4.2.2 of [RFC6749], otherwise resource server 499 could revoke the token but the client would assume that the token 500 has not expired and would not refresh the token. 502 encrypted_block: The encrypted_block (P) is encrypted and 503 authenticated using the symmetric long-term key established 504 between the STUN server and the authorization server. 506 The AEAD encryption operation has four inputs: K , N, A, and P, as 507 defined in section 2.1 of [RFC5116] and there is a single output a 508 ciphertext C or an indication that the requested encryption operation 509 could not be performed. 511 The associated data (A) MUST be the STUN server name. This ensures 512 that the client does not use the same token to gain illegal access to 513 other STUN servers provided by the same administrative domain i.e., 514 when multiple STUN servers in a single administrative domain share 515 the same symmetric key with an authorization server. 517 If AES_CBC_HMAC_SHA2 (explained in section 2.1 of 518 [I-D.mcgrew-aead-aes-cbc-hmac-sha2])) is used then the encryption 519 process is illustrated below. The ciphertext consists of the string 520 S, with the string T appended to it. Here C and A denote Ciphertext 521 and STUN server name respectively. The octet string AL (section 2.1 522 of [I-D.mcgrew-aead-aes-cbc-hmac-sha2]) is equal to the number of 523 bits in A expressed as a 64-bit unsigned big endian integer. 525 o AUTH = initial authentication key length octets of K, 527 o AS-RS = final encryption key length octets of K, 529 o S = CBC-PKCS7-ENC(AS-RS, encrypted_block), 531 * Initialization vector is set to zero because the 532 encrypted_block in each access token will not be identical and 533 hence will not result in generation of identical ciphertext. 535 o mac = MAC(AUTH, A || S || AL), 537 o T = initial T_LEN octets of mac, 538 o C = S || T. 540 The entire token i.e., the 'encrypted_block' is base64 encoded (see 541 section 4 of [RFC4648]) and the resulting access token is signaled to 542 the client. 544 7. STUN server behaviour 546 The STUN server, on receiving a request with ACCESS-TOKEN attribute, 547 performs checks listed in section 10.2.2 of [RFC5389] in addition to 548 the following steps to verify that the access token is valid: 550 o STUN server selects the keying material based on kid signalled in 551 the USERNAME attribute. 553 o The AEAD decryption operation has four inputs: K, N, A, and C, as 554 defined in section 2.2 of [RFC5116]. AEAD decryption algorithm 555 has only a single output, either a plaintext or a special symbol 556 FAIL that indicates that the inputs are not authentic. If 557 authenticated decrypt operation returns FAIL then the STUN server 558 rejects the request with an error response 401 (Unauthorized). 560 o If AES_CBC_HMAC_SHA2 is used then the final T_LEN octets are 561 stripped from C. It performs the verification of the token 562 message integrity by calculating HMAC over the the STUN server 563 name, the encrypted portion in the self-contained token and the AL 564 using AUTH key and if the resulting value does not match the mac 565 field in the self-contained token then it rejects the request with 566 an error response 401 (Unauthorized). 568 o STUN server obtains the mac_key by retrieving the content of the 569 access token (which requires decryption of the self-contained 570 token using the AS-RS key). 572 o The STUN server verifies that no replay took place by performing 573 the following check: 575 * The access token is accepted if the timestamp field (TS) in the 576 self-contained token is recent enough to the reception time of 577 the STUN request (RDnew) using the following formula: 579 lifetime + Delta > abs(RDnew - TS) 581 The RECOMMENDED value for the allowed Delta is 5 seconds. If 582 the timestamp is NOT within the boundaries then the STUN server 583 discards the request with error response 401 (Unauthorized). 585 o The STUN server uses the mac_key to compute the message integrity 586 over the request and if the resulting value does not match the 587 contents of the MESSAGE-INTEGRITY attribute then it rejects the 588 request with an error response 401 (Unauthorized). 590 o If all the checks pass, the STUN server continues to process the 591 request. 593 o Any response generated by the server MUST include the MESSAGE- 594 INTEGRITY attribute, computed using the mac_key. 596 If a STUN server receives an ACCESS-TOKEN attribute unexpectedly 597 (because it had not previously sent out a THIRD-PARTY-AUTHORIZATION), 598 it will respond with an error code of 420 (Unknown Attribute) as 599 specified in Section 7.3.1 of [RFC5389]. 601 8. STUN client behaviour 603 o The client looks for the MESSAGE-INTEGRITY attribute in the 604 response. If MESSAGE-INTEGRITY is absent or the value computed 605 for message integrity using mac_key does not match the contents of 606 the MESSAGE-INTEGRITY attribute then the response MUST be 607 discarded. 609 o If the access token expires then the client MUST obtain a new 610 token from the authorization server and use it for new STUN 611 requests. 613 9. TURN client and server behaviour 615 Changes specific to TURN are listed below: 617 o The access token can be reused for multiple Allocate requests to 618 the same TURN server. The TURN client MUST include the ACCESS- 619 TOKEN attribute only in Allocate and Refresh requests. Since the 620 access token is valid for a specific period of time, the TURN 621 server can cache it so that it can check if the access token in a 622 new allocation request matches one of the cached tokens and avoids 623 the need to decrypt the token. 625 o The lifetime provided by the TURN server in the Allocate and 626 Refresh responses MUST be less than or equal to the lifetime of 627 the token. It is RECOMMENDED that the TURN server calculate the 628 maximum allowed lifetime value using the formula: 630 lifetime + Delta - abs(RDnew - TS) 632 The RECOMMENDED value for the allowed Delta is 5 seconds. 634 o If the access token expires then the client MUST obtain a new 635 token from the authorization server and use it for new 636 allocations. The client MUST use the new token to refresh 637 existing allocations. This way client has to maintain only one 638 token per TURN server. 640 10. Operational Considerations 642 The following operational considerations should be taken into 643 account: 645 o Each authorization server should maintain the list of STUN servers 646 for which it will grant tokens, and the long-term secret shared 647 with each of those STUN servers. 649 o If manual configuration (Section 4.1.2) is used to establish 650 symmetric keys, the necessary information which includes long-term 651 secret (K) and authenticated encryption algorithm have to be 652 configured on each authorization server and STUN server for each 653 kid. The client obtains the session key and HMAC algorithm from 654 the authorization server in company with the token. 656 o When a STUN client sends a request to get access to a particular 657 STUN server (S) the authorization server must ensure that it 658 selects the appropriate kid, access-token depending on the server 659 S. 661 11. Security Considerations 663 When OAuth 2.0 is used, the interaction between the client and the 664 authorization server requires Transport Layer Security (TLS) with a 665 ciphersuite offering confidentiality protection and the guidance 666 given in [RFC7525] must be followed to avoid attacks on TLS. The 667 session key MUST NOT be transmitted in clear since this would 668 completely destroy the security benefits of the proposed scheme. An 669 attacker trying to replay message with ACCESS-TOKEN attribute can be 670 mitigated by frequent changes of nonce value as discussed in section 671 10.2 of [RFC5389]. The client may know some (but not all) of the 672 token fields encrypted with a unknown secret key and the token can be 673 subjected to known-plaintext attack, but AES is secure against this 674 attack. 676 An attacker may remove the THIRD-PARTY-AUTHORIZATION STUN attribute 677 from the error message forcing the client to pick first party 678 authentication, this attack may be mitigated by opting for Transport 679 Layer Security (TLS) [RFC5246] or Datagram Transport Layer Security 680 (DTLS) [RFC6347] as a transport protocol for Session Traversal 681 Utilities for NAT (STUN), as defined in [RFC5389]and [RFC7350]. 683 Threat mitigation discussed in section 5 of 684 [I-D.ietf-oauth-pop-architecture] and security considerations in 685 [RFC5389] are to be taken into account. 687 12. IANA Considerations 689 [Paragraphs below in braces should be removed by the RFC Editor upon 690 publication] 692 [IANA is requested to add the following attributes to the STUN 693 attribute registry [iana-stun], The THIRD-PARTY-AUTHORIZATION 694 attribute requires that IANA allocate a value in the "STUN attributes 695 Registry" from the comprehension-optional range (0x8000-0xBFFF)] 697 This document defines the THIRD-PARTY-AUTHORIZATION STUN attribute, 698 described in Section 6. IANA has allocated the comprehension- 699 optional codepoint TBD for this attribute. 701 [The ACCESS-TOKEN attribute requires that IANA allocate a value in 702 the "STUN attributes Registry" from the comprehension-required range 703 (0x0000-0x3FFF)] 705 This document defines the ACCESS-TOKEN STUN attribute, described in 706 Section 6. IANA has allocated the comprehension-required codepoint 707 TBD for this attribute. 709 12.1. Well-Known 'stun-key' URI 711 This memo registers the 'stun-key' well-known URI in the Well-Known 712 URIs registry as defined by [RFC5785]. 714 URI suffix: stun-key 716 Change controller: IETF 718 Specification document(s): This RFC 720 Related information: None 722 13. Acknowledgements 724 Authors would like to thank Dan Wing, Pal Martinsen, Oleg Moskalenko, 725 Charles Eckel, Spencer Dawkins, Hannes Tschofenig, Yaron Sheffer, Tom 726 Taylor, Christer Holmberg, Pete Resnick, Kathleen Moriarty, Richard 727 Barnes, Stephen Farrell, Alissa Cooper and Rich Salz for comments and 728 review. The authors would like to give special thanks to Brandon 729 Williams for his help. 731 Thanks to Oleg Moskalenko for providing token samples in the 732 Appendix section. 734 14. References 736 14.1. Normative References 738 [I-D.ietf-jose-json-web-algorithms] 739 Jones, M., "JSON Web Algorithms (JWA)", draft-ietf-jose- 740 json-web-algorithms-40 (work in progress), January 2015. 742 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 743 Requirement Levels", BCP 14, RFC 2119, March 1997. 745 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 746 Encodings", RFC 4648, October 2006. 748 [RFC4868] Kelly, S. and S. Frankel, "Using HMAC-SHA-256, HMAC-SHA- 749 384, and HMAC-SHA-512 with IPsec", RFC 4868, May 2007. 751 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 752 Encryption", RFC 5116, January 2008. 754 [RFC5389] Rosenberg, J., Mahy, R., Matthews, P., and D. Wing, 755 "Session Traversal Utilities for NAT (STUN)", RFC 5389, 756 October 2008. 758 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 759 6749, October 2012. 761 [iana-stun] 762 IANA, , "IANA: STUN Attributes", April 2011, 763 . 766 14.2. Informative References 768 [I-D.ietf-jose-json-web-encryption] 769 Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 770 draft-ietf-jose-json-web-encryption-40 (work in progress), 771 January 2015. 773 [I-D.ietf-jose-json-web-signature] 774 Jones, M., Bradley, J., and N. Sakimura, "JSON Web 775 Signature (JWS)", draft-ietf-jose-json-web-signature-41 776 (work in progress), January 2015. 778 [I-D.ietf-oauth-json-web-token] 779 Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 780 (JWT)", draft-ietf-oauth-json-web-token-32 (work in 781 progress), December 2014. 783 [I-D.ietf-oauth-pop-architecture] 784 Hunt, P., Richer, J., Mills, W., Mishra, P., and H. 785 Tschofenig, "OAuth 2.0 Proof-of-Possession (PoP) Security 786 Architecture", draft-ietf-oauth-pop-architecture-01 (work 787 in progress), March 2015. 789 [I-D.ietf-oauth-pop-key-distribution] 790 Bradley, J., Hunt, P., Jones, M., and H. Tschofenig, 791 "OAuth 2.0 Proof-of-Possession: Authorization Server to 792 Client Key Distribution", draft-ietf-oauth-pop-key- 793 distribution-01 (work in progress), March 2015. 795 [I-D.ietf-rtcweb-overview] 796 Alvestrand, H., "Overview: Real Time Protocols for 797 Browser-based Applications", draft-ietf-rtcweb-overview-13 798 (work in progress), November 2014. 800 [I-D.ietf-tram-stunbis] 801 Petit-Huguenin, M., Salgueiro, G., Rosenberg, J., Wing, 802 D., Mahy, R., and P. Matthews, "Session Traversal 803 Utilities for NAT (STUN)", draft-ietf-tram-stunbis-04 804 (work in progress), March 2015. 806 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] 807 McGrew, D., Foley, J., and K. Paterson, "Authenticated 808 Encryption with AES-CBC and HMAC-SHA", draft-mcgrew-aead- 809 aes-cbc-hmac-sha2-05 (work in progress), July 2014. 811 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 812 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 814 [RFC5766] Mahy, R., Matthews, P., and J. Rosenberg, "Traversal Using 815 Relays around NAT (TURN): Relay Extensions to Session 816 Traversal Utilities for NAT (STUN)", RFC 5766, April 2010. 818 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 819 Uniform Resource Identifiers (URIs)", RFC 5785, April 820 2010. 822 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 823 Security Version 1.2", RFC 6347, January 2012. 825 [RFC6819] Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 826 Threat Model and Security Considerations", RFC 6819, 827 January 2013. 829 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 830 Interchange Format", RFC 7159, March 2014. 832 [RFC7350] Petit-Huguenin, M. and G. Salgueiro, "Datagram Transport 833 Layer Security (DTLS) as Transport for Session Traversal 834 Utilities for NAT (STUN)", RFC 7350, August 2014. 836 [RFC7376] Reddy, T., Ravindranath, R., Perumal, M., and A. Yegin, 837 "Problems with Session Traversal Utilities for NAT (STUN) 838 Long-Term Authentication for Traversal Using Relays around 839 NAT (TURN)", RFC 7376, September 2014. 841 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 842 "Recommendations for Secure Use of Transport Layer 843 Security (TLS) and Datagram Transport Layer Security 844 (DTLS)", BCP 195, RFC 7525, May 2015. 846 Appendix A. Sample tickets 848 Input data (same for all samples below): 850 //STUN SERVER NAME 851 server_name = "blackdow.carleon.gov"; 853 //Shared key between AS and RS 855 long_term_key = \x48\x47\x6b\x6a\x33\x32\x4b\x4a\x47\x69\x75\x79 856 \x30\x39\x38\x73\x64\x66\x61\x71\x62\x4e\x6a\x4f 857 \x69\x61\x7a\x37\x31\x39\x32\x33 859 //MAC key of the session (included in the token) 860 mac_key = \x5a\x6b\x73\x6a\x70\x77\x65\x6f\x69\x78\x58\x6d\x76\x6e 861 \x36\x37\x35\x33\x34\x6d; 863 //length of the MAC key 864 mac_key_length = 20; 866 //The timestamp field in the token 867 token_timestamp = 92470300704768; 869 //The lifetime of the token 870 token_lifetime = 3600; 872 //nonce for AEAD 873 aead_nonce = \x68\x34\x6a\x33\x6b\x32\x6c\x32\x6e\x34\x62\x35; 875 Samples: 877 1) token encryption algorithm = AEAD_AES_256_GCM 879 Encrypted token (64 bytes = 2 + 12 +34 + 16) = 881 \x00\x0c\x68\x34\x6a\x33\x6b\x32\x6c\x32\x6e\x34\x62 882 \x35\x61\x7e\xf1\x34\xa3\xd5\xe4\x4e\x9a\x19\xcc\x7d 883 \xc1\x04\xb0\xc0\x3d\x03\xb2\xa5\x51\xd8\xfd\xf5\xcd 884 \x3b\x6d\xca\x6f\x10\xcf\xb7\x7e\x5b\x2d\xde\xc8\x4d 885 \x29\x3a\x5c\x50\x49\x93\x59\xf0\xc2\xe2\x6f\x76 887 2) token encryption algorithm = AEAD_AES_128_GCM 889 Encrypted token (64 bytes = 2 + 12 +34 + 16) = 891 \x00\x0c\x68\x34\x6a\x33\x6b\x32\x6c\x32\x6e\x34\x62 892 \x35\x7f\xb9\xe9\x9f\x08\x27\xbe\x3d\xf1\xe1\xbd\x65 893 \x14\x93\xd3\x03\x1d\x36\xdf\x57\x07\x97\x84\xae\xe5 894 \xea\xcb\x65\xfa\xd4\xf2\x7f\xab\x1a\x3f\x97\x97\x4b 895 \x69\xf8\x51\xb2\x4b\xf5\xaf\x09\xed\xa3\x57\xe0 897 Note: 898 [1] 899 After EVP_EncryptFinal_ex encrypts the final data 900 EVP_CIPHER_CTX_ctrl must be called to append 901 the authentication tag to the ciphertext. 902 //EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag); 903 [2] 904 EVP_CIPHER_CTX_ctrl must be invoked to set the 905 authentication tag before calling EVP_DecryptFinal. 906 //EVP_CIPHER_CTX_ctrl (&ctx, EVP_CTRL_GCM_SET_TAG, taglen, tag); 908 Figure 5: Sample tickets 910 Appendix B. Interaction between client and authorization server 912 Client makes an HTTP request to an authorization server to obtain a 913 token that can be used to avail itself of STUN services. The STUN 914 token is returned in JSON syntax [RFC7159], along with other OAuth 915 2.0 parameters like token type, key, token lifetime and kid defined 916 in [I-D.ietf-oauth-pop-key-distribution]. 918 +-------------------+ +--------+ +---------+ 919 | ......... STUN | | STUN | | WebRTC | 920 | .WebRTC . Client | | | | | 921 | .Client . | | Server | | Server | 922 | ......... | | | | | 923 +-------------------+ +--------+ +---------+ 924 | | STUN request | | 925 | |------------------------------------------>| | 926 | | | | 927 | | STUN error response | | 928 | | (401 Unauthorized) | | 929 | |<------------------------------------------| | 930 | | THIRD-PARTY-AUTHORIZATION | | 931 | | | | 932 | | | | 933 | | HTTP Request for token | | 934 |------------------------------------------------------------>| 935 | | HTTP Response with token parameters | | 936 |<------------------------------------------------------------| 937 |OAuth 2.0 | | 938 Attributes | | 939 |------>| | | 940 | | STUN request with ACCESS-TOKEN | | 941 | |------------------------------------------>| | 942 | | | | 943 | | STUN success response | | 944 | |<------------------------------------------| | 945 | | STUN Messages | | 946 | | ////// integrity protected ////// | | 947 | | ////// integrity protected ////// | | 948 | | ////// integrity protected ////// | | 950 Figure 6: STUN Third Party Authorization 952 [I-D.ietf-oauth-pop-key-distribution] describes the interaction 953 between the client and the authorization server. For example, the 954 client learns the STUN server name "stun1@example.com" from THIRD- 955 PARTY-AUTHORIZATION attribute value and makes the following HTTP 956 request for the access token using transport-layer security (with 957 extra line breaks for display purposes only): 959 HTTP/1.1 960 Host: server.example.com 961 Content-Type: application/x-www-form-urlencoded 962 aud=stun1@example.com 963 timestamp=1361471629 964 grant_type=implicit 965 token_type=pop 966 alg=HMAC-SHA-256-128 968 Figure 7: Request 970 [I-D.ietf-tram-stunbis] supports hash agility and accomplish this 971 agility by computing message integrity using both HMAC-SHA-1 and 972 HMAC-SHA-256-128. The client signals the algorithm supported by it 973 to the authorization server in the 'alg' parameter defined in 974 [I-D.ietf-oauth-pop-key-distribution]. The authorization server 975 determines length of the mac_key based on the HMAC algorithm conveyed 976 by the client. If the client supports both HMAC-SHA-1 and HMAC-SHA- 977 256-128 then it signals HMAC-SHA-256-128 to the authorization server, 978 gets 256-bit key from the authorization server and calculates 160-bit 979 key for HMAC-SHA-1 using SHA1 taking the 256-bit key as input. 981 If the client is authorized then the authorization server issues an 982 access token. An example of successful response: 984 HTTP/1.1 200 OK 985 Content-Type: application/json 986 Cache-Control: no-store 988 { 989 "access_token": 990 "U2FsdGVkX18qJK/kkWmRcnfHglrVTJSpS6yU32kmHmOrfGyI3m1gQj1jRPsr0uBb 991 HctuycAgsfRX7nJW2BdukGyKMXSiNGNnBzigkAofP6+Z3vkJ1Q5pWbfSRroOkWBn", 992 "token_type":"pop", 993 "expires_in":1800, 994 "kid":"22BIjxU93h/IgwEb", 995 "key":"v51N62OM65kyMvfTI08O" 996 "alg":HMAC-SHA-256-128 997 } 999 Figure 8: Response 1001 Authors' Addresses 1002 Tirumaleswar Reddy 1003 Cisco Systems, Inc. 1004 Cessna Business Park, Varthur Hobli 1005 Sarjapur Marathalli Outer Ring Road 1006 Bangalore, Karnataka 560103 1007 India 1009 Email: tireddy@cisco.com 1011 Prashanth Patil 1012 Cisco Systems, Inc. 1013 Bangalore 1014 India 1016 Email: praspati@cisco.com 1018 Ram Mohan Ravindranath 1019 Cisco Systems, Inc. 1020 Cessna Business Park, 1021 Kadabeesanahalli Village, Varthur Hobli, 1022 Sarjapur-Marathahalli Outer Ring Road 1023 Bangalore, Karnataka 560103 1024 India 1026 Email: rmohanr@cisco.com 1028 Justin Uberti 1029 Google 1030 747 6th Ave S 1031 Kirkland, WA 1032 98033 1033 USA 1035 Email: justin@uberti.name