77 |
78 | To support this user flow, we propose two complementary API components:
79 |
80 | * a client-side [javascript API](#imperative-api)
81 | * a [formating convention](#formatting) for SMS messages
82 |
83 | The former gives web pages a mechanism to receive SMSes and the latter is used as a mechanism to make sure that the origin boundaries are kept without additional mediation / gesture from the user.
84 |
85 | ## API Alternatives Considered
86 |
87 | There are two big formulations for this API that are more or less isomorphic to what's found on Android and iOS (see [prior art](#prior-art)).
88 |
89 | As we evaluate these, it is critical that we agree on a consistent criteria to measure them. From a high level perspective, we used the following ordering of constituents:
90 |
91 | 1. **users** first
92 | 2. **developers** second
93 | 3. **browser** engineers third
94 | 4. technical **purity** last
95 |
96 | With users as our highest order constituent, here are some of the criteria we used to evaluate [alternatives](#alternatives-considered):
97 |
98 | - privacy: to what extent does it secure the user's data?
99 | - efficiency: does it increase conversion rates? decrease number of taps?
100 | - complexity: does it introduce new / unnecessary concepts?
101 | - efficacy: does it cover all corner cases?
102 |
103 | With that, before we go any further, the following are some of the UX alternatives we considered.
104 |
105 | It is unclear if these formulations are necessarily mutually exclusive, but our intuition at the moment is that some of them are not.
106 |
107 | Before we get into API design, from a UX perspective, our initial intuition was that, under the right circumstances (e.g. the PWA is installed), the following UX formulation would lead to the highest levels of conversion rates:
108 |
109 | 
110 |
111 | Having said that, here are other alternatives we considered.
112 |
113 | ### Alternatives Considered
114 |
115 | There are many different UX formulations that are under consideration, with different trade-offs between user awareness, control and friction. Here are the ones worth exploring further:
116 |
117 | ##### Automatic UX
118 |
119 | The automatic UX formulation ports the user experience you'd find on Android to the Web.
120 |
121 | In this formulation, all of the UX is delegated to the developer: status indicators, intent of the flow, etc. Whenever a browser implementation may find appropriate (e.g. when the PWA is installed, possibly), a browser may chose to share the SMS directly with the developer without any user consent.
122 |
123 | Some positives here:
124 |
125 | * no user friction / taps necessary
126 | * no concept of OTP introduced
127 |
128 | And the biggest challenge being:
129 |
130 | * does it sufficiently protect the user's privacy?
131 |
132 | 
139 |
140 | ##### Unblocking UX
141 |
142 | On occasions where the user agent believes it is necessary to mediate / regulate (e.g. there isn't enough signals of trust established between the user and the origin) and get user consent before sharing the SMS, something like an InfoBar could be used:
143 |
144 | 
151 |
152 | ##### Autofill UX
153 |
154 | At the end of the spectrum, the most regulated / mediated UX is the autofill UX, which makes sure that the intent to share is well established by making a suggestion with a keyboard accessory:
155 |
156 | 
157 |
158 | Now that we established some **users** first UX formulations, lets look into our second constituents, **developers**.
159 |
160 | ### Declarative API
161 |
162 | The easiest starting point to enable this API is a declarative autocomplete field:
163 |
164 | ```html
165 |
166 | ```
167 |
168 | This has well established distribution and an existing implementation by Safari. It is ergonomically simple (easy to adopt) and effective (reuses the privacy properties of autofill suggestions).
169 |
170 | While this doesn't seem at first **mutually exclusive** (and may be, in effect, collectively constructive), to close the gap with the [tap-less android user experience](#prior-art), the declarative API ties ourselves to:
171 |
172 | * form elements
173 | * the autofill permission model
174 |
175 | So, working backwards from where we believe we want to be, the declarative autofill API wouldn't allow us to fully close the gap with the kind of experience that you'd find on [native apps](#automatic-ux).
176 |
177 | ### Imperative API
178 |
179 | In this formulation, browsers provide an imperative API to request the contents of an incoming SMS. Here is one possible formulation / shape, based on Android’s [SMS Retriever API](https://developers.google.com/identity/sms-retriever/overview):
180 |
181 | ```javascript
182 | if (window.OTPCredential) {
183 | alert("feature not available :(");
184 | return;
185 | }
186 | try {
187 | let {code} = await navigator.credentials.get({otp: {transport: ["sms"]});
188 | alert("otp received! " + code);
189 | } catch (e) {
190 | alert("timed out!");
191 | }
192 | ```
193 |
194 | There are a couple of nice side effects of the imperative API.
195 |
196 | First, it can offer browser engines a spectrum of mediation / consent / permissions / interventions without any re-activation of the ecosystem (e.g. a [permission-less UX](#automatic-ux), a [non-blocking UX](#unblocking-ux) and an [autofill UX](#autofill-ux))
197 |
198 | Second, it can derive the [declarative API](#Declarative-API) (the opposite isn't true). An interesting implication of uncovering the lower level imperative API is that it can derive the high level declarative API without any loss of (a) browser mediation and (b) graceful degradation.
199 |
200 | Here is an example of a custom element that can be embedded in pages to polyfill existing deployments of the declarative autofill API:
201 |
202 | ```javascript
203 | /**
204 | * one-time-code is a custom element that extends elements
205 | * with an autocomplete="one-time-code" with the imperative
206 | * navigator.credentials.get({otp: {transport: ["sms"]}) API.
207 | * Submits the form when it receives the SMS.
208 | *
209 | * Example:
210 | *
211 | *
215 | *
216 | * Degrades gracefully to the autofill UI or manual input when the
217 | * API is not available.
218 | *
219 | */
220 | customElements.define("one-time-code",
221 | class extends HTMLInputElement {
222 | connectedCallback() {
223 | this.receive();
224 | }
225 | async receive() {
226 | try {
227 | let {code} = await navigator.credentials.get({otp: {transport: ["sms"]}});
228 | this.value = code;
229 | this.form.submit();
230 | } catch (e) {
231 | console.log(e);
232 | }
233 | }
234 | }, {
235 | extends: "input"
236 | });
237 | ```
238 |
239 | The main drawback of this formulation is that it is (deliberately) unaware of the `` it is dealing with, so it can't necessarily be smart about it (e.g. suppress the virtual keyboard when the SMS arrives).
240 |
241 | Arguably, the right long term answer is to allow custom elements to have greater controls while [participating in forms]([https://github.com/mozilla/standards-positions/issues/150](https://github.com/mozilla/standards-positions/issues/150)) but that is still an area of active research.
242 |
243 | ### Formatting
244 |
245 | In this proposal, to support the isolation between different origins (without extra user mediation), we define a formatting convention in the SMS message that enables them to be addressed to a specific origin and routed by the browser securely:
246 |
247 | ```
248 | Your OTP is: 123ABC78.
249 | @example.com #123ABC78
250 | ```
251 |
252 | Long term, we expect the formatting to be browser agnostic ([current formulation](https://github.com/samuelgoto/sms-receiver/issues/4#issuecomment-528991114) of the long term plan), but while GMS core releases are still rolling out, Android still needs an [app hash](https://developers.google.com/identity/sms-retriever/verify#computing_your_apps_hash_string) to know which APK it should redirect the SMS to. There is an interesting trick we could do to combine URLs with App Hashes, embedding them as URL parameters (making them valid android SMSes as well as valid web urls, which we can use to derive origins):
253 |
254 | ```
255 | Your OTP is: 123ABC78.
256 | @code.sgo.to #123ABC78 ^s3LhKBB0M33
257 | ```
258 |
259 | In this formulation, the last few characters (e.g. `^s3LhKBB0M33`) are used to route the SMS from Android to the Browser APK and the origin is used to route from the Browser process to the right requesting tab.
260 |
261 | ## Security
262 |
263 | From a security perspective, the biggest consideration with this API is crossing an origin boundary, which we believe is mitigated by the [formatting](#formatting) addressing scheme.
264 |
265 | This API is also **only** available via `https` or `localhost` (for development purposes). We don't entirely adopt the concept of [trustworthy urls](https://www.w3.org/TR/powerful-features/#is-url-trustworthy) because it covers more schemes (e.g. `data://123`) than we would like to (our initial intuition is that (a) `https` and `localhost` covers most cases and (b) it needs to be clear to the user what public facing entity its sending the SMS).
266 |
267 | This API is also **only** available on main frames, to avoid abuse by third party iframes / libraries.
268 |
269 | ## Privacy
270 |
271 | From a privacy perspective, there are a few considerations to be taken:
272 |
273 | - inner frames and ad networks
274 | - fingerprinting
275 | - awareness and control
276 |
277 | The first concern is somewhat easy to address: we propose the API should be **unavailable outside of top level frames**.
278 |
279 | The second and the third concerns are hard to be talked about abstractly, outside of a specific [UX formulation](#UX). We believe, however, that under the proposed UX formulation, the following attack vectors are addressed.
280 |
281 | ### User Tracking
282 |
283 | Phone numbers are an effective stable identifier for a user that enable cross-site and online/offline tracking. Obtaining the phone number is the point at which user is typically (or should be) asked for consent and best educated about the implications of sharing this information, so is not addressed in this proposal.
284 |
285 | However, the ability to verify the user’s phone number automatically in the background via an SMS retrieval API is a mechanism by which ongoing presence of the user could be determined, at least on a particular device where the developer already knows the phone number. Existing Android APIs mitigate this by allowing existing SMS notifications and SMS history to continue to be visible to the user, giving them insight that this may be happening (and providing a disincentive for a service to “guess” the user’s phone number, spam the number, and try to detect if this user is present by seeing if retrieval works). In practice, in the Android native app ecosystem, this hasn’t been found this to be a vector for abuse, especially given the cost of sending SMS and the visibility of the attack to users.
286 |
287 | ### Phishing
288 |
289 | SMS OTP are readily phishable and an existing widespread concern. While not making this worse, this proposal attempts to mitigate by avoiding and lessening the occurrence of users to manually enter OTP (so as to be less conditioned to phishing, and/or more conscious of where they enter OTP), and by making the OTP only available via programmatic mechanism to the intended recipient (i.e. by specifying the target origin in the message contents).
290 |
291 | ## Annex
292 |
293 | ### Related APIs
294 |
295 | #### Credential Management and WebAuthn APIs
296 |
297 | CM API and WebAuthn facilitate alternative forms of authentication. CM API facilitates interaction with password credentials and WebAuthn allows developers to interact with authentication hardware that provides much stronger, phishing resistant, and more usable multi-factor authentication on the web. While better alternatives for authentication, these APIs do not provide any communication mechanism or reputation signals that developers also use phone numbers for, so are not a comprehensive alternative to phone number or SMS OTP.
298 |
299 | #### Notifications
300 |
301 | Browser notification APIs provide a communication channel to developers, but developers often still prefer or also request a verified phone numbers since it checks that the user is reachable at this number and facilitates voice communication and reasonably real-time two-way communication on practically any time of mobile phone (no dependence on OS or version, pretty much all phones can handle SMS).
302 |
303 | #### OAuth etc.
304 |
305 | OAuth and similar protocols allow developers to obtain information such as verified phone number from an identity provider (IDP). However, this relies on user having provided, verified, and maintain their phone number with the IDP, and be comfortable using this model to share data (e.g. knowing their usage of 3p services). The IDPs themselves (unless an authoritative provider for a phone number, such as a carrier), need to verify phone number ownership, and typically still use SMS OTP for that purpose.
306 |
307 | #### reCAPTCHA
308 |
309 | Captcha APIs provide an alternative anti-abuse signals (i.e. that user is not a bot) that developer sometime rely on phone numbers for (in that phone numbers are often limited and require human involvement to procure, and as such as hard to produce at scale).
310 |
311 | #### Payment APIs
312 |
313 | Phone numbers are sometimes used for carrier billing schemes. Payment APIs offer an alternative as well as signal of user quality (having a payment instrument often involves identity verification and ability / history of being able to pay).
314 |
315 |
316 | #### Heuristic Autofill
317 |
318 | In addition to autofill annotations, the browser could also heuristically extract and autofill OTP, with user confirmation and without explicit developer support.
319 |
320 | However, getting access to SMS without coordination from the developer (i.e. without explicit formatting of the SMS or indication that developer is expecting an SMS) will be a challenge, as browser would require ongoing access to SMS.
321 |
322 | Note that iOS provides heuristic-based OTP autofill, but iOS provides browser / keyboard access to SMS; but on Android, browsers may not have or even be able to request indefinite SMS access.
323 |
324 | #### Phone Number Assertion API
325 |
326 | If phone number has already been verified for a given device or user account, browser could return a verifiable assertion of the phone number.
327 |
328 | ```
329 | // This is just a draft/example of what a API could look like.
330 | let phone = await navigator.credentials.get({phone: true});
331 | verify(phone);
332 | ```
333 |
334 | This could be implemented by having developer interact with identity providers (IDPs), which have already verified and are aware of the user’s phone number, and could vouch for this information, in the same way Google Sign-In and similar federated identity flows currently work for email addresses.
335 |
336 | Several identity providers such as Facebook (Account Kit), Truecaller, and others already provide APIs like this verified phone numbers.
337 |
338 | ### Spec
339 |
340 | There are a couple of alternatives that we considered from an API shape perspective. First, subclassing `EventTarget`:
341 |
342 | ```javascript
343 | let receiver = new OTPReceiver();
344 | receiver.addEventListener("receive", ({content}) => {
345 | console.log(content);
346 | });
347 | receiver.receive();
348 | ```
349 |
350 | But it seemed awkward since this is a one-shot event.
351 |
352 | The other formulation that we think is worth noting is to use a static method outside of `navigator`. Example:
353 |
354 | ```javascript
355 | let {content} = OTPReceiver.receive();
356 | ```
357 |
358 | This could work equally well compared to `navigator.sms.receive()`, but would pollute the global namespace rather than the `navigator` namespace.
359 |
360 | The other consideration here is whether to enable aborting the request or maybe pass a custom timeout:
361 |
362 | ```javascript
363 | let abort = new AbortController();
364 | setTimeout(() => {
365 | // abort after two minutes
366 | abort.abort();
367 | }, 2 * 60 * 1000);
368 |
369 | try {
370 | let {content} = await navigator.sms.receive(abort);
371 | } catch (e) {
372 | // deal with errors
373 | }
374 | ```
375 |
376 | # Acknowledgements
377 |
378 | This is a write down of a variety of ideas coming from huge amount of people, in no particular order: @sso-google, @ayuishii, @agektmr, @slightlyoff, @reillyeon, @inexorabletash and @rmondello and team.
379 |
--------------------------------------------------------------------------------
/index.bs:
--------------------------------------------------------------------------------
1 | 
1. Introduction
684 |This section is non-normative.
685 |Many web sites need to verify credentials (e.g. phone numbers and 686 | email addresses) as part of their authentication flows. They currently 687 | rely on sending one-time-passwords (OTP) to these communication channels to 688 | be used as proof of ownership. The one-time-password is manually 689 | handed back by the user (typically by copying/pasting) to the web app 690 | which is onerous and erroneous.
691 |This a proposal for a client side javascript API that enables web 692 | sites to request OTPs and a set of transport-specific conventions (we 693 | start with SMS while leaving the door open to others) that can be used 694 | in coordination with browsers.
695 |1.1. The client side API
696 |In this proposal, websites have the ability to call a browser API to 697 | request OTPs coming from specific transports (e.g. via SMS).
698 |The browser intermediates the receipt of the SMS and the handing off 699 | to the calling website (typically asking for the user’s consent), so 700 | the API returns a promise asynchronously.
701 |709 |let { code, type} = await navigator. credentials. get({ 704 | otp: { 705 | transport: [ "sms" ] 706 |} 707 |}); 708 |
1.2. The server side API
711 |Once the client side API is called, the website’s server can send 712 | OTPs to the client via the requested transport mechanisms. For each 713 | of these transport mechanism, a server side convention is set in 714 | place to guarantee that the OTP is delivered safely and 715 | programatically.
716 |For SMS, for example, servers should send origin-bound one-time code messages to clients. [sms-one-time-codes]
717 |In the following origin-bound one-time code message, the host is "example.com", the code is "123456", and the explanatory text is "Your authentication code is 123456.\n".
"Your authentication code is 123456. 721 | 722 | @example.com #123456" 723 |724 |
1.3. Feature Detection
726 |Not all user agents necessarily need to implement the WebOTP API at 727 | the exact same moment in time, so websites need a mechanism to detect 728 | if the API is available.
729 |Websites can check for the presence of the OTPCredential global 730 | interface:
731 |738 |if ( ! window. OTPCredential) { 734 |// feature not available 735 |return ; 736 |} 737 |
1.4. Web Components
740 |For the most part, OTP verification largely relies on:
741 |-
742 |
-
743 |
input, forms and copy/paste, on the client side and
744 | -
745 |
third party frameworks to send SMS, on the server side.
746 |
We expect some of these frameworks to develop declarative versions of 748 | this API to facilitate the deployment of their customer’s existing 749 | code.
750 |759 |< script src = "sms-sdk.js" ></ script > 753 | 754 |< form > 755 |< input is = "one-time-code" required /> 756 |< input type = "submit" /> 757 |</ form > 758 |
And here is an example of how a framework could implement it 761 | using web components:
762 |customElements782 |. define( "one-time-code" , 765 |class extends HTMLInputElement{ 766 | connectedCallback() { 767 |this . receive(); 768 |} 769 |async receive() { 770 |let { code, type} = await navigator. credentials. get({ 771 | otp: { 772 | transport: [ "sms" ] 773 |} 774 |}); 775 |this . value= otp; 776 |this . form. submit(); 777 |} 778 |}, { 779 |extends : "input" 780 |}); 781 |
1.5. Abort API
784 |Many modern websites handle navigations on the client side. So, if a 785 | user navigates away from an OTP flow to another flow, the request 786 | needs to be cancelled so that the user isn’t bothered with a 787 | permission prompt that isn’t relevant anymore.
788 |To facilitate that, an abort controller can be passed to abort the 789 | request:
790 |806 |const abort= new AbortController(); 793 | 794 | setTimeout(() => { 795 |// abort after two minutes 796 | abort. abort(); 797 |}, 2 * 60 * 1000 ); 798 | 799 |let { code, type} = await navigator. credentials. get({ 800 | signal: abort. signal, 801 | otp: { 802 | transport: [ "sms" ] 803 |} 804 |}); 805 |
2. Client Side API
808 |Websites call navigator.credentials.get({otp:..., ...}) to retrieve an OTP.
The algorithm of navigator.credentials.get() looks through all of the interfaces that inherit from Credential in the Request a Credential abstract operation.
In that operation, it finds OTPCredential which inherits from Credential. It calls OTPCredential. to collect any credentials that
811 | should be available without user mediation, and if it does not find
812 | exactly one of those, it then calls [[CollectFromCredentialStore]]()OTPCredential. to have
813 | the user select a credential source and fulfill the request.[[DiscoverFromExternalSource]]()
Since this specification requires an authorization gesture to create OTP credentials, the OTPCredential. internal method inherits the default behavior of [[CollectFromCredentialStore]]()Credential.[[CollectFromCredentialStore]](), of returning an empty set.
It is then the responsibility of OTPCredential. to provide an OTP.[[DiscoverFromExternalSource]]()
2.1. The OTPCredential Interface
817 |The OTPCredential interface extends Credential and contains
818 | the attributes that are returned to the caller when a new one time
819 | password is retrieved.
OTPCredential's interface object inherits Credential's implementation of [[CollectFromCredentialStore]](origin, options, sameOriginWithAncestors), and defines its own
821 | implementation of [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors).
[827 |Exposed =Window ,SecureContext ] 823 |interface :OTPCredential Credential { 824 |readonly attribute DOMString code ; 825 | }; 826 |
-
828 |
id829 |-
830 |
This attribute is inherited from
831 |Credential [[type]]832 |-
833 |
The
835 |OTPCredentialinterface object's[[type]]internal slot's value is the string 834 | "otp". code, of type DOMString, readonly 836 |-
837 |
The retrieved one time password.
838 |
2.1.1. The [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors)
840 | [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors)This method is called every time navigator.credentials.get({otp:..., ...}) and is responsible for returning an OTP when one is requested (i.e. when options. is passed).otp
This internal method accepts three arguments:
842 |-
843 |
origin844 |-
845 |
This argument is the relevant settings object's origin, as determined by the 846 | calling
847 |get()implementation, i.e.,CredentialsContainer's Request aCredentialabstract operation. options848 |-
849 |
This argument is a
850 |CredentialRequestOptionsobject whoseoptions.member contains aotpOTPCredentialRequestOptionsobject specifying the desired attributes of the OTP to retrieve. sameOriginWithAncestors851 |-
852 |
This argument is a Boolean value which is
853 |trueif and only if the caller’s environment settings object is same-origin with its ancestors. It isfalseif caller is cross-origin.Note: Invocation of this internal method indicates that it was allowed by permissions policy, which is evaluated at the [CREDENTIAL-MANAGEMENT-1] level. 854 | See § 2.5 Permissions Policy integration.
855 |
Note: This algorithm is synchronous: the Promise resolution/rejection is handled by navigator.credentials.get().
When this method is invoked, the user agent MUST execute the following algorithm:
858 |-
859 |
- 860 | 861 |
-
862 |
Let options be the value of
863 |options..otp -
864 |
Let callerOrigin be
866 |origin. 865 | If callerOrigin is an opaque origin, return aDOMExceptionwhose name is "NotAllowedError", and terminate this algorithm. -
867 |
Let effectiveDomain be the callerOrigin’s effective domain. 868 | If effective domain is not a valid domain, then return a
869 |DOMExceptionwhose name is "SecurityError" and terminate this algorithm.Note: An effective domain may resolve to a host, which can be represented in various manners, 870 | such as domain, ipv4 address, ipv6 address, opaque host, or empty host. 871 | Only the domain format of host is allowed here. This is for simplification and also is 872 | in recognition of various issues with using direct IP address identification in concert with 873 | PKI-based security.
874 | -
875 |
If the
877 |options.is present and its aborted flag is set tosignaltrue, return aDOMExceptionwhose name is "AbortError" 876 | and terminate this algorithm. -
878 |
TODO(goto): figure out how to connect the dots here with the transport algorithms.
879 |
During the above process, the user agent SHOULD show some UI to the user to guide them in the process of sharing the OTP with the origin.
881 |2.2. CredentialRequestOptions
882 | To support obtaining OTPs via navigator.credentials.get(),
883 | this document extends the CredentialRequestOptions dictionary as follows:
888 |partial dictionary CredentialRequestOptions { 885 |OTPCredentialRequestOptions otp ; 886 | }; 887 |
-
890 |
otp, of type OTPCredentialRequestOptions 891 |-
892 |
This OPTIONAL member is used to make WebOTP requests.
893 |
2.3. OTPCredentialRequestOptions
896 | The OTPCredentialRequestOptions dictionary supplies navigator.credentials.get() with the data it needs to retrieve an
897 | OTP.
902 |dictionary { 899 |OTPCredentialRequestOptions sequence <OTPCredentialTransportType >transport = []; 900 | }; 901 |
-
904 |
transport, of type sequence<OTPCredentialTransportType>, defaulting to[]905 |-
906 |
This OPTIONAL member contains a hint as to how the server might receive the OTP. 907 | The values SHOULD be members of
908 |OTPCredentialTransportTypebut client platforms MUST ignore unknown values.
2.4. OTPCredentialTransportType
911 | 915 |enum { 912 |OTPCredentialTransportType "sms" , 913 | }; 914 |
-
920 |
sms921 |-
922 |
Indicates that the OTP is expected to arrive via SMS.
923 |
2.5. Permissions Policy integration
926 |This specification defines one policy-controlled feature identified by
927 | the feature-identifier token "otp-credentials".
928 | Its default allowlist is 'self'. [Permissions-Policy]
A Document's permissions policy determines whether any content in that document is allowed to successfully invoke the WebOTP API, i.e., via navigator.credentials.get({otp: { transport: ["sms"]}}).
930 | If disabled in any document, no content in the document will be allowed to use the foregoing methods: attempting to do so will return an error.
2.6. Using WebOTP within iframe elements
932 | The WebOTP API is available in inner frames when the origins match but it’s disabled by default in cross-origin iframes.
933 | To override this default policy and indicate that a cross-origin iframe is allowed to invoke the WebOTP API's [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) method, specify the allow attribute on the iframe element and include the otp-credentialst feature-identifier token in the allow attribute’s value.
Relying Parties utilizing the WebOTP API in an embedded context should review § 4.4 Visibility Considerations for Embedded Usage regarding UI redressing and its possible mitigations.
935 |3. Transports
936 |We expect a variety of different transport mechanisms to enable OTPs 937 | to be received, most notably via SMS, email and hardware devices.
938 |Each of these transport mechanisms will need their own conventions on 939 | how to provide OTPs to the browser.
940 |In this draft, we leave the API surface to be extensible to any number 941 | of transports.
942 |3.1. SMS
943 |One of the most commonly used transport mechanisms for OTP is via 944 | SMS messages, allowing developers to verify phone numbers. They 945 | are typically sent embedded in an SMS message, which gets copied and 946 | pasted by users.
947 |[sms-one-time-codes] defines origin-bound one-time code messages, a format for sending OTPs over SMS and associating them with origins.
948 |4. Security
949 |From a security perspective, there are two considerations with this 950 | API:
951 |-
952 |
-
953 |
tampering: preventing attacks based on the modification of the message.
954 |
4.1. Availability
956 |This API is only available on:
957 |-
958 |
-
959 |
https (or localhost, for development purposes)
960 |
This API is also only available via https or localhost (for development 962 | purposes). We don’t entirely adopt the concept of trustworthy urls 963 | because it covers more schemes (e.g. data://123) than we would like to 964 | (our initial intuition is that (a) https and localhost covers most 965 | cases and (b) it needs to be clear to the user what public facing 966 | entity its sending the SMS).
967 |4.2. Addressing
968 |Each transport mechanism is responsible for guaranteeing that the 969 | browser has enough information to route the OTP appropriately to the 970 | intended origin.
971 |For example, origin-bound one-time code messages explicitly 972 | identify the origin on which the OTP can be used.
973 |The addressing scheme must be enforced by the agent to guarantee that 974 | it gets routed appropriately.
975 |4.3. Tampering
976 |There isn’t any built-in cryptographic guarantee that the OTP that is 977 | being handed back by this API hasn’t been tampered with. For example, 978 | an attacker could send an origin-bound one-time code message to the 979 | user’s phone with an arbitrary origin which the agent happilly passes 980 | back to the requesting call.
981 | 988 |It is the responsibility for the caller to:
989 |-
990 |
-
991 |
put in place the checks necessary to verify that the OTP that was received 992 | is a valid one, for example:
993 |-
994 |
-
995 |
parsing it carefully according to its known formatting expectations 996 | (e.g. only alpha numeric values),
997 | -
998 |
storing and checking OTPs that were sent on a server side database.
999 |
-
995 |
-
1001 |
degrade gracefully when an invalid OTP is received (e.g. re-request one).
1002 |
4.4. Visibility Considerations for Embedded Usage
1004 |Simplistic use of WebOTP in an embedded context, e.g., within iframes as described in § 2.6 Using WebOTP within iframe elements, may make users vulnerable to UI Redressing attacks, also known as "Clickjacking". This is where an attacker overlays their own UI on top of a Relying Party's intended UI and attempts to trick the user into performing unintended actions with the Relying Party. For example, using these techniques, an attacker might be able to trick users into purchasing items, transferring money, etc.
5. Privacy
1006 |From a privacy perspective, the most notable consideration is for a user agent 1007 | to enforce the consensual exchange of information between the user and the 1008 | website.
1009 |Specifically, this API allows the programatic verification of personally 1010 | identifiable attributes of the user, for example email addresses and phone 1011 | numbers.
1012 |The attack vector that is most frequently raised is a targeted attack: 1013 | websites trying to find a very specific user accross all of its user 1014 | base. In this attack, if left unattended, a website can use this API to 1015 | try to find a specific user that owns a specific phone number by 1016 | sending all / some (depending on the confidence level) of its users an origin-bound one-time code message and detecting when one is received.
1017 |Notably, this API doesn’t help with the acquisition of the personal 1018 | information, but rather with its verification. That is, this API helps verifying whether the user owns a specific phone number, but doesn’t 1019 | help acquiring the phone number in the first place (it assumes that the 1020 | website already has access to it).
1021 |Nonetheless, the verification of the possession of these attributes is extra 1022 | information about the user and should be handled responsibly by a user 1023 | agent, typically via permission prompts before handing back the OTP 1024 | to the website.
1025 |6. Acknowledgements
1026 |Many thanks to 1027 | Steven Soneff, 1028 | Ayu Ishii, 1029 | Reilly Grant, 1030 | Eiji Kitamura, 1031 | Alex Russell, 1032 | Owen Campbell-Moore, 1033 | Joshua Bell, 1034 | Ricky Mondello and 1035 | Mike West 1036 | for helping craft this proposal.
1037 |Special thanks to Tab Atkins, Jr. for creating and maintaining Bikeshed, the specification 1038 | authoring tool used to create this document, and for his general 1039 | authoring advice.
1040 |