TURN Extension for Third
Party AuthorizationCisco Systems, Inc.Cessna Business Park, Varthur HobliSarjapur Marathalli Outer Ring RoadBangaloreKarnataka560103Indiatireddy@cisco.comCisco Systems, Inc.BangaloreIndiapraspati@cisco.comCisco Systems, Inc.Cessna Business Park,Kadabeesanahalli Village, Varthur Hobli,Sarjapur-Marathahalli Outer Ring RoadBangaloreKarnataka560103Indiarmohanr@cisco.comGoogle747 6th Ave SKirkland, WA98033USAjustin@uberti.nameTRAMThis 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.Traversal Using Relay NAT (TURN) TURN
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 , this document proposes the
use of third party authorization using OAuth for TURN.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.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 .WebRTC Server: A web server that supports WebRTC .Access Token: OAuth 2.0 access token.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.kid: An ephemeral and unique key identifier. The kid also allows
the resource server to select the appropriate keying material for
decryption.This specification uses the token type 'Assertion' (aka
self-contained token) described in 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.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 learns the TURN server name
“turn1@example.com” from THIRD-PARTY-AUTHORIZATION attribute
value and makes the following HTTP request for the access token using
transport-layer security (with extra line breaks for display purposes
only):If the client is authorized then the authorization server
issues an access token. An example of successful response:Access token and other attributes issued by the authorization server
are explained in .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.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 .OAuth in defines four grant types.
This specification uses the OAuth grant type "Implicit" explained in
section 1.3.2 of where the WebRTC client
is issued an access token directly. The scope of the access token
explained in section 3.3 of MUST be
TURN.The TURN and authorization servers MUST establish a symmetric key
(K), using an out of band mechanism. Symmetric key MUST be chosen to
ensure that the size of encrypted token is not large because usage of
asymmetric keys will result in large encrypted tokens which may not
fit into a single STUN message. The AS-RS, AUTH keys will be derived
from K. AS-RS key is used for encrypting the self-contained token and
message integrity of the encrypted token is calculated using the AUTH
key. The TURN and authorization servers MUST establish the symmetric
key over an authenticated secure channel. The establishment of
symmetric key is outside the scope of this specification. For example,
implementations could use one of the following mechanisms in to
establish a symmetric key.The two servers could choose to use Dynamic Symmetric Key
Provisioning Protocol (DSKPP) to
establish a symmetric key (K). The encryption and MAC algorithms
will be negotiated using the KeyProvClientHello, KeyProvServerHello
messages. A unique key identifier (referred to as KeyID) for the
symmetric key is generated by the DSKPP server (i.e. Authorization
server) and signalled to the DSKPP client (i.e TURN server) which is
equivalent to the kid defined in this specification. The AS-RS, AUTH
keys would be derived from the symmetric key using (HMAC)-based key
derivation function (HKDF) and the
default hash function is SHA-256. For example if the input symmetric
key (K) is 32 octets length, encryption algorithm is AES_128_CBC and
HMAC algorithm is HMAC-SHA-256-128 then the secondary keys AS-RS,
AUTH are generated from the input key K as followsHKDF-Extract(zero, K) -> PRKHKDF-Expand(PRK, zero, 16) -> AS-RS keyHKDF-Expand(PRK, zero, 32) -> AUTH keyThe two servers could choose to use REST API to establish a
symmetric key. To retrieve a new symmetric key, the TURN server
makes an HTTP GET request to the authorization server, specifying
TURN as the service to allocate the symmetric keys for, and
specifying the name of the TURN server. The response is returned
with content-type "application/json", and consists of a JSON object
containing the symmetric key.The AS-RS, AUTH keys are derived from K using HKDF as discussed
in . Authorization server must also
signal a unique key identifier (kid) to the TURN server which will
be used to select the appropriate keying material for decryption.
The default encryption algorithm to encrypt the self-contained token
could be Advanced Encryption Standard (AES) in Cipher Block Chaining
(CBC) mode (AES_128_CBC). The default HMAC algorithm to calculate
the integrity of the token could be HMAC-SHA-256-128. In this case
AS-RS key length must be 128-bit, AUTH key length must be 256-bit
(section 2.6 of ).TURN and authorization servers could be manually configured with
a symmetric key (K) and kid. The default encryption and HMAC
algorithms could be AES_256_CBC, HMAC-SHA-256-128.Note : The mechanisms specified in are easy to implement and deploy
compared to DSKPP but lack encryption and HMAC algorithm
agility.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.
The HMAC for the MESSAGE-INTEGRITY attribute is computed as described in
section 15.4 of where the mac_key is used
as the input key for the HMAC computation. The TURN client and server
will use the mac_key to compute the message integrity and doesn't have
to perform MD5 hash on the credentials.The following new STUN attributes are introduced by this
specification to accomplish third party authorization.This attribute is used by the TURN server to inform the client that
it supports third party authorization. This attribute value contains
the TURN server name. The TURN server may have tie-up with multiple
authorization servers and vice versa, so the client MUST provide the
TURN server name to the authorization server so that it can select the
appropriate keying material to generate the self-contained token. The
THIRD-PARTY-AUTHORIZATION attribute is a comprehension-optional
attribute (see Section 15 from ).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 ), 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 ).The token is structured as follows:The fields are described below: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
.The session key generated by the
authorization server.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).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 .The Hashed Message Authentication Code (HMAC)
is calculated with AUTH key over the encrypted portion of the
token and the TURN server name (N) conveyed in the
THIRD-PARTY-AUTHORIZATION response . Encryption is applied before
authentication on the sender side and conversely on the receiver
side. The length of the mac field is known to the TURN and
authorization server based on the negotiated MAC algorithm.For example the encryption process can be illustrated as follows.
Here C, N denote the ciphertext and TURN server name.C = AES_128_CBC(AS-RS, encrypted_block)mac = HMAC-SHA-256-128(AUTH, C | | N)The token MUST be encoded as defined in Section 4 of and then encrypted using the symmetric
long-term key established between the resource server and the
authorization server, as shown in
as AS-RS key. HMAC is computed using the encrypted portion of the
token and TURN server name to ensure that the client does not use the
same token to gain illegal access to other TURN servers provided by
the same administrative domain. This attack is possible when multiple
TURN servers in a single administrative domain share the same
symmetric key with the authorization server. 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 include the ACCESS-TOKEN attribute only in
Allocate and Refresh requests.The TURN server, on receiving a request with ACCESS-TOKEN attribute,
performs checks listed in section 10.2.2 of in addition to the following steps to verify
that the access token is valid:TURN server selects the keying material based on kid signalled in
the USERNAME attribute.It performs the verification of the token message integrity by
calculating HMAC over the encrypted portion in the self-contained
token and TURN server name using AUTH key and if the resulting value
does not match the mac field in the self-contained token then it
rejects the request with an error response 401 (Unauthorized).TURN server 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).The TURN server verifies that no replay took place by performing
the following check: The access token is accepted if the timestamp field (TS) in
the self-contained token is recent enough to the reception time
of the TURN request (RDnew) using the following formula:
Lifetime + Delta > abs(RDnew - TS). 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).The TURN server uses the mac_key to compute the message integrity
over the request 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).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.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.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.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. If an attacker tries to replay
message with ACCESS-TOKEN attribute then the server can detect that the
transaction ID as used for an old request and thus prevent the replay
attack.Security considerations discussed in and are to be taken into account.IANA is requested to add the following attributes to the STUN attribute registry, THIRD-PARTY-AUTHORIZATIONACCESS-TOKENAuthors would like to thank Dan Wing, Pal Martinsen, Oleg Moskalenko
and Charles Eckel for comments and review. The authors would like to
give special thanks to Brandon Williams for his help.IANA: STUN Attributes