== python-fido2
image:https://github.com/Yubico/python-fido2/workflows/build/badge.svg["Github actions build", link="https://github.com/Yubico/python-fido2/actions"]

Provides library functionality for communicating with a FIDO device over USB as
well as verifying attestation and assertion signatures.

NOTE: Version 2.0 is now released. For help with migration from version 1.x, see
link:doc/Migration_1-2.adoc[the migration guide].

This library aims to support the FIDO U2F and FIDO 2 protocols for
communicating with a USB authenticator via the Client-to-Authenticator Protocol
(CTAP 1 and 2). In addition to this low-level device access, classes defined in
the fido2.client and fido2.server modules implement higher level operations
which are useful when interfacing with an Authenticator, or when implementing
WebAuthn support for a Relying Party.

For usage, see the examples/ directory and
link:https://developers.yubico.com/python-fido2/API_Documentation/[API documentation].

=== References
These links related to WebAuthn and FIDO2 can help you get started:

Yubico WebAuthn/FIDO2 guide: https://developers.yubico.com/FIDO2/
W3C WebAuthn specification: https://www.w3.org/TR/webauthn/
FIDO specifications: https://fidoalliance.org/specifications/download/

=== License
This project, with the exception of the files mentioned below, is licensed
under the BSD 2-clause license.
See the COPYING file for the full license text.

This project contains source code from pyu2f (https://github.com/google/pyu2f)
which is licensed under the Apache License, version 2.0.
These files are located in fido2/hid/.
See http://www.apache.org/licenses/LICENSE-2.0,
or the COPYING.APLv2 file for the full license text.

This project also bundles the public suffix list (https://publicsuffix.org)
which is licensed under the Mozilla Public License, version 2.0.
This file is stored as fido2/public_suffix_list.dat.
See https://mozilla.org/MPL/2.0/,
or the COPYING.MPLv2 file for the full license text.

=== Requirements
fido2 is compatible with Python 3.10 and later, and is tested on Windows, MacOS,
and Linux. Support for OpenBSD, FreeBSD, and NetBSD is provided as-is and
relies on community contributions.

=== Installation

fido2 is installable by running the following command:

pip install fido2

To install the dependencies required for communication with NFC authenticators,
instead use:

pip install fido2[pcsc]

Under Windows 10 (1903 or later) access to FIDO devices is restricted and
requires running as Administrator. This library can still be used when running
as non-administrator, via the fido.client.WindowsClient class. An example of
this is included in the file examples/credential.py.

Under 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"

There may be a package already available for your distribution that does this
for you, see:
https://support.yubico.com/hc/en-us/articles/360013708900-Using-Your-U2F-YubiKey-with-Linux

Under FreeBSD you will either need to run as root or add rules for your device
to /etc/devd.conf, which can be automated by installing security/u2f-devd:

pkg install u2f-devd

==== Dependencies
This project depends on Cryptography. For instructions on installing this
dependency, see https://cryptography.io/en/latest/installation/.

NFC support is optionally available via PC/SC, using the pyscard library. For
instructions on installing this dependency, see
https://github.com/LudovicRousseau/pyscard/blob/master/INSTALL.md.

=== Development
For development of the library we use https://python-poetry.org/[poetry]. To
set up the dev environment, run this command in the root directory of the
repository:

poetry install

We also use https://pre-commit.com/[pre-commit] to run some scans on the code
prior to committing.

==== Running tests
While some tests can run on their own, most require a connected FIDO2 device to run.

WARNING: These tests are destructive, and will factory reset the device under test.
As a safety precaution, the tests will only run on a device that is in a newly reset
state, as far as the test runner can tell.

poetry run pytest

Dependencies of fido2 (2).
Dependency	Optional
cryptography	false
pyscard	true

Package profile

fido2

Releases

Release table

PyPI Downloads

Dependencies

Details

Project URLs

Dependencies

Package description