Abstract

OAuth Core 1.0 defines a protocol for delegating user access to Consumer applications without sharing the user's private credentials. Some consumer applications use the RSA_SHA1 signature method. To verify RSA_SHA1 signatures, Service Providers need to be in possession of an authentic copy of the consumer application's public key.

Whenever a consumer application changes the private key it uses to sign its OAuth requests, Service Providers need to change the public key they use to verify the requests. This draft specifies a mechanism that allows consumers to signal which public key should be used to verify requests they sign.

Table of Contents

1.  Authors
2.  Notation and Conventions
3.  Definitions
4.  The Key Rotation Extension Parameter
5.  Signature Verification
6.  Best Practices for Choosing Public Key Identifiers
7.  References
§  Author's Address

1. Authors

Dirk Balfanz (dirk@balfanz.net)

Brian Eaton (beaton@google.com)

2. 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, OCW., “OAuth Core 1.0,” .), inheriting the definitions and guidelines set by it.

3. Definitions

Public Key Identifier:

A value, unique to an OAuth Consumer, that identifies one out of a possible number of public keys, whose corresponding private key is used by the Consumer to sign OAuth requests using the RSA_SHA1 signature method, or perhaps other public-key based signature methods defined in future OAuth extensions. The public key identified by the Public Key Identifier can be used to verify OAuth requests.

4. The Key Rotation Extension Parameter

This extension defines one additional OAuth parameter to be used in OAuth requests originating from an OAuth Consumer:

xoauth_public_key:

The Public Key Identifier of the public key to be used to verify an OAuth request signed by the OAuth Consumer.

If a consumer uses the RSA_SHA1 signature method (or another public-key-based signature method to be defined in future OAuth extensions) to sign requests to the Request Token URL at the Service Provider, then it MUST include the xoauth_public_key parameter in those requests (see Section 6.1.1 of [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .)). If the consumer does not use a public-key-based signature method, then it MUST NOT include the xoauth_public_key parameter.

If a consumer uses the RSA_SHA1 signature method (or another public-key-based signature method to be defined in future OAuth extensions) to sign requests to the Access Token URL at the Service Provider, then it MUST include the xoauth_public_key parameter in those requests (see Section 6.3.1 of [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .)). If the consumer does not use a public-key-based signature method, then it MUST NOT include the xoauth_public_key parameter.

If a consumer uses the RSA_SHA1 signature method (or another public-key-based signature method to be defined in future OAuth extensions) to access protected resources at the Service Provider, then it MUST include the xoauth_public_key parameter in those access requests (see Section 7 of [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .)). If the consumer does not use a public-key-based signature method, then it MUST NOT include the xoauth_public_key parameter.

5. Signature Verification

It is up to the OAuth Consumer to define how Service Providers can, given a Public Key Identifier, obtain a copy of the public key to which the identifier refers.

The Service Provider SHALL obtain a copy of the public key identified by the xoauth_public_key parameter included in the OAuth request, and verify the signature according to Section 9.3.2 of [OAuth Core 1.0] (OAuth, OCW., “OAuth Core 1.0,” .) (if the signature method is RSA_SHA1) or other suitable mechanisms (if the signature type is a different yet-to-be-defined public-key signature method).

6. Best Practices for Choosing Public Key Identifiers

It is up to the OAuth Consumer to define how Service Providers can, given a Public Key Identifier, obtain a copy of the public key to which the identifier refers.

The OAuth Consumer SHOULD NOT use Public Key Identifiers that can by themselves (i.e., without additional information) be used to locate the public key. For example, the OAuth Consumer SHOULD NOT use URLs that point to the public key as Public Key Identifiers.

The format of the Public Key Identifier SHOULD be chosen such that service providers can authenticate the public key they obtain. For example, an OAuth Consumer might specify that its public keys are available at https://www.example.com/pubkeys and that the Public Key Identifier sent in OAuth requests can be used as a pub_key_id URI query parameter when accessing the https://www.example.com/pubkeys URL. When obtaining the public key, the Service Provider SHOULD use TLS to authenticate the Consumer.

It is RECOMMENDED that the public key be distributed in form of X.509 certificates, either self-signed or issued by a certification authority.

The rationale behind these recommended best practices is that it should be hard for an attacker to forge OAuth requests by using his own private key and trick the Service Provider into automatically downloading the attacker's public key. Instead, a Service Provider should always get an authentic copy of the real OAuth Consumer's public key.

7. References

Author's Address