{"id":13626127,"url":"https://github.com/str4d/age-plugin-yubikey","last_synced_at":"2025-05-14T13:09:00.467Z","repository":{"id":38365722,"uuid":"291547252","full_name":"str4d/age-plugin-yubikey","owner":"str4d","description":"YubiKey plugin for age","archived":false,"fork":false,"pushed_at":"2025-01-27T08:48:17.000Z","size":355,"stargazers_count":688,"open_issues_count":33,"forks_count":28,"subscribers_count":18,"default_branch":"main","last_synced_at":"2025-05-10T06:35:51.819Z","etag":null,"topics":["age-encryption","cli","encryption","plugin","rust","yubikey"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/str4d.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-30T20:32:29.000Z","updated_at":"2025-05-10T02:31:56.000Z","dependencies_parsed_at":"2024-01-15T20:47:11.089Z","dependency_job_id":"d7a4b6d9-27f9-41ab-9b66-9e9dca9f848b","html_url":"https://github.com/str4d/age-plugin-yubikey","commit_stats":{"total_commits":186,"total_committers":6,"mean_commits":31.0,"dds":0.08602150537634412,"last_synced_commit":"36290c74ebd2723832aae684d43b927c9104f744"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/str4d%2Fage-plugin-yubikey","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/str4d%2Fage-plugin-yubikey/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/str4d%2Fage-plugin-yubikey/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/str4d%2Fage-plugin-yubikey/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/str4d","download_url":"https://codeload.github.com/str4d/age-plugin-yubikey/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254149975,"owners_count":22022852,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["age-encryption","cli","encryption","plugin","rust","yubikey"],"created_at":"2024-08-01T21:02:10.585Z","updated_at":"2025-05-14T13:08:55.449Z","avatar_url":"https://github.com/str4d.png","language":"Rust","funding_links":[],"categories":["Rust","cli","Plugins"],"sub_categories":[],"readme":"# YubiKey plugin for age clients\n\n`age-plugin-yubikey` is a plugin for [age](https://age-encryption.org/v1) clients\nlike [`age`](https://age-encryption.org) and [`rage`](https://str4d.xyz/rage),\nwhich enables files to be encrypted to age identities stored on YubiKeys.\n\n## Installation\n\n| Environment | CLI command |\n|-------------|-------------|\n| Cargo (Rust 1.67+) | `cargo install age-plugin-yubikey` |\n| Homebrew (macOS or Linux) | `brew install age-plugin-yubikey` |\n| Arch Linux | `pacman -S age-plugin-yubikey` |\n| Debian | [Debian package](https://github.com/str4d/age-plugin-yubikey/releases) |\n| NixOS | Add to config:\u003cbr\u003e`environment.systemPackages = [`\u003cbr\u003e`  pkgs.age-plugin-yubikey`\u003cbr\u003e`];`\u003cbr\u003eOr run `nix-env -i age-plugin-yubikey` |\n| Ubuntu 20.04+ | [Debian package](https://github.com/str4d/age-plugin-yubikey/releases) |\n| OpenBSD | `pkg_add age-plugin-yubikey` (security/age-plugin-yubikey) |\n\nOn Windows, Linux, and macOS, you can use the\n[pre-built binaries](https://github.com/str4d/age-plugin-yubikey/releases).\n\nHelp from new packagers is very welcome.\n\n### Linux, BSD, etc.\n\nOn non-Windows, non-macOS systems, you need to ensure that the `pcscd` service\nis installed and running. \n\n| Environment | CLI command |\n|-------------|-------------|\n| Debian or Ubuntu | `sudo apt-get install pcscd` |\n| Fedora | `sudo dnf install pcsc-lite` |\n| OpenBSD | As ```root``` do:\u003cbr\u003e`pkg_add pcsc-lite ccid`\u003cbr\u003e`rcctl enable pcscd`\u003cbr\u003e`rcctl start pcscd` |\n| FreeBSD | As ```root``` do:\u003cbr\u003e`pkg install pcsc-lite libccid`\u003cbr\u003e`service pcscd enable`\u003cbr\u003e`service pcscd start` |\n| Arch | `sudo pacman -S pcsclite pcsc-tools yubikey-manager`\u003cbr\u003e`sudo systemctl enable pcscd`\u003cbr\u003e`sudo systemctl start pcscd`| \n\nWhen installing via Cargo, you also need to ensure that the development headers\nfor the `pcsc-lite` library are available, so that the `pcsc-sys` crate can be\ncompiled.\n\n| Environment | CLI command |\n|-------------|-------------|\n| Debian or Ubuntu | `sudo apt-get install libpcsclite-dev` |\n| Fedora | `sudo dnf install pcsc-lite-devel` |\n\n### Windows Subsystem for Linux (WSL)\n\nWSL does not currently provide native support for USB devices. However, Windows\nbinaries installed on the host can be run from inside a WSL environment. This\nmeans that you can encrypt or decrypt files inside a WSL environment with a\nYubiKey:\n\n1. Install `age-plugin-yubikey` on the Windows host.\n2. Install an age client inside the WSL environment.\n3. Ensure that `age-plugin-yubikey.exe` is available in the WSL environment's\n   `PATH`. For default WSL setups, the Windows host's `PATH` is automatically\n   added to the WSL environment's `PATH` (see\n   [this Microsoft blog post](https://devblogs.microsoft.com/commandline/share-environment-vars-between-wsl-and-windows/)\n   for more details).\n\n## Configuration\n\n`age-plugin-yubikey` identities have two parts:\n- The secret key material, which is stored inside a YubiKey.\n- An age identity file, which contains information that an age client can use to\n  figure out which YubiKey secret key should be used.\n\nThere are two ways to configure a YubiKey as an age identity. You can run the\nplugin binary directly to use a simple text interface, which will create an age\nidentity file:\n\n```\n$ age-plugin-yubikey\n```\n\nOr you can use command-line flags to programmatically generate an identity and\nprint it to standard output:\n\n```\n$ age-plugin-yubikey --generate \\\n    [--serial SERIAL] \\\n    [--slot SLOT] \\\n    [--name NAME] \\\n    [--pin-policy PIN-POLICY] \\\n    [--touch-policy TOUCH-POLICY]\n```\n\nOnce an identity has been created, you can regenerate it later:\n\n```\n$ age-plugin-yubikey --identity [--serial SERIAL] --slot SLOT\n```\n\nTo use the identity with an age client, it needs to be stored in a file. When\nusing the above programmatic flags, you can do this by redirecting standard\noutput to a file. On a Unix system like macOS or Ubuntu:\n\n```\n$ age-plugin-yubikey --identity --slot SLOT \u003e yubikey-identity.txt\n```\n\n## Usage\n\nThe age recipients contained in all connected YubiKeys can be printed on\nstandard output:\n\n```\n$ age-plugin-yubikey --list\n```\n\nTo encrypt files to these YubiKey recipients, ensure that `age-plugin-yubikey`\nis accessible in your `PATH`, and then use the recipients with an age client as\nnormal (e.g. `rage -r age1yubikey1...`).\n\nThe output of the `--list` command can also be used directly to encrypt files to\nall recipients (e.g. `age -R filename.txt`).\n\nTo decrypt files encrypted to a YubiKey identity, pass the identity file to the\nage client as normal (e.g. `rage -d -i yubikey-identity.txt`).\n\n## Advanced topics\n\n### Agent support\n\n`age-plugin-yubikey` does not provide or interact with an agent for decryption.\nIt does however attempt to preserve the PIN cache by not soft-resetting the\nYubiKey after a decryption or read-only operation, which enables YubiKey\nidentities configured with a PIN policy of `once` to not prompt for the PIN on\nevery decryption. **This does not work for YubiKey 4 series.**\n\nThe session that corresponds to the `once` policy can be ended in several ways,\nnot all of which are necessarily intuitive:\n\n- Unplugging the YubiKey (the obvious way).\n- Using a different applet (e.g. FIDO2). This causes the PIV applet to be closed\n  which clears its state.\n  - This is why the YubiKey 4 series does not support PIN cache preservation:\n    their serial can only be obtained by switching to the OTP applet.\n- Generating a new age identity via `age-plugin-yubikey --generate` or the CLI\n  interface. This is to avoid leaving the YubiKey authenticated with the\n  management key.\n\nIf the current PIN UX proves to be insufficient, a decryption agent will most\nlikely be implemented as a separate age plugin that interacts with\n[`yubikey-agent`](https://github.com/FiloSottile/yubikey-agent), enabling\nYubiKeys to be used simultaneously with age and SSH.\n\n### Manual setup and technical details\n\n`age-plugin-yubikey` only officially supports the following YubiKey variants,\nset up either via the text interface or the `--generate` flag:\n\n- YubiKey 4 series\n- YubiKey 5 series\n\nNOTE: Nano and USB-C variants of the above are also supported. The pre-YK4\nYubiKey NEO series is **NOT** supported. The blue \"Security Key by Yubico\" will\nalso not work (as it doesn't support PIV).\n\nIn practice, any PIV token with an ECDSA P-256 key and certificate in one of the\n20 \"retired\" slots should work. You can list all age-compatible keys with:\n\n```\n$ age-plugin-yubikey --list-all\n```\n\n`age-plugin-yubikey` implements several automatic security management features:\n\n- If it detects that the default PIN is being used, it will prompt the user to\n  change the PIN. The PUK is then set to the same value as the PIN.\n- If it detects that the default management key is being used, it generates a\n  random management key and stores it in PIN-protected metadata.\n  `age-plugin-yubikey` does not support custom management keys.\n\n## License\n\nLicensed under either of\n\n * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or\n   http://www.apache.org/licenses/LICENSE-2.0)\n * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)\n\nat your option.\n\n### Contribution\n\nUnless you explicitly state otherwise, any contribution intentionally\nsubmitted for inclusion in the work by you, as defined in the Apache-2.0\nlicense, shall be dual licensed as above, without any additional terms or\nconditions.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstr4d%2Fage-plugin-yubikey","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstr4d%2Fage-plugin-yubikey","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstr4d%2Fage-plugin-yubikey/lists"}