Merge pull request #15 from ietf-wg-httpapi/early-reviews

Early reviews

Author: richsalz

CONTRIBUTING.md

@@ -15,3 +15,42 @@ repository constitutes Contributions to the IETF Standards Process
 You agree to comply with all applicable IETF policies and procedures, including,
 BCP 78, 79, the TLP, and the TLP rules regarding code components (e.g. being
 subject to a Simplified BSD License) in Contributions.
+
+
+## Working Group Information
+
+Discussion of this work occurs on the [Building Blocks for HTTP APIs
+Working Group mailing list](mailto:[email protected])
+([archive](https://mailarchive.ietf.org/arch/browse/httpapi/),
+[subscribe](https://www.ietf.org/mailman/listinfo/httpapi)).
+In addition to contributions in GitHub, you are encouraged to participate in
+discussions there.
+
+**Note**: Some working groups adopt a policy whereby substantive discussion of
+technical issues needs to occur on the mailing list.
+
+You might also like to familiarize yourself with other
+[Working Group documents](https://datatracker.ietf.org/wg/httpapi/documents/).
+
+## How to Contribute
+
+Contributions can be made by creating pull requests, opening an issue, or
+posting to the working group mailing list. See above for the email address
+and a note about policy.
+
+Here are two ways to create a pull request ("PR"):
+
+- Copy the repository and make a pull request using the Git command-line
+tool, using the [GitHub documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) if needed.
+
+- You can use the GitHub UI as follows:
+  - View the draft source
+  - Select the pencil icon to edit the file (usually top-right on the screen)
+  - Make edits
+  - Select "Commit changes"
+  - Add a title and explanatory text
+  - Select "Propose"
+  - When prompted, click on "Create Pull Request"
+
+Document authors/editors are often happy to accept contributions of text,
+and might be willing to help you through the process. Email them and ask.

LICENSE.md

@@ -1,4 +1,4 @@
 # License
 
 See the
-[guidelines for contributions](https://github.com/richsalz/draft-rsalz-httpapi-privacy/blob/main/CONTRIBUTING.md).
+[guidelines for contributions](https://github.com/ietf-wg-httpapi/httpapi-privacy/blob/main/CONTRIBUTING.md).

README.md

@@ -4,20 +4,19 @@
 
 This is the working area for the IETF [HTTPAPI Working Group](https://datatracker.ietf.org/group/httpapi/documents/) Internet-Draft, "API Keys and Privacy".
 
-* [Editor's Copy](https://richsalz.github.io/draft-rsalz-httpapi-privacy/#go.draft-ietf-httpapi-privacy.html)
+* [Editor's Copy](https://ietf-wg-httpapi.github.io/httpapi-privacy/#go.draft-ietf-httpapi-privacy.html)
 * [Datatracker Page](https://datatracker.ietf.org/doc/draft-ietf-httpapi-privacy)
 * [Working Group Draft](https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-privacy)
-* [Compare Editor's Copy to Working Group Draft](https://richsalz.github.io/draft-rsalz-httpapi-privacy/#go.draft-ietf-httpapi-privacy.diff)
+* [Compare Editor's Copy to Working Group Draft](https://ietf-wg-httpapi.github.io/httpapi-privacy/#go.draft-ietf-httpapi-privacy.diff)
 
 
 ## Contributing
 
 See the
-[guidelines for contributions](https://github.com/richsalz/draft-rsalz-httpapi-privacy/blob/main/CONTRIBUTING.md).
-
-Contributions can be made by creating pull requests.
-The GitHub interface supports creating pull requests using the Edit (✏) button.
+[guidelines for contributions](https://github.com/ietf-wg-httpapi/httpapi-privacy/blob/main/CONTRIBUTING.md).
 
+The contributing file also has tips on how to make contributions, if you
+don't already know how to do that.
 
 ## Command Line Usage
 

draft-ietf-httpapi-privacy.md

@@ -48,7 +48,8 @@ informative:
 --- abstract
 
 Redirecting HTTP requests to HTTPS, a common pattern for human-facing web
-resources, can be an anti-pattern for authenticated API traffic. This document
+resources, can be an anti-pattern for authenticated HTTP API traffic.
+This document
 discusses the pitfalls and makes deployment recommendations for authenticated
 HTTP APIs. It does not specify a protocol.
 
@@ -71,7 +72,8 @@ intermediary implementations have a prominently displayed option to enable it
 automatically.
 
 When client authentication is used, more care must be taken. The client's
-initial request may include a Bearer token or other credential; once the request
+initial request may include a Bearer token or other credential (such as
+a Cookie); once the request
 has been sent on the network, any passive attacker who can see the traffic can
 acquire this credential and use it.
 
@@ -85,6 +87,13 @@ This document describes actions API servers and clients should take in order to
 safeguard credentials. These recommendations are not directed at resources where
 no authentication is used.
 
+Some have wondered if this document is really necessary. After all, we have
+been telling people not to send passwords and such in the clear for decades.
+Regrettably, this lesson seems to be largely forgotten by those developing
+Web-based APIs.  The blog post that motivated this document, {{BLOG}}, did a
+spot-check in May, 2024, and found over two dozen websites that were
+vulnerable to the issues listed here.
+
 
 ## Conventions and Definitions
 
@@ -110,7 +119,8 @@ new server, while HSTS requires a successful prior connection to the server and
 relies on the client to implement persistent storage of the HSTS directive.
 
 Used together, however, both approaches make clients less likely to send any
-requests over an insecure channel. Servers with authenticated endpoints SHOULD
+requests over an insecure channel.
+HTTP API servers with authenticated endpoints SHOULD
 employ both mechanisms.
 
 ## Connection Blocking
@@ -120,15 +130,17 @@ the developer or user is less likely to notice the misconfiguration. Where
 possible, it is advantageous for such a misconfiguration to fail immediately so
 that the error can be noticed and corrected.
 
-Servers MAY induce such an early failure by not accepting unencrypted
+HTTP API servers MAY induce such an early failure by not accepting unencrypted
 connections, e.g. on port 80. This makes it impossible for a client to send a
 credential over an insecure channel to the authentic server, as no such channel
-can be opened. Servers MAY alternatively restrict connections on port 80 to
+can be opened.
+HTTP API servers MAY alternatively restrict connections on port 80 to
 network sources which are more trusted, such as a VPN or virtual network
 interface.
 
 However, this mitigation is limited against active network attackers, who can
-impersonate the server and accept the client's insecure connection attempt.
+impersonate the HTTP API server and accept the client's insecure
+connection attempt.
 
 ## Credential Restriction
 
@@ -142,28 +154,32 @@ to indicate the expected usage to the client.
 
 Some deployments may not find it feasible to completely block unencrypted
 connections, whether because the hostname is shared with unauthenticated
-endpoints or for infrastructure reasons. Therefore, servers need a response for
+endpoints or for infrastructure reasons. Therefore, HTTP API servers need
+a response for
 when a credential has been received over an insecure channel.
 
 HTTP status code 403 (Forbidden) indicates that "the server understood the
-request but refuses to fulfill it" {!HTTP=RFC9110}. While this is generally
-understood to mean that "the server considers [the credentials] insufficient to
+request but refuses to fulfill it" {{!HTTP=RFC9110}}. While this is generally
+understood to mean that "the server considers \[the credentials] insufficient to
 grant access," it also states that "a request might be forbidden for reasons
-unrelated to the credentials." Servers SHOULD return status code 403 to all
+unrelated to the credentials." HTTP API servers SHOULD return status
+code 403 to all
 requests received over an insecure channel, regardless of the validity of the
 presented credentials.
 
 Because a difference in behavior would enable attackers to guess and check
-possible credentials, a server MUST NOT return a different client response
+possible credentials, an HTTP API server MUST NOT return a different client
+response
 between a valid or invalid credential presented over an insecure connection.
 Differences in behavior MUST only be visible on subsequent use of the credential
 over a secure channel.
 
 ### Credential Revocation
 
 When a request is received over an unencrypted channel, the presented credential
-is potentially compromised. Servers SHOULD revoke such credentials immediately.
-When the credential is next used over a secure channel, a server MAY return an
+is potentially compromised. HTTP API servers SHOULD revoke such
+credentials immediately.
+When the credential is next used over a secure channel, the server MAY return an
 error that indicates why the credential was revoked.
 
 Credentials in a request can take on different forms. API keys and tokens are simple
@@ -182,7 +198,8 @@ recommendations above.
 ## Implement Relevant Protocols
 
 Clients SHOULD support and query for HTTPS records {{!RFC9460}} when
-establishing a connection. This gives servers an opportunity to provide more
+establishing a connection. This gives HTTP API servers an opportunity
+to provide more
 complete information about capabilities, some of which are security-relevant.
 
 Clients SHOULD respect HSTS headers {{!RFC6797}} received
@@ -212,7 +229,7 @@ This entire document is about security of HTTP API interactions.
 The behavior recommended in {{credential-revocation}} creates the potential for
 a denial of service attack where an attacker guesses many possible credentials
 over an unencrypted connection in hopes of discovering and revoking a valid one.
-Servers implementing this mitigation MUST also guard against such attacks, such
+HTTP API servers implementing this mitigation MUST also guard against such attacks, such
 as by limiting the number of requests before closing the connection and
 rate-limiting the establishment of insecure connections.