Skip to content

Commit 976bd8e

Browse files
AlfioEmanueleFrestaAlfioEmanueleFresta
authored
refactor(examples): unify, simplify, group examples (#194)
Stacked on #193. Six small commits that unify and simplify `examples/`. - Shared helpers in `examples/common/` (`setup_logging`, UV/cable update handlers, `retry_user_errors!` macro, prompt utilities). 16 examples shed their inline copies. - JSON-first WebAuthn: `webauthn_json_hid` becomes the canonical `webauthn_hid`. `webauthn_nfc` and `webauthn_cable` now consume and emit JSON per the WebAuthn IDL too. - Naming consistency: `cred_management_hid.rs`, `device_selection_hid.rs`, `prf_replay.rs` (was `prf_test.rs`). - Folder layout: `examples/{ceremony,features,management}/` with explicit `[[example]]` entries; `cargo run --example <name>` invocations are unchanged. Net diff: -968 LOC across the example set. Side effect: fixes a pre-existing off-by-bound in `cred_management` (the credential-selection prompt was bounded against `options.len()` instead of `credlist.len()`). ## Test plan - [x] `cargo fmt --check` - [x] `cargo clippy --workspace --all-targets --all-features -- -D warnings` - [x] `cargo build --examples` with default, `nfc-backend-pcsc`, `nfc-backend-libnfc` - [ ] Smoke test against HID authenticator - [ ] Smoke test against NFC reader (PCSC backend)
1 parent 26326d0 commit 976bd8e

23 files changed

Lines changed: 872 additions & 1837 deletions

‎README.md‎

Lines changed: 19 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -54,34 +54,43 @@ Validating the relying party ID against the calling origin requires the [Public
5454

5555
## Example programs
5656

57-
After cloning, you can try out [one of the libwebauthn examples](libwebauthn/examples):
57+
Examples live in [`libwebauthn/examples/`](libwebauthn/examples) and are grouped by purpose:
58+
`ceremony/` for register and authenticate flows, `features/` for per-feature demos
59+
(extensions, preflight, PRF, device selection), and `management/` for CTAP2 admin
60+
operations. All examples share helpers from `examples/common/`.
5861

5962
```
6063
$ cd libwebauthn
6164
$ git submodule update --init
6265
```
6366

64-
| Transport | FIDO U2F | WebAuthn (FIDO2) |
65-
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
66-
| **USB (HID)** | `cargo run --example u2f_hid` | `cargo run --example webauthn_hid`<br>`cargo run --example webauthn_json_hid` |
67-
| **Bluetooth (BLE)** | `cargo run --example u2f_ble` | — |
68-
| **NFC** [^nfc] | `cargo run --features nfc-backend-pcsc --example u2f_nfc`<br>`cargo run --features nfc-backend-libnfc --example u2f_nfc` | `cargo run --features nfc-backend-pcsc --example webauthn_nfc`<br>`cargo run --features nfc-backend-libnfc --example webauthn_nfc` |
69-
| **Hybrid (caBLE v2)** | — | `cargo run --example webauthn_cable` |
67+
The basic ceremony examples (register + authenticate) cover all transports. The
68+
WebAuthn examples consume and emit JSON per the [WebAuthn IDL][webauthn].
69+
70+
| Transport | FIDO U2F | WebAuthn (FIDO2) |
71+
| --------------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
72+
| **USB (HID)** | `cargo run --example u2f_hid` | `cargo run --example webauthn_hid` |
73+
| **Bluetooth (BLE)** | `cargo run --example u2f_ble` | — |
74+
| **NFC** [^nfc] | `cargo run --features nfc-backend-pcsc --example u2f_nfc`<br>`cargo run --features nfc-backend-libnfc --example u2f_nfc` | `cargo run --features nfc-backend-pcsc --example webauthn_nfc`<br>`cargo run --features nfc-backend-libnfc --example webauthn_nfc` |
75+
| **Hybrid (caBLE v2)** | — | `cargo run --example webauthn_cable` |
7076

7177
[^nfc]: `nfc-backend-pcsc` is pure userspace and recommended on most systems. `nfc-backend-libnfc` requires the `libnfc` system library. Both can be enabled together; the first FIDO device found by either backend is used.
7278

7379
Additional HID-only examples cover specific FIDO2 features and authenticator management:
7480

7581
```
82+
# WebAuthn extension and preflight demos
7683
$ cargo run --example webauthn_extensions_hid
7784
$ cargo run --example webauthn_preflight_hid
7885
$ cargo run --example webauthn_prf_hid
79-
$ cargo run --example prf_test
80-
$ cargo run --example hid_device_selection
86+
$ cargo run --example prf_replay -- CREDENTIAL_ID FIRST_PRF_INPUT
87+
$ cargo run --example device_selection_hid
88+
89+
# CTAP2 authenticator management
8190
$ cargo run --example change_pin_hid
8291
$ cargo run --example bio_enrollment_hid
8392
$ cargo run --example authenticator_config_hid
84-
$ cargo run --example cred_management
93+
$ cargo run --example cred_management_hid
8594
```
8695

8796
## Contributing

‎libwebauthn/Cargo.toml‎

Lines changed: 62 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -91,11 +91,72 @@ qrcode = "0.14.1"
9191
# For turning on logging in unittests
9292
test-log = { version = "0.2" }
9393

94-
# Only compile NFC-examples, if NFC-features are used
94+
# Examples live in three subdirectories under examples/, grouped by purpose.
95+
# Cargo does not auto-discover examples in subdirectories, so each one is
96+
# listed here explicitly.
97+
#
98+
# ceremony/ - register and authenticate, one per transport
99+
# features/ - per-feature demos (extensions, preflight, prf, replay, device selection)
100+
# management/ - CTAP2 admin (PIN, biometrics, config, credential management)
101+
102+
[[example]]
103+
name = "u2f_hid"
104+
path = "examples/ceremony/u2f_hid.rs"
105+
106+
[[example]]
107+
name = "u2f_ble"
108+
path = "examples/ceremony/u2f_ble.rs"
109+
95110
[[example]]
96111
name = "u2f_nfc"
112+
path = "examples/ceremony/u2f_nfc.rs"
97113
required-features = ["nfc"]
98114

115+
[[example]]
116+
name = "webauthn_hid"
117+
path = "examples/ceremony/webauthn_hid.rs"
118+
99119
[[example]]
100120
name = "webauthn_nfc"
121+
path = "examples/ceremony/webauthn_nfc.rs"
101122
required-features = ["nfc"]
123+
124+
[[example]]
125+
name = "webauthn_cable"
126+
path = "examples/ceremony/webauthn_cable.rs"
127+
128+
[[example]]
129+
name = "webauthn_extensions_hid"
130+
path = "examples/features/webauthn_extensions_hid.rs"
131+
132+
[[example]]
133+
name = "webauthn_preflight_hid"
134+
path = "examples/features/webauthn_preflight_hid.rs"
135+
136+
[[example]]
137+
name = "webauthn_prf_hid"
138+
path = "examples/features/webauthn_prf_hid.rs"
139+
140+
[[example]]
141+
name = "prf_replay"
142+
path = "examples/features/prf_replay.rs"
143+
144+
[[example]]
145+
name = "device_selection_hid"
146+
path = "examples/features/device_selection_hid.rs"
147+
148+
[[example]]
149+
name = "change_pin_hid"
150+
path = "examples/management/change_pin_hid.rs"
151+
152+
[[example]]
153+
name = "bio_enrollment_hid"
154+
path = "examples/management/bio_enrollment_hid.rs"
155+
156+
[[example]]
157+
name = "authenticator_config_hid"
158+
path = "examples/management/authenticator_config_hid.rs"
159+
160+
[[example]]
161+
name = "cred_management_hid"
162+
path = "examples/management/cred_management_hid.rs"

0 commit comments

Comments
 (0)