Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

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

Python library and command line tool for configuring any YubiKey over all USB interfaces.
https://github.com/Yubico/yubikey-manager

fido2 oath openpgp otp piv python u2f webauthn yubikey

Last synced: 3 months ago
JSON representation

Python library and command line tool for configuring any YubiKey over all USB interfaces.

Awesome Lists containing this project

README 

        
== YubiKey Manager CLI

image:https://github.com/Yubico/yubikey-manager/actions/workflows/source-package.yml/badge.svg["Source package build", link="https://github.com/Yubico/yubikey-manager/actions/workflows/source-package.yml"]

image:https://github.com/Yubico/yubikey-manager/actions/workflows/windows.yml/badge.svg["Windows build", link="https://github.com/Yubico/yubikey-manager/actions/workflows/windows.yml"]

image:https://github.com/Yubico/yubikey-manager/actions/workflows/macOS.yml/badge.svg["MacOS build", link="https://github.com/Yubico/yubikey-manager/actions/workflows/macOS.yml"]

image:https://github.com/Yubico/yubikey-manager/actions/workflows/ubuntu.yml/badge.svg["Ubuntu build", link="https://github.com/Yubico/yubikey-manager/actions/workflows/ubuntu.yml"]



Python 3.8 (or later) library and command line tool for configuring a YubiKey.

If you're looking for the graphical application, it's https://developers.yubico.com/yubikey-manager-qt/[here].



=== Usage

For more usage information and examples, see the https://docs.yubico.com/software/yubikey/tools/ykman/Using_the_ykman_CLI.html[YubiKey Manager CLI User Manual].



....

Usage: ykman [OPTIONS] COMMAND [ARGS]...



  Configure your YubiKey via the command line.



  Examples:



    List connected YubiKeys, only output serial number:

    $ ykman list --serials



    Show information about YubiKey with serial number 0123456:

    $ ykman --device 0123456 info



Options:

  -d, --device SERIAL             specify which YubiKey to interact with by serial number

  -r, --reader NAME               specify a YubiKey by smart card reader name (can't be used with --device or list)

  -l, --log-level [ERROR|WARNING|INFO|DEBUG|TRAFFIC]

                                  enable logging at given verbosity level

  --log-file FILE                 write log to FILE instead of printing to stderr (requires --log-level)

  --diagnose                      show diagnostics information useful for troubleshooting

  -v, --version                   show version information about the app

  --full-help                     show --help output, including hidden commands

  -h, --help                      show this message and exit



Commands:

  info     show general information

  list     list connected YubiKeys

  config   enable or disable applications

  fido     manage the FIDO applications

  oath     manage the OATH application

  openpgp  manage the OpenPGP application

  otp      manage the YubiOTP application

  piv      manage the PIV application

....



The `--help` argument can also be used to get detailed information about specific

subcommands:



    ykman oath --help



=== Versioning/Compatibility

This project follows https://semver.org/[Semantic Versioning]. Any project

depending on yubikey-manager should take care when specifying version ranges to

not include any untested major version, as it is likely to have backwards

incompatible changes. For example, you should NOT depend on ">=5", as it has no

upper bound. Instead, depend on ">=5, <6", as any release before 6 will be

compatible.



Note that any private variables (names starting with '_') are not part of the

public API, and may be changed between versions at any time.



=== Installation

YubiKey Manager can be installed independently of platform by using pip (or

equivalent):



  pip install --user yubikey-manager



On Linux platforms you will need `pcscd` installed and running to be able to

communicate with a YubiKey over the SmartCard interface. Additionally, you may

need to set permissions for your user to access YubiKeys via the HID interfaces.

More information available link:doc/Device_Permissions.adoc[here].



Some of the libraries used by yubikey-manager have C-extensions, and may require

additional dependencies to build, such as http://www.swig.org/[swig] and

potentially https://pcsclite.apdu.fr/[PCSC lite].



=== Pre-built packages

Pre-built packages specific to your platform may be available from Yubico or

third parties. Please refer to your platforms native package manager for

detailed instructions on how to install, if available.



==== Windows

A Windows installer is available to download from the

https://github.com/Yubico/yubikey-manager/releases/latest[Releases page].



==== MacOS

A MacOS installer is available to download from the

https://github.com/Yubico/yubikey-manager/releases/latest[Releases page].



Additionally, packages are available from Homebrew and MacPorts.



===== Input Monitoring access on MacOS

When running one of the `ykman otp` commands you may run into an error such as:

`Failed to open device for communication: -536870174`. This indicates a problem

with the permission to access the OTP (keyboard) USB interface.



To access a YubiKey over this interface the application needs the `Input

Monitoring` permission. If you are not automatically prompted to grant this

permission, you may have to do so manually. Note that it is the _terminal_ you

are using that needs the permission, not the ykman executable.



To add your terminal application to the `Input Monitoring` permission list, go

to `System Preferences -> Security & Privacy -> Privacy -> Input Monitoring` to

resolve this.



===== Uninstallation of the MacOS .pkg

To uninstall yubikey-manager when installed via the pgk installer, run:



  $ sudo rm -rf /usr/local/bin/ykman /usr/local/ykman



==== Linux

Packages are available for several Linux distributions by third party package

maintainers.

Yubico also provides packages for Ubuntu in the yubico/stable PPA:



  $ sudo apt-add-repository ppa:yubico/stable

  $ sudo apt update

  $ sudo apt install yubikey-manager



==== FreeBSD

Although not being officially supported on this platform, YubiKey Manager can be

installed on FreeBSD. It's available via its ports tree or as pre-built package.

Should you opt to install and use YubiKey Manager on this platform, please be aware

that it's **NOT** maintained by Yubico.



To install the binary package, use `pkg install pyXY-yubikey-manager`, with `pyXY`

specifying the version of Python the package was built for, so in order to install

YubiKey Manager for Python 3.8, use:



  # pkg install py38-yubikey-manager



For more information about how to install packages or ports on FreeBSD, please refer

to its official documentation: https://docs.freebsd.org/en/books/handbook/ports[FreeBSD Handbook].



In order to use `ykman otp` commands, you need to make sure the _uhid(4)_ driver

attaches to the USB device:



  # usbconfig ugenX.Y add_quirk UQ_KBD_IGNORE

  # usbconfig ugenX.Y reset



The correct device to operate on _(ugenX.Y)_ can be determined using

`usbconfig list`.



When using FreeBSD 13 or higher, you can switch to the more modern _hidraw(4)_

driver. This allows YubiKey Manager to access OTP HID in a non-exclusive way,

so that the key will still function as a USB keyboard:



  # sysrc kld_list+="hidraw hkbd"

  # cat >>/boot/loader.conf<