Protecting Credentials with HTTP APIs
draft-ietf-httpapi-privacy-06

Many thanks to Barry Lieba for the ARTART review.
Thanks to the authors and working group for this document.

Thanks to Barry Leiba for the ARTART review.

I found the document to be very clear and to provide helpful guidance. There is; however, one sentence that was challenging for me to understand because I was not parsing it as I believe the authors intended. 

- Section 3.3: When authentication is used, clients SHOULD require an explicit indication from the user or caller that an insecure context is expected which is distinct from the provided URI.

I did not understand what was meant by "an insecure context is expected which is distinct from the provided URI."

Thanks to the helpful shepherd writeup from Darrel Miller, I became aware of the following GitHub issue and resolution.

- "Client HTTPS requirements (GitHub Issue #7, September 2024-June 2025):
- Martin Thomson proposed that clients MUST use HTTPS exclusively, eliminating the need for HSTS and upgrade mechanisms. After discussion, the working group adopted a compromise requiring clients to implement and use HTTPS exclusively "absent a deliberate indication that an insecure context is deliberate." This balances security with practical testing scenarios while making the default secure.

I believe the following rewording aligns with the original intent, and it certainly helps me understand what is meant.

- Section 3.3: When authentication is used, clients SHOULD require an explicit indication, which is distinct from the provided URI, from the user or caller that an insecure context is expected.

Thanks to all the reviewers (Christian, Roni, Barry, Mark); the draft is well written and gives (more?) guidance on an important topic.

I think the other ADs and reviewers have covered any comments that I would provide at this point.

Thanks to Christian Huitema for their secdir review. 

I do appreciate the goal of this BCP, and I hope my suggestions might help convey the information more clearly.  My comments are not blocking, and my goal is to make the specification more easily understood.

General:  I do agree with Christian that this draft 'buries the lede' (https://www.merriam-webster.com/wordplay/bury-the-lede-versus-lead). If the goal of the BCP is to inform the community about the risks and vulnerabilities of credential exposure via unprotected web resources, then it should be stated plainly and directly.    

Abstract, sentence 1:  I'm not sure I understand what this means.  Is it the goal to redirect an HTTP request to an HTTPS port/server?  It does not read that way.  Terms like 'anti-pattern' are not used enough for clear understanding.  

Introduction:  Clearly para 3 and 4 get to the heart of the discussion.  I recommend moving that up to the start of the Introduction.

Section 2.1, sentence 1:  I had to read this sentence 4-5 times to understand the point.  How about, 'To inform clients that unencrypted requests to a server are never appropriate, there are various mechanisms available.'  (vice the current sentence which makes it look like the 'various mechanisms' are 'never appropriate')

Section 4, sentence 1:  I'm sure it is clear to nearly everyone what this means, but I might suggest a reword to something like, 'This entire document is about how to keep user credentials secure by controlling HTTP API interactions.'  (I'm sure you can do better than my suggestion)

Thanks for the work done in this short and sweet document. Just one comment: who is the "we" in `After all, we have been telling people not to send passwords` ? The authors ? The WG ? The IETF ? Please avoid any ambiguities.

Thank you for the clean and brief write-up.

When going through the text i found it amusing that the page "Your API Shouldn't Redirect HTTP to HTTPS" (https://jviide.iki.fi/http-redirects) is actually redirected to https when one tries to access the content using legacy request to "http://jviide.iki.fi/http-redirects" 

Thanks for documenting this BCP

Thanks to the authors and the WG for their work on this document.

Please find below some comments/suggestions to help improve the document.

1) I feel that the phrase "can be an anti-pattern for authenticated HTTP API traffic" might not be clear enough to (some or many?) readers. Perhaps a bit more prose or explanation would be helpful. Essentially what is being said is that following the same pattern for APIs (as is done for browsers) is not the best idea, even if it seems so on the first look, and has pitfalls and issues such as inadvertent disclosure of secure credentials ... < please rephrase in a more appropriate manner >

2) The title includes "Privacy", but since this is about credentials, should it also not include Security in the title?

3) There are duplicate references to RFC9110 - once as "HTTP" and then again as "RFC9110"

Thanks to the authors for addressing my DISCUSS. However, I am leaving my comments in place as not all of them seem to have been addressed.

Section 1, paragraph 4
>    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.

The HTTPDIR reviewer (thanks, Mark Nottingham) raised this concern, 
and it does not appear to have been addressed in -04. 
RFC 7258 establishes an IETF-wide consensus that passive monitoring 
is an attack, and that all protocols should provide appropriate 
confidentiality, regardless of whether authentication is present. 
The current framing implicitly suggests that unencrypted HTTP is 
acceptable for unauthenticated API traffic, which sits in tension 
with RFC 7278's mandate.

A single added sentence acknowledging RFC 7258's broader scope — 
while making clear that this document's specific recommendations 
target authenticated APIs — would close the gap. For example: 
"Although this document focuses on authenticated API endpoints,
operators should be aware that RFC 7258 establishes broader 
reasons to use HTTPS regardless of whether credentials are transmitted."

Section 2.4, paragraph 1
>    HTTP status code 403 (Forbidden) indicates that "the server
>    understood the request but refuses to fulfill it" [HTTP].  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."
>    HTTP API servers SHOULD return status code 403 to all requests
>    received over an insecure channel, regardless of the validity of the
>    presented credentials.

The document says servers SHOULD return 403 to *all* requests received 
over an insecure channel, "regardless of the validity of the presented 
credentials." But what about a request with no credentials at all 
arriving over HTTP? Returning 403 to such a request discloses:

(a) the resource exists, and
(b) authentication is required.

An attacker scanning for credential-bearing endpoints could use this 
to enumerate the API surface area. The alternative (e.g., closing the 
connection without a response, or returning 400) might be preferable 
for requests with no credentials. This is worth a sentence clarifying 
the intended behavior.

Section 2.4.1, paragraph 0
>    When a request is received over an unencrypted channel, the presented
>    credential 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.

This paragraph recommends that servers SHOULD immediately revoke credentials 
received over an insecure channel. Section 4 correctly identifies a DoS risk: 
an attacker could deliberately present guessed credentials over HTTP to 
trigger revocation of valid ones. The recommended mitigation is connection 
rate-limiting, as the authors have already noted.

However, the document does not address the mirror problem: a legitimate but 
misconfigured API client that routinely sends credentials over HTTP (e.g., 
because of a deployment error) would have its credentials repeatedly revoked, 
disrupting service before the operator even notices the misconfiguration. 
This is particularly relevant given the document's stated motivation — 
that such misconfigurations are common and often go unnoticed.

A note acknowledging this trade-off (and suggesting, e.g., a notification 
mechanism or grace period rather than immediate revocation in such cases) 
would make the guidance more operationally realistic.

Section 3.2, paragraph 1
>    Clients MUST NOT send any header field that contains a secret token
>    over an insecure channel.  Such header fields include Authorization
>    and Proxy-Authorization and are described in Sections 11.6.2 and
>    11.7.2 of [RFC9110], respectively.

RFC9110 appears twice in the Normative References section under two
different labels. [HTTP] and [RFC9110]. Can this be reduced to one
reference, preferably [RFC9110], to be consistent with all other
references that use [RFCXXXX] instead of names?

Section 3.3, paragraph 0
>    When authentication is used, clients SHOULD require an explicit
>    indication from the user or caller that an insecure context is
>    expected which is distinct from the provided URI.  Depending on the
>    interface, this might be a UI preference or an API flag.

The phrase "distinct from the provided URI" is opaque. Reading it 
with the examples ("a UI preference or an API flag"), the apparent 
intent is that the indication of an allowed insecure context must 
not be derived solely from the scheme of the URI 
(i.e., using http:// is not itself a sufficient indication — 
something separate must also be set). If so, that should be stated 
directly. As written, a reader might interpret "distinct from the URI" 
as something else entirely. How about saying - "which is distinct
from the provided URI, e.g., an UI preference or an API flag."?

Found terminology that should be reviewed for inclusivity; see
https://www.rfc-editor.org/part2/#inclusive_language for background and more
guidance:

 * Term "his"; alternatives might be "they", "them", "their"

-------------------------------------------------------------------------------
NIT
-------------------------------------------------------------------------------

All comments below are about very minor potential issues that you may choose to
address in some way - or ignore - as you see fit. Some were flagged by
automated tools (via https://github.com/larseggert/ietf-reviewtool), so there
will likely be some false positives. There is no need to let me know what you
did with these suggestions.

"RFC9110", paragraph 1
> 1 creates the potential for a denial of service attack where an attacker gues
>                               ^^^^^^^^^^^^^^^^^
It appears that hyphens are missing.

Thank you to Ron Evens for the GENART review.

** idnits:
  -- Duplicate reference: RFC9110, mentioned in 'RFC9110', was also mentioned
     in 'HTTP'.

** Section 1.
   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. 

-- Consider less colloquial language.  

-- Who are these “people”? Who is the “we” and where have “we” been “telling people”?

** Section 1.  Editorial.
   Regrettably, this lesson seems to be largely
   forgotten by those developing Web-based APIs.

Respectfully, this seems like a broad generalization, [BLOG] reference aside.  Is this text is needed to motivate the work?

** Editorial.  Consider if these idioms are approachable.
-- Abstract, “This document discusses the pitfalls …”
-- Section 2.1, “Neither mechanism is foolproof.”

** Other Editorial.  Other ADs have already mentioned that this document doesn’t seem strongly related to privacy despite it being in the title.

I have no commentary not already provided, and otherwise support publication of this document.