yubikey-manager


Nameyubikey-manager JSON
Version 5.6.1 PyPI version JSON
download
home_pagehttps://github.com/Yubico/yubikey-manager
SummaryLibrary and CLI for managing your YubiKey configuration.
upload_time2025-03-18 11:18:26
maintainerNone
docs_urlNone
authorDain Nilsson
requires_python<4,>=3.8
licenseCopyright (c) 2015 Yubico AB All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
keywords yubikey yubiotp piv fido
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls. 
            == 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 a graphical application, check out  https://developers.yubico.com/yubioath-flutter/[Yubico Authenticator].

=== 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<<EOF
  hw.usb.usbhid.enable="1"
  hw.usb.quirk.0="0x1050 0x0010 0 0xffff UQ_KBD_IGNORE"  # YKS_OTP
  hw.usb.quirk.1="0x1050 0x0110 0 0xffff UQ_KBD_IGNORE"  # NEO_OTP
  hw.usb.quirk.2="0x1050 0x0111 0 0xffff UQ_KBD_IGNORE"  # NEO_OTP_CCID
  hw.usb.quirk.3="0x1050 0x0114 0 0xffff UQ_KBD_IGNORE"  # NEO_OTP_FIDO
  hw.usb.quirk.4="0x1050 0x0116 0 0xffff UQ_KBD_IGNORE"  # NEO_OTP_FIDO_CCID
  hw.usb.quirk.5="0x1050 0x0401 0 0xffff UQ_KBD_IGNORE"  # YK4_OTP
  hw.usb.quirk.6="0x1050 0x0403 0 0xffff UQ_KBD_IGNORE"  # YK4_OTP_FIDO
  hw.usb.quirk.7="0x1050 0x0405 0 0xffff UQ_KBD_IGNORE"  # YK4_OTP_CCID
  hw.usb.quirk.8="0x1050 0x0407 0 0xffff UQ_KBD_IGNORE"  # YK4_OTP_FIDO_CCID
  hw.usb.quirk.9="0x1050 0x0410 0 0xffff UQ_KBD_IGNORE"  # YKP_OTP_FIDO
  EOF
  # reboot

==== From source (for development)
To install from source, see the link:doc/Development.adoc[development]
instructions.

=== Shell completion

Experimental shell completion for the command line tool is available, provided
by the underlying CLI library (`click`) but it is not enabled by default. To
enable it, run this command once (for Bash):

  $ source <(_YKMAN_COMPLETE=bash_source ykman | sudo tee /etc/bash_completion.d/ykman)

More information on shell completion (including instructions for other shells) is
available at:
https://click.palletsprojects.com/en/stable/shell-completion/

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/Yubico/yubikey-manager",
    "name": "yubikey-manager",
    "maintainer": null,
    "docs_url": null,
    "requires_python": "<4,>=3.8",
    "maintainer_email": null,
    "keywords": "yubikey, yubiotp, piv, fido",
    "author": "Dain Nilsson",
    "author_email": "<dain@yubico.com>",
    "download_url": "https://files.pythonhosted.org/packages/a5/27/f0ab65a7a0204714df832dc16d3ce79777f76985d7c7fc96657ec32e061f/yubikey_manager-5.6.1.tar.gz",
    "platform": null,
    "description": "== YubiKey Manager CLI\nimage: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\"]\nimage: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\"]\nimage: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\"]\nimage: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\"]\n\nPython 3.8 (or later) library and command line tool for configuring a YubiKey.\nIf you're looking for a graphical application, check out  https://developers.yubico.com/yubioath-flutter/[Yubico Authenticator].\n\n=== Usage\nFor 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].\n\n....\nUsage: ykman [OPTIONS] COMMAND [ARGS]...\n\n  Configure your YubiKey via the command line.\n\n  Examples:\n\n    List connected YubiKeys, only output serial number:\n    $ ykman list --serials\n\n    Show information about YubiKey with serial number 0123456:\n    $ ykman --device 0123456 info\n\nOptions:\n  -d, --device SERIAL             specify which YubiKey to interact with by serial number\n  -r, --reader NAME               specify a YubiKey by smart card reader name (can't be used with --device or list)\n  -l, --log-level [ERROR|WARNING|INFO|DEBUG|TRAFFIC]\n                                  enable logging at given verbosity level\n  --log-file FILE                 write log to FILE instead of printing to stderr (requires --log-level)\n  --diagnose                      show diagnostics information useful for troubleshooting\n  -v, --version                   show version information about the app\n  --full-help                     show --help output, including hidden commands\n  -h, --help                      show this message and exit\n\nCommands:\n  info     show general information\n  list     list connected YubiKeys\n  config   enable or disable applications\n  fido     manage the FIDO applications\n  oath     manage the OATH application\n  openpgp  manage the OpenPGP application\n  otp      manage the YubiOTP application\n  piv      manage the PIV application\n....\n\nThe `--help` argument can also be used to get detailed information about specific\nsubcommands:\n\n    ykman oath --help\n\n=== Versioning/Compatibility\nThis project follows https://semver.org/[Semantic Versioning]. Any project\ndepending on yubikey-manager should take care when specifying version ranges to\nnot include any untested major version, as it is likely to have backwards\nincompatible changes. For example, you should NOT depend on \">=5\", as it has no\nupper bound. Instead, depend on \">=5, <6\", as any release before 6 will be\ncompatible.\n\nNote that any private variables (names starting with '_') are not part of the\npublic API, and may be changed between versions at any time.\n\n=== Installation\nYubiKey Manager can be installed independently of platform by using pip (or\nequivalent):\n\n  pip install --user yubikey-manager\n\nOn Linux platforms you will need `pcscd` installed and running to be able to\ncommunicate with a YubiKey over the SmartCard interface. Additionally, you may\nneed to set permissions for your user to access YubiKeys via the HID interfaces.\nMore information available link:doc/Device_Permissions.adoc[here].\n\nSome of the libraries used by yubikey-manager have C-extensions, and may require\nadditional dependencies to build, such as http://www.swig.org/[swig] and\npotentially https://pcsclite.apdu.fr/[PCSC lite].\n\n=== Pre-built packages\nPre-built packages specific to your platform may be available from Yubico or\nthird parties. Please refer to your platforms native package manager for\ndetailed instructions on how to install, if available.\n\n==== Windows\nA Windows installer is available to download from the\nhttps://github.com/Yubico/yubikey-manager/releases/latest[Releases page].\n\n==== MacOS\nA MacOS installer is available to download from the\nhttps://github.com/Yubico/yubikey-manager/releases/latest[Releases page].\n\nAdditionally, packages are available from Homebrew and MacPorts.\n\n===== Input Monitoring access on MacOS\nWhen running one of the `ykman otp` commands you may run into an error such as:\n`Failed to open device for communication: -536870174`. This indicates a problem\nwith the permission to access the OTP (keyboard) USB interface.\n\nTo access a YubiKey over this interface the application needs the `Input\nMonitoring` permission. If you are not automatically prompted to grant this\npermission, you may have to do so manually. Note that it is the _terminal_ you\nare using that needs the permission, not the ykman executable.\n\nTo add your terminal application to the `Input Monitoring` permission list, go\nto `System Preferences -> Security & Privacy -> Privacy -> Input Monitoring` to\nresolve this.\n\n===== Uninstallation of the MacOS .pkg\nTo uninstall yubikey-manager when installed via the pgk installer, run:\n\n  $ sudo rm -rf /usr/local/bin/ykman /usr/local/ykman\n\n==== Linux\nPackages are available for several Linux distributions by third party package\nmaintainers.\nYubico also provides packages for Ubuntu in the yubico/stable PPA:\n\n  $ sudo apt-add-repository ppa:yubico/stable\n  $ sudo apt update\n  $ sudo apt install yubikey-manager\n\n==== FreeBSD\nAlthough not being officially supported on this platform, YubiKey Manager can be\ninstalled on FreeBSD. It's available via its ports tree or as pre-built package.\nShould you opt to install and use YubiKey Manager on this platform, please be aware\nthat it's **NOT** maintained by Yubico.\n\nTo install the binary package, use `pkg install pyXY-yubikey-manager`, with `pyXY`\nspecifying the version of Python the package was built for, so in order to install\nYubiKey Manager for Python 3.8, use:\n\n  # pkg install py38-yubikey-manager\n\nFor more information about how to install packages or ports on FreeBSD, please refer\nto its official documentation: https://docs.freebsd.org/en/books/handbook/ports[FreeBSD Handbook].\n\nIn order to use `ykman otp` commands, you need to make sure the _uhid(4)_ driver\nattaches to the USB device:\n\n  # usbconfig ugenX.Y add_quirk UQ_KBD_IGNORE\n  # usbconfig ugenX.Y reset\n\nThe correct device to operate on _(ugenX.Y)_ can be determined using\n`usbconfig list`.\n\nWhen using FreeBSD 13 or higher, you can switch to the more modern _hidraw(4)_\ndriver. This allows YubiKey Manager to access OTP HID in a non-exclusive way,\nso that the key will still function as a USB keyboard:\n\n  # sysrc kld_list+=\"hidraw hkbd\"\n  # cat >>/boot/loader.conf<<EOF\n  hw.usb.usbhid.enable=\"1\"\n  hw.usb.quirk.0=\"0x1050 0x0010 0 0xffff UQ_KBD_IGNORE\"  # YKS_OTP\n  hw.usb.quirk.1=\"0x1050 0x0110 0 0xffff UQ_KBD_IGNORE\"  # NEO_OTP\n  hw.usb.quirk.2=\"0x1050 0x0111 0 0xffff UQ_KBD_IGNORE\"  # NEO_OTP_CCID\n  hw.usb.quirk.3=\"0x1050 0x0114 0 0xffff UQ_KBD_IGNORE\"  # NEO_OTP_FIDO\n  hw.usb.quirk.4=\"0x1050 0x0116 0 0xffff UQ_KBD_IGNORE\"  # NEO_OTP_FIDO_CCID\n  hw.usb.quirk.5=\"0x1050 0x0401 0 0xffff UQ_KBD_IGNORE\"  # YK4_OTP\n  hw.usb.quirk.6=\"0x1050 0x0403 0 0xffff UQ_KBD_IGNORE\"  # YK4_OTP_FIDO\n  hw.usb.quirk.7=\"0x1050 0x0405 0 0xffff UQ_KBD_IGNORE\"  # YK4_OTP_CCID\n  hw.usb.quirk.8=\"0x1050 0x0407 0 0xffff UQ_KBD_IGNORE\"  # YK4_OTP_FIDO_CCID\n  hw.usb.quirk.9=\"0x1050 0x0410 0 0xffff UQ_KBD_IGNORE\"  # YKP_OTP_FIDO\n  EOF\n  # reboot\n\n==== From source (for development)\nTo install from source, see the link:doc/Development.adoc[development]\ninstructions.\n\n=== Shell completion\n\nExperimental shell completion for the command line tool is available, provided\nby the underlying CLI library (`click`) but it is not enabled by default. To\nenable it, run this command once (for Bash):\n\n  $ source <(_YKMAN_COMPLETE=bash_source ykman | sudo tee /etc/bash_completion.d/ykman)\n\nMore information on shell completion (including instructions for other shells) is\navailable at:\nhttps://click.palletsprojects.com/en/stable/shell-completion/\n",
    "bugtrack_url": null,
    "license": "Copyright (c) 2015 Yubico AB\nAll rights reserved.\n\n  Redistribution and use in source and binary forms, with or\n  without modification, are permitted provided that the following\n  conditions are met:\n\n   1. Redistributions of source code must retain the above copyright\n      notice, this list of conditions and the following disclaimer.\n   2. Redistributions in binary form must reproduce the above\n      copyright notice, this list of conditions and the following\n      disclaimer in the documentation and/or other materials provided\n      with the distribution.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS\n\"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT\nLIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS\nFOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE\nCOPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,\nINCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,\nBUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;\nLOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER\nCAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT\nLIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN\nANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE\nPOSSIBILITY OF SUCH DAMAGE.\n",
    "summary": "Library and CLI for managing your YubiKey configuration.",
    "version": "5.6.1",
    "project_urls": {
        "Homepage": "https://github.com/Yubico/yubikey-manager"
    },
    "split_keywords": [
        "yubikey",
        " yubiotp",
        " piv",
        " fido"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "c699f590fd07b84eb65755fad953923d6acb754970d210df5aec45d9f0d84bf0",
                "md5": "18dc275a0d3ef1c96146a1b661cd3671",
                "sha256": "2acb23e63cbfa55c6b90d63099656f56de20421f2532b91a52e72326471cfc12"
            },
            "downloads": -1,
            "filename": "yubikey_manager-5.6.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "18dc275a0d3ef1c96146a1b661cd3671",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "<4,>=3.8",
            "size": 224619,
            "upload_time": "2025-03-18T11:18:24",
            "upload_time_iso_8601": "2025-03-18T11:18:24.224891Z",
            "url": "https://files.pythonhosted.org/packages/c6/99/f590fd07b84eb65755fad953923d6acb754970d210df5aec45d9f0d84bf0/yubikey_manager-5.6.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "a527f0ab65a7a0204714df832dc16d3ce79777f76985d7c7fc96657ec32e061f",
                "md5": "d65c2f07716924eec336fad64bccbf96",
                "sha256": "730da1358504de6616f1868bf48ddb788ada4b39137fb3ada435efbf39070160"
            },
            "downloads": -1,
            "filename": "yubikey_manager-5.6.1.tar.gz",
            "has_sig": false,
            "md5_digest": "d65c2f07716924eec336fad64bccbf96",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "<4,>=3.8",
            "size": 220053,
            "upload_time": "2025-03-18T11:18:26",
            "upload_time_iso_8601": "2025-03-18T11:18:26.573190Z",
            "url": "https://files.pythonhosted.org/packages/a5/27/f0ab65a7a0204714df832dc16d3ce79777f76985d7c7fc96657ec32e061f/yubikey_manager-5.6.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-03-18 11:18:26",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "Yubico",
    "github_project": "yubikey-manager",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "tox": true,
    "lcname": "yubikey-manager"
}
Dain Nilsson
Elapsed time: 1.78000s