struct {
          uint16_t nonce_length; 
          opaque nonce[nonce_length];
          opaque {
              uint16_t key_length;
              opaque mac_key[key_length];
              uint64_t timestamp;
              uint32_t lifetime;
          } encrypted_block;            
      } token;

Figure 4: Self-contained token format

Note: uintN_t means an unsigned integer of exactly N bits. Single-byte entities containing uninterpreted data are of type opaque. All values in the token are stored in network byte order.

The associated data (A) MUST be the STUN server name. This ensures that the client does not use the same token to gain illegal access to other STUN servers provided by the same administrative domain i.e., when multiple STUN servers in a single administrative domain share the same symmetric key with an authorization server.

The fields are described below:

nonce_length:

Length of the nonce field. The length of nonce for authenticated encryption with additional data (AEAD) algorithms is explained in [RFC5116].

Nonce:

Nonce (N) formation is explained in section 3.2 of [RFC5116].

key_length:

Length of the session key in octets. 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 MUST be greater than or equal to the "expires_in" parameter defined in section 4.2.2 of [RFC6749], otherwise resource server could revoke the token but the client would assume that the token has not expired and would not refresh the token.

encrypted_block:

The encrypted_block (P) is encrypted and authenticated using the symmetric long-term key established between the STUN server and the authorization server.

The AEAD encryption operation has four inputs: K , N, A, and P, as defined in section 2.1 of [RFC5116] and there is a single output a ciphertext C or an indication that the requested encryption operation could not be performed.

If AES_CBC_HMAC_SHA2 (explained in section 2.1 of [I-D.mcgrew-aead-aes-cbc-hmac-sha2])) is used then the encryption process is illustrated below. The ciphertext consists of the string S, with the string T appended to it. Here C and A denote Ciphertext and STUN server name respectively. The octet string AL (section 2.1 of [I-D.mcgrew-aead-aes-cbc-hmac-sha2]) is equal to the number of bits in A expressed as a 64-bit unsigned big endian integer.

• AUTH = initial authentication key length octets of K,
• AS-RS = final encryption key length octets of K,
• S = CBC-PKCS7-ENC(AS-RS, encrypted_block),
  • Initialization vector is set to zero because the encrypted_block in each access token will not be identical and hence will not result in generation of identical ciphertext.
• mac = MAC(AUTH, A || S || AL),
• T = initial T_LEN octets of mac,
• C = S || T.

The entire token i.e., the 'encrypted_block' is base64 encoded (see section 4 of [RFC4648]) and the resulting access token is signaled to the client.

7. STUN server behaviour

The STUN 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:

• STUN server selects the keying material based on kid signalled in the USERNAME attribute.
• The AEAD decryption operation has four inputs: K, N, A, and C, as defined in section 2.2 of [RFC5116]. AEAD decryption algorithm has only a single output, either a plaintext or a special symbol FAIL that indicates that the inputs are not authentic. If authenticated decrypt operation returns FAIL then the STUN server rejects the request with an error response 401 (Unauthorized).
• If AES_CBC_HMAC_SHA2 is used then the final T_LEN octets are stripped from C. It performs the verification of the token message integrity by calculating HMAC over the the STUN server name, the encrypted portion in the self-contained token and the AL 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).
• STUN 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 STUN 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 STUN 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 STUN server discards the request with error response 401 (Unauthorized).
• The STUN 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 STUN server continues to process the request. Any response generated by the server MUST include the MESSAGE-INTEGRITY attribute, computed using the mac_key.

If a STUN server receives an ACCESS-TOKEN attribute unexpectedly (because it had not previously sent out a THIRD-PARTY-AUTHORIZATION), it will respond with an error code of 420 (Unknown Attribute) as specified in Section 7.3.1 of [RFC5389].

8. STUN client behaviour

• The client looks for the MESSAGE-INTEGRITY attribute in the response. If MESSAGE-INTEGRITY is absent or the value computed for message integrity using mac_key does not match the contents of the MESSAGE-INTEGRITY attribute then the response MUST be discarded.
• If the access token expires then the client MUST obtain a new token from the authorization server and use it for new STUN requests.

9. TURN client and server behaviour

Changes specific to TURN are listed below:

     lifetime + Delta - abs(RDnew - TS)            

• The access token can be reused for multiple Allocate requests to the same TURN server. The TURN client MUST include the ACCESS-TOKEN attribute only in Allocate and Refresh requests. Since the access token is valid for a specific period of time, the TURN server can cache it so that it can check if the access token in a new allocation request matches one of the cached tokens and avoids the need to decrypt the token.
• 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. It is RECOMMENDED that the TURN server calculate the maximum allowed lifetime value using the formula:
• 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 use the new token to refresh existing allocations. This way client has to maintain only one token per TURN server.

10. Operational Considerations

The following operational considerations should be taken into account:

• Each authorization server should maintain the list of STUN servers for which it will grant tokens, and the long-term secret shared with each of those STUN servers.
• If manual configuration (Section 4.1.2) is used to establish symmetric keys, the necessary information which includes long-term secret (K) and authenticated encryption algorithm have to be configured on each authorization server and STUN server for each kid. The client obtains the session key and HMAC algorithm from the authorization server in company with the token.
• When a STUN client sends a request to get access to a particular STUN server (S) the authorization server must ensure that it selects the appropriate kid, access-token depending on the server S.

11. Security Considerations

When OAuth 2.0 is used the interaction between the client and the authorization server requires Transport Layer Security (TLS) with a ciphersuite offering confidentiality protection and the guidance given in [I-D.ietf-uta-tls-bcp] must be followed to avoid attacks on TLS. The session key MUST NOT be transmitted in clear since this would completely destroy the security benefits of the proposed scheme. An attacker trying to replay message with ACCESS-TOKEN attribute can be mitigated by frequent changes of nonce value as discussed in section 10.2 of [RFC5389]. The client may know some (but not all) of the token fields encrypted with a unknown secret key and the token can be subjected to known-plaintext attack, but AES is secure against this attack.

An attacker may remove the THIRD-PARTY-AUTHORIZATION STUN attribute from the error message forcing the client to pick first party authentication, this attack may be mitigated by opting for Transport Layer Security (TLS) [RFC5246] or Datagram Transport Layer Security (DTLS) [RFC6347] as a transport protocol for Session Traversal Utilities for NAT (STUN), as defined in [RFC5389]and [RFC7350].

Threat mitigation discussed in section 5 of [I-D.ietf-oauth-pop-architecture] and security considerations in [RFC5389] are to be taken into account.

12. IANA Considerations

[Paragraphs below in braces should be removed by the RFC Editor upon publication]

[IANA is requested to add the following attributes to the STUN attribute registry [iana-stun], The THIRD-PARTY-AUTHORIZATION attribute requires that IANA allocate a value in the "STUN attributes Registry" from the comprehension-optional range (0x8000-0xBFFF)]

This document defines the THIRD-PARTY-AUTHORIZATION STUN attribute, described in Section 6. IANA has allocated the comprehension-optional codepoint TBD for this attribute.

[The ACCESS-TOKEN attribute requires that IANA allocate a value in the "STUN attributes Registry" from the comprehension-required range (0x0000-0x3FFF)]

This document defines the ACCESS-TOKEN STUN attribute, described in Section 6. IANA has allocated the comprehension-required codepoint TBD for this attribute.

13. Acknowledgements

Authors would like to thank Dan Wing, Pal Martinsen, Oleg Moskalenko, Charles Eckel, Spencer Dawkins, Hannes Tschofenig, Yaron Sheffer, Tom Taylor, Christer Holmberg, Pete Resnick, Kathleen Moriarty, Richard Barnes, Stephen Farrell, Alissa Cooper and Rich Salz for comments and review. The authors would like to give special thanks to Brandon Williams for his help.

Thanks to Oleg Moskalenko for providing token samples in the Appendix section.

14. References

14.1. Normative References

14.2. Informative References

Appendix A. Sample tickets

Input data (same for all samples below):

   //STUN SERVER NAME
   server_name = "blackdow.carleon.gov";

   //Shared key between AS and RS

   long_term_key = \x48\x47\x6b\x6a\x33\x32\x4b\x4a\x47\x69\x75\x79
                   \x30\x39\x38\x73\x64\x66\x61\x71\x62\x4e\x6a\x4f
                   \x69\x61\x7a\x37\x31\x39\x32\x33

   //MAC key of the session (included in the token)
   mac_key = \x5a\x6b\x73\x6a\x70\x77\x65\x6f\x69\x78\x58\x6d\x76\x6e
             \x36\x37\x35\x33\x34\x6d;

   //length of the MAC key
   mac_key_length  =  20;

   //The timestamp field in the token
   token_timestamp = 92470300704768;

   //The lifetime of the token
   token_lifetime = 3600;

   //nonce for AEAD
   aead_nonce = \x68\x34\x6a\x33\x6b\x32\x6c\x32\x6e\x34\x62\x35;

   Samples:

     1) token encryption algorithm = AEAD_AES_256_GCM

     Encrypted token (64 bytes = 2 + 12 +34 + 16) =

    \x00\x0c\x68\x34\x6a\x33\x6b\x32\x6c\x32\x6e\x34\x62
    \x35\x61\x7e\xf1\x34\xa3\xd5\xe4\x4e\x9a\x19\xcc\x7d
    \xc1\x04\xb0\xc0\x3d\x03\xb2\xa5\x51\xd8\xfd\xf5\xcd
    \x3b\x6d\xca\x6f\x10\xcf\xb7\x7e\x5b\x2d\xde\xc8\x4d
    \x29\x3a\x5c\x50\x49\x93\x59\xf0\xc2\xe2\x6f\x76

  2) token encryption algorithm = AEAD_AES_128_GCM

     Encrypted token (64 bytes = 2 + 12 +34 + 16) =

   \x00\x0c\x68\x34\x6a\x33\x6b\x32\x6c\x32\x6e\x34\x62
   \x35\x7f\xb9\xe9\x9f\x08\x27\xbe\x3d\xf1\xe1\xbd\x65
   \x14\x93\xd3\x03\x1d\x36\xdf\x57\x07\x97\x84\xae\xe5
   \xea\xcb\x65\xfa\xd4\xf2\x7f\xab\x1a\x3f\x97\x97\x4b
   \x69\xf8\x51\xb2\x4b\xf5\xaf\x09\xed\xa3\x57\xe0


Note: 
[1] 
After EVP_EncryptFinal_ex encrypts the final data 
EVP_CIPHER_CTX_ctrl must be called to append 
the authentication tag to the ciphertext.
//EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag);
[2] 
EVP_CIPHER_CTX_ctrl must be invoked to set the 
authentication tag before calling EVP_DecryptFinal.
//EVP_CIPHER_CTX_ctrl (&ctx, EVP_CTRL_GCM_SET_TAG, taglen, tag);
    

+-------------------+                         +--------+  +---------+  
| .........  STUN   |                         |  STUN  |  |  WebRTC |
| .WebRTC .  Client |                         |        |  |         | 
| .Client .         |                         | Server |  |  Server |
| .........         |                         |        |  |         | 
+-------------------+                         +--------+  +---------+
  |       |           STUN request                    |         |
  |       |------------------------------------------>|         |
  |       |                                           |         |
  |       |         STUN error response               |         |
  |       |         (401 Unauthorized)                |         |
  |       |<------------------------------------------|         |
  |       |         THIRD-PARTY-AUTHORIZATION         |         |  
  |       |                                           |         |                                      
  |       |                                           |         | 
  |       |      HTTP Request for token               |         |
  |------------------------------------------------------------>|
  |       |      HTTP Response with token parameters  |         |
  |<------------------------------------------------------------|
  |OAuth 2.0                                          |         |
   Attributes                                         |         |
  |------>|                                           |         |
  |       |    STUN request with ACCESS-TOKEN         |         |
  |       |------------------------------------------>|         |
  |       |                                           |         |
  |       |         STUN success response             |         |
  |       |<------------------------------------------|         |
  |       |             STUN Messages                 |         |
  |       |      ////// integrity protected //////    |         |
  |       |      ////// integrity protected //////    |         |
  |       |      ////// integrity protected //////    |         |
       

     HTTP/1.1 
     Host: server.example.com
     Content-Type: application/x-www-form-urlencoded
     aud=stun1@example.com
     timestamp=1361471629
     grant_type=implicit
     token_type=pop
     alg=HMAC-SHA-256-128  
              

     HTTP/1.1 200 OK
     Content-Type: application/json
     Cache-Control: no-store

     {
       "access_token":
"U2FsdGVkX18qJK/kkWmRcnfHglrVTJSpS6yU32kmHmOrfGyI3m1gQj1jRPsr0uBb
HctuycAgsfRX7nJW2BdukGyKMXSiNGNnBzigkAofP6+Z3vkJ1Q5pWbfSRroOkWBn",
       "token_type":"pop",
       "expires_in":1800,
       "kid":"22BIjxU93h/IgwEb",
       "key":"v51N62OM65kyMvfTI08O"
       "alg":HMAC-SHA-256-128
     }