summaryrefslogtreecommitdiff
path: root/README.adoc
blob: 8693417b3cc2e9ea162a57c9c54d96690b10cee9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
== libfido2

image:https://api.travis-ci.org/Yubico/libfido2.svg?branch=master["Build Status (Travis)", link="https://travis-ci.org/Yubico/libfido2"]
image:https://github.com/yubico/libfido2/workflows/windows/badge.svg["windows build status (github actions)", link="https://github.com/Yubico/libfido2/actions"]
image:https://img.shields.io/badge/license-BSD-blue.svg["License", link="https://raw.githubusercontent.com/Yubico/libfido2/master/LICENSE"]

*libfido2* provides library functionality and command-line tools to
communicate with a FIDO device over USB, and to verify attestation and
assertion signatures.

*libfido2* supports the FIDO U2F (CTAP 1) and FIDO 2.0 (CTAP 2) protocols.

For usage, see the `examples/` directory.

=== License

*libfido2* is licensed under the BSD 2-clause license.  See the _LICENSE_
file for the full license text.

=== Supported Platforms

*libfido2* is known to work on Linux, MacOS, Windows, and OpenBSD.

=== Documentation

Documentation is available in troff and HTML formats. An
https://developers.yubico.com/libfido2/Manuals/[online mirror of *libfido2*'s documentation]
is also available.

=== Installation

==== Releases

The current release of *libfido2* is 1.3.0. Please consult Yubico's
https://developers.yubico.com/libfido2/Releases[release page] for source
and binary releases.

==== Ubuntu

  $ sudo apt-add-repository ppa:yubico/stable
  $ sudo apt update
  $ sudo apt install libfido2-dev

Or from source, on UNIX-like systems:

  $ (rm -rf build && mkdir build && cd build && cmake ..)
  $ make -C build
  $ sudo make -C build install

Depending on the platform, the PKG_CONFIG_PATH environment variable may need to
be set.

*libfido2* depends on https://github.com/pjk/libcbor[libcbor] and
https://github.com/libressl-portable/portable[LibreSSL] (alternatively,
https://www.openssl.org[OpenSSL] may be used). On Linux, libudev (part of
https://www.freedesktop.org/wiki/Software/systemd[systemd]) is also required.

For complete, OS-specific installation instructions, please refer to the
`.travis/` (Linux, MacOS) and `windows/` directories.

On Linux, you will need to add a udev rule to be able to access the FIDO
device, or run as root. For example, the udev rule may contain the following:

----
#udev rule for allowing HID access to Yubico devices for FIDO support.

KERNEL=="hidraw*", SUBSYSTEM=="hidraw", \
  MODE="0664", GROUP="plugdev", ATTRS{idVendor}=="1050"
----

On Windows 1903 and newer versions, access to FIDO devices has been restricted
to applications using the operating system's native API. Use of *libfido2*
is still possible in privileged applications.

=== OpenSSH Integration

*libfido2* includes middleware allowing https://www.openssh.com[OpenSSH] to
talk to U2F/FIDO2 devices. Note that server support is required for
authentication. In a nutshell:

==== Key Generation

  $ ssh-keygen -t [ecdsa-sk|ed25519-sk] -w /path/to/libsk-libfido2.so

==== Authentication

  $ ssh-agent -P /path/to/libsk-libfido2.so
  $ ssh-add -S /path/to/libsk-libfido2.so