| 1 |
== libfido2 |
| 2 |
|
| 3 |
image:https://github.com/yubico/libfido2/workflows/linux/badge.svg["Linux Build Status (github actions)", link="https://github.com/Yubico/libfido2/actions"] |
| 4 |
image:https://github.com/yubico/libfido2/workflows/macos/badge.svg["macOS Build Status (github actions)", link="https://github.com/Yubico/libfido2/actions"] |
| 5 |
image:https://github.com/yubico/libfido2/workflows/windows/badge.svg["Windows Build Status (github actions)", link="https://github.com/Yubico/libfido2/actions"] |
| 6 |
image:https://github.com/yubico/libfido2/workflows/fuzzer/badge.svg["Fuzz Status (github actions)", link="https://github.com/Yubico/libfido2/actions"] |
| 7 |
image:https://oss-fuzz-build-logs.storage.googleapis.com/badges/libfido2.svg["Fuzz Status (oss-fuzz)", link="https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened&can=1&q=proj:libfido2"] |
| 8 |
|
| 9 |
*libfido2* provides library functionality and command-line tools to |
| 10 |
communicate with a FIDO device over USB or NFC, and to verify attestation and |
| 11 |
assertion signatures. |
| 12 |
|
| 13 |
*libfido2* supports the FIDO U2F (CTAP 1) and FIDO2 (CTAP 2) protocols. |
| 14 |
|
| 15 |
For usage, see the `examples/` directory. |
| 16 |
|
| 17 |
=== License |
| 18 |
|
| 19 |
*libfido2* is licensed under the BSD 2-clause license. See the LICENSE |
| 20 |
file for the full license text. |
| 21 |
|
| 22 |
=== Supported Platforms |
| 23 |
|
| 24 |
*libfido2* is known to work on Linux, macOS, Windows, OpenBSD, and FreeBSD. |
| 25 |
|
| 26 |
=== Documentation |
| 27 |
|
| 28 |
Documentation is available in troff and HTML formats. An |
| 29 |
https://developers.yubico.com/libfido2/Manuals/[online mirror of *libfido2*'s documentation] |
| 30 |
is also available. |
| 31 |
|
| 32 |
=== Bindings |
| 33 |
|
| 34 |
* .NET: https://github.com/borrrden/Fido2Net[Fido2Net] |
| 35 |
* Go: https://github.com/keys-pub/go-libfido2[go-libfido2] |
| 36 |
* Perl: https://github.com/jacquesg/p5-FIDO-Raw[p5-FIDO-Raw] |
| 37 |
* Rust: https://github.com/PvdBerg1998/libfido2[libfido2] |
| 38 |
|
| 39 |
=== Releases |
| 40 |
|
| 41 |
The current release of *libfido2* is 1.15.0. Signed release tarballs are |
| 42 |
available at Yubico's |
| 43 |
https://developers.yubico.com/libfido2/Releases[release page]. |
| 44 |
|
| 45 |
=== Dependencies |
| 46 |
|
| 47 |
*libfido2* depends on https://github.com/pjk/libcbor[libcbor], |
| 48 |
https://www.openssl.org[OpenSSL] 1.1 or newer, and https://zlib.net[zlib]. |
| 49 |
On Linux, libudev |
| 50 |
(part of https://www.freedesktop.org/wiki/Software/systemd[systemd]) is also |
| 51 |
required. |
| 52 |
|
| 53 |
=== Installation |
| 54 |
|
| 55 |
==== Fedora 35 and 34 |
| 56 |
|
| 57 |
$ sudo dnf install libfido2 libfido2-devel fido2-tools |
| 58 |
|
| 59 |
==== Ubuntu 22.04 (Jammy) and 20.04 (Focal) |
| 60 |
|
| 61 |
$ sudo apt install libfido2-1 libfido2-dev libfido2-doc fido2-tools |
| 62 |
|
| 63 |
Alternatively, newer versions of *libfido2* are available in Yubico's PPA. |
| 64 |
Follow the instructions for Ubuntu 18.04 (Bionic) below. |
| 65 |
|
| 66 |
==== Ubuntu 18.04 (Bionic) |
| 67 |
|
| 68 |
$ sudo apt install software-properties-common |
| 69 |
$ sudo apt-add-repository ppa:yubico/stable |
| 70 |
$ sudo apt update |
| 71 |
$ sudo apt install libfido2-1 libfido2-dev libfido2-doc fido2-tools |
| 72 |
|
| 73 |
On Linux, you may need to add a udev rule to be able to access the FIDO |
| 74 |
device. For example, the udev rule may contain the following: |
| 75 |
|
| 76 |
---- |
| 77 |
#udev rule for allowing HID access to Yubico devices for FIDO support. |
| 78 |
|
| 79 |
KERNEL=="hidraw*", SUBSYSTEM=="hidraw", \ |
| 80 |
MODE="0664", GROUP="plugdev", ATTRS{idVendor}=="1050" |
| 81 |
---- |
| 82 |
|
| 83 |
==== macOS |
| 84 |
|
| 85 |
$ brew install libfido2 |
| 86 |
|
| 87 |
==== Windows |
| 88 |
|
| 89 |
Please consult Yubico's |
| 90 |
https://developers.yubico.com/libfido2/Releases[release page] for ARM, ARM64, |
| 91 |
Win32, and Win64 artefacts. |
| 92 |
|
| 93 |
=== Building from source |
| 94 |
|
| 95 |
On UNIX-like systems: |
| 96 |
|
| 97 |
$ cmake -B build |
| 98 |
$ make -C build |
| 99 |
$ sudo make -C build install |
| 100 |
|
| 101 |
Depending on the platform, |
| 102 |
https://www.freedesktop.org/wiki/Software/pkg-config/[pkg-config] may need to |
| 103 |
be installed, or the PKG_CONFIG_PATH environment variable set. For complete, |
| 104 |
OS-specific build instructions, please refer to the `.actions/` |
| 105 |
(Linux, macOS, BSD) and `windows/` directories. |
| 106 |
|
| 107 |
=== Build-time Customisation |
| 108 |
|
| 109 |
*libfido2* supports a number of CMake options. Some of the options require |
| 110 |
additional dependencies. Options that are disabled by default are not |
| 111 |
officially supported. |
| 112 |
|
| 113 |
[%autowidth.stretch] |
| 114 |
|=== |
| 115 |
|*Option* |*Description* |*Default* |
| 116 |
| BUILD_EXAMPLES | Build example programs | ON |
| 117 |
| BUILD_MANPAGES | Build man pages | ON |
| 118 |
| BUILD_SHARED_LIBS | Build a shared library | ON |
| 119 |
| BUILD_STATIC_LIBS | Build a static library | ON |
| 120 |
| BUILD_TOOLS | Build auxiliary tools | ON |
| 121 |
| FUZZ | Enable fuzzing instrumentation | OFF |
| 122 |
| NFC_LINUX | Enable netlink NFC support on Linux | ON |
| 123 |
| USE_HIDAPI | Use hidapi as the HID backend | OFF |
| 124 |
| USE_PCSC | Enable experimental PCSC support | OFF |
| 125 |
| USE_WINHELLO | Abstract Windows Hello as a FIDO device | ON |
| 126 |
|=== |
| 127 |
|
| 128 |
The USE_HIDAPI option requires https://github.com/libusb/hidapi[hidapi]. The |
| 129 |
USE_PCSC option requires https://github.com/LudovicRousseau/PCSC[pcsc-lite] on |
| 130 |
Linux. |
| 131 |
|
| 132 |
=== Development |
| 133 |
|
| 134 |
Please use https://github.com/Yubico/libfido2/discussions[GitHub Discussions] |
| 135 |
to ask questions and suggest features, and |
| 136 |
https://github.com/Yubico/libfido2/pulls[GitHub pull-requests] for code |
| 137 |
contributions. |
| 138 |
|
| 139 |
=== Reporting bugs |
| 140 |
|
| 141 |
Please use https://github.com/Yubico/libfido2/issues[GitHub Issues] to report |
| 142 |
bugs. To report security issues, please contact [email protected]. A PGP |
| 143 |
public key can be found at |
| 144 |
https://www.yubico.com/support/security-advisories/issue-rating-system/. |