/
index.bs
2434 lines (1808 loc) · 132 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-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>
# 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 web 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:
* 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 discreet 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):
- User navigates to example.com on their laptop, is guided through a flow to create and register a credential on their phone.
- 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.
: HTML5
:: The concept of <dfn for='web'>origin</dfn> and the <dfn>Navigator</dfn> interface are defined in [[!HTML5]].
: 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 normalizing an algorithm are defined in
[[WebCryptoAPI#algorithm-dictionary]].
:: The <dfn dictionary>CryptoKey</dfn> type for representing cryptographic keys is defined in
[[WebCryptoAPI#cryptokey-interface]].
:: The <dfn dictionary>JsonWebKey</dfn> dictionary for representing cryptographic keys is defined in
[[WebCryptoAPI#JsonWebKey-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, public keys, signature counters, etc.
See also <a>attestation format</a>, and <a>attestation type</a>.
: <dfn>Attestation Certificate</dfn>
:: A X.509 Certificate for a key pair used by an <a>Authenticator</a> to attest to its manufacture and capabilities. The
<a>Authenticator</a> uses the attestation private key to sign the <a>[RP]</a>-specific public key (and additional data) it
generates and returns upon invocation via the <a>authenticatorMakeCredential</a> operation.
: <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>eTLD+1</dfn>
:: Also known as a <em>Registered Domain</em> [[PSL]], an eTLD+1 is an <em>effective Top-Level Domain Name</em> (eTLD), plus the
next domain name label, proceeding from right to left. An eTLD is also known as a <em>public suffix</em> [[RFC7719]].
: <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 others.
: <dfn>Relying Party Identifier</dfn>
: <dfn>RP ID</dfn>
:: A Relying Party Identifier is derived from a <a>[RP]</a>'s web origin's hostname by computing the hostname's <a>eTLD+1</a>.
: <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]. who
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 web 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 web origins.
The client facilitates these security measures by providing correct web 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 Navigator interface:
<pre class="idl">
partial interface Navigator {
readonly attribute WebAuthentication authentication;
};
</pre>
## <dfn interface>WebAuthentication</dfn> Interface ## {#iface-credential}
<pre class="idl">
interface WebAuthentication {
Promise < ScopedCredentialInfo > makeCredential (
Account accountInformation,
sequence < ScopedCredentialParameters > cryptoParameters,
BufferSource attestationChallenge,
optional CredentialOptions 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.
- 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 {{CredentialOptions/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 {{CredentialOptions/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.
3. Set |callerOrigin| to the <a link-for='web'>origin</a> of the caller. Derive the RP ID from |callerOrigin| by computing the
"public suffix + 1" or "PS+1" (which is also referred to as the "Effective Top-Level Domain plus One" or "<a>eTLD+1</a>")
part of |callerOrigin| [[PSL]]. Let |rpId| be the lowercase form of this RP ID. Set |rpIdHash| to the SHA-256 hash of the
UTF-8 encoding of |rpId|.
4. Process each element of <a>cryptoParameters</a> using the following steps, to produce a new sequence `normalizedParameters`:
- Let |current| be the currently selected element of <a>cryptoParameters</a>.
- If `current.type` does not contain a {{CredentialType}} supported by this implementation, then stop processing |current|
and move on to the next element in <a>cryptoParameters</a>.
- Let `normalizedAlgorithm` be the result of normalizing an algorithm using the procedure defined in [[!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 <a>cryptoParameters</a>.
- Add a new object of type {{ScopedCredentialParameters}} to `normalizedParameters`, with |type| set to `current.type` and
|algorithm| set to `normalizedAlgorithm`.
5. If <a>excludeList</a> is undefined, set it to the empty list.
6. If {{CredentialOptions/extensions}} was specified, process any extensions supported by this client platform, to produce the
extension data that needs to be sent to the authenticator. Call this data |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>, <a>accountInformation</a>, `normalizedParameters`,
<a>excludeList</a> and |clientExtensions| as parameters. Add a corresponding entry to |issuedRequests|.
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.
10. Resolve |promise| with a <a>DOMException</a> whose name is "NotFoundError", 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.
3. Set |callerOrigin| to the <a link-for='web'>origin</a> of the caller. Derive the RP ID from |callerOrigin| by computing the
"public suffix + 1" or "PS+1" (which is also referred to as the "Effective Top-Level Domain plus One" or "<a>eTLD+1</a>")
part of |callerOrigin| [[PSL]]. Let |rpId| be the lowercase form of this RP ID. Set |rpIdHash| to the SHA-256 hash of the
UTF-8 encoding of |rpId|.
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. Call this data |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 <a>allowList</a> is undefined or empty, let |credentialList| be an empty list. Otherwise, execute a platform-specific
procedure to determine which, if any, credentials listed in <a>allowList</a> 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.
- If the above filtering process concludes that none of the credentials on <a>allowList</a> 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. Resolve |promise| with a <a>DOMException</a> whose name is "NotFoundError", 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.
## <dfn interface>ScopedCredentialInfo</dfn> Interface ## {#iface-credentialInfo}
<pre class="idl">
interface ScopedCredentialInfo {
readonly attribute Credential credential;
readonly attribute CryptoKey publicKey;
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 a unique identifier for the credential represented by this object.
The <dfn>publicKey</dfn> attribute contains the public key associated with the credential, represented as a
CryptoKey object as defined in [[WebCryptoAPI#cryptokey-interface]].
The <dfn>attestation</dfn> attribute contains a key attestation statement returned by the authenticator. This provides
information about the credential and the authenticator it is held in, such as 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;
DOMString name;
DOMString id;
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>name</dfn> member contains a detailed name for the account, such as "john.p.smith@example.com".
The <dfn>id</dfn> member contains an identifier for the account, stored for the use of the [RP]. This is not meant to be
displayed to the user.
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 CredentialType 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>CredentialOptions</dfn>) ## {#credential-options}
<pre class="idl">
dictionary CredentialOptions {
unsigned long timeoutSeconds;
sequence < CredentialDescription > excludeList;
WebAuthnExtensions extensions;
};
</pre>
<div dfn-for="CredentialOptions">
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>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>
## WebAuthn Assertion (interface <dfn interface>WebAuthnAssertion</dfn>) ## {#iface-assertion}
<pre class="idl">
interface WebAuthnAssertion {
readonly attribute Credential credential;
readonly attribute ArrayBuffer clientData;
readonly attribute ArrayBuffer level2Data;
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>level2Data</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;
sequence < CredentialDescription > 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>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 wants to pass extensions to the platform, it SHOULD 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 [[#signature-format]] for details).
## Credential Attestation Statement (interface <dfn interface>WebAuthnAttestation</dfn>) ## {#iface-attestation}
<pre class="idl">
interface WebAuthnAttestation {
readonly attribute USVString format;
readonly attribute ArrayBuffer clientData;
readonly attribute ArrayBuffer level2Data; // was authenticatorData
readonly attribute any level1Data; // was statement
};
</pre>
Authenticators also provide some form of attestation. The basic requirement is that the authenticator can produce, for each
credential public key, attestation information that can be verified by a <a>[RP]</a>. Typically, this information contains a
signature by an attesting key over the attested public key and a challenge, as well as a certificate or similar information
providing provenance information for the attesting key, enabling a trust decision to be made.
<div dfn-for="WebAuthnAttestation">
The <dfn>format</dfn> member specifies the format of attestation level1Data 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>level2Data</em></b> member contains the serialized data returned by the authenticator. See
[[#sec-authenticator-data]].
The <dfn>level1Data</dfn> element contains the actual attestation statement. The structure of this object depends on the
attestation format. For more details, see [[#cred-attestation-stmts]].
</div>
This attestation statement 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 level1Data, 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 DOMString rpId;
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>origin</dfn> member contains the fully qualified web origin of the requester, as provided to the authenticator by
the client, in the syntax defined by [[RFC6454]].
The <dfn>rpId</dfn> member contains the RP ID of the requester, as computed by the client.
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>CredentialType</dfn>) ### {#credentialType}
<pre class="idl">
enum CredentialType {
"ScopedCred"
};
</pre>
<div dfn-for="CredentialType">
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 statement 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>Credential</dfn>) ### {#credential-identifier}
<pre class="idl">
interface Credential {
readonly attribute CredentialType 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="Credential">
The <dfn>type</dfn> attribute contains a value of type {{CredentialType}}, 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>CredentialDescription</dfn>) ### {#credential-dictionary}
<pre class="idl">
dictionary CredentialDescription {
required CredentialType type;
required BufferSource id;
};
</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 {{Credential}} object returned by these methods.
<div dfn-for="CredentialDescription">
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>
### 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. However,
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 {{CredentialType}} 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 {{Credential}} 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 obtains user consent for creating 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. Once user
consent is obtained, the authenticator generates the appropriate cryptographic keys and creates a new credential. It also
generates an identifier for the credential, such that this identifier is globally unique with high probability across all
credentials with the same type across all authenticators. It then associates the credential with the specified RP ID hash such
that it will be able to retrieve the RP ID hash later, given the credential ID. Finally, it generates an attestation statement
that describes its own attributes as well as some attributes of the credential. For more details on attestation, see
[[#cred-attestation-stmts]].
On successful completion of this operation, the authenticator returns the following to the client:
- The type and unique identifier of the new credential.
- The public key associated with the new credential.
- The attestation statement, including information about the attestation format used.
If the user refuses consent, the authenticator returns an appropriate error status to the client.
### 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].
When this method is invoked, the authenticator allows the user to select a credential from among the credentials associated with
that [RP] (as determined by an exact match of the RP ID hash) and matching the specified criteria, then obtains user consent
for using that credential. The prompt for obtaining this consent may be shown by the authenticator if it has its own output
capability, or by the user agent otherwise. Once a credential is selected and user consent is obtained, the authenticator
computes a cryptographic signature using the credential's private key and constructs an assertion signature as specified in
[[#signature-format]].
On successful completion, the authenticator returns to the user agent:
- The identifier of the credential used to generate the signature.
- The <a>level2Data</a> used to generate the signature.
- The signature itself.
If the authenticator cannot find any credential corresponding to the specified [RP] that matches the specified criteria, it
terminates the operation and returns an error.
If the user refuses consent, the authenticator returns an appropriate error status to the client.
### The <dfn>authenticatorCancel</dfn> operation ### {#op-cancel}
This operation takes no input parameters and returns no result.
When this operation is invoked by the client in an authenticator session, it has the effect of terminating any
<a>authenticatorMakeCredential</a> or <a>authenticatorGetAssertion</a> operation currently in progress in that authenticator
session. The authenticator stops prompting for, or accepting, any user input related to authorizing the canceled operation. The
client ignores any further responses from the authenticator for the canceled operation.
This operation is ignored if it is invoked in an authenticator session which does not have an <a>authenticatorMakeCredential</a>
or <a>authenticatorGetAssertion</a> operation currently in progress.
## Signature Format ## {#signature-format}
WebAuthn signatures are bound to various contextual data. These data are observed, and added at different levels of the stack as
a signature request passes from the server to the authenticator. In verifying a signature, the server checks these bindings
against expected values.
The components of a system using WebAuthn can be divided into three layers:
1. The <a>[RP]</a> (RP), which uses the WebAuthn services. The RP consists of a server component and a web-application running
in a browser.
2. The <a>WebAuthn Client</a> platform, which consists of the User Agent and the OS and device on which it executes.
3. The <a>Authenticator</a> itself, which provides key management and cryptographic signatures. This may be embedded in the
WebAuthn client, or housed in a separate device entirely. In the latter case, the interface between the WebAuthn client and
the authenticator is a separately-defined protocol.
This specification defines the common signature format shared by all the above layers. This includes how the different
contextual bindings are encoded, signed over, and delivered to the RP.
The goals of this design can be summarized as follows.
- The scheme for generating signatures should accommodate cases where the link between the client platform and authenticator
is very limited, in bandwidth and/or latency. Examples include Bluetooth Low Energy and Near-Field Communication.
- The data processed by the authenticator should be small and easy to interpret in low-level code. In particular, authenticators
should not have to parse high-level encodings such as JSON.
- Both the client platform and the authenticator should have the flexibility to add contextual bindings as needed.
- The design aims to reuse as much as possible of existing encoding formats in order to aid adoption and implementation.
The contextual bindings are divided in two: Those added by the RP or the client platform, referred to as client data; and those
added by the authenticator, referred to as the authenticator data. The client data must be signed over, but an authenticator is
otherwise not interested in its contents. To save bandwidth and processing requirements on the authenticator, the client
platform hashes the {{ClientData}} and sends only the result to the authenticator. The authenticator signs over the combination
of this <a>clientDataHash</a>, and its own authenticator data.
### Level2Data ### {#sec-authenticator-data}
The level2Data encodes contextual bindings made by the <a>authenticator</a> itself. These bindings are typically controlled
(generated or at least verified) by the authenticator itself, and derive their trust from the [RP]'s assessment of the security
of the authenticator. The level2Data has a compact but extensible encoding. This is desired since authenticators can be
devices with limited capabilities and low power requirements, with much simpler software stacks than the client platform
components.
Note: Some authenticators cannot fully control the level2Data. This is indicated in the related metadata to such authenticator.
The encoding of authenticator data is a byte array of 37 bytes or more, as follows.
<table class="complex data longlastcol">
<tr>
<th>Length (in bytes)</th>
<th>Description</th>
</tr>
<tr>
<td>32</td>
<td>
SHA-256 hash of the RP ID associated with the credential.
</td>
</tr>
<tr>
<td>1</td>
<td>
Flags (bit 0 is the least significant bit):
- Bit 0: Test of User Presence (`TUP`) result.
- Bits 1-5: Reserved for future use (`RFU`).
- Bit 6: Attestation data included (`AT`). Indicates whether the authenticator added attestation data.
- Bit 7: Extension data included (`ED`). Indicates if the authenticator data has extensions.
</td>
</tr>
<tr>
<td>4</td>
<td>Signature counter (`signCount`), 32-bit unsigned big-endian integer.</td>
</tr>
<tr>
<td>variable (if present)</td>
<td>
Attestation data (if present). See below for details. Its length n depends on the length of the public key and
credential ID of the credential being attested.
</td>
</tr>
<tr>
<td>variable (if present)</td>
<td>
Extension-defined authenticator data. This is a CBOR [[RFC7049]] map with extension identifiers as keys, and
extension authenticator data values as values. See [[#extensions]] for details.
</td>
</tr>
</table>
Note that the RP ID hash is originally received from the client when the credential is created, and again when an assertion is
generated. However, it differs from other client data in some important ways. First, unlike the client data, the RP ID of a
credential does not change between operations but instead remains the same for the lifetime of that credential. Secondly, it is