README.adoc
1== libfido2
2
3image:https://github.com/yubico/libfido2/workflows/linux/badge.svg["Linux Build Status (github actions)", link="https://github.com/Yubico/libfido2/actions"]
4image:https://github.com/yubico/libfido2/workflows/macos/badge.svg["macOS Build Status (github actions)", link="https://github.com/Yubico/libfido2/actions"]
5image:https://github.com/yubico/libfido2/workflows/windows/badge.svg["Windows Build Status (github actions)", link="https://github.com/Yubico/libfido2/actions"]
6image:https://github.com/yubico/libfido2/workflows/fuzzer/badge.svg["Fuzz Status (github actions)", link="https://github.com/Yubico/libfido2/actions"]
7image: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
10communicate with a FIDO device over USB or NFC, and to verify attestation and
11assertion signatures.
12
13*libfido2* supports the FIDO U2F (CTAP 1) and FIDO2 (CTAP 2) protocols.
14
15For usage, see the `examples/` directory.
16
17=== License
18
19*libfido2* is licensed under the BSD 2-clause license. See the LICENSE
20file 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
28Documentation is available in troff and HTML formats. An
29https://developers.yubico.com/libfido2/Manuals/[online mirror of *libfido2*'s documentation]
30is 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
41The current release of *libfido2* is 1.14.0. Signed release tarballs are
42available at Yubico's
43https://developers.yubico.com/libfido2/Releases[release page].
44
45=== Dependencies
46
47*libfido2* depends on https://github.com/pjk/libcbor[libcbor],
48https://www.openssl.org[OpenSSL] 1.1 or newer, and https://zlib.net[zlib].
49On Linux, libudev
50(part of https://www.freedesktop.org/wiki/Software/systemd[systemd]) is also
51required.
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
63Alternatively, newer versions of *libfido2* are available in Yubico's PPA.
64Follow 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
73On Linux, you may need to add a udev rule to be able to access the FIDO
74device. 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
79KERNEL=="hidraw*", SUBSYSTEM=="hidraw", \
80 MODE="0664", GROUP="plugdev", ATTRS{idVendor}=="1050"
81----
82
83==== macOS
84
85 $ brew install libfido2
86
87==== Windows
88
89Please consult Yubico's
90https://developers.yubico.com/libfido2/Releases[release page] for ARM, ARM64,
91Win32, and Win64 artefacts.
92
93=== Building from source
94
95On UNIX-like systems:
96
97 $ cmake -B build
98 $ make -C build
99 $ sudo make -C build install
100
101Depending on the platform,
102https://www.freedesktop.org/wiki/Software/pkg-config/[pkg-config] may need to
103be installed, or the PKG_CONFIG_PATH environment variable set. For complete,
104OS-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
110additional dependencies. Options that are disabled by default are not
111officially 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
128The USE_HIDAPI option requires https://github.com/libusb/hidapi[hidapi]. The
129USE_PCSC option requires https://github.com/LudovicRousseau/PCSC[pcsc-lite] on
130Linux.
131
132=== Development
133
134Please use https://github.com/Yubico/libfido2/discussions[GitHub Discussions]
135to ask questions and suggest features, and
136https://github.com/Yubico/libfido2/pulls[GitHub pull-requests] for code
137contributions.
138
139=== Reporting bugs
140
141Please use https://github.com/Yubico/libfido2/issues[GitHub Issues] to report
142bugs. To report security issues, please contact security@yubico.com. A PGP
143public key can be found at
144https://www.yubico.com/support/security-advisories/issue-rating-system/.
145
