idnits 2.17.1 draft-uberti-rtcweb-turn-rest-00.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 : ---------------------------------------------------------------------------- ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 217: '... SHOULD reject the request with a 40...' RFC 2119 keyword, line 225: '...cation fails, it SHOULD reject the req...' RFC 2119 keyword, line 232: '... the TURN server MUST verify the MESSA...' RFC 2119 keyword, line 254: '...ey compromise is RECOMMENDED. To faci...' RFC 2119 keyword, line 255: '... the TURN server SHOULD be able to val...' Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 08, 2013) is 3943 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) == Unused Reference: 'RFC2616' is defined on line 297, but no explicit reference was found in the text == Outdated reference: A later version (-08) exists of draft-petithuguenin-behave-turn-uris-03 ** Obsolete normative reference: RFC 5766 (Obsoleted by RFC 8656) -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Uberti 3 Internet-Draft Google 4 Intended status: Standards Track July 08, 2013 5 Expires: January 09, 2014 7 A REST API For Access To TURN Services 8 draft-uberti-rtcweb-turn-rest-00 10 Abstract 12 This document describes a proposed standard REST API for obtaining 13 access to TURN services via ephemeral (i.e. time-limited) 14 credentials. These credentials are vended by a web service over 15 HTTP, and then supplied to and checked by a TURN server using the 16 standard TURN protocol. The usage of ephemeral credentials ensures 17 that access to the TURN server can be controlled even if the 18 credentials can be discovered by the user, as is the case in WebRTC 19 where TURN credentials must be specified in Javascript. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on January 09, 2014. 38 Copyright Notice 40 Copyright (c) 2013 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 2. HTTP Interactions . . . . . . . . . . . . . . . . . . . . . . 3 57 2.1. Request . . . . . . . . . . . . . . . . . . . . . . . . . 3 58 2.2. Response . . . . . . . . . . . . . . . . . . . . . . . . 4 59 3. WebRTC Interactions . . . . . . . . . . . . . . . . . . . . . 4 60 4. TURN Interactions . . . . . . . . . . . . . . . . . . . . . . 5 61 4.1. Client . . . . . . . . . . . . . . . . . . . . . . . . . 5 62 4.2. Server . . . . . . . . . . . . . . . . . . . . . . . . . 5 63 5. Implementation Notes . . . . . . . . . . . . . . . . . . . . 6 64 5.1. Revocation . . . . . . . . . . . . . . . . . . . . . . . 6 65 5.2. Key Rotation . . . . . . . . . . . . . . . . . . . . . . 6 66 6. Security Considerations . . . . . . . . . . . . . . . . . . . 6 67 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 68 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 6 69 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 6 70 9.1. Normative References . . . . . . . . . . . . . . . . . . 7 71 9.2. Informative References . . . . . . . . . . . . . . . . . 7 72 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7 74 1. Introduction 76 TURN [RFC5766] is a protocol that is often used to improve the 77 connectivity of P2P applications. By providing a cloud-based relay 78 service, TURN ensures that a connection can be established even when 79 one or both sides is incapable of a direct P2P connection. However, 80 as a relay service, it imposes a nontrivial cost on the service 81 provider. Therefore, access to a TURN service is almost always 82 access-controlled. 84 TURN provides a mechanism to control access via "long-term" username/ 85 password credentials that are provided as part of the TURN protocol. 86 It is expected that these credentials will be kept secret; if the 87 credentials are discovered, the TURN server could be used by 88 unauthorized users or applications. However, in web applications, 89 ensuring this secrecy is typically impossible. 91 To address this problem, this document proposes an API that can be 92 used to retrieve ephemeral TURN credentials from a web service. For 93 simplicity, the design has been kept intentionally stateless; to use 94 this mechanism, the only interaction needed between the web service 95 and the TURN service is to share a secret key. 97 2. HTTP Interactions 99 To retrieve a new set of credentials, the client makes a HTTP POST 100 request, specifying TURN as the service to allocate credentials for, 101 and optionally specifying a user id parameter. The purpose of the 102 user id parameter is to simplify debugging on the TURN server, as 103 well as provide the ability to control the number of credentials 104 handed out for a specific user, if desired. The TURN credentials and 105 their lifetime are returned as JSON, along with URIs that indicate 106 how to connect to the server using the TURN protocol. To avoid the 107 need for state passing between the web service and TURN server, the 108 returned credentials consist of a TURN username that encodes all the 109 necessary state (expiry time and application user id), and a TURN 110 password that is a digest of this state, signed with the shared 111 secret key. Since the returned credentials are ephemeral, they will 112 eventually expire. This does not affect existing TURN allocations, 113 as they are tied to a specific 5-tuple, but requests to allocate new 114 TURN ports will fail after the expiry time. This is significant in 115 the case of an ICE restart, where the client will need to allocate a 116 new set of candidates, including TURN candidates. To get a new set 117 of ephemeral credentials, the client can simply re-issue the original 118 HTTP request with the same parameters, which will return the new 119 credentials in its JSON response. To prevent unauthorized use, the 120 HTTP requests can be ACLed by various means, e.g. IP address (if 121 coming from a server), Origin header, User-Agent header, login 122 cookie, API key, etc. 124 2.1. Request 126 The request includes the following parameters, specified in the URL: 128 o service: specifies the desired service (turn) 130 o username: an optional user id to be associated with the 131 credentials 133 o key: if an API key is used for authentication, the API key 135 Example: 137 POST /?service=turn&username=fred 139 2.2. Response 141 The response is returned with content-type "application/json", and 142 consists of a JSON object with the following parameters: 144 o username: the TURN username to use, which is a colon-delimited 145 combination of the expiration timestamp and the username parameter 146 from the request (if specified). The timestamp is intended to be 147 opaque to the web application, so its format is arbitrary, but for 148 simplicity, use of UNIX timestamps is recommended. 150 o password: the TURN password to use; this value is computed from 151 the a secret key shared with the TURN server and the returned 152 username value, by performing base64(hmac(secret key, returned 153 username)). HMAC-SHA1 is one HMAC algorithm that can be used, but 154 any algorithm that incorporates a shared secret is acceptable, as 155 long as both the web server and TURN server use the same algorithm 156 and secret. 158 o ttl: the duration for which the username and password are valid, 159 in seconds. A value of one day (86400 seconds) is recommended. 161 o uris: an array of TURN URIs, in the form specified in 162 [I-D.petithuguenin-behave-turn-uris]. This is used to indicate 163 the different addresses and/or protocols that can be used to reach 164 the TURN server. 166 Example: 168 { 169 "username" : "12334939:fred", 170 "password" : "adfsaflsjflds", 171 "ttl" : 86400, 172 "uris" : [ 173 "turn:1.2.3.4:9991?transport=udp", 174 "turn:1.2.3.4:9992?transport=tcp", 175 "turns:1.2.3.4:443?transport=tcp" 176 ] 177 } 179 3. WebRTC Interactions 181 The returned JSON is parsed and supplied when creating a WebRTC 182 RTCPeerConnection, to tell it how to access the TURN server. 184 Example: 186 var iceServer = { 187 "username": response.username, 188 "credential": response.password, 189 "uris": response.uris 190 }; 191 var config = {"iceServers": [iceServer]}; 192 var pc = new RTCPeerConnection(config); 194 When the credentials are updated (e.g. because they are about to 195 expire), a new RTCConfiguration with the updated credentials can be 196 supplied to the existing RTCPeerConnection via the updateIce method. 197 This update must not affect existing TURN allocations, because TURN 198 requires that the username stay constant for an allocation, but the 199 new credentials will be used for any new allocations. 201 [TODO: make sure this behavior is specified in the W3C API spec] 203 4. TURN Interactions 205 4.1. Client 207 WebRTC's TURN request uses the supplied "username" value for its 208 USERNAME attribute, and the "password" value for the input to the 209 MESSAGE-INTEGRITY hash. 211 4.2. Server 213 When processing ALLOCATE requests, the TURN server will split the 214 USERNAME attribute into its timestamp and user id components, and 215 verify that the timestamp, which indicates when the credentials 216 expire, has not yet been reached. If this verification fails, it 217 SHOULD reject the request with a 401 (Unauthorized) error. 219 If desired, the TURN server can optionally verify that the parsed 220 user id value corresponds to a currently valid user of an external 221 service (e.g. is currently logged in to the web app that is making 222 use of TURN). This requires proprietary communication between the 223 TURN server and external service on each ALLOCATE request, so this 224 usage is not recommended for typical applications. If this external 225 verification fails, it SHOULD reject the request with a 401 226 (Unauthorized) error. 228 For non-ALLOCATE requests, the TURN server merely verifies that the 229 USERNAME matches the USERNAME that was used in the ALLOCATE (since it 230 must remain constant). 232 As in RFC 5766, the TURN server MUST verify the MESSAGE-INTEGRITY 233 using the password associated with the supplied USERNAME. For the 234 usage outlined in this document, the password will always be 235 constructed using the supplied username and the shared secret as 236 indicated in the "HTTP Interactions" section above. 238 5. Implementation Notes 240 5.1. Revocation 242 In the system as described here, revoking specific credentials is not 243 possible. The assumption is that TURN services are of low enough 244 value that waiting for the timeout to expire is a valid approach for 245 dealing with possibly-compromised credentials. 247 In extreme abuse cases, TURN server blacklists of timestamp+username 248 values can be supplied by an administrator to stop abuse of specific 249 credential sets. 251 5.2. Key Rotation 253 As indicated in [RFC2104], periodic rotation of the shared secret to 254 protect against key compromise is RECOMMENDED. To facilitate the 255 rollover, the TURN server SHOULD be able to validate incoming 256 MESSAGE-INTEGRITY tokens based on at least 2 shared secrets at any 257 time. 259 6. Security Considerations 261 Because the USERNAME values in a TURN ALLOCATE request are typically 262 visible to eavesdroppers, inclusion of an externally identifying user 263 id, such as a login name, may allow a passive attacker to determine 264 the identities of the parties in a conversation. To prevent this 265 problem, use of opaque user id values is recommended. 267 7. IANA Considerations 269 None. 271 8. Acknowledgements 273 Harald Alvestrand, Alfred Godoy, and Philipp Hancke provided key 274 input on the initial design. Dave Cridland, Cullen Jennings, Oleg 275 Moskalenko, and Matthew Robertson pointed out several errors and 276 omissions. 278 9. References 279 9.1. Normative References 281 [I-D.petithuguenin-behave-turn-uris] 282 Petit-Huguenin, M., Nandakumar, S., Salgueiro, G., and P. 283 Jones, "Traversal Using Relays around NAT (TURN) Uniform 284 Resource Identifiers", draft-petithuguenin-behave-turn- 285 uris-03 (work in progress), January 2013. 287 [RFC5766] Mahy, R., Matthews, P., and J. Rosenberg, "Traversal Using 288 Relays around NAT (TURN): Relay Extensions to Session 289 Traversal Utilities for NAT (STUN)", RFC 5766, April 2010. 291 9.2. Informative References 293 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 294 Hashing for Message Authentication", RFC 2104, February 295 1997. 297 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 298 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 299 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 301 Author's Address 303 Justin Uberti 304 Google 305 747 6th St S 306 Kirkland, WA 98033 307 USA 309 Email: justin@uberti.name