OAuth Request Body Hash 1.0 Draft 1

Abstract

The OAuth Core signature workflow guarantees the integrity of the HTTP request body only for application/x-www-form-urlencoded content types. This specification extends the OAuth signature to provide an integrity check of the HTTP request body for other content types. Alternate proposals for providing integrity checks on the request body require signing oracles that are unacceptable in some OAuth deployments.

Table of Contents

1.  Notation and Conventions
2.  Related Work
3.  Body Hash
4.  Example
5.  Security Considerations
6.  References
§  Author's Address

1.  Notation and Conventions

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] (Bradner, B., “Key words for use in RFCs to Indicate Requirement Levels,” .). Domain name examples use [RFC2606] (Eastlake, D. and A. Panitz, “Reserved Top Level DNS Names,” .).

Unless otherwise noted, this specification is written as a direct continuation of [OAuth Core 1.0] (OAuth Core Workgroup, “OAuth Core 1.0,” .), inheriting the definitions and guidelines set by it.

2.  Related Work

The OAuth Core specification [OAuth Core 1.0] (OAuth Core Workgroup, “OAuth Core 1.0,” .) provides integrity checking only for application/x-www-form-urlencoded request bodies. Other types of request bodies are left unsigned. An eavesdropper or man-in-the-middle who obtains a signed request URL may be able to replay that URL with a different HTTP request body. This security risk is unacceptable for some OAuth deployments.

Existing practice in the OAuth community [OAuth Body Signing] (, “Again : signing the body of HTTP POST and HTTP PUT requests,” .) attempts to address this security concern by adding an HMAC of the request body into the signature workflow. This approach does guarantee the integrity of the request body, but can create additional security problems for some OAuth Consumers because it requires signing a raw, uninterpreted byte stream. OpenSocial request signing [OpenSocial Request Signing] (OpenSocial Foundation, “OpenSocial Request Signing,” .) uses OAuth signatures, but cannot use raw body signing because the OpenSocial specification requires that OpenSocial containers control the value of some of the parameters in the OAuth signature base string (such as opensocial_viewer_id), while allowing application authors to control the value of other parameters. OpenSocial containers cannot provide an oracle that signs raw byte streams because doing so would allow application authors to forge requests that include false opensocial parameters.

This specification attempts to address these limitations by providing an integrity check on the request body without requiring that OAuth Consumers create a signing oracle.

3.  Body Hash

To access a Protected Resource, the Consumer sends an HTTP request to the Service Provider's resource endpoint URL. If the request cannot have a body, or if the request body has an application/x-www-form-urlencoded content type, the Consumer MUST NOT include a body hash. If the OAuth signature method is PLAINTEXT, the Consumer MUST NOT include a body hash. Otherwise the Consumer MUST include an oauth_body_hash parameter in the request.

If the OAuth signature method is HMAC-SHA1 or RSA-SHA1, the body hash is the SHA1 hash [RFC3174] (Eastlake, 3rd, D. and P. Jones, “US Secure Hash Algorithm 1 (SHA1),” .) of the bytes of the request body. Updates to OAuth that specify new signature methods SHOULD also specify the hash algorithm used to generate the body hash.

The value of the oauth_body_hash parameter is the base64-encoded [RFC2045] (Freed, N. and N. Borenstein, “Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies,” .) hash of the request body.

4.  Example

An HTTP request like:

  PUT /resource
  Host: www.example.com
  Content-Type: application/octet-stream
  Content-Length: 12

  Hello World!

signed using the HMAC-SHA1 or RSA-SHA1 OAuth signature algorithm would generate a Signature Base String of:

  PUT&http%3A%2F%2Fwww.example.com%2Fresource&oauth_body_hash%3D
  Lve95gjOVATpfV8EL5X4nxwjKHE%253D

5.  Security Considerations

Many factors besides the bytes of the request body can influence the interpretation of the body of the HTTP request. For example, a content-type or content-encoding header can change the way a server handles an HTTP request. This specification does not include an integrity check on the HTTP request headers. OAuth deployments whose security could be impacted by an attacker who replays an HTTP request with modified request headers SHOULD use other mechanisms (such as HTTPS) to protect the confidentiality and integrity of the entire HTTP request.

6. References

Author's Address