doc: Add RFC documents

1 files changed, 220 insertions, 0 deletions

diff --git a/doc/rfc/rfc8959.txt b/doc/rfc/rfc8959.txt
new file mode 100644
index 0000000..de45718
--- /dev/null
+++ b/doc/rfc/rfc8959.txt
@@ -0,0 +1,220 @@
+
+
+
+
+Internet Engineering Task Force (IETF)                     M. Nottingham
+Request for Comments: 8959                                  January 2021
+Category: Informational                                                 
+ISSN: 2070-1721
+
+
+                     The "secret-token" URI Scheme
+
+Abstract
+
+   This document registers the "secret-token" URI scheme to aid in the
+   identification of authentication tokens.
+
+Status of This Memo
+
+   This document is not an Internet Standards Track specification; it is
+   published for informational purposes.
+
+   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).  Not all documents
+   approved by the IESG are candidates for any level of Internet
+   Standard; see Section 2 of RFC 7841.
+
+   Information about the current status of this document, any errata,
+   and how to provide feedback on it may be obtained at
+   https://www.rfc-editor.org/info/rfc8959.
+
+Copyright Notice
+
+   Copyright (c) 2021 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
+   (https://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.
+
+Table of Contents
+
+   1.  Introduction
+     1.1.  Notational Conventions
+   2.  The "secret-token" URI Scheme
+   3.  IANA Considerations
+   4.  Security Considerations
+   5.  References
+     5.1.  Normative References
+     5.2.  Informative References
+   Acknowledgements
+   Author's Address
+
+1.  Introduction
+
+   It has become increasingly common to use bearer tokens as an
+   authentication mechanism in various protocols.
+
+   A bearer token is a security token with the property that any party
+   in possession of the token (a "bearer") can use the token in any way
+   that any other party in possession of it can.  Using a bearer token
+   does not require a bearer to prove possession of cryptographic key
+   material (proof-of-possession).
+
+   Unfortunately, the number of security incidents involving accidental
+   disclosure of these tokens has also increased.  For example, we now
+   regularly hear about a developer committing an access token to a
+   public source code repository, either because they didn't realize it
+   was included in the committed code or because they didn't realize the
+   implications of its disclosure.
+
+   This specification registers the "secret-token" URI scheme to aid
+   prevention of such accidental disclosures.  When tokens are easier to
+   unambiguously identify, they can trigger warnings in continuous
+   integration systems or be used in source code repositories
+   themselves.  They can also be scanned for separately.
+
+   For example, if cloud.example.net issues access tokens to its clients
+   for later use, and it does so by formatting them as "secret-token"
+   URIs, tokens that "leak" into places that they don't belong are
+   easier to identify.  This could be through a variety of mechanisms;
+   for example, if repo.example.com can be configured to refuse commits
+   containing "secret-token" URIs, it helps its customers avoid
+   accidental disclosures.
+
+   "secret-token" URIs are intended to aid in identification of
+   generated secrets, like API keys and similar tokens.  They are not
+   intended for use in controlled situations where ephemeral tokens are
+   used, such as things like Cross-Site Request Forgery (CSRF) tokens.
+
+1.1.  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
+   BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
+   capitals, as shown here.
+
+   This document uses ABNF [RFC5234].  It also uses the pchar rule from
+   [RFC3986].
+
+2.  The "secret-token" URI Scheme
+
+   The "secret-token" URI scheme identifies a token that is intended to
+   be a secret.
+
+   secret-token-URI    = secret-token-scheme ":" token
+   secret-token-scheme = "secret-token"
+   token               = 1*pchar
+
+   See [RFC3986], Section 3.3 for a definition of pchar.  Disallowed
+   characters -- including non-ASCII characters -- MUST be encoded into
+   UTF-8 [RFC3629] and then percent-encoded ([RFC3986], Section 2.1).
+
+   When a token is both generated and presented for authentication, the
+   entire URI MUST be used, without changes.
+
+   For example, given the URI:
+
+   secret-token:E92FB7EB-D882-47A4-A265-A0B6135DC842%20foo
+
+   This (character-for-character, case-sensitive) string will both be
+   issued by the token authority and required for later access.
+   Therefore, if the example above were used as a bearer token in
+   [RFC6750], a client might send:
+
+   GET /authenticated/stuff HTTP/1.1
+   Host: www.example.com
+   Authorization: Bearer
+     secret-token:E92FB7EB-D882-47A4-A265-A0B6135DC842%20foo
+
+3.  IANA Considerations
+
+   This document registers the following value in the "Uniform Resource
+   Identifier (URI) Schemes" registry:
+
+   Scheme name:  secret-token
+   Status:  provisional
+   Applications/protocols that use this scheme:  none yet
+   Contact:  iesg@iesg.org
+   Change Controller:  IESG
+   References:  RFC 8959
+
+4.  Security Considerations
+
+   The token ABNF rule allows tokens as small as one character.  This is
+   not recommended practice; applications should evaluate their
+   requirements for entropy and issue tokens correspondingly.  See
+   [RFC4086] for more information.
+
+   This URI scheme is intended to reduce the incidence of accidental
+   disclosure; it cannot prevent intentional disclosure.
+
+   If it is difficult to correctly handle secret material, or unclear as
+   to what the appropriate handling is, users might choose to obfuscate
+   their secret tokens in order to evade detection (for example,
+   removing the URI scheme for storage).  Mitigating this risk is often
+   beyond the reach of the system using the "secret-token" URI; users
+   can be cautioned against such practices and be provided tools to
+   help.
+
+5.  References
+
+5.1.  Normative References
+
+   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
+              Requirement Levels", BCP 14, RFC 2119,
+              DOI 10.17487/RFC2119, March 1997,
+              <https://www.rfc-editor.org/info/rfc2119>.
+
+   [RFC3629]  Yergeau, F., "UTF-8, a transformation format of ISO
+              10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
+              2003, <https://www.rfc-editor.org/info/rfc3629>.
+
+   [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,
+              <https://www.rfc-editor.org/info/rfc3986>.
+
+   [RFC5234]  Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
+              Specifications: ABNF", STD 68, RFC 5234,
+              DOI 10.17487/RFC5234, January 2008,
+              <https://www.rfc-editor.org/info/rfc5234>.
+
+   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
+              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
+              May 2017, <https://www.rfc-editor.org/info/rfc8174>.
+
+5.2.  Informative References
+
+   [RFC4086]  Eastlake 3rd, D., Schiller, J., and S. Crocker,
+              "Randomness Requirements for Security", BCP 106, RFC 4086,
+              DOI 10.17487/RFC4086, June 2005,
+              <https://www.rfc-editor.org/info/rfc4086>.
+
+   [RFC6750]  Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
+              Framework: Bearer Token Usage", RFC 6750,
+              DOI 10.17487/RFC6750, October 2012,
+              <https://www.rfc-editor.org/info/rfc6750>.
+
+Acknowledgements
+
+   The definition of bearer tokens is from [RFC6750].
+
+Author's Address
+
+   Mark Nottingham
+   Prahran VIC
+   Australia
+
+   Email: mnot@mnot.net
+   URI:   https://www.mnot.net/