!!! Overview
[{$pagename}] is defined (As far as we know) only in [OAuth 2.0 Message Authentication Code (MAC) Tokens draft-ietf-oauth-v2-http-mac-05.txt|https://tools.ietf.org/html/draft-ietf-oauth-v2-http-mac-05|target='_blank'].


[{$pagename}] describes how to use [MAC] Tokens in HTTP requests and responses to access [Protected Resources] via the [OAuth 2.0] protocol ([RFC 6749]).  An [OAuth Client] willing to access a [Protected Resource] needs to demonstrate possession of a [Symmetric Key] by using it with a keyed message digest function to the request.  The keyed  message digest function is computed over a flexible set of parameters from the HTTP message.

The [MAC] Token mechanism requires the establishment of a shared [Symmetric Key] between the [OAuth Client] and the [Resource Server].  The [{$pagename}] specification defines a three party key distribution protocol to dynamically distribute this session key from the [Authorization Server] to the [OAuth Client] and the [Resource Server].

The design goal for this mechanism is to support the requirements outlined in [Appendix A|https://tools.ietf.org/html/draft-ietf-oauth-v2-http-mac-05|target='_blank']. In particular, when a server uses this mechanism, a passive attacker will be unable to use an eavesdropped access token exchanged between the [OAuth Client] and the [Resource Server]. In addition, this mechanism helps secure the access token against leakage when sent over a secure channel to the wrong [Resource Server] if the [OAuth Client] provided information about the [Resource Server] it wants to interact with in the request to the [Authorization Server].

Since a keyed message digest only provides [integrity] protection and [data-origin|non-Repudiation] [authentication] [confidentiality] protection can only be added by the usage of [Transport Layer Security] ([TLS]).  This specification provides a mechanism for channel binding is included to ensure that a [TLS] channel is not terminated prematurely and indeed covers the entire end-to-end communication.


!! [client|OAuth Client] [Key-Exchange]
[Authorization Servers] issue MAC Tokens based on requests from [clients|OAuth Client].  The request MUST include the audience parameter defined in [OAuth 2.0 Audience Information], which indicates the [Resource Server] the [client|OAuth Client] wants to interact with.  This specification assumes use of the [Authorization Code Grant].  If the request is processed successfully by the [Authorization Servers] it __MUST__ return at least the following parameters to the [client|OAuth Client]:
* kid - The name of the key (key id), which is an identifier generated by the [Resource Server].  It is __RECOMMENDED__ that the [Authorization Servers] generates this key id by computing a hash over the [Access Token], for example using [SHA-1], and to encode it in a [base64] format.
* access_token - The OAuth 2.0 [Access Token].
* mac_key - The [Session Key] generated by the [Authorization Servers].  Note that the lifetime of the [Session Key] is equal to the lifetime of the [Access Token].
* mac_algorithm - The MAC algorithm used to calculate the request [MAC].  The value MUST be one of "hmac-sha-1", "hmac-sha-256", or a registered extension algorithm name as described in Section 9.2 which uses the [OAuth Parameters Registry].  The authorization server is assumed to know the set of algorithms supported by the [client|OAuth Client] and the [Resource Server].  It selects an algorithm that meets the security policies and is supported by both nodes.

!! [Resource Server] and [Authorization Server] [Key-Exchange]
The transport of the mac_key from the [Authorization Servers] to the [Resource Server] is accomplished by conveying the encrypting mac_key inside the [Access Token].  At the time of writing only one standardized format for carrying the [Access Token] is defined: the [JSON Web Token] ([JWT]).  Note that the header of the [JSON Web Encryption] ([JWE]) structure, which is a [JWT] with encrypted content, MUST contain a key id (kid) in the header to allow the [Resource Server] to select the appropriate keying material for decryption.  The keying material is a [Symmetric Key] or an [Asymmetric Key] long-term key established between the [Resource Server] and the [Authorization Servers].  The establishment of this long-term key is outside the scope of this specification.

This document defines two new claims to be carried in the JWT:
* mac_key - The session key generated by the [Authorization Servers].
* kid - The name of the key (key id), which is an identifier generated by the [Resource Server].

These two parameters match the content of the mac_key and the kid conveyed to the client.

!! More Information
There might be more information for this subject on one of the following:
[{ReferringPagesPlugin before='*' after='\n' }]