Skip to content

Update README for the current state of the library #377

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jschanck merged 1 commit into from
Sep 14, 2026
Merged

Update README for the current state of the library #377

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 34 additions & 15 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,36 +1,48 @@
# A Rust library for interacting with CTAP1/CTAP2 Security Keys

[![Build Status](https://travis-ci.org/mozilla/authenticator-rs.svg?branch=master)](https://travis-ci.org/mozilla/authenticator-rs)
[![Build and test](https://github.com/mozilla/authenticator-rs/actions/workflows/ci.yml/badge.svg?branch=ctap2-2021)](https://github.com/mozilla/authenticator-rs/actions/workflows/ci.yml)
![Maturity Level](https://img.shields.io/badge/maturity-release-green.svg)

This is a cross-platform library for interacting with Security Key-type devices via Rust.
This is a cross-platform library for directly interacting with Security Key-type devices via Rust.

* **Supported Platforms**: Windows, Linux, FreeBSD, NetBSD, OpenBSD, and macOS.
* **Supported Transports**: USB HID.
* **Supported Protocols**: [FIDO U2F over USB](https://fidoalliance.org/specs/fido-u2f-v1.1-id-20160915/fido-u2f-raw-message-formats-v1.1-id-20160915.html). [CTAP2 support](https://fidoalliance.org/specs/fido-v2.0-ps-20190130/fido-client-to-authenticator-protocol-v2.0-ps-20190130.html) is forthcoming, with work being done in the **unstable** [`ctap2` branch](https://github.com/mozilla/authenticator-rs/tree/ctap2).
- **Supported Platforms**: FreeBSD, Linux, macOS[^1], NetBSD, OpenBSD, and Windows[^2].
- **Supported Transports**: USB HID.
- **Supported Protocols**: [FIDO CTAP1 (U2F)][u2f], [CTAP 2.0][], CTAP 2.1-PRE, [CTAP 2.1][].

This library is primarily intended [for use by Firefox][ffx] on platforms that
_do not_ provide WebAuthn APIs (as there are on Android, iOS, [macOS][] and
[Windows][hello]). It implements a subset of the CTAP protocol that is useful
for a web browser.

This library currently focuses on USB security keys, but is expected to be extended to
support additional transports.

[^1]: [macOS has its own platform WebAuthn API][macOS] (which also supports iCloud Keychain), but still allows direct, transport level communication with authenticators.

[^2]: Windows 10 v1903 and later block direct, transport level access to authenticators to applications _not_ running as Administrator, breaking this library for most applications. [Applications will need to use the platform APIs instead][hello].

## Usage

There's only a simple example function that tries to register and sign right now. It uses
[env_logger](http://rust-lang-nursery.github.io/log/env_logger/) for logging, which you
configure with the `RUST_LOG` environment variable:
Proper usage should be to call into this library from something else - e.g., Firefox.

```
cargo build --example main
RUST_LOG=debug cargo run --example main
[The `ctap2` example](./examples/ctap2.rs) will register and sign a non-discoverable credential
with a USB CTAP1 or CTAP2 authenticator, in a similar manner to a web browser that supports the
WebAuthn API:

```sh
cargo build --example ctap2
RUST_LOG=debug cargo run --example ctap2
```

Proper usage should be to call into this library from something else - e.g., Firefox. There are
some [C headers exposed for the purpose](./src/u2fhid-capi.h).
There are more examples in [the `examples` directory](./examples/).

[The `RUST_LOG` environment variable controls logging](http://rust-lang-nursery.github.io/log/env_logger/).

## Tests

There are some tests of the cross-platform runloop logic and the protocol decoder:

```
```sh
cargo test
```

Expand All @@ -41,10 +53,17 @@ There are not (yet) fuzzers for the C API used by callers (such as Gecko).

To fuzz, you will need cargo-fuzz (the latest version from GitHub) as well as Rust Nightly.

```
```sh
rustup install nightly
cargo install cargo-fuzz

cargo +nightly fuzz run u2f_read -- -max_len=512
cargo +nightly fuzz run u2f_read_write -- -max_len=512
```

[CTAP 2.0]: https://fidoalliance.org/specs/fido-v2.0-ps-20190130/fido-client-to-authenticator-protocol-v2.0-ps-20190130.html
[CTAP 2.1]: https://fidoalliance.org/specs/fido-v2.1-ps-20210615/fido-client-to-authenticator-protocol-v2.1-ps-errata-20220621.html
[ffx]: https://searchfox.org/firefox-main/source/dom/webauthn
[hello]: https://github.com/microsoft/webauthn
[macOS]: https://developer.apple.com/documentation/authenticationservices/public-private-key-authentication
[u2f]: https://fidoalliance.org/specs/fido-u2f-v1.1-id-20160915/fido-u2f-raw-message-formats-v1.1-id-20160915.html
Loading