contrib/libfido2/README.adoc

   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.14.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 security@yubico.com. A PGP
 143 public key can be found at
 144 https://www.yubico.com/support/security-advisories/issue-rating-system/.