[OAUTH-WG] OAuth Signature Draft Pre 00

Nat Sakimura Tue, 24 Aug 2010 06:50:05 -0700

Hi.

It has been a few weeks since then I volunteered to do this work.
I have written up to this pre 00 draft then have been doing some reality
checks on some script languages etc.


No. This pre-00 draft is far from being feature complete.
I still need to copy and paste the Magic Signatures text etc.
Also, I should add how this spec is being used in some of the major flows.

However, since I will not be able to work on it this week, I thought it
would be worthwhile to share this early draft so that you have some clarity
into the progress.

Apparently, Yaron has been working on it as well. We will compare the notes
and try to merge, I hope.

So, here it is!

#For those of you who have seen the private draft, it has not been changed
since July 31.

Best,

=nat

Title: OAuth Signatures 1.0 draft 00

TOC

Open Authentication Working Group	D. Balfanz
Internet-Draft	Google
Intended status: Informational	J. Bradley
Expires: February 1, 2011	Wingaa
	N. Sakimura (Editor)
	Nomura Research Institute
	L. Shephard
	P. Tarjan
	Facebook
	July 31, 2010

OAuth Signatures 1.0 draft 00
draft-sakimura-oauth-signatures-00

Abstract

This specification defines signing mechanism to be used in OAuth 2.0. The OAuth requests and responses together with signature related parameters are encoded into JSON envelope and then signing algorithm is applied to obtain Base64url encoded signature using signatory's key. The resulting signature is concatenated with the Base64url encoded JSON envelope to which the signature is applied by a period "." so that it could be included in URLs.

Requirements Language

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 RFC 2119 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [RFC2119].

Status of this Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress.”

This Internet-Draft will expire on February 1, 2011.

Copyright Notice

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

1. Definitions
2. Envelope Structures
3. Creating Signature
4. Signature Verification
5. Key Discovery and the Trust
    5.1. Shared key in HMAC-SHA256
    5.2. X.509 Certificates
6. IANA Considerations
7. Security Considerations
8. Acknowledgements
9. References
    9.1. Normative References
    9.2. Informative References
Appendix A. An Appendix
§ Authors' Addresses

TOC

1. Definitions

Server Descriptors

A server descriptor is a https or http URL. This URL resolves to a document that describes the server (such as keys used to sign requests or tokens, location of certain endpoints, etc.).

Signature

A digital signature that provably binds a message to a signer's keypair or Hash-based Message Authentication Code that can be used to verify both the data integrity and the authenticity of a message.

Signer

In this specification, an arbitrary identifier associated with a key used in a signature.

Base64url Encoding

The URL and Filename safe variant of the base64 encoding as described in RFC4648 (Josefsson, S., “The Base16, Base32, and Base64 Data Encodings,” October 2006.) [RFC4648], section 5.

HMAC-SHA256

Hash-based Message Authentication Code using SHA-256 as the hash function.

RSA-SHA256

RSASSA-PKCS1-v1_5 signature algorithm from RFC3447 (Jonsson, J. and B. Kaliski, “Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography Specifications Version 2.1,” February 2003.) [RFC3447] section 8.2, also known as PKCS#1, using SHA-256 as the hash function for EMSA-PKCS1-v1_5.

TOC

2. Envelope Structures

OAuth Signature Envelope is a JSON object that contains following fields. Note that most of them are OPTIONAL.

algorithm - A String that identifies the algorithm used. This specification defines the following: "HMAC-SHA256", "RSA-SHA256".
signer - OPTIONAL. A string that allows the verifier to determine the server descriptor of the Signer. This could be the server descriptor itself, or some form of identifier, which the verifier can map to a server descriptor.
keyid - OPTIONAL. A String that identifies the key that was used to sign.
not_before - OPTIONAL. An integer that represents when does this signature becomes valid (seconds since midnight 1/1/1970 zulu).
not_after - OPTIONAL. An integer that represents when does this signature expires (seconds since midnight 1/1/1970 zulu).
audience - OPTIONAL. The audience for this token. The precise semantics of this field, and how it is validated, depends on the application.
method - OPTIONAL. A String that represents the HTTP method used to execute the HTTP request.
nonce - OPTIONAL. A string that is used to prevent replay attacks. Receivers of OAuth2 Signed Token may verify that nonces have not been previously used within a reasonable interval.
bodyhash - OPTIONAL. A base64url encoded string of hash of the request body. Which hash algorithm is used depends on the signature algorithm specified in the payload.
oauth_token - OPTIONAL. A string that represents OAuth Token.
certs_uri - OPTIONAL. An URI that points to the X.509 public key certificates that can be used to verify the signature.
type - OPTIONAL. The String "oauth-sig" that signify that the type of this JSON object.

The Envelope MAY contain any other fields of arbitrary types, in which case the keys MUST NOT collied with the fields defined above.

Following is a non-normative example of such envelope for HMAC-SHA256

{
    "algorithm":"HMAC-SHA256",
    "oauth_token":"asdfjklsdfjwoIjfk",
    "not_after":12345678,
    "user_id":1223,
    "profile_id":1223
}

Following is a non-normative example of such envelope for RSA-SHA256

{
    "algorithm":"RSA-SHA256",
    "signer":"example.com",
    "audience":"https://example-client.com/redirect_uri",
    "certs_uri":"http://example.com/mycerts.pem",
    "oauth_token":"asdfjklsdfjwoIjfk",
    "not_after":12345678,
    "user_id":"1223",
    "profile_id":"1223"
}

TOC

3. Creating Signature

The basic steps of creating the string with the signature is as follows:

Base64url encode the envelope to obtain the "payload".
Apply signature over the "payload" by the specified algorithm to obtain the signature.
Base64url encode the signature to obtain the "signature string".
Concatenate the "signature string" and the "payload" with a period "."(ASCII 0x2E). This string is called "JSON Token".

Line breaks are for display purposes only.

vlXgu64BQGFSQrY0ZcJBZASMvYvTHu9GQ0YM9rjPSso
.
eyJhbGdvcml0aG0iOiJITUFDLVNIQTI1NiIsIjAiOiJwYXlsb2FkIn0

TOC

4. Signature Verification

To verify the signature, the verifier MUST have an access to a trusted signature verification key. Trusted key MAY BE established in the following ways:

If the key is the shared key in HMAC-SHA256, the key MUST BE the client_secret defined in the OAuth 2.0 specification.
If the key is RSA key defined in X.509 self-signed certificate, the key MUST be obtained through the Discovery mechanism defined in Section 5.

The verification involves the following steps:

Split the JSON Token by a period "."(ASCII 0x2E) to obtain the signature and the payload.
Base64url decode both the "signature string" and the "payload" to obtain the signature and the envelope respectively.
If the algorithm is "HMAC-SHA256", calculate the signature from the payload using the client_secret. If the algorithm is "RSA-SHA256", then use RSASSA-PKCS1-v1_5 verification algorithm from RFC3447 (Jonsson, J. and B. Kaliski, “Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography Specifications Version 2.1,” February 2003.) [RFC3447] section 8.2.1. to verify the Signature.
If the not_before field is specified, verify that the current time is not before the not_before timestamp in the payload, and that the current time is not after the expiration time of the token (defined as not_before + token_lifetime). The verifier SHOULD be lenient and anticipate some clock skew on the issuer's side.
If the audience field is specified, verify the audience field in an application-dependent manner.
If the method field is specified, verify that the method in the token payload equals the method used to access the HTTP resource
If the audience field is specified, verify that the audience in the token payload matches the URI used to access the HTTP resource.
If the nonce is specified, verify that the token nonce has not been used within the lifetime of the token.
if the body_hash is specified, verify that the received request body hashes to the specified value.

TOC

5. Key Discovery and the Trust

To verify the signature, the trusted key MUST be found by the verifier first. This specification defines three such methods.

TOC

5.1. Shared key in HMAC-SHA256

When HMAC-SHA256 is specified as the algorithm, the client_secret defined in OAuth 2.0 is used as the shared key.

TOC

5.2. X.509 Certificates

X.509 Certificates are found from the uri in 'certs_uri' field. The uri MUST return a X.509 file in PEM format with "application/x-pem-file" as the mime-type. It MAY contain the certificate chain. The CN of the obtained certificate MUST match the uri found in the 'signer' field. Other attributes in the X.509 certificates SHOULD be checked to verify the validity of the certificates.

TOC

6. IANA Considerations

This document makes no request of IANA.

Note to RFC Editor: this section may be removed on publication as an RFC.

TOC

7. Security Considerations

[TODO]

TOC

8. Acknowledgements

[TODO]

TOC

9. References

TOC

9.1. Normative References

[RFC2119]	Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, March 1997 (TXT, HTML, XML).
[RFC3447]	Jonsson, J. and B. Kaliski, “Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography Specifications Version 2.1,” RFC 3447, February 2003 (TXT).
[RFC4648]	Josefsson, S., “The Base16, Base32, and Base64 Data Encodings,” RFC 4648, October 2006 (TXT).

TOC

9.2. Informative References

[InfRef]

“,” 2004.

TOC

Appendix A. An Appendix

TOC

Authors' Addresses

	Dirk Balfanz
	Google

	John Bradley
	Wingaa

	Nat Sakimura (Editor)
	Nomura Research Institute

	Luke Shephard
	Facebook

	Paul Tarjan
	Facebook

<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="3"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="info" docName="draft-sakimura-oauth-signatures-00"
     ipr="trust200902">
  <front>
    <title abbrev="osig">OAuth Signatures 1.0 draft 00</title>

    <author fullname="Dirk Balfanz" initials="D. " surname="Balfanz">
      <organization>Google</organization>
    </author>

    <author fullname="John Bradley" initials="J." surname="Bradley">
      <organization>Wingaa</organization>
    </author>

    <author fullname="Nat Sakimura (Editor)" initials="N. "
            surname="Sakimura  (Editor)">
      <organization>Nomura Research Institute</organization>
    </author>

    <author fullname="Luke Shephard" initials="L." surname="Shephard">
      <organization>Facebook</organization>
    </author>

    <author fullname="Paul Tarjan" initials="P." surname="Tarjan">
      <organization>Facebook</organization>
    </author>

    <date day="31" month="July" year="2010" />

    <workgroup>Open Authentication Working Group</workgroup>

    <keyword>Signature</keyword>

    <keyword>Draft</keyword>

    <abstract>
      <t>This specification defines signing mechanism to be used in OAuth 2.0.
      The OAuth requests and responses together with signature related
      parameters are encoded into JSON envelope and then signing algorithm is
      applied to obtain Base64url encoded signature using signatory's key. The
      resulting signature is concatenated with the Base64url encoded JSON
      envelope to which the signature is applied by a period "." so that it
      could be included in URLs.</t>
    </abstract>

    <note title="Requirements Language">
      <t>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 <xref
      target="RFC2119">RFC 2119</xref>.</t>
    </note>
  </front>

  <middle>
    <section title="Definitions">
      <t></t>

      <t><list style="hanging">
          <t hangText="Server Descriptors">A server descriptor is a https or
          http URL. This URL resolves to a document that describes the server
          (such as keys used to sign requests or tokens, location of certain
          endpoints, etc.).</t>

          <t hangText="Signature">A digital signature that provably binds a
          message to a signer's keypair or Hash-based Message Authentication
          Code that can be used to verify both the data integrity and the
          authenticity of a message.</t>

          <t hangText="Signer">In this specification, an arbitrary identifier
          associated with a key used in a signature.</t>

          <t hangText="Base64url Encoding">The URL and Filename safe variant
          of the base64 encoding as described in <xref
          target="RFC4648">RFC4648</xref>, section 5.</t>

          <t hangText="HMAC-SHA256">Hash-based Message Authentication Code
          using SHA-256 as the hash function.</t>

          <t hangText="RSA-SHA256">RSASSA-PKCS1-v1_5 signature algorithm from
          <xref target="RFC3447">RFC3447</xref> section 8.2, also known as
          PKCS#1, using SHA-256 as the hash function for EMSA-PKCS1-v1_5.</t>
        </list></t>
    </section>

    <section title="Envelope Structures">
      <t>OAuth Signature Envelope is a JSON object that contains following
      fields. Note that most of them are OPTIONAL.</t>

      <t><list style="symbols">
          <t>algorithm - A String that identifies the algorithm used. This
          specification defines the following: "HMAC-SHA256",
          "RSA-SHA256".</t>

          <t>signer - OPTIONAL. A string that allows the verifier to determine
          the server descriptor of the Signer. This could be the server
          descriptor itself, or some form of identifier, which the verifier
          can map to a server descriptor.</t>

          <t>keyid - OPTIONAL. A String that identifies the key that was used
          to sign.</t>

          <t>not_before - OPTIONAL. An integer that represents when does this
          signature becomes valid (seconds since midnight 1/1/1970 zulu).</t>

          <t>not_after - OPTIONAL. An integer that represents when does this
          signature expires (seconds since midnight 1/1/1970 zulu).</t>

          <t>audience - OPTIONAL. The audience for this token. The precise
          semantics of this field, and how it is validated, depends on the
          application.</t>

          <t>method - OPTIONAL. A String that represents the HTTP method used
          to execute the HTTP request.</t>

          <t>nonce - OPTIONAL. A string that is used to prevent replay
          attacks. Receivers of OAuth2 Signed Token may verify that nonces
          have not been previously used within a reasonable interval.</t>

          <t>bodyhash - OPTIONAL. A base64url encoded string of hash of the
          request body. Which hash algorithm is used depends on the signature
          algorithm specified in the payload.</t>

          <t>oauth_token - OPTIONAL. A string that represents OAuth Token.</t>

          <t>certs_uri - OPTIONAL. An URI that points to the X.509 public key
          certificates that can be used to verify the signature.</t>

          <t>type - OPTIONAL. The String "oauth-sig" that signify that the
          type of this JSON object.</t>
        </list></t>

      <t>The Envelope MAY contain any other fields of arbitrary types, in
      which case the keys MUST NOT collied with the fields defined above.</t>

      <figure>
        <preamble>Following is a non-normative example of such envelope for
        HMAC-SHA256</preamble>

        <artwork><![CDATA[{
    "algorithm":"HMAC-SHA256",
    "oauth_token":"asdfjklsdfjwoIjfk",
    "not_after":12345678,
    "user_id":1223,
    "profile_id":1223
}

]]></artwork>

        <postamble></postamble>
      </figure>

      <figure>
        <preamble>Following is a non-normative example of such envelope for
        RSA-SHA256</preamble>

        <artwork><![CDATA[{
    "algorithm":"RSA-SHA256",
    "signer":"example.com",
    "audience":"https://example-client.com/redirect_uri";,
    "certs_uri":"http://example.com/mycerts.pem";,
    "oauth_token":"asdfjklsdfjwoIjfk",
    "not_after":12345678,
    "user_id":"1223",
    "profile_id":"1223"
}

]]></artwork>

        <postamble></postamble>
      </figure>

      <t></t>
    </section>

    <section title="Creating Signature">
      <t>The basic steps of creating the string with the signature is as
      follows:</t>

      <t><list style="numbers">
          <t>Base64url encode the envelope to obtain the "payload".</t>

          <t>Apply signature over the "payload" by the specified algorithm to
          obtain the signature.</t>

          <t>Base64url encode the signature to obtain the "signature
          string".</t>

          <t>Concatenate the "signature string" and the "payload" with a
          period "."(ASCII 0x2E). This string is called "JSON Token".</t>
        </list><figure>
          <preamble>Line breaks are for display purposes only. </preamble>

          <artwork><![CDATA[vlXgu64BQGFSQrY0ZcJBZASMvYvTHu9GQ0YM9rjPSso
.
eyJhbGdvcml0aG0iOiJITUFDLVNIQTI1NiIsIjAiOiJwYXlsb2FkIn0
]]></artwork>

          <postamble></postamble>
        </figure></t>
    </section>

    <section anchor="verification" title="Signature Verification">
      <t>To verify the signature, the verifier MUST have an access to a
      trusted signature verification key. Trusted key MAY BE established in
      the following ways:</t>

      <t><list style="numbers">
          <t>If the key is the shared key in HMAC-SHA256, the key MUST BE the
          client_secret defined in the OAuth 2.0 specification.</t>

          <t>If the key is RSA key defined in X.509 self-signed certificate,
          the key MUST be obtained through the Discovery mechanism defined in
          Section 5.</t>
        </list></t>

      <t>The verification involves the following steps: <list style="numbers">
          <t>Split the JSON Token by a period "."(ASCII 0x2E) to obtain the
          signature and the payload.</t>

          <t>Base64url decode both the "signature string" and the "payload" to
          obtain the signature and the envelope respectively.</t>

          <t>If the algorithm is "HMAC-SHA256", calculate the signature from
          the payload using the client_secret. If the algorithm is
          "RSA-SHA256", then use RSASSA-PKCS1-v1_5 verification algorithm from
          <xref target="RFC3447">RFC3447</xref> section 8.2.1. to verify the
          Signature.</t>

          <t>If the not_before field is specified, verify that the current
          time is not before the not_before timestamp in the payload, and that
          the current time is not after the expiration time of the token
          (defined as not_before + token_lifetime). The verifier SHOULD be
          lenient and anticipate some clock skew on the issuer's side.</t>

          <t>If the audience field is specified, verify the audience field in
          an application-dependent manner.</t>

          <t>If the method field is specified, verify that the method in the
          token payload equals the method used to access the HTTP resource</t>

          <t>If the audience field is specified, verify that the audience in
          the token payload matches the URI used to access the HTTP
          resource.</t>

          <t>If the nonce is specified, verify that the token nonce has not
          been used within the lifetime of the token.</t>

          <t>if the body_hash is specified, verify that the received request
          body hashes to the specified value.</t>
        </list></t>

      <t></t>
    </section>

    <section anchor="discovery" title="Key Discovery and the Trust">
      <t>To verify the signature, the trusted key MUST be found by the
      verifier first. This specification defines three such methods.</t>

      <section anchor="skey" title="Shared key in HMAC-SHA256">
        <t>When HMAC-SHA256 is specified as the algorithm, the client_secret
        defined in OAuth 2.0 is used as the shared key.</t>
      </section>

      <section anchor="x509" title="X.509 Certificates">
        <t>X.509 Certificates are found from the uri in 'certs_uri' field. The
        uri MUST return a X.509 file in PEM format with
        "application/x-pem-file" as the mime-type. It MAY contain the
        certificate chain. The CN of the obtained certificate MUST match the
        uri found in the 'signer' field. Other attributes in the X.509
        certificates SHOULD be checked to verify the validity of the
        certificates.</t>
      </section>
    </section>

    <section anchor="IANA" title="IANA Considerations">
      <t>This document makes no request of IANA.</t>

      <t>Note to RFC Editor: this section may be removed on publication as an
      RFC.</t>
    </section>

    <section anchor="Security" title="Security Considerations">
      <t>[TODO]</t>
    </section>

    <section anchor="Acknowledgements" title="Acknowledgements">
      <t>[TODO]</t>
    </section>
  </middle>

  <back>
    <references title="Normative References">
      <?rfc include="reference.RFC.2119"?>

      <?rfc include='reference.RFC.4648'?>

      <?rfc include='reference.RFC.3447'?>
    </references>

    <references title="Informative References">
      <reference anchor="InfRef">
        <front>
          <title></title>

          <author>
            <organization></organization>
          </author>

          <date year="2004" />
        </front>
      </reference>
    </references>

    <section title="An Appendix">
      <t></t>
    </section>
  </back>
</rfc>

_______________________________________________
OAuth mailing list
OAuth@ietf.org
https://www.ietf.org/mailman/listinfo/oauth

[OAUTH-WG] OAuth Signature Draft Pre 00

OAuth Signatures 1.0 draft 00
draft-sakimura-oauth-signatures-00

Abstract

Requirements Language

Status of this Memo

Copyright Notice

Table of Contents

1. Definitions

2. Envelope Structures

3. Creating Signature

4. Signature Verification

5. Key Discovery and the Trust

5.1. Shared key in HMAC-SHA256

5.2. X.509 Certificates

6. IANA Considerations

7. Security Considerations

8. Acknowledgements

9. References

9.1. Normative References

9.2. Informative References

Appendix A. An Appendix

Authors' Addresses

Reply via email to

[OAUTH-WG] OAuth Signature Draft Pre 00

OAuth Signatures 1.0 draft 00draft-sakimura-oauth-signatures-00

Abstract

Requirements Language

Status of this Memo

Copyright Notice

Table of Contents

1. Definitions

2. Envelope Structures

3. Creating Signature

4. Signature Verification

5. Key Discovery and the Trust

5.1. Shared key in HMAC-SHA256

5.2. X.509 Certificates

6. IANA Considerations

7. Security Considerations

8. Acknowledgements

9. References

9.1. Normative References

9.2. Informative References

Appendix A. An Appendix

Authors' Addresses

Reply via email to

OAuth Signatures 1.0 draft 00
draft-sakimura-oauth-signatures-00