-
Notifications
You must be signed in to change notification settings - Fork 160
/
index.bs
2642 lines (1995 loc) · 145 KB
/
index.bs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<pre class='metadata'>
Title: Web Authentication: An API for accessing Scoped Credentials
Status: ED
Prepare for TR: true
TR: https://www.w3.org/TR/webauthn/
ED: https://w3c.github.io/webauthn/
Previous Version: https://www.w3.org/TR/2016/WD-webauthn-20160928/
Previous Version: https://www.w3.org/TR/2016/WD-webauthn-20160902/
Previous Version: https://www.w3.org/TR/2016/WD-webauthn-20160531/
Shortname: webauthn
Level:
Editor: Vijay Bharadwaj, w3cid 55440, Microsoft, vijay.bharadwaj@microsoft.com
Editor: Hubert Le Van Gong, w3cid 84817, PayPal, hlevangong@paypal.com
Editor: Dirk Balfanz, w3cid 47648, Google, balfanz@google.com
Editor: Alexei Czeskis, w3cid 87258, Google, aczeskis@google.com
Editor: Arnar Birgisson, w3cid 87332, Google, arnarb@google.com
Editor: Jeff Hodges, w3cid 43843, PayPal, Jeff.Hodges@paypal.com
Editor: Michael B. Jones, w3cid 38745, Microsoft, mbj@microsoft.com
Editor: Rolf Lindemann, w3cid 84447, Nok Nok Labs, rolf@noknok.com
Editor: J.C. Jones, w3cid 87240, Mozilla, jc@mozilla.com
group: webauthn
Issue Tracking: Github https://github.com/w3c/webauthn/issues
Text Macro: RP Relying Party
Text Macro: RPS Relying Parties
Text Macro: INFORMATIVE <em>This section is not normative.</em>
Text Macro: WAC WebAuthn Client
Ignored Vars: op, alg, type, algorithm
Abstract: This specification defines an API enabling the creation and use of strong, attested, cryptographic scoped credentials
by web applications, for the purpose of strongly authenticating users. Conceptually, one or more credentials, each scoped to a
given Relying Party, are created and stored on an authenticator by the user agent in conjunction with the web application. The
user agent mediates access to scoped credentials in order to preserve user privacy. Authenticators are responsible for ensuring
that no operation is performed without user consent. Authenticators provide cryptographic proof of their properties to relying
parties via attestation. This specification also describes the functional model for WebAuthn conformant authenticators,
including their signature and attestation functionality.
Boilerplate: omit conformance, omit feedback-header
Markup Shorthands: css off, markdown on
</pre>
<pre class="anchors">
<!-- spec: HTML; urlPrefix: https://html.spec.whatwg.org/multipage/ -->
spec: HTML51; urlPrefix: http://www.w3.org/TR/html51/; for: web
type: dfn
urlPrefix: browsers.html
text: origin; url: concept-cross-origin
text: opaque origin; url: opaque-origin; for:web
text: tuple origin
text: relaxing the same-origin restriction
type: dfn
urlPrefix: webappapis.html;
text: current settings object; for:web; url:current-settings-object
text: Navigator; for: interface; url:the-navigator-object
spec: WebCryptoAPI; urlPrefix: https://www.w3.org/TR/WebCryptoAPI/; for: web
type: dfn
text: normalizing an algorithm; url: dfn-normalize-an-algorithm
</pre> <!-- class=anchors -->
# Introduction # {#intro}
[INFORMATIVE]
This specification defines an API enabling the creation and use of strong, attested, cryptographic <em><a>scoped
credentials</a></em> by web applications, for the purpose of strongly authenticating users. A <a>scoped credential</a> is
created and stored by an <em><a>authenticator</a></em> at the behest of a <em><a>[RP]</a></em>, subject to <em><a>user
consent</a></em>. Subsequently, the scoped credential can only be accessed by origins belonging to that [RP].
This scoping is enforced jointly by <em><a>conforming User Agents</a></em> and <em><a>authenticators</a></em>.
Additionally, privacy across <a>[RPS]</a> is maintained; [RPS] are not able to detect any properties, or even
the existence, of credentials scoped to other [RPS].
[RPS] employ the <a>Web Authentication API</a> during two distinct, but related, <a>ceremonies</a> involving a user. The first
is <a>Registration</a>, where a <a>scoped credential</a> is created on an <a>authenticator</a>, and associated by a <a>[RP]</a>
with the present user's account (the account may already exist or may be created at this time). The second is
<a>Authentication</a>, where the <a>[RP]</a> is presented with a <em><a>WebAuthn Assertion</a></em> proving the presence and
consent of the user who registered the <a>scoped credential</a>. Functionally, the <a>Web Authentication API</a> comprises two
methods (along with associated data structures): <a>makeCredential()</a> and <a>getAssertion()</a>. The former is used during
<a>Registration</a> and the latter during <a>Authentication</a>.
Broadly, compliant <a>authenticators</a> protect <a>scoped credentials</a>, and
interact with user agents to implement the <a>Web Authentication API</a>. Some
authenticators may run on the same computing device (e.g., smart phone, tablet,
desktop PC) as the user agent is running on. For instance, such an authenticator
might consist of a Trusted Execution Environment (TEE) applet, a Trusted
Platform Module (TPM), or a Secure Element (SE) integrated into the computing
device in conjunction with some means for <a>user verification</a>, along with
appropriate platform software to mediate access to these components'
functionality. Other authenticators may operate autonomously from the computing
device running the user agent, and be accessed over a transport such as
Universal Serial Bus (USB), Bluetooth Low Energy (BLE) or Near Field
Communications (NFC).
## Use Cases ## {#use-cases}
The below use case scenarios illustrate use of two very different types of <a>authenticators</a>, as well as outline further
scenarios. Additional scenarios, including sample code, are given later in [[#sample-scenarios]].
### Registration ### {#usecase-registration}
- On a phone:
* User navigates to example.com in a browser and signs in to an existing account using whatever method they have been using
(possibly a legacy method such as a password), or creates a new account.
* The phone prompts, "Do you want to register this device with example.com?"
* User agrees.
* The phone prompts the user for a previously configured <a>authorization gesture</a> (PIN, biometric, etc.); the user
provides this.
* Website shows message, "Registration complete."
### Authentication ### {#usecase-authentication}
- On a laptop or desktop:
* User navigates to example.com in a browser, sees an option to "Sign in with your phone."
* User chooses this option and gets a message from the browser, "Please complete this action on your phone."
- Next, on their phone:
* User sees a discrete prompt or notification, "Sign in to example.com."
* User selects this prompt / notification.
* User is shown a list of their example.com identities, e.g., "Sign in as Alice / Sign in as Bob."
* User picks an identity, is prompted for an <a>authorization gesture</a> (PIN, biometric, etc.) and provides this.
- Now, back on the laptop:
* Web page shows that the selected user is signed-in, and navigates to the signed-in page.
### Other use cases and configurations ### {#other-configurations}
A variety of additional use cases and configurations are also possible, including (but not limited to):
- A user navigates to example.com on their laptop, is guided through a flow to create and register a credential on their phone.
- A user obtains an discrete, cross-platform authenticator, such as a "fob" with USB or USB+NFC/BLE connectivity options, loads example.com in their browser on a laptop or phone, and is guided though a flow to create and register a credential on the fob.
- A [RP] prompts the user for their <a>authorization gesture</a> in order to authorize a single transaction, such as a payment
or other financial transaction.
# Conformance # {#conformance}
This specification defines criteria for a <a>Conforming User Agent</a>: A User Agent MUST behave as described in this
specification in order to be considered conformant. <a>Conforming User Agents</a> MAY implement algorithms given in this
specification in any way desired, so long as the end result is indistinguishable from the result that would be obtained by the
specification's algorithms. A conforming User Agent MUST also be a conforming implementation of the IDL fragments of this
specification, as described in the “Web IDL” specification. [[!WebIDL-1]]
This specification also defines a model of a conformant <a>authenticator</a> (see [[#authenticator-model]]). This is a set of
functional and security requirements for an authenticator to be usable by a <a>Conforming User Agent</a>. As described in
[[#use-cases]], an authenticator may be implemented in the operating system underlying the User Agent, or in external hardware,
or a combination of both.
## Dependencies ## {#dependencies}
This specification relies on several other underlying specifications.
: HTML
:: The concepts of <a link-for='web'>current settings object</a>, <a link-for='web'>origin</a>,
<a link-for='web'>opaque origin</a>, <a>relaxing the same-origin restriction</a>, and the <a>Navigator</a> interface are
defined in [[!HTML51]].
: Web IDL
:: Many of the interface definitions and all of the IDL in this specification depend on [[!WebIDL-1]]. This updated version of
the Web IDL standard adds support for <dfn>Promises</dfn>, which are now the preferred mechanism for asynchronous
interaction in all new web APIs.
: DOM
:: <dfn>DOMException</dfn> and the DOMException values used in this specification are defined in [[!DOM4]].
: Web Cryptography API
:: The <dfn dictionary>AlgorithmIdentifier</dfn> type and the method for <a>normalizing an algorithm</a> are defined in
[[WebCryptoAPI#algorithm-dictionary]].
: Base64url encoding
:: The term <dfn>Base64url Encoding</dfn> refers to the base64 encoding using the URL- and filename-safe character set defined
in Section 5 of [[!RFC4648]], with all trailing '=' characters omitted (as permitted by Section 3.2) and without the
inclusion of any line breaks, whitespace, or other additional characters. This is the same encoding as used by JSON Web
Signature (JWS) [[RFC7515]].
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
[[!RFC2119]].
# Terminology # {#terminology}
: <dfn>ASCII case-insensitive match</dfn>
:: A method of testing two strings for equality by comparing them exactly, code point for code point, except that the codepoints
in the range U+0041 .. U+005A (i.e. LATIN CAPITAL LETTER A to LATIN CAPITAL LETTER Z) and the corresponding codepoints in
the range U+0061 .. U+007A (i.e. LATIN SMALL LETTER A to LATIN SMALL LETTER Z) are also considered to match.
: <dfn>Assertion</dfn>
:: See <a>WebAuthn Assertion</a>.
: <dfn>Attestation</dfn>
:: Generally, a statement that serves to bear witness, confirm, or authenticate.
In the WebAuthn context, attestation is employed to attest to the provenance of an authenticator and the data it emits;
including, for example: credential IDs, credential key pairs, signature counters, etc. <dfn>Attestation information</a> is
conveyed in <a>attestation statements</a>.
See also <a>attestation format</a>, and <a>attestation type</a>.
: <dfn>Attestation Certificate</dfn>
:: A X.509 Certificate for the <dfn>attestation key pair</dfn> used by an <a>Authenticator</a> to attest to its manufacture
and capabilities. At <a>registration</a> time, the <a>authenticator</a> uses the <dfn>attestation private key</dfn> to sign
the <a>[RP]</a>-specific <a>credential public key</a> (and additional data) that it generates and returns via the
<a>authenticatorMakeCredential</a> operation. [RPS] use the <dfn>attestation public key</dfn> conveyed in the <a>attestation
certificate</a> to verify the attestation signature. Note that in the case of <a>self attestation</a>, the
<a>authenticator</a> has no distinct <a>attestation key pair</a> nor <a>attestation certificate</a>, see <a>self
attestation</a> for details.
: <dfn>Authentication</dfn>
:: The <a>ceremony</a> where a user, and the user's computing device(s) (containing at least one <a>authenticator</a>) work in
concert to cryptographically prove to an <a>[RP]</a> that the user controls the private key associated with a
previously-registered <a>scoped credential</a> (see <a>Registration</a>). Note that this includes employing <a>user
verification</a>.
: <dfn>Authenticator</dfn>
:: A cryptographic device used by a <a>[WAC]</a> to (i) generate a <a>scoped credential</a> and register it with a <a>[RP]</a>,
and (ii) subsequently used to cryptographically sign and return, in the form of an <a>WebAuthn Assertion</a>, a challenge
and other data presented by a <a>[RP]</a> (in concert with the <a>[WAC]</a>) in order to effect authentication.
: <dfn>Authorization Gesture</dfn>
:: Essentially the same as <a>user verification</a>.
: <dfn>Ceremony</dfn>
:: The concept of a ceremony [[Ceremony]] is an extension of the concept of a network protocol, with human nodes alongside
computer nodes and with communication links that include UI, human-to-human communication and transfers of physical objects
that carry data. What is out-of-band to a protocol is in-band to a ceremony. In this specification, <a>Registration</a>,
<a>Authentication</a>, and <a>user verification</a> are ceremonies.
: <dfn>Client</dfn>
:: See <a>Conforming User Agent</a>.
: <dfn>Conforming User Agent</dfn>
:: A user agent implementing, in conjunction with the underlying platform, the <a>Web Authentication API</a> and algorithms
given in this specification, and handling communication between <a>Authenticators</a> and <a>[RPS]</a>.
: <dfn>Credential Public Key</dfn>
:: The public key portion of an <a>[RP]</a>-specific <dfn>credential key pair</dfn>, generated by an <a>authenticator</a> and
returned to an [RP] at <a>registration</a> time (see also <a>scoped credential</a>). The private key portion of the
<a>credential key pair</a> is known as the <dfn>credential private key</dfn>. Note that in the case of <a>self
attestation</a>, the <a>credential key pair</a> is also used as the <a>attestation key pair</a>, see <a>self attestation</a>
for details.
: <dfn>Registration</dfn>
:: The <a>ceremony</a> where a user, a <a>[RP]</a>, and the user's computing device(s) (containing at least one
<a>authenticator</a>) work in concert to create a <a>scoped credential</a> and associate it with the user's <a>[RP]</a>
account. Note that this includes employing <a>user verification</a>.
: <dfn>[RP]</dfn>
:: The entity whose web application utilizes the <a>Web Authentication API</a> to register and authenticate users. See
<a>Registration</a> and <a>Authentication</a>, respectively.
Note: While the term [RP] is used in other contexts (e.g., X.509 and OAuth), an entity acting as a [RP] in one context is
not necessarily a [RP] in other contexts.
: <dfn>Relying Party Identifier</dfn>
: <dfn>RP ID</dfn>
:: An identifier for the [RP] on whose behalf a given registration or authentication ceremony is being performed. Scoped
credentials can only be used for authentication by the same entity (as identified by RP ID) that created and registered
them. By default, the RP ID for a WebAuthn operation is set to the <a link-for='web'>current settings object</a>'s
<a link-for='web'>origin</a>. This default can be overridden by the caller subject to certain restrictions, as specified in
[[#makeCredential]] and [[#getAssertion]].
: <dfn>Scoped Credential</dfn>
:: Generically, a credential is data one entity presents to another in order to authenticate the former's identity [[RFC4949]].
A WebAuthn <em><a>scoped credential</a></em> is a <code>{ identifier, type }</code> pair identifying authentication
information established by the authenticator and the [RP], together, at <a>registration</a> time. The authentication
information consists of an asymmetric key pair, where the public key portion is returned to the [RP], which stores it in
conjunction with the present user's account. The authenticator maps the private key to the [RP]'s <a>RP ID</a> and stores
it. Subsequently, only that [RP], as identified by its <a>RP ID</a>, is able to employ the <a>scoped credential</a> in
<a>authentication</a> ceremonies, via the <a>getAssertion()</a> method. The [RP] uses its copy of the stored public key to
verify the resultant <a>WebAuthn Assertion</a>.
: <dfn>User Consent</dfn>
:: User consent means the user agrees with what they are being asked, i.e., it encompasses reading and understanding prompts.
<a>User verification</a> encompasses the means employed by the user to indicate consent.
: <dfn>User Verification</dfn>
:: The process by which an <a>authenticator</a> <em>locally authorizes</em> the invocation of the
<a>authenticatorMakeCredential</a> and <a>authenticatorGetAssertion</a> operations, for example through a touch plus pin
code, a password, a gesture (e.g., presenting a fingerprint), or other modality. Note that invocation of said operations
implies use of key material managed by the authenticator.
: <dfn>WebAuthn Assertion</dfn>
:: The cryptographically signed {{WebAuthnAssertion}} object returned by an <a>authenticator</a> as the result of a
<a>authenticatorGetAssertion</a> operation.
: <dfn>[WAC]</dfn>
:: See <a>Conforming User Agent</a>.
# <dfn>Web Authentication API</dfn> # {#api}
This section normatively specifies the API for creating and using scoped credentials. Support for deleting credentials is
deliberately omitted; this is expected to be done through platform-specific user interfaces rather than from a script. The basic
idea is that the credentials belong to the user and are managed by an authenticator, with which the [RP] interacts through the
client (consisting of the browser and underlying OS platform). Scripts can (with the user's consent) request the browser to
create a new credential for future use by the [RP]. Scripts can also request the user’s permission to perform authentication
operations with an existing credential. All such operations are performed in the authenticator and are mediated by the browser
and/or platform on the user's behalf. At no point does the script get access to the credentials themselves; it only gets
information about the credentials in the form of objects.
The security properties of this API are provided by the client and the authenticator working together. The authenticator, which
holds and manages credentials, ensures that all operations are scoped to a particular origin, and cannot be replayed against
a different origin, by incorporating the origin in its responses. Specifically, as defined in [[#signature-format]], the full
origin of the requester is included, and signed over, in the attestation statement produced when a new credential is created as
well as in all assertions produced by WebAuthn credentials.
Additionally, to maintain user privacy and prevent malicious [RPS] from probing for the presence of credentials belonging to
other [RPS], each credential is also associated with a Relying Party Identifier, or RP ID. This RP ID is provided by the client
to the authenticator for all operations, and the authenticator ensures that credentials created by a [RP] can only be used in
operations requested by the same RP ID. Separating the origin from the RP ID in this way allows the API to be used in cases
where a single [RP] maintains multiple origins.
The client facilitates these security measures by providing correct origins and RP IDs to the authenticator for each
operation. Since this is an integral part of the WebAuthn security model, user agents MUST only expose this API to callers in
<dfn>secure contexts</dfn>, as defined in [[secure-contexts]].
The Web Authentication API is defined by the union of the Web IDL fragments presented in the following sections. A combined IDL listing is given in the [[#idl-index]]. The API is defined as a part of the <a>Navigator</a> interface:
<pre class="idl">
partial interface Navigator {
readonly attribute WebAuthentication authentication;
};
</pre>
## <dfn interface>WebAuthentication</dfn> Interface ## {#iface-credential}
<pre class="idl">
[SecureContext]
interface WebAuthentication {
Promise < ScopedCredentialInfo > makeCredential (
Account accountInformation,
sequence < ScopedCredentialParameters > cryptoParameters,
BufferSource attestationChallenge,
optional ScopedCredentialOptions options
);
Promise < WebAuthnAssertion > getAssertion (
BufferSource assertionChallenge,
optional AssertionOptions options
);
};
</pre>
This interface has two methods, which are described in the following subsections.
### Create a new credential (<dfn method for="WebAuthentication">makeCredential()</dfn> method) ### {#makeCredential}
With this method, a script can request the User Agent to create a new credential of a given type and persist it to the
underlying platform, which may involve data storage managed by the browser or the OS. The user agent will prompt the user to
approve this operation. On success, the promise will be resolved with a {{ScopedCredentialInfo}} object describing the newly
created credential.
This method takes the following parameters:
- The <dfn>accountInformation</dfn> parameter specifies information about the user account for which the credential is being
created. This is meant for later use by the authenticator when it needs to prompt the user to select a credential. An
authenticator is only required to store one credential for any given value of {{accountInformation}}. Specifically, if an
authenticator already has a credential for the specified value of {{Account/id}} in {{accountInformation}}, and if this
credential is not listed in the {{ScopedCredentialOptions/excludeList}} member of {{options}}, then after successful
execution of this method:
- Any calls to {{getAssertion()}} that do not specify {{AssertionOptions/allowList}} will not result in the older
credential being offered to the user.
- Any calls to {{getAssertion()}} that specify the older credential in the {{AssertionOptions/allowList}} may also not
result in it being offered to the user.
- The <dfn>cryptoParameters</dfn> parameter supplies information about the desired properties of the credential to be created.
The sequence is ordered from most preferred to least preferred. The platform makes a best effort to create the most
preferred credential that it can.
- The <dfn>attestationChallenge</dfn> parameter contains a challenge intended to be used for generating the attestation
statement of the newly created credential.
- The optional <dfn dfn-for="makeCredential()">options</dfn> parameter specifies additional options, as described in
[[#credential-options]].
When this method is invoked, the user agent MUST execute the following algorithm:
1. If the {{ScopedCredentialOptions/timeoutSeconds}} member of {{options}} is <a>present</a>, check if its value lies
within a reasonable range as defined by
the platform and if not, correct it to the closest value lying within that range. Set |adjustedTimeout| to this adjusted
value. If {{ScopedCredentialOptions/timeoutSeconds}} was not specified, then set |adjustedTimeout| to a platform-specific
default.
2. Let |promise| be a new <a data-lt="Promises">Promise</a>. Return |promise| and start a timer for |adjustedTimeout| seconds.
Then asynchronously continue executing the following steps. If any fatal error is encountered in this process other than the
ones enumerated below, cancel the timer, reject |promise| with a DOMException whose name is "UnknownError", and terminate
this algorithm.
3. Set |callerOrigin| to the <a link-for='web'>current settings object</a>'s <a link-for='web'>origin</a>. If |callerOrigin| is
an <a link-for='web'>opaque origin</a>, reject |promise| with a <a>DOMException</a> whose name is "NotAllowedError", and
terminate this algorithm. Otherwise,
- If the {{ScopedCredentialOptions/rpId}} member of {{options}} is not <a>present</a>, then set |rpId| to |callerOrigin|,
and |rpIdHash| to the SHA-256 hash of |rpId|.
- If the {{ScopedCredentialOptions/rpId}} member of {{options}} is <a>present</a>, then invoke the procedure used for
<a>relaxing the same-origin
restriction</a> by setting the `document.domain` attribute, using {{ScopedCredentialOptions/rpId}} as the given value
but without changing the current document's `domain`. If no errors are thrown, set |rpId| to the value of `host` as
computed by this procedure, and |rpIdHash| to the SHA-256 hash of |rpId|. Otherwise, reject |promise| with a
<a>DOMException</a> whose name is "SecurityError", and terminate this algorithm.
4. Process each element of {{cryptoParameters}} using the following steps, to produce a new sequence |normalizedParameters|.
- Let |current| be the currently selected element of {{cryptoParameters}}.
- If `current.type` does not contain a {{ScopedCredentialType}} supported by this implementation, then stop processing
|current| and move on to the next element in {{cryptoParameters}}.
- Let |normalizedAlgorithm| be the result of <a>normalizing an algorithm</a> [[!WebCryptoAPI]],
with |alg| set to `current.algorithm` and |op| set to 'generateKey'. If an error occurs during this
procedure, then stop processing |current| and move on to the next element in {{cryptoParameters}}.
- Add a new object of type {{ScopedCredentialParameters}} to |normalizedParameters|, with |type| set to `current.type` and
|algorithm| set to |normalizedAlgorithm|.
5. If |normalizedAlgorithm| is empty and {{cryptoParameters}} was not empty, cancel the timer started in step 2, reject
|promise| with a DOMException whose name is "NotSupportedError", and terminate this algorithm.
6. If the {{ScopedCredentialOptions/extensions}} member of {{options}} is <a>present</a>, process any extensions supported by
this client platform, to produce the extension data that needs to be sent to the authenticator. If an error is encountered
while processing an extension, skip that extension and do not produce any extension data for it. Call the result of this
processing |clientExtensions|.
7. Use {{attestationChallenge}}, |callerOrigin| and |rpId|, along with the token binding key associated with |callerOrigin| (if
any), to create a {{ClientData}} structure representing this request. Choose a hash algorithm for {{ClientData/hashAlg}} and
compute the <a>clientDataJSON</a> and <a>clientDataHash</a>.
8. Initialize |issuedRequests| to an empty list.
9. For each authenticator currently available on this platform: asynchronously invoke the <a>authenticatorMakeCredential</a>
operation on that authenticator with |rpIdHash|, <a>clientDataHash</a>, {{accountInformation}}, |normalizedParameters|,
{{ScopedCredentialOptions/excludeList}} and |clientExtensions| as parameters. Add a corresponding entry to |issuedRequests|.
- For each credential C in the {{ScopedCredentialOptions/excludeList}} member of {{options}} that has a non-empty
|transports| list, optionally use only the specified transports to test for the existence of C.
10. While |issuedRequests| is not empty, perform the following actions depending upon the |adjustedTimeout| timer and responses
from the authenticators:
- If the |adjustedTimeout| timer expires, then for each entry in |issuedRequests| invoke the <a>authenticatorCancel</a>
operation on that authenticator and remove its entry from the list.
- If any authenticator returns a status indicating that the user cancelled the operation, delete that authenticator's
entry from |issuedRequests|. For each remaining entry in |issuedRequests| invoke the <a>authenticatorCancel</a>
operation on that authenticator and remove its entry from the list.
- If any authenticator returns an error status, delete the corresponding entry from |issuedRequests|.
- If any authenticator indicates success:
- Remove this authenticator's entry from |issuedRequests|.
- Create a new {{ScopedCredentialInfo}} object named |value| and populate its fields with the values returned from the
authenticator as well as the <a>clientDataJSON</a> computed earlier.
- For each remaining entry in |issuedRequests| invoke the <a>authenticatorCancel</a> operation on that authenticator and
remove its entry from the list.
- Resolve |promise| with |value| and terminate this algorithm.
11. Reject |promise| with a <a>DOMException</a> whose name is "NotAllowedError", and terminate this algorithm.
During the above process, the user agent SHOULD show some UI to the user to guide them in the process of selecting and
authorizing an authenticator.
### Use an existing credential (<dfn method for="WebAuthentication">getAssertion()</dfn> method) ### {#getAssertion}
This method is used to discover and use an existing scoped credential, with the user's consent. The script optionally specifies
some criteria to indicate what credentials are acceptable to it. The user agent and/or platform locates credentials matching the
specified criteria, and guides the user to pick one that the script should be allowed to use. The user may choose not to provide
a credential even if one is present, for example to maintain privacy.
This method takes the following parameters:
- The <dfn>assertionChallenge</dfn> parameter contains a challenge that the selected authenticator is expected to sign to
produce the assertion.
- The optional <dfn dfn-for="getAssertion()">options</dfn> parameter specifies additional options, as described in
[[#assertion-options]].
When this method is invoked, the user agent MUST execute the following algorithm:
1. If {{AssertionOptions/timeoutSeconds}} was specified, check if its value lies within a reasonable range as defined by the
platform and if not, correct it to the closest value lying within that range. Set |adjustedTimeout| to this adjusted value.
If {{AssertionOptions/timeoutSeconds}} was not specified, then set |adjustedTimeout| to a platform-specific default.
2. Let |promise| be a new <a data-lt="Promises">Promise</a>. Return |promise| and start a timer for |adjustedTimeout| seconds.
Then asynchronously continue executing the following steps. If any fatal error is encountered in this process other than the
ones enumerated below, cancel the timer, reject |promise| with a DOMException whose name is "UnknownError", and terminate
this algorithm.
3. Set |callerOrigin| to the <a link-for='web'>current settings object</a>'s <a link-for='web'>origin</a>. If |callerOrigin| is
an <a link-for='web'>opaque origin</a>, reject |promise| with a <a>DOMException</a> whose name is "NotAllowedError", and
terminate this algorithm. Otherwise,
- If {{AssertionOptions/rpId}} is not specified, then set |rpId| to |callerOrigin|, and |rpIdHash| to the SHA-256
hash of |rpId|.
- If {{AssertionOptions/rpId}} is specified, then invoke the procedure used for <a>relaxing the same-origin restriction</a>
by setting the `document.domain` attribute, using {{AssertionOptions/rpId}} as the given value but without changing the
current document's `domain`. If no errors are thrown, set |rpId| to the value of `host` as computed by this procedure,
and |rpIdHash| to the SHA-256 hash of |rpId|. Otherwise, reject |promise| with a <a>DOMException</a> whose name is
"SecurityError", and terminate this algorithm.
4. If {{AssertionOptions/extensions}} was specified, process any extensions supported by this client platform, to produce the
extension data that needs to be sent to the authenticator. If an error is encountered while processing an extension, skip
that extension and do not produce any extension data for it. Call the result of this processing |clientExtensions|.
5. Use {{assertionChallenge}}, |callerOrigin| and |rpId|, along with the token binding key associated with |callerOrigin| (if
any), to create a {{ClientData}} structure representing this request. Choose a hash algorithm for {{ClientData/hashAlg}} and
compute the <a>clientDataJSON</a> and <a>clientDataHash</a>.
6. Initialize |issuedRequests| to an empty list.
7. For each authenticator currently available on this platform, perform the following steps:
- If {{AssertionOptions/allowList}} is empty, let |credentialList| be an empty list. Otherwise, execute a
platform-specific procedure to determine which, if any, credentials listed in {{AssertionOptions/allowList}} might be
present on this authenticator, and set |credentialList| to this filtered list. If no such filtering is possible, set
|credentialList| to an empty list.
- For each credential C within the |credentialList| that has a non-empty |transports| list, optionally use only the
specified transports to get assertions using credential C.
- If the above filtering process concludes that none of the credentials on {{AssertionOptions/allowList}} can possibly be on this
authenticator, do not perform any of the following steps for this authenticator, and proceed to the next authenticator
(if any).
- Asynchronously invoke the <a>authenticatorGetAssertion</a> operation on this authenticator with |rpIdHash|,
<a>clientDataHash</a>, |credentialList|, and |clientExtensions| as parameters.
- Add an entry to |issuedRequests|, corresponding to this request.
8. While |issuedRequests| is not empty, perform the following actions depending upon the |adjustedTimeout| timer and responses
from the authenticators:
- If the timer for |adjustedTimeout| expires, then for each entry in |issuedRequests| invoke the <a>authenticatorCancel</a>
operation on that authenticator and remove its entry from the list.
- If any authenticator returns a status indicating that the user cancelled the operation, delete that authenticator's entry
from |issuedRequests|. For each remaining entry in |issuedRequests| invoke the <a>authenticatorCancel</a> operation on
that authenticator, and remove its entry from the list.
- If any authenticator returns an error status, delete the corresponding entry from |issuedRequests|.
- If any authenticator returns success:
- Remove this authenticator's entry from |issuedRequests|.
- Create a new {{WebAuthnAssertion}} object named |value| and populate its fields with the values returned from the
authenticator as well as the <a>clientDataJSON</a> computed earlier.
- For each remaining entry in |issuedRequests| invoke the <a>authenticatorCancel</a> operation on that authenticator and
remove its entry from the list.
- Resolve |promise| with |value| and terminate this algorithm.
9. Reject |promise| with a <a>DOMException</a> whose name is "NotAllowedError", and terminate this algorithm.
During the above process, the user agent SHOULD show some UI to the user to guide them in the process of selecting and
authorizing an authenticator with which to complete the operation.
## Information about Scoped Credential (interface <dfn interface>ScopedCredentialInfo</dfn>) ## {#iface-credentialInfo}
<pre class="idl">
[SecureContext]
interface ScopedCredentialInfo {
readonly attribute ScopedCredential credential;
readonly attribute WebAuthnAttestation attestation;
};
</pre>
<div dfn-for="ScopedCredentialInfo">
This interface represents a newly-created scoped credential. It contains information about the credential that can be used
to locate it later for use, and also contains metadata that can be used by the <a>[RP]</a> to assess the strength of the
credential during registration.
The <dfn>credential</dfn> attribute contains an object whose attributes state the type of, and identifier for, the
credential represented by {{ScopedCredentialInfo}}.
The <dfn>attestation</dfn> attribute contains an attestation statement returned by the authenticator. This provides
information about the credential and the authenticator it is held in, such as the <a>credential public key</a> and the level
of security assurance provided by the authenticator.
</div>
## User Account Information (dictionary <dfn dictionary>Account</dfn>) ## {#iface-account}
<pre class="idl">
dictionary Account {
required DOMString rpDisplayName;
required DOMString displayName;
required DOMString id;
DOMString name;
DOMString imageURL;
};
</pre>
<div dfn-for="Account">
This dictionary is used by the caller to specify information about the user account and <a>[RP]</a> with which a credential
is to be associated. It is intended to help the authenticator in providing a friendly credential selection interface for the
user.
The <dfn>rpDisplayName</dfn> member contains the friendly name of the [RP], such as "Acme Corporation", "Widgets Inc" or
"Awesome Site".
The <dfn>displayName</dfn> member contains the friendly name associated with the user account by the [RP], such as "John P.
Smith".
The <dfn>id</dfn> member contains an identifier for the account, specified by the [RP]. This is not meant to be displayed
to the user. It is used by the [RP] to control the number of credentials - an authenticator will never contain more than one
credential for a given [RP] under the same {{Account/id}}.
The <dfn>name</dfn> member contains a detailed name for the account, such as "john.p.smith@example.com".
The <dfn>imageURL</dfn> member contains a URL that resolves to the user's account image. This may be a URL that can be used
to retrieve an image containing the user's current avatar, or a data URI that contains the image data.
</div>
## Parameters for Credential Generation (dictionary <dfn dictionary>ScopedCredentialParameters</dfn>) ## {#credential-params}
<pre class="idl">
dictionary ScopedCredentialParameters {
required ScopedCredentialType type;
required AlgorithmIdentifier algorithm;
};
</pre>
<div dfn-for="ScopedCredentialParameters">
This dictionary is used to supply additional parameters when creating a new credential.
The <dfn>type</dfn> member specifies the type of credential to be created.
The <dfn>algorithm</dfn> member specifies the cryptographic signature algorithm with which the newly generated credential
will be used, and thus also the type of asymmetric key pair to be generated, e.g., RSA or Elliptic Curve.
</div>
## Additional options for Credential Generation (dictionary <dfn dictionary>ScopedCredentialOptions</dfn>) ## {#credential-options}
<pre class="idl">
dictionary ScopedCredentialOptions {
unsigned long timeoutSeconds;
USVString rpId;
sequence < ScopedCredentialDescriptor > excludeList = [];
WebAuthnExtensions extensions;
};
</pre>
<div dfn-for="ScopedCredentialOptions">
This dictionary is used to supply additional options when creating a new credential. All these parameters are optional.
- The <dfn>timeoutSeconds</dfn> parameter specifies a time, in seconds, that the caller is willing to wait for the call to
complete. This is treated as a hint, and may be overridden by the platform.
- The <dfn>rpId</dfn> parameter explicitly specifies the RP ID that the credential should be associated with. If it is
omitted, the RP ID will be set to the <a link-for='web'>current settings object</a>'s <a link-for='web'>origin</a>.
- The <dfn>excludeList</dfn> parameter is intended for use by <a>[RPS]</a> that wish to limit the creation of multiple
credentials for the same account on a single authenticator. The platform is requested to return an error if the new
credential would be created on an authenticator that also contains one of the credentials enumerated in this parameter.
- The <dfn>extensions</dfn> parameter contains additional parameters requesting additional processing by the client and
authenticator. For example, the caller may request that only authenticators with certain capabilities be used to create
the credential, or that additional information be returned in the attestation statement. Alternatively, the caller may
specify an additional message that they would like the authenticator to display to the user. Extensions are defined in
[[#extensions]].
</div>
## Web Authentication Assertion (interface <dfn interface>WebAuthnAssertion</dfn>) ## {#iface-assertion}
<pre class="idl">
[SecureContext]
interface WebAuthnAssertion {
readonly attribute ScopedCredential credential;
readonly attribute ArrayBuffer clientData;
readonly attribute ArrayBuffer authenticatorData;
readonly attribute ArrayBuffer signature;
};
</pre>
Scoped credentials produce a cryptographic signature that provides proof of possession of a private key as well as evidence of
user consent to a specific transaction. The structure of these signatures is defined as follows.
<div dfn-for="WebAuthnAssertion">
The <dfn>credential</dfn> member represents the credential that was used to generate this assertion.
The <dfn>clientData</dfn> member contains the parameters sent to the authenticator by the client, in serialized form. See
[[#sec-client-data]] for the format of this parameter and how it is generated.
The <b><em>authenticatorData</em></b> member contains the serialized data returned by the authenticator. See
[[#sec-authenticator-data]].
The <dfn>signature</dfn> member contains the raw signature returned from the authenticator. See
[[#authenticator-signature]].
</div>
## Additional options for Assertion Generation (dictionary <dfn dictionary>AssertionOptions</dfn>) ## {#assertion-options}
<pre class="idl">
dictionary AssertionOptions {
unsigned long timeoutSeconds;
USVString rpId;
sequence < ScopedCredentialDescriptor > allowList = [];
WebAuthnExtensions extensions;
};
</pre>
<div dfn-for="AssertionOptions">
This dictionary is used to supply additional options when generating an assertion. All these parameters are optional.
- The optional <dfn>timeoutSeconds</dfn> parameter specifies a time, in seconds, that the caller is willing to wait for the
call to complete. This is treated as a hint, and may be overridden by the platform.
- The optional <dfn>rpId</dfn> parameter specifies the rpId claimed by the caller. If it is omitted, it will be assumed to
be equal to the <a link-for='web'>current settings object</a>'s <a link-for='web'>origin</a>.
- The optional <dfn>allowList</dfn> member contains a list of credentials acceptable to the caller, in order of the caller's
preference.
- The optional <dfn>extensions</dfn> parameter contains additional parameters requesting additional processing by the client
and authenticator. For example, if transaction confirmation is sought from the user, then the prompt string would be
included in an extension. Extensions are defined in a companion specification.
</div>
## WebAuthn Assertion Extensions (dictionary <dfn dictionary>WebAuthnExtensions</dfn>) ## {#iface-assertion-extensions}
<pre class="idl">
dictionary WebAuthnExtensions {
};
</pre>
This is a dictionary containing zero or more extensions as defined in [[#extensions]]. An extension is an additional parameter
that can be passed to the <a>getAssertion()</a> method and triggers some additional processing by the client platform and/or the
authenticator.
If the caller wishes to pass extensions to the platform, it MUST do so by adding one entry per extension to this dictionary
with the extension identifier as the key, and the extension's value as the value (see [[#extensions]] for details).
## Credential Attestation Structure (interface <dfn interface>WebAuthnAttestation</dfn>) ## {#iface-attestation}
<pre class="idl">
[SecureContext]
interface WebAuthnAttestation {
readonly attribute USVString format;
readonly attribute ArrayBuffer clientData;
readonly attribute ArrayBuffer authenticatorData;
readonly attribute any attestation;
};
</pre>
Authenticators must also provide some form of attestation. The basic requirement is that the authenticator can produce, for each
<a>credential public key</a>, attestation information that can be verified by a <a>[RP]</a>. Typically, this information
contains a signature by an attestation private key over the attested <a>credential public key</a> and a challenge, as well as a
certificate or similar information providing provenance information for the <a>attestation public key</a>, enabling a trust
decision to be made. However, if an <a>attestation key pair</a> is not available, then the authenticator MUST perform <a>self
attestation</a> of the <a>credential public key</a> with the corresponding <a>credential private key</a>.
<div dfn-for="WebAuthnAttestation">
The <dfn>format</dfn> member specifies the format of attestation statement contained in this structure. Attestation formats
are defined in [[#attestation-formats]]. This specification supports a number of attestation formats, in
[[#defined-attestation-formats]]. Other attestation formats may be defined in later versions of this specification.
The <dfn>clientData</dfn> member contains the <a>clientDataJSON</a> (see [[#signature-format]]). The exact JSON encoding
must be preserved as the hash (<a>clientDataHash</a>) has been computed over it.
The <b><em>authenticatorData</em></b> member contains the serialized data returned by the authenticator. See
[[#sec-authenticator-data]].
The <dfn>attestation</dfn> element contains the actual <dfn>attestation statement</dfn>. The structure of this object
depends on the <a>attestation format</a>. For more details, see [[#cred-attestation-stmts]].
</div>
This attestation structure is delivered to the <a>[RP]</a> by the [RP]'s script running on the client, using methods outside
the scope of this specification. It contains all the information that the [RP]'s server requires to validate the statement, as
well as to decode and validate the bindings of both the client and authenticator data.
## Supporting Data Structures ## {#supporting-data-structures}
The scoped credential type uses certain data structures that are specified in supporting specifications. These are as follows.
### Client data used in WebAuthn signatures (dictionary <dfn dictionary>ClientData</dfn>) ### {#sec-client-data}
The client data represents the contextual bindings of both the [RP] and the client platform. It is a key-value mapping with
string-valued keys. Values may be any type that has a valid encoding in JSON. Its structure is defined by the following Web IDL.
<pre class="idl">
dictionary ClientData {
required DOMString challenge;
required DOMString origin;
required AlgorithmIdentifier hashAlg;
DOMString tokenBinding;
WebAuthnExtensions extensions;
};
</pre>
<div dfn-for="ClientData">
The <dfn>challenge</dfn> member contains the base64url encoding of the challenge provided by the RP.
The <dfn for="ClientData">origin</dfn> member contains the fully qualified origin of the requester, as provided to the authenticator by
the client, in the syntax defined by [[RFC6454]].
The <dfn>hashAlg</dfn> member specifies the hash algorithm used to compute <a>clientDataHash</a> (see
[[#authenticator-signature]]). Use "S256" for SHA-256, "S384" for SHA384, "S512" for SHA512, and "SM3" for SM3 (see
[[#iana-considerations]]). This algorithm is chosen by the client at its sole discretion.
The <dfn>tokenBinding</dfn> member contains the base64url encoding of the Token Binding ID that this client uses for the
Token Binding protocol when communicating with the [RP]. This can be omitted if no Token Binding has been negotiated between
the client and the [RP].
The optional <dfn>extensions</dfn> member contains additional parameters generated by processing the extensions passed in
by the [RP]. WebAuthn extensions are detailed in Section [[#extensions]].
</div>
This structure is used by the client to compute the following quantities:
: <dfn>clientDataJSON</dfn>
:: This is the UTF-8 encoded JSON serialization [[RFC7159]] of a {{ClientData}} dictionary.
: <dfn>clientDataHash</dfn>
:: This is the hash (computed using <a>hashAlg</a>) of <a>clientDataJSON</a>.
### Credential Type enumeration (enum <dfn enum>ScopedCredentialType</dfn>) ### {#credentialType}
<pre class="idl">
enum ScopedCredentialType {
"ScopedCred"
};
</pre>
<div dfn-for="ScopedCredentialType">
This enumeration defines the valid credential types. It is an extension point; values may be added to it in the future, as
more credential types are defined. The values of this enumeration are used for versioning the WebAuthn assertion and
attestation structures according to the type of the authenticator.
Currently one credential type is defined, namely "<dfn>ScopedCred</dfn>".
</div>
### Unique Identifier for Credential (interface <dfn interface>ScopedCredential</dfn>) ### {#credential-identifier}
<pre class="idl">
[SecureContext]
interface ScopedCredential {
readonly attribute ScopedCredentialType type;
readonly attribute ArrayBuffer id;
};
</pre>
This interface contains the attributes that are returned to the caller when a new credential is created, and can be used later
by the caller to select a credential for use.
<div dfn-for="ScopedCredential">
The <dfn>type</dfn> attribute contains a value of type {{ScopedCredentialType}}, indicating the specification and version
that this credential conforms to.
The <dfn>id</dfn> attribute contains an identifier for the credential, chosen by the platform with help from the
authenticator. This identifier is used to look up credentials for use, and is therefore expected to be globally unique with
high probability across all credentials of the same type, across all authenticators. This API does not constrain the format
or length of this identifier, except that it must be sufficient for the platform to uniquely select a key. For example, an
authenticator without on-board storage may create identifiers that consist of the key material wrapped with a key that is
burned into the authenticator.
</div>
### Credential Descriptor (dictionary <dfn dictionary>ScopedCredentialDescriptor</dfn>) ### {#credential-dictionary}
<pre class="idl">
dictionary ScopedCredentialDescriptor {
required ScopedCredentialType type;
required BufferSource id;
sequence < Transport > transports;
};
</pre>
This dictionary contains the attributes that are specified by a caller when referring to a credential as an input parameter to
the {{makeCredential()}} or {{getAssertion()}} method. It mirrors the fields of the {{ScopedCredential}} object returned by
these methods.
<div dfn-for="ScopedCredentialDescriptor">
The <dfn>type</dfn> attribute contains the type of the credential the caller is referring to.
The <dfn>id</dfn> attribute contains the identifier of the credential that the caller is referring to.
</div>
### Credential Transport enumeration (enum <dfn enum>ExternalTransport</dfn>) ### {#transport}
<pre class="idl">
enum Transport {
"usb",
"nfc",
"ble"
};
</pre>
<div dfn-for="Transport">
Authenticators may communicate with Clients using a variety of transports.
This enumeration defines a hint as to how Clients might communicate with a
particular Authenticator in order to obtain an assertion for a specific
credential. Note that these hints represent the [RP]'s best belief as to
how an Authenticator may be reached. A [RP] may obtain a list of
transports hints from some attestation formats or via some out-of-band
mechanism; it is outside the scope of this specification to define that
mechanism.
<ul>
<li><dfn>usb</dfn> - the respective Authenticator may be contacted over
USB.
<li><dfn>nfc</dfn> - the respective Authenticator may be contacted over
Near Field Communication (NFC).
<li><dfn>ble</dfn> - the respective Authenticator may be contacted over
Bluetooth Smart (Bluetooth Low Energy / BLE).
</ul>
</div>
### Cryptographic Algorithm Identifier (type {{AlgorithmIdentifier}}) ### {#alg-identifier}
A string or dictionary identifying a cryptographic algorithm and optionally a set of parameters for that algorithm. This type is
defined in [[!WebCryptoAPI]].
# WebAuthn Authenticator model # {#authenticator-model}
The API defined in this specification implies a specific abstract functional model for an <a>authenticator</a>. This section
describes the authenticator model. Client platforms may implement and expose this abstract model in any way desired. For
instance, this abstract model does not define specific error codes or methods of returning them; however, it does define error
behavior in terms of the needs of the client. Therefore, specific error codes are mentioned as a means of showing which error
conditions must be distinguishable (or not) from each other in order to enable a compliant and secure client implementation.
The overall requirement is that the behavior of the client's Web Authentication API implementation, when operating on the
authenticators supported by that platform, MUST be indistinguishable from the behavior specified in [[#api]].
In this abstract model, each authenticator stores some number of scoped credentials. Each scoped credential has an identifier
which is unique (or extremely unlikely to be duplicated) among all scoped credentials. Each credential is also associated with a
<a>[RP]</a>, whose identity is represented by a <a>Relying Party Identifier</a> (<a>RP ID</a>).
Each authenticator has an AAGUID, which is a 128-bit identifier that indicates the type (e.g. make and model) of the
authenticator. The AAGUID MUST be chosen by the manufacturer to be identical across all substantially identical authenticators
made by that manufacturer, and different (with probability 1-2<sup>-128</sup> or greater) from the AAGUIDs of all other types of
authenticators. The RP MAY use the AAGUID to infer certain properties of the authenticator, such as certification level and
strength of key protection, using information from other sources.
## Authenticator operations ## {#authenticator-ops}
A client must connect to an authenticator in order to invoke any of the operations of that authenticator. This connection
defines an authenticator session. An authenticator must maintain isolation between sessions. It may do this by only allowing one
session to exist at any particular time, or by providing more complicated session management.
The following operations can be invoked by the client in an authenticator session.
### The <dfn>authenticatorMakeCredential</dfn> operation ### {#op-make-cred}
This operation must be invoked in an authenticator session which has no other operations in progress. It takes the following
input parameters:
- The SHA-256 hash of the caller's RP ID, as determined by the user agent and the client.
- The <a>clientDataHash</a>, which is the hash of the serialized {{ClientData}} and is provided by the client.
- The {{Account}} information provided by the [RP].
- The {{ScopedCredentialType}} and cryptographic parameters requested by the [RP], with the cryptographic algorithms normalized
as per the procedure in [[WebCryptoAPI#algorithm-normalization-normalize-an-algorithm]].
- A list of {{ScopedCredential}} objects provided by the [RP] with the intention that, if any of these are known to the
authenticator, it should not create a new credential.
- Extension data created by the client based on the extensions requested by the [RP].
When this operation is invoked, the authenticator must perform the following procedure:
- Check if all the supplied parameters are syntactically well-formed and of the correct length. If not, return an error code
equivalent to UnknownError and terminate the operation.
- Check if at least one of the specified combinations of {{ScopedCredentialType}} and cryptographic parameters is supported. If
not, return an error code equivalent to NotSupportedError and terminate the operation.
- Check if a credential matching any of the supplied {{ScopedCredential}} identifiers is present on this authenticator. If so,
return an error code equivalent to NotAllowedError and terminate the operation.
- Prompt the user for consent to create a new credential. The prompt for obtaining this consent is shown by the authenticator
if it has its own output capability, or by the user agent otherwise. If the user denies consent, return an error code
equivalent to NotAllowedError and terminate the operation.
- Once user consent has been obtained, generate a new credential object:
- Generate a set of cryptographic keys using the most preferred combination of {{ScopedCredentialType}} and cryptographic
parameters supported by this authenticator.
- Generate an identifier for this credential, such that this identifier is globally unique with high probability across all
credentials with the same type across all authenticators.
- Associate the credential with the specified RP ID hash and the user's account identifier {{Account/id}}.
- Delete any older credentials with the same RP ID hash and {{Account/id}} that are stored locally in the authenticator.
- If any error occurred while creating the new credential object, return an error code equivalent to UnknownError and terminate
the operation.
- Process all the supported extensions requested by the client, and generate an attestation statement. If no authority key is
available to sign such an attestation statement, then the authenticator performs <a>self attestation</a> of the credential
with its own private key. For more details on attestation, see [[#cred-attestation-stmts]].
On successful completion of this operation, the authenticator must return the following to the client:
- The type and unique identifier of the new credential.
- The new <a>credential public key</a>.
- The fields of the attestation structure {{WebAuthnAttestation}}, including information about the attestation format used.
### The <dfn>authenticatorGetAssertion</dfn> operation ### {#op-get-assertion}
This operation must be invoked in an authenticator session which has no other operations in progress. It takes the following
input parameters:
- The SHA-256 hash of the caller's RP ID, as determined by the user agent and the client.
- The <a>clientDataHash</a>, which is the hash of the serialized {{ClientData}} and is provided by the client.
- A list of credentials acceptable to the [RP] (possibly filtered by the client).
- Extension data created by the client based on the extensions requested by the [RP].