OAuth Request Body Hash 1.0 Draft 3

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.

Table of Contents

1.  Notation and Conventions
2.  Related Work
3.  Request Signing and Verification
    3.1.  Consumer/Service Provider Interoperability
    3.2.  When To Include a Body Hash
    3.3.  Hash Algorithm
    3.4.  Calculating the Hash
    3.5.  Transmitting the Hash
    3.6.  Hash Verification
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.  Request Signing and Verification

3.1.  Consumer/Service Provider Interoperability

Signing of non-form-encoded request bodies is not part of the OAuth Core specification. Service providers MAY require signing of non-form-encoded request bodies in the manner described in this specification.

Consumers SHOULD always sign their request bodies according to this specification. A Service Provider that only supports the OAuth Core specification will be able to verify the signature on the request, but will not have the security benefits of the signed request body. A Service Provider that also supports the oauth_body_hash parameter will be able to verify the integrity of the request body.

3.2.  When To Include a Body Hash

Not all requests can have a request body. For example, HTTP GET and HEAD requests do not use request bodies. If a request cannot have a body, Consumers SHOULD NOT send a body hash.

If a request uses the application/x-www-form-urlencoded content-type, body integrity checks are provided by the OAuth Core specification. Consumers SHOULD NOT send a body hash on requests that use the application/x-www-form-urlencoded content-type.

A body hash SHOULD be sent on all other requests.

3.3.  Hash Algorithm

If the OAuth signature method is HMAC-SHA1 or RSA-SHA1, SHA1 [RFC3174] (Eastlake, 3rd, D. and P. Jones, “US Secure Hash Algorithm 1 (SHA1),” .) MUST be used as the body hash algorithm.

If the OAuth signature method is PLAINTEXT, use of this specification provides no security benefit and is NOT RECOMMENDED.

Updates to OAuth that specify new signature methods SHOULD also specify the hash algorithm used to generate the body hash.

3.4.  Calculating the Hash

The body hash value is obtained by executing the selected hash algorithm over the HTTP Entity Body defined in section 7.2 of RFC 2616 [RFC2616] (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” .).

3.5.  Transmitting the Hash

The body hash value needs to be transmitted to the Service Provider for verification. For transport the body hash value MUST be base64-encoded [RFC2045] (Freed, N. and N. Borenstein, “Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies,” .) and sent to the service provider as the oauth_body_hash OAuth Protocol Parameter. Protocol Parameters are signed as per section 9 "Signing Request" of the OAuth Core specification, and transmitted to the Service Provider as per section 5 "Parameters" of the OAuth Core specification

3.6.  Hash Verification

Service Providers verify the integrity of request bodies by verifying the OAuth signature as described in the OAuth Core specification and also verifying the value of the oauth_body_hash OAuth protocol parameter.

To verify the oauth_body_hash parameter the Service Provider first calculates the body hash as described above. The Service Provider then compares the calculated parameter with the value sent by the Consumer. If the OAuth signature verifies, and the body hash sent by the Consumer and the body hash calculated by the Service Provider match, body integrity is intact.

Service Providers SHOULD base64 decode the oauth_body_hash parameter and compare the raw octets of the hash values rather than the encoded versions. This reduces the risk of small differences in URL encoding or base64 encoding causing spurious integrity check failures.

4.  Example

Sample HTTP request:

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

  Hello World!

Signed request with body hash:

  PUT /resource
  Host: www.example.com
  Authorization: OAuth realm="http%3A%2F%2Fwww.example.com", oauth_body_hash="Lve95gjOVATpfV8EL5X4nxwjKHE%3D", oauth_consumer_key="consumer", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1236874155", oauth_nonce="10288510250934", oauth_version="1.0", oauth_signature="08bUFF%2Fjmp59mWB7cSgCYBUpJ0U%3D"
  Content-Type: application/octet-stream
  Content-Length: 12

  Hello World!

Corresponding Signature Base String:

  PUT&http%3A%2F%2Fwww.example.com%2Fresource&oauth_body_hash%3DLve95gjOVATpfV8EL5X4nxwjKHE%253D%26oauth_consumer_key%3Dconsumer%26oauth_nonce%3D10369470270925%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1236874236%26oauth_version%3D1.0

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