TRAM T. Reddy
Internet-Draft P. Patil
Intended status: Standards Track R. Ravindranath
Expires: October 25, 2014 Cisco
J. Uberti
Google
April 23, 2014
TURN Extension for Third Party Authorization
draft-reddy-tram-turn-third-party-authz-01
Abstract
This document proposes the use of OAuth to obtain and validate
ephemeral tokens that can be used for TURN authentication. The usage
of ephemeral tokens ensure that access to a TURN server can be
controlled even if the tokens are compromised, as is the case in
WebRTC where TURN credentials must be specified in Javascript.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on October 25, 2014.
Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
Reddy, et al. Expires October 25, 2014 [Page 1]
Internet-Draft TURN for 3rd party Authorization April 2014
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Solution Overview . . . . . . . . . . . . . . . . . . . . . . 3
4. Obtaining a Token Using OAuth . . . . . . . . . . . . . . . . 5
4.1. Key Establishment . . . . . . . . . . . . . . . . . . . . 7
4.1.1. HTTP interactions . . . . . . . . . . . . . . . . . . 8
5. Forming a Request . . . . . . . . . . . . . . . . . . . . . . 9
6. STUN Attributes . . . . . . . . . . . . . . . . . . . . . . . 9
6.1. THIRD-PARTY-AUTHORIZATION . . . . . . . . . . . . . . . . 9
6.2. ACCESS-TOKEN . . . . . . . . . . . . . . . . . . . . . . 9
7. Receiving a request with ACCESS-TOKEN attribute . . . . . . . 11
8. Changes to Client . . . . . . . . . . . . . . . . . . . . . . 11
9. Security Considerations . . . . . . . . . . . . . . . . . . . 12
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12
11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 12
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 12
12.1. Normative References . . . . . . . . . . . . . . . . . . 12
12.2. Informative References . . . . . . . . . . . . . . . . . 13
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13
1. Introduction
TURN [RFC5766] is a protocol that is often used to improve the
connectivity of P2P applications. By providing a cloud-based relay
service, TURN ensures that a connection can be established even when
one or both sides is incapable of a direct P2P connection. However,
as a relay service, it imposes a nontrivial cost on the service
provider. Therefore, access to a TURN service is almost always
access-controlled.
TURN provides a mechanism to control access via "long-term" username/
password credentials that are provided as part of the TURN protocol.
It is expected that these credentials will be kept secret; if the
credentials are discovered, the TURN server could be used by
unauthorized users or applications. However, in web applications,
ensuring this secrecy is typically impossible. To address this
problem and the ones described in [I-D.ietf-tram-auth-problems], this
document proposes the use of third party authorization using OAuth
for TURN.
Reddy, et al. Expires October 25, 2014 [Page 2]
Internet-Draft TURN for 3rd party Authorization April 2014
To achieve third party authorization, a resource owner e.g. WebRTC
server, authorizes a TURN client to access resources on the TURN
server.
Using OAuth, a client obtains an ephemeral token from an
authorization server e.g. WebRTC server, and the token is presented
to the TURN server instead of the traditional mechanism of presenting
username/password credentials. The TURN server validates the
authenticity of the token and provides required services.
2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
o WebRTC Server: A web server that supports WebRTC
[I-D.ietf-rtcweb-overview].
o Access Token: OAuth 2.0 access token.
o mac_key: The session key generated by the authorization server.
Note that the lifetime of the session key is equal to the lifetime
of the access token.
o kid: An ephemeral and unique key identifier. The kid also allows
the resource server to select the appropriate keying material for
decryption.
3. Solution Overview
This specification uses the token type 'Assertion' (aka self-
contained token) described in [RFC6819] where all the information
necessary to authenticate the validity of the token is contained
within the token itself. This approach has the benefit of avoiding a
protocol between the TURN server and the authorization server for
token validation, thus reducing latency. The exact mechanism used by
a client to obtain a token from the OAuth authorization server is
outside the scope of this document. For example, a client could make
an HTTP request to an authorization server to obtain a token that can
be used to avail TURN services. The TURN token is returned in JSON,
along with other OAuth Parameters like token type, mac_key, kid,
token lifetime etc. The client is oblivious to the content of the
token. The token is embedded within a TURN request sent to the TURN
server. Once the TURN server has determined the token is valid, TURN
services are offered for a determined period of time.
Reddy, et al. Expires October 25, 2014 [Page 3]
Internet-Draft TURN for 3rd party Authorization April 2014
+-------------------+ +--------+ +---------+
| ......... TURN | | TURN | | WebRTC |
| .WebRTC . Client | | | | |
| .Client . | | Server | | Server |
| ......... | | | | |
+-------------------+ +--------+ +---------+
| | Allocate request | |
| |------------------------------------------>| |
| | | |
| | Allocate error response | |
| |<------------------------------------------| |
| | THIRD-PARTY-AUTHORIZATION | |
| | | |
| | | |
| | HTTP Request for token | |
|------------------------------------------------------------>|
| | HTTP Response with token parameters | |
|<------------------------------------------------------------|
|OAuth | | |
Attributes | |
|------>| | |
| | Allocate request ACCESS-TOKEN | |
| |------------------------------------------>| |
| | | |
| | Allocate success response | |
| |<------------------------------------------| |
| | TURN Messages | |
| | ////// integrity protected ////// | |
| | ////// integrity protected ////// | |
| | ////// integrity protected ////// | |
Figure 1: TURN Third Party Authorization
Note : An implementation may choose to contact the WebRTC server to
obtain a token even before it makes an allocate request, if it knows
the server details before hand. For example, once a client has
learnt that a TURN server supports Third Party authorization from a
WebRTC server, the client can obtain the token before making
subsequent allocate requests.
For example, the client makes the following HTTP request for the
access token using transport-layer security (with extra line breaks
for display purposes only):
Reddy, et al. Expires October 25, 2014 [Page 4]
Internet-Draft TURN for 3rd party Authorization April 2014
POST /o/oauth2/token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
kid=22BIjxU93h/IgwEb
timestamp=1361471629
grant_type=implicit
Figure 2: Request
If the client is authorized then the authorization server issues an
access token.An example of successful response:
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
"access_token":
"U2FsdGVkX18qJK/kkWmRcnfHglrVTJSpS6yU32kmHmOrfGyI3m1gQj1jRPsr0uBb
HctuycAgsfRX7nJW2BdukGyKMXSiNGNnBzigkAofP6+Z3vkJ1Q5pWbfSRroOkWBn",
"token_type":"mac",
"expires_in":1800,
"kid":"22BIjxU93h/IgwEb",
"mac_key":"v51N62OM65kyMvfTI08O"
}
Figure 3: Response
Access token and other attributes issued by the authorization server
are explained in Section 6.2.
4. Obtaining a Token Using OAuth
A TURN client should know the authentication capability of the TURN
server before deciding to use third party authorization with it. A
TURN client initially makes a request without any authorization. If
the TURN server supports or mandates third party authorization, it
will return an error message indicating support for third party
authorization. The TURN server includes an ERROR-CODE attribute with
a value of 401 (Unauthorized), a nonce value in a NONCE attribute and
a SOFTWARE attribute that gives information about the TURN server's
software. The TURN servers also includes additional STUN attribute
THIRD-PARTY-AUTHORIZATION signaling the TURN client that the TURN
server supports third party authorization.
Reddy, et al. Expires October 25, 2014 [Page 5]
Internet-Draft TURN for 3rd party Authorization April 2014
The following mapping of OAuth concepts to WebRTC is used :
+----------------------+----------------------------+
| OAuth | WebRTC |
+======================+============================+
| Client | WebRTC client |
+----------------------+----------------------------+
| Resource owner | WebRTC server |
+----------------------+----------------------------+
| Authorization server | Authorization server |
+----------------------+----------------------------+
| Resource server | TURN Server |
+----------------------+----------------------------+
Figure 4: OAuth terminology mapped to WebRTC terminology
Using the OAuth 2.0 authorization framework, a WebRTC client (third-
party application) obtains limited access to a TURN (resource server)
on behalf of the WebRTC server (resource owner or authorization
server). The WebRTC client requests access to resources controlled
by the resource owner (WebRTC server) and hosted by the resource
server (TURN server). The WebRTC client obtains access token,
lifetime, session key (in the mac_key parameter) and key id (kid).
The TURN client conveys the access token and other OAuth parameters
learnt from the authorization server to the resource server (TURN
server). The TURN server obtains the session key from the access
token. The TURN server validates the token, computes the message
integrity of the request and takes appropriate action i.e permits the
TURN client to create allocations. This is shown in an abstract way
in Figure 5.
Reddy, et al. Expires October 25, 2014 [Page 6]
Internet-Draft TURN for 3rd party Authorization April 2014
+---------------+
| +<******+
+------------->| Authorization | *
| | Server | *
| +----------|(WebRTC Server)| * AS-RS,
| | | | * AUTH keys
(2) | | +---------------+ * (1)
Access | | (3) *
Token | | Access Token *
Request | | + *
| | Session Key *
| | *
| V V
+-------+---+ +-+----=-----+
| | (4) | |
| | TURN Request + Access | |
| WebRTC | Token | TURN |
| Client |---------------------->| Server |
| (Alice) | Allocate Response | |
| |<----------------------| |
+-----------+ +------------+
User : Alice
****: Out-of-Band Long-Term Key Establishment
Figure 5: Interactions
OAuth in [RFC6749] defines four grant types. This specification uses
the OAuth grant type "Implicit" explained in section 1.3.2 of
[RFC6749] where the WebRTC client is issued an access token directly.
The scope of the access token explained in section 3.3 of [RFC6749]
MUST be TURN.
4.1. Key Establishment
The TURN and authorization servers establish symmetric key (AS-RS
key) for confidentiality and authentication key (AUTH key) for
integrity, using an out of band mechanism. The Token is encrypted
using Advanced Encryption Standard (AES) in Cipher Block Chaining
(CBC) mode, using the AS-RS key for confidentiality.The default AS-RS
key size is 128 bits, and all implementations MUST support this key
size. Implementations MAY also support key sizes of 192 bits and 256
bits. Symmetric keys MUST be chosen to ensure that the size of
encrypted token is not large. Usage of asymmetric keys will result
in large encrypted tokens which may not fit into a single STUN
message. The integrity of the token is calculated with the AUTH key
and using HMAC-SHA-256-128 algorithm. AUTH key length MUST be
256-bit (section 2.6 of [RFC4868]). Authorization server MUST also
Reddy, et al. Expires October 25, 2014 [Page 7]
Internet-Draft TURN for 3rd party Authorization April 2014
also signal a unique key identifier (kid) to the TURN server which
will be used to select the appropriate keying material for
decryption.
The TURN and Authorization servers MUST establish the symmetric key
over an authenticated secure channel. For example, the two servers
could choose to use Dynamic Symmetric Key Provisioning Protocol
[RFC6063] or simply use HTTP for this exchange. The following
example describes HTTP interactions that could be used to obtain the
symmetric key.
4.1.1. HTTP interactions
To retrieve a new set of symmetric keys, the TURN server makes an
HTTP GET request to the Authorization server, specifying TURN as the
service to allocate the symmetric keys for, and optionally specifying
the domain name/IP Address of the TURN server. The response is
returned with content-type "application/json", and consists of a JSON
object containing the symmetric key.
Request
-------
service - specifies the desired service (turn)
domain - an optional domain to be associated with the key
example: GET /?service=turn&domain=turn.example.com
Response
--------
ckey - symmetric key (AS-RS key)
akey - authentication key (AUTH key)
ttl - the duration for which the key is valid, in seconds.
example:
{
"ckey" : "ESIzRFVmd4iZABEiM0RVZgKn6WjLaTC1",
"akey" : "FXAghRMVTzkBGNaaN496523WIISKerLi",
"ttl" : 86400,
"kid" :"22BIjxU93h/IgwEb"
}
Reddy, et al. Expires October 25, 2014 [Page 8]
Internet-Draft TURN for 3rd party Authorization April 2014
5. Forming a Request
When a TURN server responds that third party authorization is
required, a TURN client re-attempts the request, this time including
access token and kid values in ACCESS-TOKEN and USERNAME STUN
attributes. The TURN client includes a MESSAGE-INTEGRITY attribute
as the last attribute in the message over the contents of the TURN
message. MESSAGE-INTEGRITY attribute is calculated using the long-
term credentials mechanism specified in section 10.2 of [RFC5389],
using the "kid" value from the returned JSON for its USERNAME
attribute, and the mac_key for computing the message integrity.
6. STUN Attributes
The following new STUN attributes are introduced by this
specification to accomplish third party authorization.
6.1. THIRD-PARTY-AUTHORIZATION
This attribute is used by the TURN server to inform the client that
it supports third party authorization. This attribute is used by the
TURN server to inform the client that it supports third party
authorization. This optional attribute value be a URL that the
client should contact, to obtain a token for third party
authorization. The format for the URL will be as described in
[RFC3986]. The THIRD-PARTY-AUTHORIZATION attribute is a
comprehension-optional attribute (see Section 15 from [RFC5389]).
The TURN server may have tie-up with multiple authorization servers
so the client MUST provide the TURN server domain name or IP address
to the authorization server so that it can select the appropriate
keying material to generate the self-contained token.
6.2. ACCESS-TOKEN
The access token is issued by the authorization server. OAuth does
not impose any limitation on the length of the access token but if
path MTU is unknown then STUN messages over IPv4 would need to be
less than 548 bytes (Section 7.1 of [RFC5389]), access token length
needs to be restricted to fit within the maximum STUN message size.
Note that the self-contained token is opaque to the client and it
MUST NOT examine the ticket. The ACCESS-TOKEN attribute is a
comprehension-optional attribute (see Section 15 from [RFC5389]).
The token is structured as follows:
Reddy, et al. Expires October 25, 2014 [Page 9]
Internet-Draft TURN for 3rd party Authorization April 2014
struct {
ushort key_length;
opaque mac_key[key_length];
opaque timestamp[8];
long lifetime;
opaque mac[16];
} token;
Figure 6: Self-contained token format
The fields are described below:
key_length: Length of the session key. key length of 160-bits MUST
be supported (i.e only 160-bit key is used by HMAC-SHA-1 for
message integrity of STUN message). The key length facilitates
the hash agility plan discussed in section 16.3 of [RFC5389].
mac_key: The session key generated by the authorization server.
Timestamp: 64-bit unsigned integer field containing a timestamp.
The value indicates the time since January 1, 1970, 00:00 UTC, by
using a fixed point format. In this format, the integer number of
seconds is contained in the first 48 bits of the field, and the
remaining 16 bits indicate the number of 1/64K fractions of a
second (Native format - Unix).
Lifetime: The lifetime of the access token, in seconds. For
example, the value 3600 indicates one hour. The Lifetime value
SHOULD be equal to the "expires_in" parameter defined in section
4.2.2 of [RFC6749].
mac: The Message Authentication Code (MAC) is calculated with AUTH
key and using HMAC-SHA-256-128 algorithm over key, timestamp and
lifetime fields to verify the integrity of the access token.
The token MUST be encoded as defined in Section 4 of [RFC4648] and
then encrypted using the symmetric long-term key established between
the resource server and the authorization server, as shown in
Figure 5 as AS-RS key. Since the access token is valid for a
specific period of time the resource server MUST cache it so that it
need not to be provided in every request within an existing
allocation. The access token can be re-used for multiple Allocate
requests to the same TURN server. The TURN client MUST only include
the ACCESS-TOKEN attribute in Allocate and Refresh requests.
Reddy, et al. Expires October 25, 2014 [Page 10]
Internet-Draft TURN for 3rd party Authorization April 2014
7. Receiving a request with ACCESS-TOKEN attribute
The TURN server, on receiving a request with ACCESS-TOKEN attribute,
performs checks listed in section 10.2.2 of [RFC5389] in addition to
the following steps to verify that the access token is valid:
o When the TURN server receives a message with a new access token,
it obtains the mac_key by retrieving the content of the access
token (which requires decryption of the self-contained token using
the AS-RS key).
o The TURN server calculates HMAC-SHA-256-128 over key, timestamp
and lifetime fields in the self-contained token and if the
resulting value does not match the mac field in self-contained
token then it rejects the request with an error response 401
(Unauthorized).
o The TURN server verifies that no replay took place by performing
the following check:
o
* The received timestamp (timestamp field in self-contained
token) is checked and the access token is accepted if the
timestamp is recent enough to the reception time of the TURN
request (RDnew) using the following formula: Lifetime + Delta >
abs(RDnew - TSnew). The RECOMMENDED value for the allowed
Delta is 5 seconds. If the timestamp is NOT within the
boundaries then the TURN server discards the request with error
response 401 (Unauthorized).
o The TURN server uses the mac_key to compute the value for the
message integrity and if the resulting value does not match the
contents of the MESSAGE-INTEGRITY attribute then it rejects the
request with an error response 401 (Unauthorized).
o If all the checks pass, the TURN server continues to process the
request. Any response generated by the server MUST include the
MESSAGE-INTEGRITY attribute, computed using the mac_key.
The lifetime provided by the TURN server in the Allocate and Refresh
responses MUST be less than or equal to the lifetime of the token.
8. Changes to Client
o A TURN response is discarded by the client if the value computed
for message integrity using mac_key does not match the contents of
the MESSAGE-INTEGRITY attribute.
Reddy, et al. Expires October 25, 2014 [Page 11]
Internet-Draft TURN for 3rd party Authorization April 2014
o If the access token expires then the client MUST obtain a new
token from the authorization server and use it for new
allocations. The client MUST also use the new token to refresh
existing allocations. This way client has to maintain only one
token per TURN server.
9. Security Considerations
When OAuth is used the interaction between the client and the
authorization server requires Transport Layer Security (TLS) with a
ciphersuite offering confidentiality protection. The session key
MUST NOT be transmitted in clear since this would completely destroy
the security benefits of the proposed scheme.
Security considerations discussed in [I-D.ietf-oauth-v2-http-mac] are
to be taken into account.
10. IANA Considerations
IANA is requested to add the following attributes to the STUN
attribute registry [iana-stun],
o THIRD-PARTY-AUTHORIZATION
o ACCESS-TOKEN
11. Acknowledgements
Authors would like to thank Dan Wing, Pal Martinsen and Oleg
Moskalenko for comments and review. The authors would like to give
special thanks to Brandon Williams for his help.
12. References
12.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, RFC
3986, January 2005.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, October 2006.
[RFC4868] Kelly, S. and S. Frankel, "Using HMAC-SHA-256, HMAC-
SHA-384, and HMAC-SHA-512 with IPsec", RFC 4868, May 2007.
Reddy, et al. Expires October 25, 2014 [Page 12]
Internet-Draft TURN for 3rd party Authorization April 2014
[RFC5389] Rosenberg, J., Mahy, R., Matthews, P., and D. Wing,
"Session Traversal Utilities for NAT (STUN)", RFC 5389,
October 2008.
[RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC
6749, October 2012.
[iana-stun]
IANA, , "IANA: STUN Attributes", April 2011,
<http://www.iana.org/assignments/stun-parameters/stun-pa
rameters.xml>.
12.2. Informative References
[I-D.ietf-oauth-v2-http-mac]
Richer, J., Mills, W., Tschofenig, H., and P. Hunt, "OAuth
2.0 Message Authentication Code (MAC) Tokens", draft-ietf-
oauth-v2-http-mac-05 (work in progress), January 2014.
[I-D.ietf-rtcweb-overview]
Alvestrand, H., "Overview: Real Time Protocols for Brower-
based Applications", draft-ietf-rtcweb-overview-09 (work
in progress), February 2014.
[I-D.ietf-tram-auth-problems]
Reddy, T., R, R., Perumal, M., and A. Yegin, "Problems
with STUN Authentication for TURN", draft-ietf-tram-auth-
problems-00 (work in progress), March 2014.
[RFC5766] Mahy, R., Matthews, P., and J. Rosenberg, "Traversal Using
Relays around NAT (TURN): Relay Extensions to Session
Traversal Utilities for NAT (STUN)", RFC 5766, April 2010.
[RFC6063] Doherty, A., Pei, M., Machani, S., and M. Nystrom,
"Dynamic Symmetric Key Provisioning Protocol (DSKPP)", RFC
6063, December 2010.
[RFC6819] Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0
Threat Model and Security Considerations", RFC 6819,
January 2013.
Authors' Addresses
Reddy, et al. Expires October 25, 2014 [Page 13]
Internet-Draft TURN for 3rd party Authorization April 2014
Tirumaleswar Reddy
Cisco Systems, Inc.
Cessna Business Park, Varthur Hobli
Sarjapur Marathalli Outer Ring Road
Bangalore, Karnataka 560103
India
Email: tireddy@cisco.com
Prashanth Patil
Cisco Systems, Inc.
Bangalore
India
Email: praspati@cisco.com
Ram Mohan Ravindranath
Cisco Systems, Inc.
Cessna Business Park,
Kadabeesanahalli Village, Varthur Hobli,
Sarjapur-Marathahalli Outer Ring Road
Bangalore, Karnataka 560103
India
Email: rmohanr@cisco.com
Justin Uberti
Google
747 6th Ave S
Kirkland, WA
98033
USA
Email: justin@uberti.name
Reddy, et al. Expires October 25, 2014 [Page 14]