HTTP Status Code

[MikeBishop]

Discussion in Notes indicates that 403, while unintuitive, appears to be the closest HTTP status code for "I won't serve this over an unencrypted channel." For reference:

• 403 (Forbidden): "the server understood the request but refuses to fulfill it"
  • "server considers [the credentials] insufficient to grant access."
  • "However, a request might be forbidden for reasons unrelated to the credentials."
• 421 (Misdirected Request): "the request was directed at a server that is unable or unwilling to produce an authoritative response for the target URI"
  • "a target URI that does not match an origin for which the server has been configured or does not match the connection context over which the request was received."
  • More appropriate for receiving an "https://" URI over a non-TLS connection
• 426 (Upgrade Required): "server refuses to perform the request using the current protocol but might be willing to do so after the client upgrades to a different protocol."
  • However, "server MUST send an Upgrade header field in a 426 response to indicate the required protocol(s)" is probably a non-starter unless the server implements RFC2817, which is fairly niche

Should we recommend one of these, mint a new status code, or stay silent on the topic?

[MikeBishop]

(Note that a new status code would probably not be informational, and might belong in a separate draft.)

[richsalz]

I think we should use 403 and not define a new status code. One reason is we want this to be adopted quickly.

[jviide]

I think 403 is a good option. Its defined semantics can be understood to include the "I won't serve HTTP" scenario. 426 would have been my favorite if not for RFC 9110 stating:

the server MUST send an Upgrade header field

and

The Upgrade header field only applies to switching protocols on top of the existing connection; it cannot be used to switch the underlying connection (transport) protocol, nor to switch the existing communication to a different connection.

[jviide]

A side note: I don't know if this is an appropriate for this specific document, but how about to explicitly recommending attaching an informational error message along with the 403/426/421/... error? Pre-existing status codes may to have multiple meanings, so a developer accidentally using HTTP instead of HTTPS might confuse the response to mean that the credentials are wrong. As an example, Stripe returns status code 403 with the following response payload that nudges the developer towards a correct solution:

{
  "error": {
    "message" : "The Stripe API is only accessible over HTTPS.  Please see <https://stripe.com/docs> for more information.",
    "type": "invalid_request_error"
  }
}

Anthropic also recommends revoking the API key manually (with status 400), which is one approach for cases where auto-revocation is not a viable option:

{
  "error": {
    "type": "invalid_request_error",
    "message": "This request was sent over HTTP. Only HTTPS is supported for API use. Consider revoking your API key, as it was sent in plaintext over the internet with this request."
  }
}

Of course different services format their errors differently, so it might be hard to suggest something overly specific.

[richsalz]

I think having a SHOULD about detailed error response, and a sample or two is a great idea!

[MikeBishop]

So long as the 400 please-revoke path gets sent regardless of the credential. Otherwise, that offers an explicit unencrypted signal that a valid credential was used. I'd prefer to keep the current advice that the response should not vary based on whether the credential used was valid or not.

[jviide]

I agree. The same message should be sent whether the credentials are valid or not.

Maybe there could be an explicit recommendation to not check credential validity at all on the plaintext HTTP side of the API. That could also help avoid timing differences in addition to accidental message differences and such between valid and non-valid credentials.

[Acconut]

I agree with the points that were already brought up. 403 is a good choice, unless there is a use for a generic client/intermediary to detect such error responses. But I don't think there is a need for this.

The response should include a descriptive message in the body, but the server must not validate or further inspect the provided credentials.