Implementers' Draft B. Eaton Google, Inc March 12, 2009 OAuth Request Body Hash 1.0 Draft 3 Eaton [Page 1] OAuth Request Body Hash 1.0 Draft 3 March 2009 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 . . . . . . . . . . . . . . . . . . . 3 2. Related Work . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Request Signing and Verification . . . . . . . . . . . . . . . 5 3.1. Consumer/Service Provider Interoperability . . . . . . . . 5 3.2. When To Include a Body Hash . . . . . . . . . . . . . . . 5 3.3. Hash Algorithm . . . . . . . . . . . . . . . . . . . . . . 5 3.4. Calculating the Hash . . . . . . . . . . . . . . . . . . . 5 3.5. Transmitting the Hash . . . . . . . . . . . . . . . . . . 6 3.6. Hash Verification . . . . . . . . . . . . . . . . . . . . 6 4. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 5. Security Considerations . . . . . . . . . . . . . . . . . . . 8 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 10 Eaton [Page 2] OAuth Request Body Hash 1.0 Draft 3 March 2009 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]. Domain name examples use [RFC2606]. Unless otherwise noted, this specification is written as a direct continuation of [OAuth Core 1.0], inheriting the definitions and guidelines set by it. Eaton [Page 3] OAuth Request Body Hash 1.0 Draft 3 March 2009 2. Related Work The OAuth Core specification [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] 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] 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. Eaton [Page 4] OAuth Request Body Hash 1.0 Draft 3 March 2009 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] 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]. Eaton [Page 5] OAuth Request Body Hash 1.0 Draft 3 March 2009 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] 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. Eaton [Page 6] OAuth Request Body Hash 1.0 Draft 3 March 2009 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 (with some line breaks added for readability): 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 (with some line breaks added for readability): PUT&http%3A%2F%2Fwww.example.com%2Fresource&oauth_body_hash%3D Lve95gjOVATpfV8EL5X4nxwjKHE%253D%26oauth_consumer_key%3Dconsum er%26oauth_nonce%3D10369470270925%26oauth_signature_method%3DH MAC-SHA1%26oauth_timestamp%3D1236874236%26oauth_version%3D1.0 Eaton [Page 7] OAuth Request Body Hash 1.0 Draft 3 March 2009 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. Eaton [Page 8] OAuth Request Body Hash 1.0 Draft 3 March 2009 6. References [OAuth Body Signing] "Again : signing the body of HTTP POST and HTTP PUT requests", . [OAuth Core 1.0] OAuth Core Workgroup, "OAuth Core 1.0". [OpenSocial Request Signing] OpenSocial Foundation, "OpenSocial Request Signing". [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies", RFC 2045. [RFC2119] Bradner, B., "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119. [RFC2606] Eastlake, D. and A. Panitz, "Reserved Top Level DNS Names", RFC 2606. [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616. [RFC3174] Eastlake, 3rd, D. and P. Jones, "US Secure Hash Algorithm 1 (SHA1)", RFC 3174. Eaton [Page 9] OAuth Request Body Hash 1.0 Draft 3 March 2009 Author's Address Brian Eaton Google, Inc Email: beaton@google.com Eaton [Page 10]