Skip to content

Commit fbb9a04

Browse files
james-d-elliottjames-d-elliott
authored
docs: add additional documentation (#573)
* docs: add additional documentation * docs: fix lints
1 parent 4c8d30f commit fbb9a04

3 files changed

Lines changed: 126 additions & 39 deletions

File tree

‎README.md‎

Lines changed: 101 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -41,25 +41,30 @@ While we strive to avoid such changes and strive to notify users they may be una
4141

4242
## Quickstart
4343

44-
`go get github.com/go-webauthn/webauthn` and initialize it in your application with basic configuration values.
44+
First run `go get github.com/go-webauthn/webauthn` and initialize it in your application with basic configuration
45+
values.
4546

46-
Make sure your `user` model is able to handle the interface functions laid out in `webauthn/types.go`. This means also
47-
supporting the storage and retrieval of the credential and authenticator structs in `webauthn/credential.go` and
48-
`webauthn/authenticator.go`, respectively.
47+
Make sure your `user` model is able to handle the interface functions laid out in the
48+
[webauthn.User](https://pkg.go.dev/github.com/go-webauthn/webauthn/webauthn#User) interface. This means also
49+
supporting the storage and retrieval of the [webauthn.Credential] struct which can be encoded fairly easily.
4950

5051
## Notable Changes
5152

5253
The notable breaking changes made by this library are documented in the [breaking changes](BREAKING.md) documentation.
5354

54-
## Documentation
55+
## Examples
5556

56-
The intent is to move all documentation into the [go docs], and this is the location we'd recommend checking.
57+
The examples are documented in the [go docs -> webauthn -> examples].
5758

58-
## Examples
59+
## Documentation
60+
61+
The intent is to move all documentation into the [go docs], and a good starting place is the [go docs -> webauthn]
62+
location.
5963

60-
The examples are documented in the [go docs].
64+
### Credential Record
6165

62-
## Credential Record
66+
**_Important:_** It is considered critical that implementers carefully read the [webauthn.Credential] struct
67+
documentation as part of the implementation process.
6368

6469
The WebAuthn Level 3 specification describes the Credential Record which includes several required and optional elements
6570
that you should store for. See [§ 4 Terminology](https://www.w3.org/TR/webauthn-3/#credential-record) for details.
@@ -69,21 +74,22 @@ This section describes this element.
6974
The fields listed in the specification have corresponding fields in the [webauthn.Credential] struct. See the below
7075
table for more information. We also include JSON mappings for those that wish to just store these values as JSON.
7176

72-
| Specification Field | Library Field | JSON Field | Notes |
73-
|:-------------------------:|:--------------------------:|:--------------------------:|:-----------------------------------------------------------------------------------------:|
74-
| type | N/A | N/A | This field is always `publicKey` for WebAuthn |
75-
| id | ID | id | |
76-
| publicKey | PublicKey | publicKey | |
77-
| attestationFormat | AttestationType | attestationType | This field is currently named incorrectly and this will be corrected. |
78-
| signCount | Authenticator.SignCount | authenticator.signCount | |
79-
| transports | Transport | transport | |
80-
| uvInitialized | Flags.UserVerified | flags.userVerified | |
81-
| backupEligible | Flags.BackupEligible | flags.backupEligible | |
82-
| backupState | Flags.BackupState | flags.backupState | |
83-
| attestationObject | Attestation.Object | attestation.object | This field is a composite of the attestationObject and the relevant values to validate it |
84-
| attestationClientDataJSON | Attestation.ClientDataJSON | attestation.clientDataJSON | |
85-
86-
### Flags
77+
| Specification Field | Library Field | JSON Field | Notes |
78+
|:-------------------------:|:--------------------------:|:--------------------------:|:-----------------------------------------------------------------------------------------------------------------------------------------------:|
79+
| type | N/A | N/A | This field is always `public-key` for WebAuthn. |
80+
| id | ID | id | |
81+
| publicKey | PublicKey | publicKey | |
82+
| attestationFormat | AttestationType | attestationType | This field is currently named incorrectly and this will be corrected. |
83+
| signCount | Authenticator.SignCount | authenticator.signCount | |
84+
| transports | Transport | transport | |
85+
| uvInitialized | Flags.UserVerified | flags.userVerified | |
86+
| backupEligible | Flags.BackupEligible | flags.backupEligible | |
87+
| backupState | Flags.BackupState | flags.backupState | |
88+
| N/A | Attestation | attestation | This field is a composite object containing fields from the Credential Record and additional fields to assist in validation of this Credential. |
89+
| attestationObject | Attestation.Object | attestation.object | |
90+
| attestationClientDataJSON | Attestation.ClientDataJSON | attestation.clientDataJSON | |
91+
92+
#### Flags
8793

8894
It's important to note that the recommendations and requirements for flag storage have changed over the course of the
8995
evolution of the WebAuthn specification. We at the present time only make the flags classified like this available for
@@ -98,13 +104,13 @@ to retrieve the raw value and
98104
restore it; and instead of using the individual flags to store the value store the Protocol Value, and only store the
99105
individual flags as a means to perform compliance related decisions.
100106

101-
### Storage
107+
#### Storage
102108

103109
It is also important to note that restoring the [webauthn.Credential] with the correct values will likely affect the
104110
validity of the [webauthn.Credential], i.e. if some values are not restored the [webauthn.Credential] may fail
105111
validation in this scenario.
106112

107-
### Verification
113+
#### Verification
108114

109115
As long as the [webauthn.Credential] struct has exactly the same values when restored the [Credential Verify] function
110116
can be leveraged to verify the credential against the [metadata.Provider]. This can be either done during registration,
@@ -118,6 +124,69 @@ At this time no tooling exists to verify the credential automatically outside th
118124
this is considered domain logic and beyond the scope of what we provide documentation for; we just provide the necessary
119125
tooling to implement this yourself.
120126

127+
## Support
128+
129+
This section indicates various support statuses for specific elements of the spec. The level column indicates the spec
130+
level this library currently supports for that statement format by the first number, and the number in parenthesis
131+
represents when the format was introduced into the spec.
132+
133+
### Attestation Format
134+
135+
| Format | Identifier | Supported | Level |
136+
|:-------------------------------------------------------------------------------------------------------------------------:|:-------------------:|:-----------:|:-----:|
137+
| [§8.2 Packed Attestation Statement Format](https://www.w3.org/TR/webauthn/#sctn-packed-attestation) | `packed` | Yes | 3 (1) |
138+
| [§8.3 TPM Attestation Statement Format](https://www.w3.org/TR/webauthn/#sctn-tpm-attestation) | `tpm` | Yes | 3 (1) |
139+
| [§8.4 Android Key Attestation Statement Format](https://www.w3.org/TR/webauthn/#sctn-android-key-attestation) | `android-key` | Yes | 3 (1) |
140+
| [§8.5 Android SafetyNet Attestation Statement Format](https://www.w3.org/TR/webauthn/#sctn-android-safetynet-attestation) | `android-safetynet` | Yes | 3 (1) |
141+
| [§8.6 FIDO U2F Attestation Statement Format](https://www.w3.org/TR/webauthn/#sctn-fido-u2f-attestation) | `fido-u2f` | Yes | 3 (1) |
142+
| [§8.7 None Attestation Statement Format](https://www.w3.org/TR/webauthn/#sctn-none-attestation) | `none` | Yes | 3 (1) |
143+
| [§8.8 Apple Anonymous Attestation Statement Format](https://www.w3.org/TR/webauthn/#sctn-apple-anonymous-attestation) | `apple` | Yes | 3 (2) |
144+
| [§8.9 Compound Attestation Statement Format](https://www.w3.org/TR/webauthn-3/#sctn-compound-attestation) | `compound` | In Progress | 3 (3) |
145+
146+
### Extensions
147+
148+
Standardized and Specification Listed Extensions:
149+
150+
| Extension | Identifier | Supported (Registration) | Supported (Authentication) | Level |
151+
|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:--------------:|:------------------------:|:--------------------------:|:-----:|
152+
| [§10.1.1 FIDO AppID Extension](https://www.w3.org/TR/webauthn/#sctn-appid-extension) | `appid` | N/A[^2] | Yes (manual) | 3 (1) |
153+
| [§10.1.2 FIDO AppID Exclusion Extension](https://www.w3.org/TR/webauthn/#sctn-appid-exclude-extension) | `appidExclude` | Yes (manual) | N/A[^1] | 3 (1) |
154+
| [§10.1.3 Credential Properties Extension](https://www.w3.org/TR/webauthn-3/#sctn-authenticator-credential-properties-extension) | `credProps` | Yes (manual) | N/A[^1] | 3 (2) |
155+
| [§10.1.5 Large Blob Storage Extension](https://www.w3.org/TR/webauthn/#sctn-large-blob-extension) | `largeBlob` | Yes (manual) | Yes (manual) | 3 (2) |
156+
157+
CTAP2 Extensions Which Are Largely unsupported:
158+
159+
| Extension | Identifier | Supported (Registration) | Supported (Authentication) |
160+
|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:---------------------:|:------------------------:|:--------------------------:|
161+
| [Credential Protection Extension](https://fidoalliance.org/specs/fido-v2.2-ps-20250714/fido-client-to-authenticator-protocol-v2.2-ps-20250714.html#sctn-credProtect-extension) | `credProtect` | Yes (manual) | N/A[^1] |
162+
| [Credential Blob Extension](https://fidoalliance.org/specs/fido-v2.2-ps-20250714/fido-client-to-authenticator-protocol-v2.2-ps-20250714.html#sctn-credBlob-extension) | `credBlob` | Yes (manual) | Yes (manual) |
163+
| [Large Blob Key Extension](https://fidoalliance.org/specs/fido-v2.2-ps-20250714/fido-client-to-authenticator-protocol-v2.2-ps-20250714.html#sctn-largeBlobKey-extension) | `largeBlobKey` | Yes (manual) | Yes (manual) |
164+
| [Minimum PIN Length Extension](https://fidoalliance.org/specs/fido-v2.2-ps-20250714/fido-client-to-authenticator-protocol-v2.2-ps-20250714.html#sctn-minpinlength-extension) | `minPinLength` | Yes (manual) | Yes (manual) |
165+
| [PIN Complexity Extension](https://fidoalliance.org/specs/fido-v2.2-ps-20250714/fido-client-to-authenticator-protocol-v2.2-ps-20250714.html#sctn-pincomplexitypolicy-extension) | `pinComplexityPolicy` | Yes (manual) | N/A[^1] |
166+
| [HMAC Secret Extension](https://fidoalliance.org/specs/fido-v2.2-ps-20250714/fido-client-to-authenticator-protocol-v2.2-ps-20250714.html#sctn-hmac-secret-extension) | `hmac-secret` | Yes (manual) | Yes (manual) |
167+
| [HMAC Secret MakeCredential Extension](https://fidoalliance.org/specs/fido-v2.2-ps-20250714/fido-client-to-authenticator-protocol-v2.2-ps-20250714.html#sctn-hmac-secret-make-cred-extension) | `hmac-secret-mc` | N/A[^2] | Yes (manual) |
168+
| [Third-Party Payment Authentication Extension](https://fidoalliance.org/specs/fido-v2.2-ps-20250714/fido-client-to-authenticator-protocol-v2.2-ps-20250714.html#sctn-thirdPartyPayment-extension) | `thirdPartyPayment` | Yes (manual) | Yes (manual) |
169+
170+
[^1]: This extension is only applicable during Registration.
171+
[^2]: This extension is only applicable during Authentication.
172+
173+
Extensions that have been deprecated and removed from the spec. The deprecated level is the first spec level that did
174+
not include the extension. These are all technically supported by the extensions map, but have no official support from
175+
this library, and are most likely not supported by either browsers or authenticators.
176+
177+
These extensions often either were excluded due to privacy or security concerns, were introduced into the core of the
178+
spec as legitimate inputs outside of extensions, or never received support from browsers or authenticators.
179+
180+
| Format | Identifier | Level (Added) | Level (Deprecated) |
181+
|:-----------------------------------------------------------------------------------------------------------------------------------------:|:---------------------:|:-------------:|:------------------:|
182+
| [Generic Transaction Authorization Extension](https://www.w3.org/TR/webauthn-1/#sctn-generic-txauth-extension) | `txAuthGeneric` | 1 | 2 |
183+
| [Authenticator Selection Extension](https://www.w3.org/TR/webauthn-1/#sctn-authenticator-selection-extension) | `authnSel` | 1 | 2 |
184+
| [Supported Extensions Extension](https://www.w3.org/TR/webauthn-1/#sctn-supported-extensions-extension) | `exts` | 1 | 2 |
185+
| [User Verification Index Extension](https://www.w3.org/TR/webauthn-1/#sctn-uvi-extension) | `uvi` | 1 | 2 |
186+
| [Location Extension](https://www.w3.org/TR/webauthn-1/#sctn-location-extension) | `loc` | 1 | 2 |
187+
| [User Verification Method Extension](https://www.w3.org/TR/webauthn-1/#sctn-uvm-extension) | `uvm` | 1 | 3 |
188+
| [Biometric Authenticator Performance Bounds Extension](https://www.w3.org/TR/webauthn-1/#sctn-authenticator-biometric-criteria-extension) | `biometricPerfBounds` | 1 | 2 |
189+
121190
## Acknowledgements
122191

123192
We graciously acknowledge the original authors of this library [github.com/duo-labs/webauthn] for their amazing
@@ -129,4 +198,9 @@ Without their amazing work this library could not exist.
129198
[webauthn.Credential]: https://pkg.go.dev/github.com/go-webauthn/webauthn/webauthn#Credential
130199
[metadata.Provider]: https://pkg.go.dev/github.com/go-webauthn/webauthn/metadata#Provider
131200
[Credential Verify]: https://pkg.go.dev/github.com/go-webauthn/webauthn/webauthn#Credential.Verify
132-
[go docs]: https://pkg.go.dev/github.com/go-webauthn/webauthn/webauthn
201+
202+
[go docs]: https://pkg.go.dev/github.com/go-webauthn/webauthn
203+
204+
[go docs -> webauthn]: https://pkg.go.dev/github.com/go-webauthn/webauthn/webauthn
205+
206+
[go docs -> webauthn -> examples]: https://pkg.go.dev/github.com/go-webauthn/webauthn/webauthn#pkg-examples

0 commit comments

Comments
 (0)