< draft-ietf-oauth-v2-http-mac-03.txt   draft-ietf-oauth-v2-http-mac-04.txt >
Network Working Group Richer OAuth J. Richer
Internet-Draft The MITRE Corporation Internet-Draft The MITRE Corporation
Intended status: Standards Track W. Mills Intended status: Standards Track W. Mills
Expires: August 29, 2013 Yahoo! Inc. Expires: January 16, 2014 Yahoo! Inc.
H. Tschofenig, Ed. H. Tschofenig, Ed.
Nokia Siemens Networks Nokia Siemens Networks
February 25, 2013 P. Hunt
Oracle Corporation
July 15, 2013
OAuth 2.0 Message Authentication Code (MAC) Tokens OAuth 2.0 Message Authentication Code (MAC) Tokens
draft-ietf-oauth-v2-http-mac-03 draft-ietf-oauth-v2-http-mac-04.txt
Abstract Abstract
This specification describes how to use MAC Tokens in HTTP requests This specification describes how to use MAC Tokens in HTTP requests
to access OAuth 2.0 protected resources. An OAuth client willing to to access OAuth 2.0 protected resources. An OAuth client willing to
access a protected resource needs to demonstrate possession of a access a protected resource needs to demonstrate possession of a
crytographic key by using it with a keyed message digest function to crytographic key by using it with a keyed message digest function to
the request. the request.
The document also defines a key distribution protocol for obtaining a The document also defines a key distribution protocol for obtaining a
skipping to change at page 1, line 40 skipping to change at page 1, line 42
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on August 29, 2013. This Internet-Draft will expire on January 16, 2014.
Copyright Notice Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the Copyright (c) 2013 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. Architecture . . . . . . . . . . . . . . . . . . . . . . . . . 5 3. Architecture . . . . . . . . . . . . . . . . . . . . . . . . . 6
4. Key Distribution . . . . . . . . . . . . . . . . . . . . . . . 7 4. Key Distribution . . . . . . . . . . . . . . . . . . . . . . . 8
4.1. Session Key Transport to Client . . . . . . . . . . . . . 7 4.1. Session Key Transport to Client . . . . . . . . . . . . . 8
4.2. Session Key Transport to Resource Server . . . . . . . . . 9 4.2. Session Key Transport to Resource Server . . . . . . . . . 9
5. The Authenticator . . . . . . . . . . . . . . . . . . . . . . 10 5. The Authenticator . . . . . . . . . . . . . . . . . . . . . . 11
5.1. The Authenticator . . . . . . . . . . . . . . . . . . . . 10 5.1. The Authenticator . . . . . . . . . . . . . . . . . . . . 11
5.2. MAC Input String . . . . . . . . . . . . . . . . . . . . . 13 5.2. MAC Input String . . . . . . . . . . . . . . . . . . . . . 14
5.3. Keyed Message Digest Algorithms . . . . . . . . . . . . . 14 5.3. Keyed Message Digest Algorithms . . . . . . . . . . . . . 14
5.3.1. hmac-sha-1 . . . . . . . . . . . . . . . . . . . . . . 14 5.3.1. hmac-sha-1 . . . . . . . . . . . . . . . . . . . . . . 14
5.3.2. hmac-sha-256 . . . . . . . . . . . . . . . . . . . . . 14 5.3.2. hmac-sha-256 . . . . . . . . . . . . . . . . . . . . . 15
6. Verifying the Authenticator . . . . . . . . . . . . . . . . . 15 6. Verifying the Authenticator . . . . . . . . . . . . . . . . . 16
6.1. Timestamp Verification . . . . . . . . . . . . . . . . . . 15 6.1. Timestamp Verification . . . . . . . . . . . . . . . . . . 16
6.2. Error Handling . . . . . . . . . . . . . . . . . . . . . . 16 6.2. Error Handling . . . . . . . . . . . . . . . . . . . . . . 17
7. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 7. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
8. Security Considerations . . . . . . . . . . . . . . . . . . . 17 8. Security Considerations . . . . . . . . . . . . . . . . . . . 19
8.1. Key Distribution . . . . . . . . . . . . . . . . . . . . . 17 8.1. Key Distribution . . . . . . . . . . . . . . . . . . . . . 19
8.2. Offering Confidentiality Protection for Access to 8.2. Offering Confidentiality Protection for Access to
Protected Resources . . . . . . . . . . . . . . . . . . . 17 Protected Resources . . . . . . . . . . . . . . . . . . . 19
8.3. Authentication of Resource Servers . . . . . . . . . . . . 18 8.3. Authentication of Resource Servers . . . . . . . . . . . . 19
8.4. Plaintext Storage of Credentials . . . . . . . . . . . . . 18 8.4. Plaintext Storage of Credentials . . . . . . . . . . . . . 20
8.5. Entropy of Session Keys . . . . . . . . . . . . . . . . . 18 8.5. Entropy of Session Keys . . . . . . . . . . . . . . . . . 20
8.6. Denial of Service / Resource Exhaustion Attacks . . . . . 19 8.6. Denial of Service / Resource Exhaustion Attacks . . . . . 21
8.7. Timing Attacks . . . . . . . . . . . . . . . . . . . . . . 19 8.7. Timing Attacks . . . . . . . . . . . . . . . . . . . . . . 21
8.8. CSRF Attacks . . . . . . . . . . . . . . . . . . . . . . . 19 8.8. CSRF Attacks . . . . . . . . . . . . . . . . . . . . . . . 21
8.9. Protecting HTTP Header Fields . . . . . . . . . . . . . . 20 8.9. Protecting HTTP Header Fields . . . . . . . . . . . . . . 22
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23
9.1. JSON Web Token Claims . . . . . . . . . . . . . . . . . . 20 9.1. JSON Web Token Claims . . . . . . . . . . . . . . . . . . 23
9.2. MAC Token Algorithm Registry . . . . . . . . . . . . . . . 20 9.2. MAC Token Algorithm Registry . . . . . . . . . . . . . . . 23
9.2.1. Registration Template . . . . . . . . . . . . . . . . 21 9.2.1. Registration Template . . . . . . . . . . . . . . . . 24
9.2.2. Initial Registry Contents . . . . . . . . . . . . . . 21 9.2.2. Initial Registry Contents . . . . . . . . . . . . . . 24
9.3. OAuth Access Token Type Registration . . . . . . . . . . . 22 9.3. OAuth Access Token Type Registration . . . . . . . . . . . 24
9.3.1. The "mac" OAuth Access Token Type . . . . . . . . . . 22 9.3.1. The "mac" OAuth Access Token Type . . . . . . . . . . 25
9.4. OAuth Parameters Registration . . . . . . . . . . . . . . 22 9.4. OAuth Parameters Registration . . . . . . . . . . . . . . 25
9.4.1. The "mac_key" OAuth Parameter . . . . . . . . . . . . 22 9.4.1. The "mac_key" OAuth Parameter . . . . . . . . . . . . 25
9.4.2. The "mac_algorithm" OAuth Parameter . . . . . . . . . 22 9.4.2. The "mac_algorithm" OAuth Parameter . . . . . . . . . 25
9.4.3. The "kid" OAuth Parameter . . . . . . . . . . . . . . 23 9.4.3. The "kid" OAuth Parameter . . . . . . . . . . . . . . 26
10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 23 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 27
11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 23 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28
11.1. Normative References . . . . . . . . . . . . . . . . . . . 23 11.1. Normative References . . . . . . . . . . . . . . . . . . . 28
11.2. Informative References . . . . . . . . . . . . . . . . . . 25 11.2. Informative References . . . . . . . . . . . . . . . . . . 29
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 25 Appendix A. Background Information . . . . . . . . . . . . . . . 31
A.1. Security and Privacy Threats . . . . . . . . . . . . . . . 31
A.2. Threat Mitigation . . . . . . . . . . . . . . . . . . . . 32
A.2.1. Confidentiality Protection . . . . . . . . . . . . . . 32
A.2.2. Sender Constraint . . . . . . . . . . . . . . . . . . 33
A.2.3. Key Confirmation . . . . . . . . . . . . . . . . . . . 34
A.2.4. Summary . . . . . . . . . . . . . . . . . . . . . . . 35
A.3. Requirements . . . . . . . . . . . . . . . . . . . . . . . 36
A.4. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . 40
A.4.1. Access to an 'Unprotected' Resource . . . . . . . . . 40
A.4.2. Offering Application Layer End-to-End Security . . . . 40
A.4.3. Preventing Access Token Re-Use by the Resource
Server . . . . . . . . . . . . . . . . . . . . . . . . 41
A.4.4. TLS Channel Binding Support . . . . . . . . . . . . . 41
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 42
1. Introduction 1. Introduction
This specification describes how to use MAC Tokens in HTTP requests This specification describes how to use MAC Tokens in HTTP requests
and responses to access protected resources via the OAuth 2.0 and responses to access protected resources via the OAuth 2.0
protocol [RFC6749]. An OAuth client willing to access a protected protocol [RFC6749]. An OAuth client willing to access a protected
resource needs to demonstrate possession of a symmetric key by using resource needs to demonstrate possession of a symmetric key by using
it with a keyed message digest function to the request. The keyed it with a keyed message digest function to the request. The keyed
message digest function is computed over a flexible set of parameters message digest function is computed over a flexible set of parameters
from the HTTP message. from the HTTP message.
The MAC Token mechanism requires the establishment of a shared The MAC Token mechanism requires the establishment of a shared
symmetric key between the client and the resource server. This symmetric key between the client and the resource server. This
specification defines a three party key distribution protocol to specification defines a three party key distribution protocol to
dynamically distribute this session key from the authorization server dynamically distribute this session key from the authorization server
to the client and the resource server. to the client and the resource server.
The design goal for this mechanism is to support the requirements The design goal for this mechanism is to support the requirements
outlined in [I-D.tschofenig-oauth-security]. In particular, when a outlined in Appendix A. In particular, when a server uses this
server uses this mechanism, a passive attacker will be unable to use mechanism, a passive attacker will be unable to use an eavesdropped
an eavesdropped access token exchanged between the client and the access token exchanged between the client and the resource server.
resource server. In addition, this mechanism helps secure the access In addition, this mechanism helps secure the access token against
token against leakage when sent over a secure channel to the wrong leakage when sent over a secure channel to the wrong resource server
resource server if the client provided information about the resource if the client provided information about the resource server it wants
server it wants to interact with in the request to the authorization to interact with in the request to the authorization server.
server.
Since a keyed message digest only provides integrity protection and Since a keyed message digest only provides integrity protection and
data-origin authentication confidentiality protection can only be data-origin authentication confidentiality protection can only be
added by the usage of Transport Layer Security (TLS). This added by the usage of Transport Layer Security (TLS). This
specification provides a mechanism for channel binding is included to specification provides a mechanism for channel binding is included to
ensure that a TLS channel is not terminated prematurely and indeed ensure that a TLS channel is not terminated prematurely and indeed
covers the entire end-to-end communication. covers the entire end-to-end communication.
2. Terminology 2. Terminology
skipping to change at page 22, line 39 skipping to change at page 25, line 35
[[ this document ]] [[ this document ]]
9.4. OAuth Parameters Registration 9.4. OAuth Parameters Registration
This specification registers the following parameters in the OAuth This specification registers the following parameters in the OAuth
Parameters Registry established by [RFC6749]. Parameters Registry established by [RFC6749].
9.4.1. The "mac_key" OAuth Parameter 9.4.1. The "mac_key" OAuth Parameter
Parameter name: mac_key Parameter name: mac_key
Parameter usage location: authorization response, token response Parameter usage location: authorization response, token response
Change controller: IETF Change controller: IETF
Specification document(s): [[ this document ]] Specification document(s): [[ this document ]]
Related information: None Related information: None
9.4.2. The "mac_algorithm" OAuth Parameter 9.4.2. The "mac_algorithm" OAuth Parameter
Parameter name: mac_algorithm Parameter name: mac_algorithm
Parameter usage location: authorization response, token response Parameter usage location: authorization response, token response
Change controller: IETF Change controller: IETF
Specification document(s): [[ this document ]] Specification document(s): [[ this document ]]
Related information: None Related information: None
9.4.3. The "kid" OAuth Parameter 9.4.3. The "kid" OAuth Parameter
Parameter name: kid Parameter name: kid
Parameter usage location: authorization response, token response Parameter usage location: authorization response, token response
Change controller: IETF Change controller: IETF
Specification document(s): [[ this document ]] Specification document(s): [[ this document ]]
Related information: None Related information: None
10. Acknowledgments 10. Acknowledgments
This document is based on OAuth 1.0 and we would like to thank Eran This document is based on OAuth 1.0 and we would like to thank Eran
Hammer-Lahav for his work on incorporating the ideas into OAuth 2.0. Hammer-Lahav for his work on incorporating the ideas into OAuth 2.0.
As part of this initial work the following persons provided feedback: As part of this initial work the following persons provided feedback:
Ben Adida, Adam Barth, Phil Hunt, Rasmus Lerdorf, James Manger, Ben Adida, Adam Barth, Rasmus Lerdorf, James Manger, William Mills,
William Mills, Scott Renfro, Justin Richer, Toby White, Peter Scott Renfro, Justin Richer, Toby White, Peter Wolanin, and Skylar
Wolanin, and Skylar Woodward Woodward
Further work in this document was done as part of OAuth working group Further work in this document was done as part of OAuth working group
conference calls late 2012/early 2013 and in design team conference conference calls late 2012/early 2013 and in design team conference
calls February 2013. The following persons (in addition to the OAuth calls February 2013. The following persons (in addition to the OAuth
WG chairs, Hannes Tschofenig, and Derek Atkins) provided their input WG chairs, Hannes Tschofenig, and Derek Atkins) provided their input
during these calls: Bill Mills, Justin Richer, Phil Hunt, Prateek during these calls: Bill Mills, Justin Richer, Phil Hunt, Prateek
Mishra, Mike Jones, George Fletcher, John Bradley, Tony Nadalin, Mishra, Mike Jones, George Fletcher, Leif Johansson, Lucy Lynch, John
Thomas Hardjono, Brian Campbell Bradley, Tony Nadalin, Klaas Wierenga, Thomas Hardjono, Brian
Campbell
In the appendix of this document we re-use content from [RFC4962] and
the authors would like thank Russ Housely and Bernard Aboba for their
work on RFC 4962.
11. References 11. References
11.1. Normative References 11.1. Normative References
[I-D.ietf-httpbis-p1-messaging] [I-D.ietf-httpbis-p1-messaging]
Fielding, R. and J. Reschke, "Hypertext Transfer Protocol Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
(HTTP/1.1): Message Syntax and Routing", (HTTP/1.1): Message Syntax and Routing",
draft-ietf-httpbis-p1-messaging-22 (work in progress), draft-ietf-httpbis-p1-messaging-23 (work in progress),
February 2013. July 2013.
[I-D.ietf-jose-json-web-encryption] [I-D.ietf-jose-json-web-encryption]
Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web
Encryption (JWE)", draft-ietf-jose-json-web-encryption-08 Encryption (JWE)", draft-ietf-jose-json-web-encryption-12
(work in progress), December 2012. (work in progress), July 2013.
[I-D.ietf-oauth-json-web-token] [I-D.ietf-oauth-json-web-token]
Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", draft-ietf-oauth-json-web-token-06 (work in (JWT)", draft-ietf-oauth-json-web-token-10 (work in
progress), December 2012. progress), July 2013.
[I-D.richer-oauth-introspection] [I-D.richer-oauth-introspection]
Richer, J., "OAuth Token Introspection", Richer, J., "OAuth Token Introspection",
draft-richer-oauth-introspection-03 (work in progress), draft-richer-oauth-introspection-04 (work in progress),
February 2013. May 2013.
[I-D.tschofenig-oauth-audience] [I-D.tschofenig-oauth-audience]
Tschofenig, H., "OAuth 2.0: Audience Information", Tschofenig, H., "OAuth 2.0: Audience Information",
draft-tschofenig-oauth-audience-00 (work in progress), draft-tschofenig-oauth-audience-00 (work in progress),
February 2013. February 2013.
[NIST-FIPS-180-3]
National Institute of Standards and Technology, "Secure
Hash Standard (SHS). FIPS PUB 180-3, October 2008".
[RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part One: Format of Internet Message Extensions (MIME) Part One: Format of Internet Message
Bodies", RFC 2045, November 1996. Bodies", RFC 2045, November 1996.
[RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed-
Hashing for Message Authentication", RFC 2104, Hashing for Message Authentication", RFC 2104,
February 1997. February 1997.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
skipping to change at page 24, line 45 skipping to change at page 29, line 10
[RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S.,
Leach, P., Luotonen, A., and L. Stewart, "HTTP Leach, P., Luotonen, A., and L. Stewart, "HTTP
Authentication: Basic and Digest Access Authentication", Authentication: Basic and Digest Access Authentication",
RFC 2617, June 1999. RFC 2617, June 1999.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005. RFC 3986, January 2005.
[RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness
Requirements for Security", BCP 106, RFC 4086, June 2005.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226, IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008. May 2008.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246, August 2008. (TLS) Protocol Version 1.2", RFC 5246, August 2008.
[RFC5929] Altman, J., Williams, N., and L. Zhu, "Channel Bindings
for TLS", RFC 5929, July 2010.
[RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265,
April 2011. April 2011.
[RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework",
RFC 6749, October 2012. RFC 6749, October 2012.
[W3C.REC-html401-19991224] [W3C.REC-html401-19991224]
Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01 Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01
Specification", World Wide Web Consortium Specification", World Wide Web Consortium
Recommendation REC-html401-19991224, December 1999, Recommendation REC-html401-19991224, December 1999,
<http://www.w3.org/TR/1999/REC-html401-19991224>. <http://www.w3.org/TR/1999/REC-html401-19991224>.
11.2. Informative References 11.2. Informative References
[I-D.tschofenig-oauth-security] [I-D.hardjono-oauth-kerberos]
Tschofenig, H. and P. Hunt, "OAuth 2.0 Security: Going Hardjono, T., "OAuth 2.0 support for the Kerberos V5
Beyond Bearer Tokens", draft-tschofenig-oauth-security-01 Authentication Protocol", draft-hardjono-oauth-kerberos-01
(work in progress), December 2012. (work in progress), December 2010.
[I-D.tschofenig-oauth-hotk]
Bradley, J., Hunt, P., Nadalin, A., and H. Tschofenig,
"The OAuth 2.0 Authorization Framework: Holder-of-the-Key
Token Usage", draft-tschofenig-oauth-hotk-02 (work in
progress), February 2013.
[NIST-FIPS-180-3]
National Institute of Standards and Technology, "Secure
Hash Standard (SHS). FIPS PUB 180-3, October 2008".
[NIST800-63]
Burr, W., Dodson, D., Perlner, R., Polk, T., Gupta, S.,
and E. Nabbus, "NIST Special Publication 800-63-1,
INFORMATION SECURITY", December 2008.
[RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness
Requirements for Security", BCP 106, RFC 4086, June 2005.
[RFC4120] Neuman, C., Yu, T., Hartman, S., and K. Raeburn, "The
Kerberos Network Authentication Service (V5)", RFC 4120,
July 2005.
[RFC4279] Eronen, P. and H. Tschofenig, "Pre-Shared Key Ciphersuites
for Transport Layer Security (TLS)", RFC 4279,
December 2005.
[RFC4962] Housley, R. and B. Aboba, "Guidance for Authentication,
Authorization, and Accounting (AAA) Key Management",
BCP 132, RFC 4962, July 2007.
[RFC5056] Williams, N., "On the Use of Channel Bindings to Secure
Channels", RFC 5056, November 2007.
[RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849,
April 2010.
[RFC5929] Altman, J., Williams, N., and L. Zhu, "Channel Bindings
for TLS", RFC 5929, July 2010.
[RFC6125] Saint-Andre, P. and J. Hodges, "Representation and
Verification of Domain-Based Application Service Identity
within Internet Public Key Infrastructure Using X.509
(PKIX) Certificates in the Context of Transport Layer
Security (TLS)", RFC 6125, March 2011.
[RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
Framework: Bearer Token Usage", RFC 6750, October 2012.
Appendix A. Background Information
With the desire to define a security mechanism in addition to bearer
tokens a design team was formed to collect threats, explore different
threat mitigation techniques, describe use cases, and to derive
requirements for the MAC token based security mechanism defined in
the body of this document. This appendix provides information about
this thought process that should help to motivate design decision.
A.1. Security and Privacy Threats
The following list presents several common threats against protocols
utilizing some form of tokens. This list of threats is based on NIST
Special Publication 800-63 [NIST800-63]. We exclude a discussion of
threats related to any form of identity proofing and authentication
of the Resource Owner to the Authorization Server since these
procedures are not part of the OAuth 2.0 protocol specificaiton
itself.
Token manufacture/modification:
An attacker may generate a bogus tokens or modify the token
content (such as authentication or attribute statements) of an
existing token, causing Resource Server to grant inappropriate
access to the Client. For example, an attacker may modify the
token to extend the validity period. A Client may modify the
token to have access to information that they should not be able
to view.
Token disclosure: Tokens may contain personal data, such as real
name, age or birthday, payment information, etc.
Token redirect:
An attacker uses the token generated for consumption by the
Resource Server to obtain access to another Resource Server.
Token reuse:
An attacker attempts to use a token that has already been used
once with a Resource Server. The attacker may be an eavesdropper
who observes the communication exchange or, worse, one of the
communication end points. A Client may, for example, leak access
tokens because it cannot keep secrets confidential. A Client may
also re-use access tokens for some other Resource Servers.
Finally, a Resource Server may use a token it had obtained from a
Client and use it with another Resource Server that the Client
interacts with. A Resource Server, offering relatively
unimportant application services, may attempt to use an access
token obtained from a Client to access a high-value service, such
as a payment service, on behalf of the Client using the same
access token.
We excluded one threat from the list, namely 'token repudiation'.
Token repudiation refers to a property whereby a Resource Server is
given an assurance that the Authorization Server cannot deny to have
created a token for the Client. We believe that such a property is
interesting but most deployments prefer to deal with the violation of
this security property through business actions rather than by using
cryptography.
A.2. Threat Mitigation
A large range of threats can be mitigated by protecting the content
of the token, using a digital signature or a keyed message digest.
Alternatively, the content of the token could be passed by reference
rather than by value (requiring a separate message exchange to
resolve the reference to the token content). To simplify the
subsequent description we assume that the token itself is digitally
signed by the Authorization Server and therefore cannot be modified.
To deal with token redirect it is important for the Authorization
Server to include the identifier of the intended recipient - the
Resource Server. A Resource Server must not be allowed to accept
access tokens that are not meant for its consumption.
To provide protection against token disclosure two approaches are
possible, namely (a) not to include sensitive information inside the
token or (b) to ensure confidentiality protection. The latter
approach requires at least the communication interaction between the
Client and the Authorization Server as well as the interaction
between the Client and the Resource Server to experience
confidentiality protection. As an example, Transport Layer Security
with a ciphersuite that offers confidentiality protection has to be
applied. Encrypting the token content itself is another alternative.
In our scenario the Authorization Server would, for example, encrypt
the token content with a symmetric key shared with the Resource
Server.
To deal with token reuse more choices are available.
A.2.1. Confidentiality Protection
In this approach confidentiality protection of the exchange is
provided on the communication interfaces between the Client and the
Resource Server, and between the Client and the Authorization Server.
No eavesdropper on the wire is able to observe the token exchange.
Consequently, a replay by a third party is not possible. An
Authorization Server wants to ensure that it only hands out tokens to
Clients it has authenticated first and who are authorized. For this
purpose, authentication of the Client to the Authorization Server
will be a requirement to ensure adequate protection against a range
of attacks. This is, however, true for the description in
Appendix A.2.2 and Appendix A.2.3 as well. Furthermore, the Client
has to make sure it does not distribute the access token to entities
other than the intended the Resource Server. For that purpose the
Client will have to authenticate the Resource Server before
transmitting the access token.
A.2.2. Sender Constraint
Instead of providing confidentiality protection the Authorization
Server could also put the identifier of the Client into the protected
token with the following semantic: 'This token is only valid when
presented by a Client with the following identifer.' When the access
token is then presented to the Resource Server how does it know that
it was provided by the Client? It has to authenticate the Client!
There are many choices for authenticating the Client to the Resource
Server, for example by using client certificates in TLS [RFC5246], or
pre-shared secrets within TLS [RFC4279]. The choice of the preferred
authentication mechanism and credential type may depend on a number
of factors, including
o security properties
o available infrastructure
o library support
o credential cost (financial)
o performance
o integration into the existing IT infrastructure
o operational overhead for configuration and distribution of
credentials
This long list hints to the challenge of selecting at least one
mandatory-to-implement Client authentication mechanism.
A.2.3. Key Confirmation
A variation of the mechanism of sender authentication described in
Appendix A.2.2 is to replace authentication with the proof-of-
possession of a specific (session) key, i.e., key confirmation. In
this model the Resource Server would not authenticate the Client
itself but would rather verify whether the Client knows the session
key associated with a specific access token. Examples of this
approach can be found with the OAuth 1.0 MAC token [RFC5849],
Kerberos [RFC4120] when utilizing the AP_REQ/AP_REP exchange (see
also [I-D.hardjono-oauth-kerberos] for a comparison between Kerberos
and OAuth), the Holder-of-the-Key approach
[I-D.tschofenig-oauth-hotk], and also the MAC token approach defined
in this document.
To illustrate key confirmation the first examples borrow from
Kerberos and use symmetric key cryptography. Assume that the
Authorization Server shares a long-term secret with the Resource
Server, called K(Authorization Server-Resource Server). This secret
would be established between them in an initial registration phase.
When the Client requests an access token the Authorization Server
creates a fresh and unique session key Ks and places it into the
token encrypted with the long term key K(Authorization Server-
Resource Server). Additionally, the Authorization Server attaches Ks
to the response message to the Client (in addition to the access
token itself) over a confidentiality protected channel. When the
Client sends a request to the Resource Server it has to use Ks to
compute a keyed message digest for the request (in whatever form or
whatever layer). The Resource Server, when receiving the message,
retrieves the access token, verifies it and extracts K(Authorization
Server-Resource Server) to obtain Ks. This key Ks is then used to
verify the keyed message digest of the request message.
Note that in this example one could imagine that the mechanism to
protect the token itself is based on a symmetric key based mechanism
to avoid any form of public key infrastructure but this aspect is not
further elaborated in the scenario.
A similar mechanism can also be designed using asymmetric
cryptography. When the Client requests an access token the
Authorization Server creates an ephemeral public / privacy key pair
(PK/SK) and places the public key PK into the protected token. When
the Authorization Server returns the access token to the Client it
also provides the PK/SK key pair over a confidentiality protected
channel. When the Client sends a request to the Resource Server it
has to use the privacy key SK to sign the request. The Resource
Server, when receiving the message, retrieves the access token,
verifies it and extracts the public key PK. It uses this ephemeral
public key to verify the attached signature.
A.2.4. Summary
As a high level message, there are various ways how the threats can
be mitigated and while the details of each solution is somewhat
different they all ultimately accomplish the goal.
The three approaches are:
Confidentiality Protection:
The weak point with this approach, which is briefly described in
Appendix A.2.1, is that the Client has to be careful to whom it
discloses the access token. What can be done with the token
entirely depends on what rights the token entitles the presenter
and what constraints it contains. A token could encode the
identifier of the Client but there are scenarios where the Client
is not authenticated to the Resource Server or where the
identifier of the Client rather represents an application class
rather than a single application instance. As such, it is
possible that certain deployments choose a rather liberal approach
to security and that everyone who is in possession of the access
token is granted access to the data.
Sender Constraint:
The weak point with this approach, which is briefly described in
Appendix A.2.2, is to setup the authentication infrastructure such
that Clients can be authenticated towards Resource Servers.
Additionally, Authorization Server must encode the identifier of
the Client in the token for later verification by the Resource
Server. Depending on the chosen layer for providing Client-side
authentication there may be additional challenges due Web server
load balancing, lack of API access to identity information, etc.
Key Confirmation:
The weak point with this approach, see Appendix A.2.3, is the
increased complexity: a complete key distribution protocol has to
be defined.
In all cases above it has to be ensured that the Client is able to
keep the credentials secret.
A.3. Requirements
In an attempt to address the threats described in Appendix A.1 the
Bearer Token, which corresponds to the description in Appendix A.2.1,
was standardized and the work on a JSON-based token format has been
started [I-D.ietf-oauth-json-web-token]. The required capability to
protected the content of a JSON token using integrity and
confidentiality mechanisms is work in progress at the time of
writing.
Consequently, the purpose of the remaining document is to provide
security that goes beyond the Bearer Token offered security
protection.
RFC 4962 [RFC4962] gives useful guidelines for designers of
authentication and key management protocols. While RFC 4962 was
written with the AAA framework used for network access authentication
in mind the offered suggestions are useful for the design of other
key management systems as well. The following requirements list
applies OAuth 2.0 terminology to the requirements outlined in RFC
4962.
These requirements include
Cryptographic Algorithm Independent:
The key management protocol MUST be cryptographic algorithm
independent.
Strong, fresh session keys:
Session keys MUST be strong and fresh. Each session deserves an
independent session key, i.e., one that is generated specifically
for the intended use. In context of OAuth this means that keying
material is created in such a way that can only be used by the
combination of a Client instance, protected resource, and
authorization scope.
Limit Key Scope:
Following the principle of least privilege, parties MUST NOT have
access to keying material that is not needed to perform their
role. Any protocol that is used to establish session keys MUST
specify the scope for session keys, clearly identifying the
parties to whom the session key is available.
Replay Detection Mechanism:
The key management protocol exchanges MUST be replay protected.
Replay protection allows a protocol message recipient to discard
any message that was recorded during a previous legitimate
dialogue and presented as though it belonged to the current
dialogue.
Authenticate All Parties:
Each party in the key management protocol MUST be authenticated to
the other parties with whom they communicate. Authentication
mechanisms MUST maintain the confidentiality of any secret values
used in the authentication process. Secrets MUST NOT be sent to
another party without confidentiality protection.
Authorization:
Client and Resource Server authorization MUST be performed. These
entities MUST demonstrate possession of the appropriate keying
material, without disclosing it. Authorization is REQUIRED
whenever a Client interacts with an Authorization Server. The
authorization checking prevents an elevation of privilege attack,
and it ensures that an unauthorized authorized is detected.
Keying Material Confidentiality and Integrity:
While preserving algorithm independence, confidentiality and
integrity of all keying material MUST be maintained.
Confirm Cryptographic Algorithm Selection:
The selection of the "best" cryptographic algorithms SHOULD be
securely confirmed. The mechanism SHOULD detect attempted roll-
back attacks.
Uniquely Named Keys:
Key management proposals require a robust key naming scheme,
particularly where key caching is supported. The key name
provides a way to refer to a key in a protocol so that it is clear
to all parties which key is being referenced. Objects that cannot
be named cannot be managed. All keys MUST be uniquely named, and
the key name MUST NOT directly or indirectly disclose the keying
material.
Prevent the Domino Effect:
Compromise of a single Client MUST NOT compromise keying material
held by any other Client within the system, including session keys
and long-term keys. Likewise, compromise of a single Resource
Server MUST NOT compromise keying material held by any other
Resource Server within the system. In the context of a key
hierarchy, this means that the compromise of one node in the key
hierarchy must not disclose the information necessary to
compromise other branches in the key hierarchy. Obviously, the
compromise of the root of the key hierarchy will compromise all of
the keys; however, a compromise in one branch MUST NOT result in
the compromise of other branches. There are many implications of
this requirement; however, two implications deserve highlighting.
First, the scope of the keying material must be defined and
understood by all parties that communicate with a party that holds
that keying material. Second, a party that holds keying material
in a key hierarchy must not share that keying material with
parties that are associated with other branches in the key
hierarchy.
Bind Key to its Context:
Keying material MUST be bound to the appropriate context. The
context includes the following.
* The manner in which the keying material is expected to be used.
* The other parties that are expected to have access to the
keying material.
* The expected lifetime of the keying material. Lifetime of a
child key SHOULD NOT be greater than the lifetime of its parent
in the key hierarchy.
Any party with legitimate access to keying material can determine
its context. In addition, the protocol MUST ensure that all
parties with legitimate access to keying material have the same
context for the keying material. This requires that the parties
are properly identified and authenticated, so that all of the
parties that have access to the keying material can be determined.
The context will include the Client and the Resource Server
identities in more than one form.
Authorization Restriction:
If Client authorization is restricted, then the Client SHOULD be
made aware of the restriction.
Client Identity Confidentiality:
A Client has identity confidentiality when any party other than
the Resource Server and the Authorization Server cannot
sufficiently identify the Client within the anonymity set. In
comparison to anonymity and pseudonymity, identity confidentiality
is concerned with eavesdroppers and intermediaries. A key
management protocol SHOULD provide this property.
Resource Owner Identity Confidentiality:
Resource servers SHOULD be prevented from knowing the real or
pseudonymous identity of the Resource Owner, since the
Authorization Server is the only entity involved in verifying the
Resource Owner's identity.
Collusion:
Resource Servers that collude can be prevented from using
information related to the Resource Owner to track the individual.
That is, two different Resource Servers can be prevented from
determining that the same Resource Owner has authenticated to both
of them. This requires that each Authorization Server obtains
different keying material as well as different access tokens with
content that does not allow identification of the Resource Owner.
AS-to-RS Relationship Anonymity:
This MAC Token security does not provide AAS-to-RS Relationship
Anonymity since the Client has to inform the resource server about
the Resource Server it wants to talk to. The Authorization Server
needs to know how to encrypt the session key the Client and the
Resource Server will be using.
As an additional requirement a solution MUST enable support for
channel bindings. The concept of channel binding, as defined in
[RFC5056], allows applications to establish that the two end-points
of a secure channel at one network layer are the same as at a higher
layer by binding authentication at the higher layer to the channel at
the lower layer.
Furthermore, there are performance concerns specifically with the
usage of asymmetric cryptography. As such, the requirement can be
phrases as 'faster is better'. [QUESTION: How are we trading the
benefits of asymmetric cryptography against the performance impact?]
Finally, there are threats that relate to the experience of the
software developer as well as operational policies. Verifying the
servers identity in TLS is discussed at length in [RFC6125].
A.4. Use Cases
This section lists use cases that provide additional requirements and
constrain the solution space.
A.4.1. Access to an 'Unprotected' Resource
This use case is for a web client that needs to access a resource
where no integrity and confidentiality protection is provided for the
exchange of data using TLS following the OAuth-based request. In
accessing the resource, the request, which includes the access token,
must be protected against replay, and modification.
While it is possible to utilize bearer tokens in this scenario, as
described in [RFC6750], with TLS protection when the request to the
protected resource is made there may be the desire to avoid using TLS
between the client and the resource server at all. In such a case
the bearer token approach is not possible since it relies on TLS for
ensuring integrity and confidentiality protection of the access token
exchange since otherwise replay attacks are possible: First, an
eavesdropper may steal an access token and represent it at a
different resource server. Second, an eavesdropper may steal an
access token and replay it against the same resource server at a
later point in time. In both cases, if the attack is successful, the
adversary gets access to the resource owners data or may perform an
operation selected by the adversary (e.g., sending a message). Note
that the adversary may obtain the access token (if the
recommendations in [RFC6749] and [RFC6750] are not followed) using a
number of ways, including eavesdropping the communication on the
wireless link.
Consequently, the important assumption in this use case is that a
resource server does not have TLS support and the security solution
should work in such a scenario. Furthermore, it may not be necessary
to provide authentication of the resource server towards the client.
A.4.2. Offering Application Layer End-to-End Security
In Web deployments resource servers are often placed behind load
balancers. Note that the load balancers are deployed by the same
organization that operates the resource servers. These load
balancers may terminate Transport Layer Security (TLS) and the
resulting HTTP traffic may be transmitted in clear from the load
balancer to the resource server. With application layer security
independent of the underlying TLS security it is possible to allow
application servers to perform cryptographic verification on an end-
to-end basis.
The key aspect in this use case is therefore to offer end-to-end
security in the presence of load balancers via application layer
security.
A.4.3. Preventing Access Token Re-Use by the Resource Server
Imagine a scenario where a resource server that receives a valid
access token re-uses it with other resource server. The reason for
re-use may be malicious or may well be legimiate. In a legimiate use
case consider a case where the resource server needs to consult third
party resource servers to complete the requested operation. In both
cases it may be assumed that the scope of the access token is
sufficiently large that it allows such a re-use. For example,
imagine a case where a company operates email services as well as
picture sharing services and that company had decided to issue access
tokens with a scope that allows access to both services.
With this use case the desire is to prevent such access token re-use.
This also implies that the legimiate use cases require additional
enhancements for request chaining.
A.4.4. TLS Channel Binding Support
In this use case we consider the scenario where an OAuth 2.0 request
to a protected resource is secured using TLS but the client and the
resource server demand that the underlying TLS exchange is bound to
additional application layer security to prevent cases where the TLS
connection is terminated at a load balancer or a TLS proxy is used
that splits the TLS connection into two separate connections.
In this use case additional information is conveyed to the resource
server to ensure that no entity entity has tampered with the TLS
connection.
Authors' Addresses Authors' Addresses
Justin Richer Justin Richer
The MITRE Corporation The MITRE Corporation
Email: jricher@mitre.org Email: jricher@mitre.org
William Mills William Mills
Yahoo! Inc. Yahoo! Inc.
skipping to change at page 26, line 4 skipping to change at page 42, line 17
Justin Richer Justin Richer
The MITRE Corporation The MITRE Corporation
Email: jricher@mitre.org Email: jricher@mitre.org
William Mills William Mills
Yahoo! Inc. Yahoo! Inc.
Phone: Phone:
Email: wmills@yahoo-inc.com Email: wmills@yahoo-inc.com
Hannes Tschofenig (editor) Hannes Tschofenig (editor)
Nokia Siemens Networks Nokia Siemens Networks
Linnoitustie 6 Linnoitustie 6
Espoo 02600 Espoo 02600
Finland Finland
Phone: +358 (50) 4871445 Phone: +358 (50) 4871445
Email: Hannes.Tschofenig@gmx.net Email: Hannes.Tschofenig@gmx.net
URI: http://www.tschofenig.priv.at URI: http://www.tschofenig.priv.at
Phil Hunt
Oracle Corporation
Phone:
Email: phil.hunt@yahoo.com
 End of changes. 33 change blocks. 
78 lines changed or deleted 656 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/