diff options
Diffstat (limited to 'README.adoc')
-rw-r--r-- | README.adoc | 88 |
1 files changed, 88 insertions, 0 deletions
diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..8693417 --- /dev/null +++ b/README.adoc | |||
@@ -0,0 +1,88 @@ | |||
1 | == libfido2 | ||
2 | |||
3 | image:https://api.travis-ci.org/Yubico/libfido2.svg?branch=master["Build Status (Travis)", link="https://travis-ci.org/Yubico/libfido2"] | ||
4 | image:https://github.com/yubico/libfido2/workflows/windows/badge.svg["windows build status (github actions)", link="https://github.com/Yubico/libfido2/actions"] | ||
5 | image:https://img.shields.io/badge/license-BSD-blue.svg["License", link="https://raw.githubusercontent.com/Yubico/libfido2/master/LICENSE"] | ||
6 | |||
7 | *libfido2* provides library functionality and command-line tools to | ||
8 | communicate with a FIDO device over USB, and to verify attestation and | ||
9 | assertion signatures. | ||
10 | |||
11 | *libfido2* supports the FIDO U2F (CTAP 1) and FIDO 2.0 (CTAP 2) protocols. | ||
12 | |||
13 | For usage, see the `examples/` directory. | ||
14 | |||
15 | === License | ||
16 | |||
17 | *libfido2* is licensed under the BSD 2-clause license. See the _LICENSE_ | ||
18 | file for the full license text. | ||
19 | |||
20 | === Supported Platforms | ||
21 | |||
22 | *libfido2* is known to work on Linux, MacOS, Windows, and OpenBSD. | ||
23 | |||
24 | === Documentation | ||
25 | |||
26 | Documentation is available in troff and HTML formats. An | ||
27 | https://developers.yubico.com/libfido2/Manuals/[online mirror of *libfido2*'s documentation] | ||
28 | is also available. | ||
29 | |||
30 | === Installation | ||
31 | |||
32 | ==== Releases | ||
33 | |||
34 | The current release of *libfido2* is 1.3.0. Please consult Yubico's | ||
35 | https://developers.yubico.com/libfido2/Releases[release page] for source | ||
36 | and binary releases. | ||
37 | |||
38 | ==== Ubuntu | ||
39 | |||
40 | $ sudo apt-add-repository ppa:yubico/stable | ||
41 | $ sudo apt update | ||
42 | $ sudo apt install libfido2-dev | ||
43 | |||
44 | Or from source, on UNIX-like systems: | ||
45 | |||
46 | $ (rm -rf build && mkdir build && cd build && cmake ..) | ||
47 | $ make -C build | ||
48 | $ sudo make -C build install | ||
49 | |||
50 | Depending on the platform, the PKG_CONFIG_PATH environment variable may need to | ||
51 | be set. | ||
52 | |||
53 | *libfido2* depends on https://github.com/pjk/libcbor[libcbor] and | ||
54 | https://github.com/libressl-portable/portable[LibreSSL] (alternatively, | ||
55 | https://www.openssl.org[OpenSSL] may be used). On Linux, libudev (part of | ||
56 | https://www.freedesktop.org/wiki/Software/systemd[systemd]) is also required. | ||
57 | |||
58 | For complete, OS-specific installation instructions, please refer to the | ||
59 | `.travis/` (Linux, MacOS) and `windows/` directories. | ||
60 | |||
61 | On Linux, you will need to add a udev rule to be able to access the FIDO | ||
62 | device, or run as root. For example, the udev rule may contain the following: | ||
63 | |||
64 | ---- | ||
65 | #udev rule for allowing HID access to Yubico devices for FIDO support. | ||
66 | |||
67 | KERNEL=="hidraw*", SUBSYSTEM=="hidraw", \ | ||
68 | MODE="0664", GROUP="plugdev", ATTRS{idVendor}=="1050" | ||
69 | ---- | ||
70 | |||
71 | On Windows 1903 and newer versions, access to FIDO devices has been restricted | ||
72 | to applications using the operating system's native API. Use of *libfido2* | ||
73 | is still possible in privileged applications. | ||
74 | |||
75 | === OpenSSH Integration | ||
76 | |||
77 | *libfido2* includes middleware allowing https://www.openssh.com[OpenSSH] to | ||
78 | talk to U2F/FIDO2 devices. Note that server support is required for | ||
79 | authentication. In a nutshell: | ||
80 | |||
81 | ==== Key Generation | ||
82 | |||
83 | $ ssh-keygen -t [ecdsa-sk|ed25519-sk] -w /path/to/libsk-libfido2.so | ||
84 | |||
85 | ==== Authentication | ||
86 | |||
87 | $ ssh-agent -P /path/to/libsk-libfido2.so | ||
88 | $ ssh-add -S /path/to/libsk-libfido2.so | ||