From e162ecfdf095efbaf2ef6a9c9a7ff01b4dce50e2 Mon Sep 17 00:00:00 2001 From: Alfie Fresta Date: Sat, 20 Jun 2026 12:26:17 +0100 Subject: [PATCH] docs: document UV update wiring and add license, msrv, cable rows Document the Channel UX-update API (get_ux_update_sender, get_ux_update_receiver, send_ux_update) and extend the crate-level example with the async UV update handler loop callers must run. Add README License and MSRV sections, list the cloud-assisted caBLE v2 transport, make NFC opt-in explicit, and drop the stale git submodule instruction. --- README.md | 26 ++++++++++++++++++++------ libwebauthn/src/lib.rs | 22 +++++++++++++++++++--- libwebauthn/src/transport/channel.rs | 3 +++ 3 files changed, 42 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 6ba79268..7fbb3863 100644 --- a/README.md +++ b/README.md @@ -51,10 +51,18 @@ Validating the relying party ID against the calling origin requires the [Public | ---------------------------- | --------------------- | --------------------- | | **USB (HID)** | 🟢 Supported (hidapi) | 🟢 Supported (hidapi) | | **Bluetooth Low Energy** | 🟢 Supported (bluez) | 🟢 Supported (bluez) | -| **NFC** | 🟢 Supported (pcsc or libnfc) | 🟢 Supported (pcsc or libnfc) | +| **NFC** [^nfc-optin] | 🟢 Supported (pcsc or libnfc) | 🟢 Supported (pcsc or libnfc) | | **TPM 2.0 (Platform)** | 🟠 Planned ([#4][#4]) | 🟠 Planned ([#4][#4]) | +| **Hybrid (caBLE v2, cloud-assisted)** | N/A | 🟢 Supported | | **CTAP 2.3 hybrid (QR-initiated, BLE only)** | N/A | 🟢 Supported | +USB, BLE, and the two hybrid transports build with the default features. NFC is +opt-in: the crate ships with `default = []` for the NFC stack, so enable the +`nfc-backend-pcsc` feature (pure userspace, recommended) or `nfc-backend-libnfc` +(requires the `libnfc` system library) to compile it in. + +[^nfc-optin]: Off by default. Enable `nfc-backend-pcsc` and/or `nfc-backend-libnfc`. + ## Example programs Examples live in [`libwebauthn/examples/`](libwebauthn/examples) and are grouped by purpose: @@ -62,11 +70,6 @@ Examples live in [`libwebauthn/examples/`](libwebauthn/examples) and are grouped (extensions, preflight, PRF, device selection), and `management/` for CTAP2 admin operations. All examples share helpers from `examples/common/`. -``` -$ cd libwebauthn -$ git submodule update --init -``` - The basic ceremony examples (register + authenticate) cover all transports. The WebAuthn examples consume and emit JSON per the [WebAuthn IDL][webauthn]. @@ -103,6 +106,17 @@ $ cargo run --example cred_management_hid $ cargo run --example persistent_cred_management_hid ``` +## Minimum Supported Rust Version (MSRV) + +libwebauthn uses Rust edition 2021 and tracks recent stable Rust. CI builds and +tests on the current stable toolchain. There is no separate older MSRV floor: if +a recent stable `rustc` builds the crate, it is supported. + +## License + +Licensed under the GNU Lesser General Public License v2.1 or later +(`LGPL-2.1-or-later`). See [COPYING](COPYING) for the full text. + ## Contributing We welcome contributions! diff --git a/libwebauthn/src/lib.rs b/libwebauthn/src/lib.rs index e1f3c64e..c5f8af13 100644 --- a/libwebauthn/src/lib.rs +++ b/libwebauthn/src/lib.rs @@ -36,8 +36,9 @@ //! SystemPublicSuffixList, //! }; //! use libwebauthn::transport::hid::list_devices; -//! use libwebauthn::transport::{ChannelSettings, Device}; +//! use libwebauthn::transport::{Channel, ChannelSettings, Device}; //! use libwebauthn::webauthn::WebAuthn; +//! use libwebauthn::UvUpdate; //! //! # async fn run() -> Result<(), Box> { //! // 1. Enumerate authenticators on your transport of choice (HID shown here). @@ -47,7 +48,22 @@ //! // 2. Open a channel to the device. //! let mut channel = device.channel(ChannelSettings::default()).await?; //! -//! // 3. Build a request from its WebAuthn IDL JSON. +//! // 3. Drive user-verification updates on a separate task: each update +//! // carries the means to answer it. See `examples/ceremony/`. +//! let mut updates = channel.get_ux_update_receiver(); +//! tokio::spawn(async move { +//! while let Ok(update) = updates.recv().await { +//! match update { +//! UvUpdate::PresenceRequired => println!("Touch your authenticator"), +//! UvUpdate::PinRequired(request) => { +//! let _ = request.send_pin("the user's PIN"); +//! } +//! _ => {} +//! } +//! } +//! }); +//! +//! // 4. Build a request from its WebAuthn IDL JSON. //! let origin: RequestOrigin = "https://example.org".try_into().expect("invalid origin"); //! let psl = SystemPublicSuffixList::auto().expect("public suffix list unavailable"); //! let settings = RequestSettings { @@ -60,7 +76,7 @@ //! let request = //! MakeCredentialRequest::prepare(&origin, request_json, &settings).await?; //! -//! // 4. Run the ceremony on the channel. +//! // 5. Run the ceremony on the channel. //! let _response = channel.webauthn_make_credential(&request).await?; //! } //! # Ok(()) diff --git a/libwebauthn/src/transport/channel.rs b/libwebauthn/src/transport/channel.rs index 1f3fec6e..105a14c4 100644 --- a/libwebauthn/src/transport/channel.rs +++ b/libwebauthn/src/transport/channel.rs @@ -44,12 +44,15 @@ pub trait Channel: Send + Sync + Display + Ctap2AuthTokenStore { /// UX updates for this channel, must include UV updates. type UxUpdate: Send + Sync + Debug + From; + /// Broadcast sender fanning UX updates out to subscribed receivers. fn get_ux_update_sender(&self) -> &broadcast::Sender; + /// Subscribe to this channel's UX updates; drive the receiver on a separate task so the ceremony can make progress. fn get_ux_update_receiver(&self) -> broadcast::Receiver { self.get_ux_update_sender().subscribe() } + /// Broadcast a UX update to all current receivers. #[instrument(skip(self))] async fn send_ux_update(&mut self, state: Self::UxUpdate) { trace!("Sending UX update");