doc: Add RFC documents

1 files changed, 1123 insertions, 0 deletions

diff --git a/doc/rfc/rfc7636.txt b/doc/rfc/rfc7636.txt
new file mode 100644
index 0000000..653cb53
--- /dev/null
+++ b/doc/rfc/rfc7636.txt
@@ -0,0 +1,1123 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF)                  N. Sakimura, Ed.
+Request for Comments: 7636                     Nomura Research Institute
+Category: Standards Track                                     J. Bradley
+ISSN: 2070-1721                                            Ping Identity
+                                                              N. Agarwal
+                                                                  Google
+                                                          September 2015
+
+
+          Proof Key for Code Exchange by OAuth Public Clients
+
+Abstract
+
+   OAuth 2.0 public clients utilizing the Authorization Code Grant are
+   susceptible to the authorization code interception attack.  This
+   specification describes the attack as well as a technique to mitigate
+   against the threat through the use of Proof Key for Code Exchange
+   (PKCE, pronounced "pixy").
+
+Status of This Memo
+
+   This is an Internet Standards Track document.
+
+   This document is a product of the Internet Engineering Task Force
+   (IETF).  It represents the consensus of the IETF community.  It has
+   received public review and has been approved for publication by the
+   Internet Engineering Steering Group (IESG).  Further information on
+   Internet Standards is available in Section 2 of RFC 5741.
+
+   Information about the current status of this document, any errata,
+   and how to provide feedback on it may be obtained at
+   http://www.rfc-editor.org/info/rfc7636.
+
+Copyright Notice
+
+   Copyright (c) 2015 IETF Trust and the persons identified as the
+   document authors.  All rights reserved.
+
+   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.
+
+
+
+
+Sakimura, et al.             Standards Track                    [Page 1]
+
+RFC 7636                       OAUTH PKCE                 September 2015
+
+
+Table of Contents
+
+   1. Introduction ....................................................3
+      1.1. Protocol Flow ..............................................5
+   2. Notational Conventions ..........................................6
+   3. Terminology .....................................................7
+      3.1. Abbreviations ..............................................7
+   4. Protocol ........................................................8
+      4.1. Client Creates a Code Verifier .............................8
+      4.2. Client Creates the Code Challenge ..........................8
+      4.3. Client Sends the Code Challenge with the
+           Authorization Request ......................................9
+      4.4. Server Returns the Code ....................................9
+           4.4.1. Error Response ......................................9
+      4.5. Client Sends the Authorization Code and the Code
+           Verifier to the Token Endpoint ............................10
+      4.6. Server Verifies code_verifier before Returning the
+           Tokens ....................................................10
+   5. Compatibility ..................................................11
+   6. IANA Considerations ............................................11
+      6.1. OAuth Parameters Registry .................................11
+      6.2. PKCE Code Challenge Method Registry .......................11
+           6.2.1. Registration Template ..............................12
+           6.2.2. Initial Registry Contents ..........................13
+   7. Security Considerations ........................................13
+      7.1. Entropy of the code_verifier ..............................13
+      7.2. Protection against Eavesdroppers ..........................13
+      7.3. Salting the code_challenge ................................14
+      7.4. OAuth Security Considerations .............................14
+      7.5. TLS Security Considerations ...............................15
+   8. References .....................................................15
+      8.1. Normative References ......................................15
+      8.2. Informative References ....................................16
+   Appendix A.  Notes on Implementing Base64url Encoding without
+                Padding  .............................................17
+   Appendix B.  Example for the S256 code_challenge_method ...........17
+   Acknowledgements ..................................................19
+   Authors' Addresses ................................................20
+
+
+
+
+
+
+
+
+
+
+
+
+
+Sakimura, et al.             Standards Track                    [Page 2]
+
+RFC 7636                       OAUTH PKCE                 September 2015
+
+
+1.  Introduction
+
+   OAuth 2.0 [RFC6749] public clients are susceptible to the
+   authorization code interception attack.
+
+   In this attack, the attacker intercepts the authorization code
+   returned from the authorization endpoint within a communication path
+   not protected by Transport Layer Security (TLS), such as inter-
+   application communication within the client's operating system.
+
+   Once the attacker has gained access to the authorization code, it can
+   use it to obtain the access token.
+
+   Figure 1 shows the attack graphically.  In step (1), the native
+   application running on the end device, such as a smartphone, issues
+   an OAuth 2.0 Authorization Request via the browser/operating system.
+   The Redirection Endpoint URI in this case typically uses a custom URI
+   scheme.  Step (1) happens through a secure API that cannot be
+   intercepted, though it may potentially be observed in advanced attack
+   scenarios.  The request then gets forwarded to the OAuth 2.0
+   authorization server in step (2).  Because OAuth requires the use of
+   TLS, this communication is protected by TLS and cannot be
+   intercepted.  The authorization server returns the authorization code
+   in step (3).  In step (4), the Authorization Code is returned to the
+   requester via the Redirection Endpoint URI that was provided in step
+   (1).
+
+   Note that it is possible for a malicious app to register itself as a
+   handler for the custom scheme in addition to the legitimate OAuth 2.0
+   app.  Once it does so, the malicious app is now able to intercept the
+   authorization code in step (4).  This allows the attacker to request
+   and obtain an access token in steps (5) and (6), respectively.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Sakimura, et al.             Standards Track                    [Page 3]
+
+RFC 7636                       OAUTH PKCE                 September 2015
+
+
+    +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
+    | End Device (e.g., Smartphone)  |
+    |                                |
+    | +-------------+   +----------+ | (6) Access Token  +----------+
+    | |Legitimate   |   | Malicious|<--------------------|          |
+    | |OAuth 2.0 App|   | App      |-------------------->|          |
+    | +-------------+   +----------+ | (5) Authorization |          |
+    |        |    ^          ^       |        Grant      |          |
+    |        |     \         |       |                   |          |
+    |        |      \   (4)  |       |                   |          |
+    |    (1) |       \  Authz|       |                   |          |
+    |   Authz|        \ Code |       |                   |  Authz   |
+    | Request|         \     |       |                   |  Server  |
+    |        |          \    |       |                   |          |
+    |        |           \   |       |                   |          |
+    |        v            \  |       |                   |          |
+    | +----------------------------+ |                   |          |
+    | |                            | | (3) Authz Code    |          |
+    | |     Operating System/      |<--------------------|          |
+    | |         Browser            |-------------------->|          |
+    | |                            | | (2) Authz Request |          |
+    | +----------------------------+ |                   +----------+
+    +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
+
+             Figure 1: Authorization Code Interception Attack
+
+   A number of pre-conditions need to hold for this attack to work:
+
+   1. The attacker manages to register a malicious application on the
+      client device and registers a custom URI scheme that is also used
+      by another application.  The operating systems must allow a custom
+      URI scheme to be registered by multiple applications.
+
+   2. The OAuth 2.0 authorization code grant is used.
+
+   3. The attacker has access to the OAuth 2.0 [RFC6749] "client_id" and
+      "client_secret" (if provisioned).  All OAuth 2.0 native app
+      client-instances use the same "client_id".  Secrets provisioned in
+      client binary applications cannot be considered confidential.
+
+   4. Either one of the following condition is met:
+
+      4a. The attacker (via the installed application) is able to
+          observe only the responses from the authorization endpoint.
+          When "code_challenge_method" value is "plain", only this
+          attack is mitigated.
+
+
+
+
+
+Sakimura, et al.             Standards Track                    [Page 4]
+
+RFC 7636                       OAUTH PKCE                 September 2015
+
+
+      4b. A more sophisticated attack scenario allows the attacker to
+          observe requests (in addition to responses) to the
+          authorization endpoint.  The attacker is, however, not able to
+          act as a man in the middle.  This was caused by leaking http
+          log information in the OS.  To mitigate this,
+          "code_challenge_method" value must be set either to "S256" or
+          a value defined by a cryptographically secure
+          "code_challenge_method" extension.
+
+   While this is a long list of pre-conditions, the described attack has
+   been observed in the wild and has to be considered in OAuth 2.0
+   deployments.  While the OAuth 2.0 threat model (Section 4.4.1 of
+   [RFC6819]) describes mitigation techniques, they are, unfortunately,
+   not applicable since they rely on a per-client instance secret or a
+   per-client instance redirect URI.
+
+   To mitigate this attack, this extension utilizes a dynamically
+   created cryptographically random key called "code verifier".  A
+   unique code verifier is created for every authorization request, and
+   its transformed value, called "code challenge", is sent to the
+   authorization server to obtain the authorization code.  The
+   authorization code obtained is then sent to the token endpoint with
+   the "code verifier", and the server compares it with the previously
+   received request code so that it can perform the proof of possession
+   of the "code verifier" by the client.  This works as the mitigation
+   since the attacker would not know this one-time key, since it is sent
+   over TLS and cannot be intercepted.
+
+1.1.  Protocol Flow
+
+                                                 +-------------------+
+                                                 |   Authz Server    |
+       +--------+                                | +---------------+ |
+       |        |--(A)- Authorization Request ---->|               | |
+       |        |       + t(code_verifier), t_m  | | Authorization | |
+       |        |                                | |    Endpoint   | |
+       |        |<-(B)---- Authorization Code -----|               | |
+       |        |                                | +---------------+ |
+       | Client |                                |                   |
+       |        |                                | +---------------+ |
+       |        |--(C)-- Access Token Request ---->|               | |
+       |        |          + code_verifier       | |    Token      | |
+       |        |                                | |   Endpoint    | |
+       |        |<-(D)------ Access Token ---------|               | |
+       +--------+                                | +---------------+ |
+                                                 +-------------------+
+
+                     Figure 2: Abstract Protocol Flow
+
+
+
+Sakimura, et al.             Standards Track                    [Page 5]
+
+RFC 7636                       OAUTH PKCE                 September 2015
+
+
+   This specification adds additional parameters to the OAuth 2.0
+   Authorization and Access Token Requests, shown in abstract form in
+   Figure 2.
+
+   A. The client creates and records a secret named the "code_verifier"
+      and derives a transformed version "t(code_verifier)" (referred to
+      as the "code_challenge"), which is sent in the OAuth 2.0
+      Authorization Request along with the transformation method "t_m".
+
+   B. The Authorization Endpoint responds as usual but records
+      "t(code_verifier)" and the transformation method.
+
+   C. The client then sends the authorization code in the Access Token
+      Request as usual but includes the "code_verifier" secret generated
+      at (A).
+
+   D. The authorization server transforms "code_verifier" and compares
+      it to "t(code_verifier)" from (B).  Access is denied if they are
+      not equal.
+
+   An attacker who intercepts the authorization code at (B) is unable to
+   redeem it for an access token, as they are not in possession of the
+   "code_verifier" secret.
+
+2.  Notational Conventions
+
+   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
+   "OPTIONAL" in this document are to be interpreted as described in
+   "Key words for use in RFCs to Indicate Requirement Levels" [RFC2119].
+   If these words are used without being spelled in uppercase, then they
+   are to be interpreted with their natural language meanings.
+
+   This specification uses the Augmented Backus-Naur Form (ABNF)
+   notation of [RFC5234].
+
+   STRING denotes a sequence of zero or more ASCII [RFC20] characters.
+
+   OCTETS denotes a sequence of zero or more octets.
+
+   ASCII(STRING) denotes the octets of the ASCII [RFC20] representation
+   of STRING where STRING is a sequence of zero or more ASCII
+   characters.
+
+   BASE64URL-ENCODE(OCTETS) denotes the base64url encoding of OCTETS,
+   per Appendix A, producing a STRING.
+
+
+
+
+
+Sakimura, et al.             Standards Track                    [Page 6]
+
+RFC 7636                       OAUTH PKCE                 September 2015
+
+
+   BASE64URL-DECODE(STRING) denotes the base64url decoding of STRING,
+   per Appendix A, producing a sequence of octets.
+
+   SHA256(OCTETS) denotes a SHA2 256-bit hash [RFC6234] of OCTETS.
+
+3.  Terminology
+
+   In addition to the terms defined in OAuth 2.0 [RFC6749], this
+   specification defines the following terms:
+
+   code verifier
+      A cryptographically random string that is used to correlate the
+      authorization request to the token request.
+
+   code challenge
+      A challenge derived from the code verifier that is sent in the
+      authorization request, to be verified against later.
+
+   code challenge method
+      A method that was used to derive code challenge.
+
+   Base64url Encoding
+      Base64 encoding using the URL- and filename-safe character set
+      defined in Section 5 of [RFC4648], with all trailing '='
+      characters omitted (as permitted by Section 3.2 of [RFC4648]) and
+      without the inclusion of any line breaks, whitespace, or other
+      additional characters.  (See Appendix A for notes on implementing
+      base64url encoding without padding.)
+
+3.1.  Abbreviations
+
+   ABNF   Augmented Backus-Naur Form
+
+   Authz  Authorization
+
+   PKCE   Proof Key for Code Exchange
+
+   MITM   Man-in-the-middle
+
+   MTI    Mandatory To Implement
+
+
+
+
+
+
+
+
+
+
+
+Sakimura, et al.             Standards Track                    [Page 7]
+
+RFC 7636                       OAUTH PKCE                 September 2015
+
+
+4.  Protocol
+
+4.1.  Client Creates a Code Verifier
+
+   The client first creates a code verifier, "code_verifier", for each
+   OAuth 2.0 [RFC6749] Authorization Request, in the following manner:
+
+   code_verifier = high-entropy cryptographic random STRING using the
+   unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"
+   from Section 2.3 of [RFC3986], with a minimum length of 43 characters
+   and a maximum length of 128 characters.
+
+   ABNF for "code_verifier" is as follows.
+
+   code-verifier = 43*128unreserved
+   unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
+   ALPHA = %x41-5A / %x61-7A
+   DIGIT = %x30-39
+
+   NOTE: The code verifier SHOULD have enough entropy to make it
+   impractical to guess the value.  It is RECOMMENDED that the output of
+   a suitable random number generator be used to create a 32-octet
+   sequence.  The octet sequence is then base64url-encoded to produce a
+   43-octet URL safe string to use as the code verifier.
+
+4.2.  Client Creates the Code Challenge
+
+   The client then creates a code challenge derived from the code
+   verifier by using one of the following transformations on the code
+   verifier:
+
+   plain
+      code_challenge = code_verifier
+
+   S256
+      code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
+
+   If the client is capable of using "S256", it MUST use "S256", as
+   "S256" is Mandatory To Implement (MTI) on the server.  Clients are
+   permitted to use "plain" only if they cannot support "S256" for some
+   technical reason and know via out-of-band configuration that the
+   server supports "plain".
+
+   The plain transformation is for compatibility with existing
+   deployments and for constrained environments that can't use the S256
+   transformation.
+
+
+
+
+
+Sakimura, et al.             Standards Track                    [Page 8]
+
+RFC 7636                       OAUTH PKCE                 September 2015
+
+
+   ABNF for "code_challenge" is as follows.
+
+   code-challenge = 43*128unreserved
+   unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
+   ALPHA = %x41-5A / %x61-7A
+   DIGIT = %x30-39
+
+4.3.  Client Sends the Code Challenge with the Authorization Request
+
+   The client sends the code challenge as part of the OAuth 2.0
+   Authorization Request (Section 4.1.1 of [RFC6749]) using the
+   following additional parameters:
+
+   code_challenge
+      REQUIRED.  Code challenge.
+
+   code_challenge_method
+      OPTIONAL, defaults to "plain" if not present in the request.  Code
+      verifier transformation method is "S256" or "plain".
+
+4.4.  Server Returns the Code
+
+   When the server issues the authorization code in the authorization
+   response, it MUST associate the "code_challenge" and
+   "code_challenge_method" values with the authorization code so it can
+   be verified later.
+
+   Typically, the "code_challenge" and "code_challenge_method" values
+   are stored in encrypted form in the "code" itself but could
+   alternatively be stored on the server associated with the code.  The
+   server MUST NOT include the "code_challenge" value in client requests
+   in a form that other entities can extract.
+
+   The exact method that the server uses to associate the
+   "code_challenge" with the issued "code" is out of scope for this
+   specification.
+
+4.4.1.  Error Response
+
+   If the server requires Proof Key for Code Exchange (PKCE) by OAuth
+   public clients and the client does not send the "code_challenge" in
+   the request, the authorization endpoint MUST return the authorization
+   error response with the "error" value set to "invalid_request".  The
+   "error_description" or the response of "error_uri" SHOULD explain the
+   nature of error, e.g., code challenge required.
+
+
+
+
+
+
+Sakimura, et al.             Standards Track                    [Page 9]
+
+RFC 7636                       OAUTH PKCE                 September 2015
+
+
+   If the server supporting PKCE does not support the requested
+   transformation, the authorization endpoint MUST return the
+   authorization error response with "error" value set to
+   "invalid_request".  The "error_description" or the response of
+   "error_uri" SHOULD explain the nature of error, e.g., transform
+   algorithm not supported.
+
+4.5.  Client Sends the Authorization Code and the Code Verifier to the
+      Token Endpoint
+
+   Upon receipt of the Authorization Code, the client sends the Access
+   Token Request to the token endpoint.  In addition to the parameters
+   defined in the OAuth 2.0 Access Token Request (Section 4.1.3 of
+   [RFC6749]), it sends the following parameter:
+
+   code_verifier
+      REQUIRED.  Code verifier
+
+   The "code_challenge_method" is bound to the Authorization Code when
+   the Authorization Code is issued.  That is the method that the token
+   endpoint MUST use to verify the "code_verifier".
+
+4.6.  Server Verifies code_verifier before Returning the Tokens
+
+   Upon receipt of the request at the token endpoint, the server
+   verifies it by calculating the code challenge from the received
+   "code_verifier" and comparing it with the previously associated
+   "code_challenge", after first transforming it according to the
+   "code_challenge_method" method specified by the client.
+
+   If the "code_challenge_method" from Section 4.3 was "S256", the
+   received "code_verifier" is hashed by SHA-256, base64url-encoded, and
+   then compared to the "code_challenge", i.e.:
+
+   BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) == code_challenge
+
+   If the "code_challenge_method" from Section 4.3 was "plain", they are
+   compared directly, i.e.:
+
+   code_verifier == code_challenge.
+
+   If the values are equal, the token endpoint MUST continue processing
+   as normal (as defined by OAuth 2.0 [RFC6749]).  If the values are not
+   equal, an error response indicating "invalid_grant" as described in
+   Section 5.2 of [RFC6749] MUST be returned.
+
+
+
+
+
+
+Sakimura, et al.             Standards Track                   [Page 10]
+
+RFC 7636                       OAUTH PKCE                 September 2015
+
+
+5.  Compatibility
+
+   Server implementations of this specification MAY accept OAuth2.0
+   clients that do not implement this extension.  If the "code_verifier"
+   is not received from the client in the Authorization Request, servers
+   supporting backwards compatibility revert to the OAuth 2.0 [RFC6749]
+   protocol without this extension.
+
+   As the OAuth 2.0 [RFC6749] server responses are unchanged by this
+   specification, client implementations of this specification do not
+   need to know if the server has implemented this specification or not
+   and SHOULD send the additional parameters as defined in Section 4 to
+   all servers.
+
+6.  IANA Considerations
+
+   IANA has made the following registrations per this document.
+
+6.1.  OAuth Parameters Registry
+
+   This specification registers the following parameters in the IANA
+   "OAuth Parameters" registry defined in OAuth 2.0 [RFC6749].
+
+   o  Parameter name: code_verifier
+   o  Parameter usage location: token request
+   o  Change controller: IESG
+   o  Specification document(s): RFC 7636 (this document)
+
+   o  Parameter name: code_challenge
+   o  Parameter usage location: authorization request
+   o  Change controller: IESG
+   o  Specification document(s): RFC 7636 (this document)
+
+   o  Parameter name: code_challenge_method
+   o  Parameter usage location: authorization request
+   o  Change controller: IESG
+   o  Specification document(s): RFC 7636 (this document)
+
+6.2.  PKCE Code Challenge Method Registry
+
+   This specification establishes the "PKCE Code Challenge Methods"
+   registry.  The new registry should be a sub-registry of the "OAuth
+   Parameters" registry.
+
+   Additional "code_challenge_method" types for use with the
+   authorization endpoint are registered using the Specification
+   Required policy [RFC5226], which includes review of the request by
+   one or more Designated Experts (DEs).  The DEs will ensure that there
+
+
+
+Sakimura, et al.             Standards Track                   [Page 11]
+
+RFC 7636                       OAUTH PKCE                 September 2015
+
+
+   is at least a two-week review of the request on the oauth-ext-
+   review@ietf.org mailing list and that any discussion on that list
+   converges before they respond to the request.  To allow for the
+   allocation of values prior to publication, the Designated Expert(s)
+   may approve registration once they are satisfied that an acceptable
+   specification will be published.
+
+   Registration requests and discussion on the oauth-ext-review@ietf.org
+   mailing list should use an appropriate subject, such as "Request for
+   PKCE code_challenge_method: example").
+
+   The Designated Expert(s) should consider the discussion on the
+   mailing list, as well as the overall security properties of the
+   challenge method when evaluating registration requests.  New methods
+   should not disclose the value of the code_verifier in the request to
+   the Authorization endpoint.  Denials should include an explanation
+   and, if applicable, suggestions as to how to make the request
+   successful.
+
+6.2.1.  Registration Template
+
+   Code Challenge Method Parameter Name:
+      The name requested (e.g., "example").  Because a core goal of this
+      specification is for the resulting representations to be compact,
+      it is RECOMMENDED that the name be short -- not to exceed 8
+      characters without a compelling reason to do so.  This name is
+      case-sensitive.  Names may not match other registered names in a
+      case-insensitive manner unless the Designated Expert(s) states
+      that there is a compelling reason to allow an exception in this
+      particular case.
+
+   Change Controller:
+      For Standards Track RFCs, state "IESG".  For others, give the name
+      of the responsible party.  Other details (e.g., postal address,
+      email address, and home page URI) may also be included.
+
+   Specification Document(s):
+      Reference to the document(s) that specifies the parameter,
+      preferably including URI(s) that can be used to retrieve copies of
+      the document(s).  An indication of the relevant sections may also
+      be included but is not required.
+
+
+
+
+
+
+
+
+
+
+Sakimura, et al.             Standards Track                   [Page 12]
+
+RFC 7636                       OAUTH PKCE                 September 2015
+
+
+6.2.2.  Initial Registry Contents
+
+   Per this document, IANA has registered the Code Challenge Method
+   Parameter Names defined in Section 4.2 in this registry.
+
+   o  Code Challenge Method Parameter Name: plain
+   o  Change Controller: IESG
+   o  Specification Document(s): Section 4.2 of RFC 7636 (this document)
+
+   o  Code Challenge Method Parameter Name: S256
+   o  Change Controller: IESG
+   o  Specification Document(s): Section 4.2 of RFC 7636 (this document)
+
+7.  Security Considerations
+
+7.1.  Entropy of the code_verifier
+
+   The security model relies on the fact that the code verifier is not
+   learned or guessed by the attacker.  It is vitally important to
+   adhere to this principle.  As such, the code verifier has to be
+   created in such a manner that it is cryptographically random and has
+   high entropy that it is not practical for the attacker to guess.
+
+   The client SHOULD create a "code_verifier" with a minimum of 256 bits
+   of entropy.  This can be done by having a suitable random number
+   generator create a 32-octet sequence.  The octet sequence can then be
+   base64url-encoded to produce a 43-octet URL safe string to use as a
+   "code_challenge" that has the required entropy.
+
+7.2.  Protection against Eavesdroppers
+
+   Clients MUST NOT downgrade to "plain" after trying the "S256" method.
+   Servers that support PKCE are required to support "S256", and servers
+   that do not support PKCE will simply ignore the unknown
+   "code_verifier".  Because of this, an error when "S256" is presented
+   can only mean that the server is faulty or that a MITM attacker is
+   trying a downgrade attack.
+
+   The "S256" method protects against eavesdroppers observing or
+   intercepting the "code_challenge", because the challenge cannot be
+   used without the verifier.  With the "plain" method, there is a
+   chance that "code_challenge" will be observed by the attacker on the
+   device or in the http request.  Since the code challenge is the same
+   as the code verifier in this case, the "plain" method does not
+   protect against the eavesdropping of the initial request.
+
+   The use of "S256" protects against disclosure of the "code_verifier"
+   value to an attacker.
+
+
+
+Sakimura, et al.             Standards Track                   [Page 13]
+
+RFC 7636                       OAUTH PKCE                 September 2015
+
+
+   Because of this, "plain" SHOULD NOT be used and exists only for
+   compatibility with deployed implementations where the request path is
+   already protected.  The "plain" method SHOULD NOT be used in new
+   implementations, unless they cannot support "S256" for some technical
+   reason.
+
+   The "S256" code challenge method or other cryptographically secure
+   code challenge method extension SHOULD be used.  The "plain" code
+   challenge method relies on the operating system and transport
+   security not to disclose the request to an attacker.
+
+   If the code challenge method is "plain" and the code challenge is to
+   be returned inside authorization "code" to achieve a stateless
+   server, it MUST be encrypted in such a manner that only the server
+   can decrypt and extract it.
+
+7.3.  Salting the code_challenge
+
+   To reduce implementation complexity, salting is not used in the
+   production of the code challenge, as the code verifier contains
+   sufficient entropy to prevent brute-force attacks.  Concatenating a
+   publicly known value to a code verifier (containing 256 bits of
+   entropy) and then hashing it with SHA256 to produce a code challenge
+   would not increase the number of attempts necessary to brute force a
+   valid value for code verifier.
+
+   While the "S256" transformation is like hashing a password, there are
+   important differences.  Passwords tend to be relatively low-entropy
+   words that can be hashed offline and the hash looked up in a
+   dictionary.  By concatenating a unique though public value to each
+   password prior to hashing, the dictionary space that an attacker
+   needs to search is greatly expanded.
+
+   Modern graphics processors now allow attackers to calculate hashes in
+   real time faster than they could be looked up from a disk.  This
+   eliminates the value of the salt in increasing the complexity of a
+   brute-force attack for even low-entropy passwords.
+
+7.4.  OAuth Security Considerations
+
+   All the OAuth security analysis presented in [RFC6819] applies, so
+   readers SHOULD carefully follow it.
+
+
+
+
+
+
+
+
+
+Sakimura, et al.             Standards Track                   [Page 14]
+
+RFC 7636                       OAUTH PKCE                 September 2015
+
+
+7.5.  TLS Security Considerations
+
+   Current security considerations can be found in "Recommendations for
+   Secure Use of Transport Layer Security (TLS) and Datagram Transport
+   Layer Security (DTLS)" [BCP195].  This supersedes the TLS version
+   recommendations in OAuth 2.0 [RFC6749].
+
+8.  References
+
+8.1.  Normative References
+
+   [BCP195]   Sheffer, Y., Holz, R., and P. Saint-Andre,
+              "Recommendations for Secure Use of Transport Layer
+              Security (TLS) and Datagram Transport Layer Security
+              (DTLS)", BCP 195, RFC 7525, May 2015,
+              <http://www.rfc-editor.org/info/bcp195>.
+
+   [RFC20]    Cerf, V., "ASCII format for network interchange", STD 80,
+              RFC 20, DOI 10.17487/RFC0020, October 1969,
+              <http://www.rfc-editor.org/info/rfc20>.
+
+   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
+              Requirement Levels", BCP 14, RFC 2119,
+              DOI 10.17487/RFC2119, March 1997,
+              <http://www.rfc-editor.org/info/rfc2119>.
+
+   [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
+              Resource Identifier (URI): Generic Syntax", STD 66, RFC
+              3986, DOI 10.17487/RFC3986, January 2005,
+              <http://www.rfc-editor.org/info/rfc3986>.
+
+   [RFC4648]  Josefsson, S., "The Base16, Base32, and Base64 Data
+              Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
+              <http://www.rfc-editor.org/info/rfc4648>.
+
+   [RFC5226]  Narten, T. and H. Alvestrand, "Guidelines for Writing an
+              IANA Considerations Section in RFCs", BCP 26, RFC 5226,
+              DOI 10.17487/RFC5226, May 2008,
+              <http://www.rfc-editor.org/info/rfc5226>.
+
+   [RFC5234]  Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
+              Specifications: ABNF", STD 68, RFC 5234,
+              DOI 10.17487/RFC5234, January 2008,
+              <http://www.rfc-editor.org/info/rfc5234>.
+
+
+
+
+
+
+
+Sakimura, et al.             Standards Track                   [Page 15]
+
+RFC 7636                       OAUTH PKCE                 September 2015
+
+
+   [RFC6234]  Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms
+              (SHA and SHA-based HMAC and HKDF)", RFC 6234,
+              DOI 10.17487/RFC6234, May 2011,
+              <http://www.rfc-editor.org/info/rfc6234>.
+
+   [RFC6749]  Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
+              RFC 6749, DOI 10.17487/RFC6749, October 2012,
+              <http://www.rfc-editor.org/info/rfc6749>.
+
+8.2.  Informative References
+
+   [RFC6819]  Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0
+              Threat Model and Security Considerations", RFC 6819,
+              DOI 10.17487/RFC6819, January 2013,
+              <http://www.rfc-editor.org/info/rfc6819>.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Sakimura, et al.             Standards Track                   [Page 16]
+
+RFC 7636                       OAUTH PKCE                 September 2015
+
+
+Appendix A.  Notes on Implementing Base64url Encoding without Padding
+
+   This appendix describes how to implement a base64url-encoding
+   function without padding, based upon the standard base64-encoding
+   function that uses padding.
+
+   To be concrete, example C# code implementing these functions is shown
+   below.  Similar code could be used in other languages.
+
+     static string base64urlencode(byte [] arg)
+     {
+       string s = Convert.ToBase64String(arg); // Regular base64 encoder
+       s = s.Split('=')[0]; // Remove any trailing '='s
+       s = s.Replace('+', '-'); // 62nd char of encoding
+       s = s.Replace('/', '_'); // 63rd char of encoding
+       return s;
+     }
+
+   An example correspondence between unencoded and encoded values
+   follows.  The octet sequence below encodes into the string below,
+   which when decoded, reproduces the octet sequence.
+
+   3 236 255 224 193
+
+   A-z_4ME
+
+Appendix B.  Example for the S256 code_challenge_method
+
+   The client uses output of a suitable random number generator to
+   create a 32-octet sequence.  The octets representing the value in
+   this example (using JSON array notation) are:
+
+      [116, 24, 223, 180, 151, 153, 224, 37, 79, 250, 96, 125, 216, 173,
+      187, 186, 22, 212, 37, 77, 105, 214, 191, 240, 91, 88, 5, 88, 83,
+      132, 141, 121]
+
+   Encoding this octet sequence as base64url provides the value of the
+   code_verifier:
+
+       dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
+
+   The code_verifier is then hashed via the SHA256 hash function to
+   produce:
+
+     [19, 211, 30, 150, 26, 26, 216, 236, 47, 22, 177, 12, 76, 152, 46,
+      8, 118, 168, 120, 173, 109, 241, 68, 86, 110, 225, 137, 74, 203,
+      112, 249, 195]
+
+
+
+
+Sakimura, et al.             Standards Track                   [Page 17]
+
+RFC 7636                       OAUTH PKCE                 September 2015
+
+
+   Encoding this octet sequence as base64url provides the value of the
+   code_challenge:
+
+       E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
+
+   The authorization request includes:
+
+       code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
+       &code_challenge_method=S256
+
+   The authorization server then records the code_challenge and
+   code_challenge_method along with the code that is granted to the
+   client.
+
+   In the request to the token_endpoint, the client includes the code
+   received in the authorization response as well as the additional
+   parameter:
+
+       code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
+
+   The authorization server retrieves the information for the code
+   grant.  Based on the recorded code_challenge_method being S256, it
+   then hashes and base64url-encodes the value of code_verifier:
+
+   BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
+
+   The calculated value is then compared with the value of
+   "code_challenge":
+
+   BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) == code_challenge
+
+   If the two values are equal, then the authorization server can
+   provide the tokens as long as there are no other errors in the
+   request.  If the values are not equal, then the request must be
+   rejected, and an error returned.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Sakimura, et al.             Standards Track                   [Page 18]
+
+RFC 7636                       OAUTH PKCE                 September 2015
+
+
+Acknowledgements
+
+   The initial draft version of this specification was created by the
+   OpenID AB/Connect Working Group of the OpenID Foundation.
+
+   This specification is the work of the OAuth Working Group, which
+   includes dozens of active and dedicated participants.  In particular,
+   the following individuals contributed ideas, feedback, and wording
+   that shaped and formed the final specification:
+
+      Anthony Nadalin, Microsoft
+      Axel Nenker, Deutsche Telekom
+      Breno de Medeiros, Google
+      Brian Campbell, Ping Identity
+      Chuck Mortimore, Salesforce
+      Dirk Balfanz, Google
+      Eduardo Gueiros, Jive Communications
+      Hannes Tschonfenig, ARM
+      James Manger, Telstra
+      Justin Richer, MIT Kerberos
+      Josh Mandel, Boston Children's Hospital
+      Lewis Adam, Motorola Solutions
+      Madjid Nakhjiri, Samsung
+      Michael B. Jones, Microsoft
+      Paul Madsen, Ping Identity
+      Phil Hunt, Oracle
+      Prateek Mishra, Oracle
+      Ryo Ito, mixi
+      Scott Tomilson, Ping Identity
+      Sergey Beryozkin
+      Takamichi Saito
+      Torsten Lodderstedt, Deutsche Telekom
+      William Denniss, Google
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Sakimura, et al.             Standards Track                   [Page 19]
+
+RFC 7636                       OAUTH PKCE                 September 2015
+
+
+Authors' Addresses
+
+   Nat Sakimura (editor)
+   Nomura Research Institute
+   1-6-5 Marunouchi, Marunouchi Kitaguchi Bldg.
+   Chiyoda-ku, Tokyo  100-0005
+   Japan
+
+   Phone: +81-3-5533-2111
+   Email: n-sakimura@nri.co.jp
+   URI:   http://nat.sakimura.org/
+
+
+   John Bradley
+   Ping Identity
+   Casilla 177, Sucursal Talagante
+   Talagante, RM
+   Chile
+
+   Phone: +44 20 8133 3718
+   Email: ve7jtb@ve7jtb.com
+   URI:   http://www.thread-safe.com/
+
+
+   Naveen Agarwal
+   Google
+   1600 Amphitheatre Parkway
+   Mountain View, CA  94043
+   United States
+
+   Phone: +1 650-253-0000
+   Email: naa@google.com
+   URI:   http://google.com/
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Sakimura, et al.             Standards Track                   [Page 20]
+