wicg/sms-one-time-codes

A way to format SMS messages for use with browser autofill features such as HTML’s autocomplete=one-time-code.

Explainer: Origin-bound one-time codes delivered via SMS

• Draft spec (eds. Theresa O'Connor from Apple and Sam Goto from Google)
• Issue tracker
• You're welcome to contribute!

Table of Contents

• Introduction
  • Deficiencies of the status quo
• Goals
  • Non-goals
• Proposal
• Benefits
• Alternative approaches
  • No special syntax (status quo)
• Stakeholder Feedback
• Acknowledgements

Introduction

Many websites make use of one-time codes for authentication.

SMS is a popular mechanism for delivering such codes to users, but using SMS to deliver one-time codes can be risky.

This proposal attempts to reduce some of the risks associated with SMS delivery of one-time codes. It does not attempt to reduce or solve all of them. For instance, it doesn't solve the SMS delivery hijacking risk, but it does attempt to reduce the phishing risk.

Deficiencies of the status quo

Suppose a user receives the message "747723 is your ExampleCo authentication code." It's possible, even likely, that 747723 is a one-time code for use on https://example.com. But because there is no standard text format for SMS delivery of one-time codes, systems which want to make programmatic use of such codes must rely on heuristics, both to locate the code in the message and to associate the code with a website. Heuristics are prone to failure and may even be hazardous.

End users shouldn't have to manually copy-and-paste one-time codes from SMSes to their browser, and codes sent by a site should only be provided to the actual site which sent it.

Goals

The goals of this proposal are to

1. eliminate the need to rely on heuristics for programmatic extraction of one-time codes from SMS messages, and to
2. reliably associate one-time codes intended for use on a specific website with that site.

Non-goals

This proposal does not set out to

1. expose the contents of arbitrary SMS messages to websites, or to
2. restrict the sources from which browsers may source one-time codes for providing them to websites.

Proposal

To address this, we propose a lightweight text format that services may use for delivering one-time codes over SMS. The format associates the code with the website's origin. We call such codes origin-bound one-time codes, and we call such messages origin-bound one-time code messages.

The message format is about as simple as it gets. Messages begin with (optional) human-readable text. The last line of the message contains the origin and the code, with the prefix characters "@" and "#" denoting which is which. Here's an example:

747723 is your ExampleCo authentication code.
    
@example.com #747723

In this example,

• "https://example.com" is the origin the code is associated with,
• "747723" is the code, and
• "747723 is your ExampleCo authentication code.\n\n" is human-readable explanatory text.

The characters "@" and "#" identify the origin and the code, respectively. (We can always introduce additional prefix characters in the future if it turns out we need to include additional information in these messages.)

Some sites use third-party iframes for authentication. In such cases, the third-party iframe's origin can be specified using the same "@" field after the code.

747723 is your ExampleCo authentication code.

@example.com #747723 @ecommerce.example

In this example,

• "https://example.com" is the origin the code is associated with,
• "747723" is the code,
• "https://ecommerce.example" is the origin of the third-party iframe, and
• "747723 is your ExampleCo authentication code.\n\n" is human-readable explanatory text.

Benefits

Adoption of this format would improve the reliability of systems which today heuristically extract one-time codes from SMS, with clear end-user benefit. It improves reliability of both extracting the code and also associating that code with an origin.

Adoption of this proposal could improve the number of services on which a browser can offer assistance with providing SMS one-time codes to websites (e.g. an AutoFill feature), and could reduce the odds users would enter one-time codes delivered over SMS on sites other than the originating one.

Alternative approaches

No special syntax (status quo)

We believe the status quo provides insufficient programmability (because it relies on heuristics) and, in particular, many typical SMS one-time code message formats in the wild lack reliable origin information.

Stakeholder Feedback

• Safari: Positive.
• Chrome: Positive.
• Firefox: Mixed signals. See mozilla/standards-positions#152 for some relevant discussion.

Acknowledgements

Many thanks to Aaron Parecki, Eric Shepherd, Eryn Wells, Jay Mulani, Paul Knight, Ricky Mondello, and Steven Soneff for their valuable feedback on this proposal.

sms-one-time-codes's Issues

Incubation status?

@samuelgoto @hober, what's the status of this incubation? Did it end up getting upstreamed to HTML or somewhere else or is the work still ongoing?

Format is inconsistent with iOS docs

https://developer.apple.com/documentation/security/one-time_codes/enabling_autofill_for_domain-bound_sms_codes says that the embedded domain is introduced with %. https://wicg.github.io/sms-one-time-codes/#format says it's introduced with @. Which is it?

Unable to use on ports other than 443

The Protocol and port number are hard-coded in the specification. Was this done on purpose?

ExampleCo staff won't / will ask for this code.

OTP codes have two common use cases:

1. Verifying the identity of a user that contacts the support team (phone / chat)
2. Verifying the identity of a user logging in / performing step-up authentication on a system

Malicious actors very commonly get in touch with an end-user under the guise of being a legitimate support team member and ask the end-user to provide the OTP code that they just sent. Appending the following text will serve as a mitigation to users falling for this attack vector:

1. "ExampleCo staff will ask for this code"
2. "ExampleCo staff will NOT ask for this code"

A mechanism for strict domain matching

I think it would be useful to allow a service that wants to send domain-bound codes to be able to opt into a stricter matching mechanism. Common examples that come to mind are hosting services or blog services that have user login on their TLD-plus-one and serve user content from subdomains. For example, Example Hosting Service has a login form on example.com and serves userA's content from userA.example.com.

Under our current matching scheme a code sent as @example.com #123456 would match example.com and userA.example.com since they're "same site" with each other. We should give these sites a way to express that they only want to match with example.com and no subdomains with a minimal amount of extra syntax. I think a natural extension of what we have so far is to use two @ signs as the field sigil. So, an SMS that reads @@example.com #123456 would match only example.com.

☂️ Migrate SMS format from other places

• Publish sms-one-time-codes explainer and spec
• Add sms-one-time-codes to WICG's biblio.json
  • Wait for this to propagate to https://github.com/tobie/specref/blob/master/refs/wicg.json
  • Wait for this to propagate to https://github.com/tabatkins/bikeshed-data biblio
  • Get one of Fantasai, Peter, or Tab to update https://github.com/tabatkins/bikeshed-data anchors
• Update WebOTP to cite sms-one-time-codes
• Drop the old explainer from webkit/explainers
• Transfer or resolve related issues filed in webkit/explainers
  • WebKit/explainers#8
  • WebKit/explainers#11
  • WebKit/explainers#25
  • WebKit/explainers#28
• Transfer or resolve related issues filed in WICG/WebOTP
  • WICG/web-otp#5
  • WICG/web-otp#15

Parsing logic may accept hosts that are invalid to use with an https origin

The current parsing algorithm accepts any character between '@' and space to be the host part of the origin.

However per URL spec host cannot contain certain characters:
"A forbidden host code point is U+0000 NULL, U+0009 TAB, U+000A LF, U+000D CR, U+0020 SPACE, U+0023 (#), U+0025 (%), U+002F (/), U+003A (:), U+003C (<), U+003E (>), U+003F (?), U+0040 (@), U+005B ([), U+005C (), U+005D (]), or U+005E (^)."

I think it makes sense to verify the captured host is valid before accepting it.

Allowing multiple whitespace between host and code

IMHO the current parsing logic is a bit too strict when handling the space between host and code:

1. It requires exactly one SPACE
2. It requires SPACE and not a more general whitespace which includes TAB as well.

I suggest we relax these two requirements.

A secondary but somewhat related concern the parsing logic in some places uses ASCII whitespace and in some place uses SPACE. I think it would be much easier to have a single concept of white space that we use in the whole parsing algorithm.

This could be either:

• ASCII whitespace: which includes U+0009 TAB, U+000A LF, U+000C FF, U+000D CR, or U+0020 SPACE. One concern is that it includes LF and CR which are not relevant given that parsing is happening on a single line.
• Custom define white space for this spec to just be: U+0020 SPACE + U+0009 TAB

use GitHub Actions to publish to gh-pages

Allow origin-bound one-time code to be on the same line as the explanatory text

Currently the origin-bound one-time code messages can optionally begin with human-readable explanatory text. When such text is in place, the origin-bound one-time code must be on a new line (last line). The benefits are obvious (easy to distinguish from explanatory text, easy to parse etc.)

Problem
We found that the newline character from SMS is not very reliable. e.g. it may get translated into whitespace by SMS carriers / aggregators due to different encoding. We have seen several partners encountering this issue with the WebOTP API and we suppose Safari may have similar observation. In addition, many partners prefer not to use newlines in their SMS due to this particular reason along with other reasons.

Proposal
We suggest dropping the newline requirement from the SMS and allow origin-bound one-time code to be on the same line as the explanatory text. Here are some examples.

Valid origin-bound one-time code message as of today

747723 is your ExampleCo authentication code.
@example.com #747723

747723 is your ExampleCo authentication code.
@example.com #747723 sent by ExampleCo

@example.com #747723   Your ExampleCo authentication code is 747723.

Proposed valid origin-bound one-time code message

747723 is your ExampleCo authentication code. @example.com #747723

747723 is your ExampleCo authentication code. @example.com #747723 sent by ExampleCo

747723 is your ExampleCo authentication code. @example.com #747723 sent by @ExampleCo

Third-party authentication / nested iframes

Lots of sites embed an iframe from a different origin that handles authentication for them. This is sometimes a third party, or maybe it's a separate service run by the same party. One obvious example is icloud.com, which uses apple.com for authentication.

Should we support such cases? If so, why, and how would the spec need to change? If not, why not?