Origin-bound one-time codes delivered via SMS

Draft Community Group Report,

This version:
https://wicg.github.io/sms-one-time-codes/
Issue Tracking:
GitHub
Editors:
(Apple)
(Google)

Abstract

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

Status of this document

This specification was published by the Web Platform Incubator Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

Introduction

This section is non-normative.

Many websites deliver one-time codes over SMS. [GSM-SMS]

Without a standard format for such messages, programmatic extraction of codes from them has to rely on heuristics, which are often unreliable and error-prone. Additionally, without a mechanism for associating such codes with specific websites, users might be tricked into providing the code to malicious sites.

This specification defines a format for the delivery of one-time codes over SMS. This format associates the one-time code with a specific origin.

1. Infrastructure

This specification depends on the Infra Standard. [INFRA]

2. Origin-bound one-time codes

An origin-bound one-time code is a tuple consisting of an origin and a code (a string).

(("https", "example.com", null, null), "747723") is an origin-bound one-time code whose origin is ("https", "example.com", null, null) and whose code is "747723".

2.1. Usage

Many User Agents help users fill out forms on websites. Sites can use features like autocomplete=one-time-code to hint to User Agents that they could assist the user with providing a one-time code to the website. [HTML]

In this section, an active origin is an origin of a top-level browsing context's active document.

When a User Agent is in possession of an origin-bound one-time code and an active origin is same origin with the origin-bound one-time code's origin, the User Agent may assist the user with providing the origin-bound one-time code's code to the website.

When a User Agent is in possession of an origin-bound one-time code and an active origin is same site but not same origin with the origin-bound one-time code's origin, the User Agent may assist the user with providing the origin-bound one-time code's code to the website, and should indicate the origin-bound one-time code's origin to the user.

When a User Agent is in possession of an origin-bound one-time code and an active origin is neither same site nor same origin with the origin-bound one-time code's origin, the User Agent should not assist the user with providing the origin-bound one-time code's code to the website.

Note: because the scheme of an origin-bound one-time code's origin is always "https", assisting the user with providing origin-bound one-time codes is only available in secure contexts.

This specification does not impose any requirements or restrictions on the use of one-time codes which are not origin-bound one-time codes.

3. Message format

An origin-bound one-time code message is a string for which parsing an origin-bound one-time code message successfully returns an origin-bound one-time code.

3.1. Authoring

This section is non-normative. § 3.2 Parsing is the normative text.

Origin-bound one-time code messages can optionally begin with human-readable explanatory text. This consists of all but the last line of the message. The last line of the message contains both a host and a code, each prefixed with a sigil: U+0040 (@) before the host, and U+0023 (#) before the code.

In the following origin-bound one-time code message, the host is "example.com", the code is "747723", and the explanatory text is "747723 is your ExampleCo authentication code.\n\n".

"747723 is your ExampleCo authentication code.

@example.com #747723"

The last line has to begin with U+0040 (@). (Which is to say, the host always comes before the code in the message.)

The message "something @example.com #747723" is not an origin-bound one-time code message, because its last line does not begin with U+0040 (@).

The message "#747723 @example.com" is not an origin-bound one-time code message, because its last line does not begin with U+0040 (@).

Exactly one U+0020 (SPACE) separates the two values in the last line of the message.

The message "@example.com code #747723" is not an origin-bound one-time code message, because several characters appear between the two values on the last line of the message.

Trailing text in the last line is ignored. This is because we might identify additional information to include in origin-bound one-time code messages in the future. If we do, new syntax could be introduced after the existing syntax in the last line.

In the origin-bound one-time code message "@example.com #747723 %future", the host is "example.com", the code is "747723", and the explanatory text is "". The trailing text " %future" is ignored.

3.2. Parsing

To parse an origin-bound one-time code message from message, run these steps:

  1. Let line be the last line of message, and position be 0.

  2. If the code point at position within line is not U+0040 (@), return failure.

  3. Advance position by 1.

  4. Let host be the result of collecting a sequence of code points which are not ASCII whitespace from line with position.

  5. If host is the empty string, return failure.

  6. If host is not a valid domain string or a valid IPv4-address string or a valid IPv6-address string, return failure.

  7. If the code point at position within line is not U+0020 (SPACE), return failure.

  8. Advance position by 1.

  9. If the code point at position within line is not U+0023 (#), return failure.

  10. Advance position by 1.

  11. Let code be the result of collecting a sequence of code points which are not ASCII whitespace from line with position.

  12. If code is the empty string, return failure.

  13. Return the origin-bound one-time code (("https", host, null, null), code).

The last line of string is the result of running these steps:

  1. Normalize newlines in string.

  2. Let lines be the result of strictly splitting string on U+000A (LF).

  3. Return the last item of lines.

4. Security considerations

This specification attempts to mitigate the phishing risk associated with the delivery of one-time codes over SMS by enabling User Agents to know what website the one-time code is intended for.

This specification does not attempt to mitigate other risks associated with the delivery of one-time codes over SMS, such as SMS spoofing, SIM swapping, SIM cloning, ISMI-catchers, or interception of the message by an untrusted party.

Sites would do well to consider using non-SMS technologies such as [WEBAUTHN] for authentication or verification.

5. Privacy considerations

Any party which has access to a user’s SMS messages (such as the user’s cellular carrier, mobile operating system, or anyone who intercepted the message) can learn that the user has an account on the service identified in an origin-bound one-time code message delivered over SMS.

On some platforms, User Agents might need access to all incoming SMS messages—even messages which are not origin-bound one-time code messages—in order to support the autofilling of origin-bound one-time codes delivered over SMS in origin-bound one-time code messages.

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.

Conformance

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[INFRA]
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[URL]
Anne van Kesteren. URL Standard. Living Standard. URL: https://url.spec.whatwg.org/

Informative References

[GSM-SMS]
Richard Burbidge. Technical realization of the Short Message Service (SMS). URL: http://www.3gpp.org/ftp/Specs/html-info/23040.htm
[SECURE-CONTEXTS]
Mike West. Secure Contexts. 15 September 2016. CR. URL: https://www.w3.org/TR/secure-contexts/
[WEBAUTHN]
Dirk Balfanz; et al. Web Authentication:An API for accessing Public Key Credentials Level 1. 4 March 2019. REC. URL: https://www.w3.org/TR/webauthn-1/