DOCSEARCHbyAlgolia
Submit Docs

YubiKey Manager

repository·main·Indexed 19 days ago

https://github.com/yubico/yubikey-manager

A Python 3.10+ library and command-line tool (ykman) used to configure YubiKey applications, including FIDO, OATH, OpenPGP, YubiOTP, and PIV. It provides functionality for device discovery, connection management via SmartCard, OTP, and Fido connections, and supports custom Python scripting for device automation.

Tokens
6.2K
Snippets
28
Records
37
Agent score
74%

What's inside yubikey-manager

  1. Use ykman/scripting.py utilities

    main

    The ykman.scripting module (commonly imported as s) provides helper functions for interacting with YubiKeys during script execution.

    s.single()

    Connects to a single YubiKey. Useful for scripts targeting one specific device.

    s.multi(allow_initial=True)

    An iterator that watches for connected YubiKeys. It allows you to perform actions on multiple devices or wait for a specific device to be plugged in.

    • allow_initial: If set to True, the function will include YubiKeys that are already connected when the call is made. If False (the default), the call will fail if YubiKeys are already connected, which acts as a safety measure to prevent accidental programming of the wrong device.
    from ykman import scripting as s

# Connect to the first available YubiKey
device = s.single()
print("Found a YubiKey:", device)

# Iterate through YubiKeys as they are connected
for device in s.multi(allow_initial=True):
    print("New device detected:", device)

  2. Run ykman from source

    main

    Use the uv run command to execute the ykman CLI directly from the source code. You can view help information, inspect a YubiKey, or enable debug logging.

    # Run the CLI
uv run ykman

# Show available commands
uv run ykman --help

# Show information about an inserted YubiKey
uv run ykman info

# Run in DEBUG mode
uv run ykman --log-level DEBUG info

  3. Install development dependencies

    main

    This project uses uv for development. Ensure uv is installed and configured following the uv Getting Started guide.

    Depending on your operating system, you must also install swig and other system libraries:

    • Windows: Ensure the swig executable is in your PATH.
    • macOS: Use Homebrew to install swig.
    • Linux (Debian-based): Install swig, libu2f-udev, pcscd, and libpcsclite-dev via apt.
    • Linux (RPM-based): Install pcsc-lite-devel, python3-devel, and swig via dnf (tested on Fedora 34).
    # macOS
brew install swig

# Linux (Debian-based)
sudo apt install swig libu2f-udev pcscd libpcsclite-dev

# Linux (RPM-based)
sudo dnf install pcsc-lite-devel python3-devel swig

  5. Pass arguments to ykman scripts

    main

    You can pass command-line arguments to your script by appending them to the ykman script command. These arguments are accessible within your Python script via the standard sys.argv list. Note that sys.argv[0] is always the script name, so your first custom argument will be at sys.argv[1] and will always be a string type.

    ykman script myscript.py 123456 a_word "a string with spaces"

  6. Run integration tests

    main

    WARNING: ONLY run these on dedicated developer keys, as it will permanently delete data on the device(s)!

    To run integration tests, you must provide the serial number of the YubiKey (obtain this via ykman list). Ensure no other YubiKeys are connected during the test.

    To run tests over NFC, specify both the reader type and the device serial number.

    # Run tests on a specific device via serial number
uv run pytest --device 123456

# Run tests over NFC
uv run pytest --reader HID --device 123456

  7. Configure Smart Card access on Linux

    main
    Smart card access is required for commands involving piv, oath, openpgp, and hsmauth, as well as any commands issued over NFC. On Linux, this access is managed via pcscd (the PC/SC Smart Card Daemon). To ensure compatibility, make sure pcscd is installed and currently running.

  8. Configure FIDO access on Linux

    main

    The fido command requires access to the YubiKey via the USB HID interface. On Linux, permissions are granted through udev rules.

    An example udev rules file that grants access to a wide range of FIDO devices (not limited to YubiKeys) is available here: https://github.com/Yubico/libu2f-host/blob/master/70-u2f.rules.

  9. Configure Keyboard access for Yubico OTP on Linux

    main

    The otp command requires access to the YubiKey via the USB keyboard interface. On Linux, this is typically managed using udev rules. To grant the necessary permissions, you must provide a udev rules file that allows access to the keyboard interface.

    An example rules file can be found in the yubikey-personalization repository: https://github.com/Yubico/yubikey-personalization/blob/master/69-yubikey.rules.

  10. Run custom Python scripts with ykman script

    main

    The ykman script subcommand allows you to execute custom Python scripts within the YubiKey Manager context. This provides your scripts with access to the full ykman library and its Python dependencies.

    WARNING: Only run scripts that you fully trust. Scripts have the power to modify YubiKey settings and can potentially harm both your device and your computer.

    ykman script myscript.py

  11. Set up code style and type checking hooks

    main

    The project uses ruff for linting, and mypy/pyright for static type checking. These are managed via pre-commit. To install and use these hooks, install pre-commit as a tool and then install the git hooks.

    uv tool install pre-commit
pre-commit install

  12. Install YubiKey Manager CLI

    main

    YubiKey Manager can be installed using pip on most platforms. For Linux, ensure pcscd is installed and running to communicate via the SmartCard interface. You may also need to configure user permissions for HID interface access.

    Platform Specifics:

    • Windows/macOS: Download installers from the official Releases page.
    • macOS (Homebrew/MacPorts): Available via standard package managers.
    • FreeBSD: Available via ports or pre-built packages (not officially maintained by Yubico).
    • Linux: Recommended to use pip, pipx, or uv.
    pip install --user yubikey-manager