{"id":21338260,"url":"https://github.com/smlx/piv-agent","last_synced_at":"2025-04-07T12:03:48.619Z","repository":{"id":37088472,"uuid":"307038773","full_name":"smlx/piv-agent","owner":"smlx","description":"An SSH and GPG agent which you can use with your PIV hardware security device (e.g. a Yubikey).","archived":false,"fork":false,"pushed_at":"2025-03-04T06:07:47.000Z","size":5987,"stargazers_count":89,"open_issues_count":9,"forks_count":6,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-31T11:01:41.230Z","etag":null,"topics":["gpg","gpg-agent","hacktoberfest","pgp","piv","ssh","ssh-agent","yubikey"],"latest_commit_sha":null,"homepage":"https://smlx.github.io/piv-agent/","language":"Go","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/smlx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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-10-25T06:34:04.000Z","updated_at":"2025-03-21T18:22:07.000Z","dependencies_parsed_at":"2023-02-09T09:46:17.771Z","dependency_job_id":"6ebcf3e6-9407-4f66-b758-de7f5cb4e595","html_url":"https://github.com/smlx/piv-agent","commit_stats":{"total_commits":331,"total_committers":2,"mean_commits":165.5,"dds":"0.36253776435045315","last_synced_commit":"82546219729eff8adc512253ce6627309e1788f7"},"previous_names":[],"tags_count":42,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smlx%2Fpiv-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smlx%2Fpiv-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smlx%2Fpiv-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smlx%2Fpiv-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smlx","download_url":"https://codeload.github.com/smlx/piv-agent/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247648976,"owners_count":20972945,"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":["gpg","gpg-agent","hacktoberfest","pgp","piv","ssh","ssh-agent","yubikey"],"created_at":"2024-11-22T00:12:15.293Z","updated_at":"2025-04-07T12:03:48.599Z","avatar_url":"https://github.com/smlx.png","language":"Go","readme":"# PIV Agent\n\n[![Release](https://github.com/smlx/piv-agent/actions/workflows/release.yaml/badge.svg)](https://github.com/smlx/piv-agent/actions/workflows/release.yaml)\n[![coverage](https://raw.githubusercontent.com/smlx/piv-agent/badges/.badges/main/coverage.svg)](https://github.com/smlx/piv-agent/actions/workflows/coverage.yaml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/smlx/piv-agent)](https://goreportcard.com/report/github.com/smlx/piv-agent)\n[![User Documentation](https://github.com/smlx/piv-agent/actions/workflows/user-documentation.yaml/badge.svg)](https://smlx.github.io/piv-agent/)\n\n## About\n\n* `piv-agent` is an SSH and GPG agent providing simple integration of [PIV](https://csrc.nist.gov/projects/piv/piv-standards-and-supporting-documentation) hardware (e.g. a [Yubikey](https://developers.yubico.com/yubico-piv-tool/YubiKey_PIV_introduction.html)) with `ssh`, and `gpg` workflows such as [`git`](https://git-scm.com/) signing, [`pass`](https://www.passwordstore.org/) encryption, or [keybase](https://keybase.io/) chat.\n* `piv-agent` originated as a reimplementation of [yubikey-agent](https://github.com/FiloSottile/yubikey-agent) because I needed some extra features, and also to gain a better understanding of the PIV applet on security key hardware.\n* `piv-agent` makes heavy use of the Go standard library and supplementary `crypto` packages, as well as [`piv-go`](https://github.com/go-piv/piv-go/) and [`pcsclite`](https://pcsclite.apdu.fr/). Thanks for the great software!\n\n---\n**DISCLAIMER**\n\nI make no assertion about the security or otherwise of this software and I am not a cryptographer.\nIf you are, please take a look at the code and send PRs or issues. :green_heart:\n\n---\n\n### Features\n\n* implements (a subset of) both `ssh-agent` and `gpg-agent` functionality\n* support for multiple hardware security keys\n* support for multiple slots in those keys\n* support for multiple touch policies\n* all cryptographic keys are generated on the hardware security key, rather than on your laptop\n  * secret keys never touch your hard drive\n* uses systemd (Linux) or launchd (macOS) socket activation\n  * as a result, automatically drop the transaction on the security key and cached passphrases after some period of disuse\n* provides \"fall-back\" to traditional SSH and OpenPGP keyfiles\n\n### Design philosophy\n\nThis agent should require no interaction and in general do the right thing when security keys are plugged/unplugged, laptop is power cycled, etc.\n\nIt is highly opinionated:\n\n* Only supports 256-bit ECC keys on hardware tokens\n* Only supports ed25519 SSH keys on disk (`~/.ssh/id_ed25519`)\n* Requires socket activation\n\nIt makes some concession to practicality with OpenPGP:\n\n* Supports RSA signing and decryption for OpenPGP keyfiles.\n  RSA OpenPGP keys are widespread and Debian in particular [only documents RSA keys](https://wiki.debian.org/Keysigning).\n\nIt tries to strike a balance between security and usability:\n\n* Takes a persistent transaction on the hardware token, effectively caching the PIN.\n* Caches passphrases for on-disk keys (i.e. `~/.ssh/id_ed25519`) in memory, so these only need to be provided once after the agent starts.\n* After a period of inactivity (32 minutes by default) it exits, dropping both of these.\n  Socket activation restarts it automatically as required.\n\n### Hardware support\n\nTested with:\n\n* [YubiKey 5C](https://www.yubico.com/au/product/yubikey-5c/), firmware 5.2.4\n\nWill be tested with (once PIV support [is available](https://github.com/solokeys/solo2/discussions/88)):\n\n* [Solo V2](https://www.kickstarter.com/projects/conorpatrick/solo-v2-safety-net-against-phishing/)\n\nAny device implementing the SCard API (PC/SC), and supported by [`piv-go`](https://github.com/go-piv/piv-go/) / [`pcsclite`](https://pcsclite.apdu.fr/) may work.\nIf you have tested another device with `piv-agent` successfully, please send a PR adding it to this list.\n\n### Platform support\n\nCurrently tested on Linux with `systemd` and macOS with `launchd`.\n\n### Protocol / Encryption Algorithm support\n\n| Supported | Not Supported | Support Blocked (Curve25519) |\n| ---       | ---           | ---                          |\n| ✅        | ❌            | ⏳                           |\n\nCurve25519 algorithms are blocked on hardware support.\nCurrently I'm only aware of Solo V2 which intends to implement this non-standard curve.\nSupport is not yet available (see the link above).\n\n#### ssh-agent\n\n|                     | Security Key | Keyfile |\n| ---                 | ---          | ---     |\n| ecdsa-sha2-nistp256 | ✅           | ❌      |\n| ssh-ed25519         | ⏳           | ✅      |\n\n\n#### gpg-agent\n\n|                               | Security Key | Keyfile |\n| ---                           | ---          | ---     |\n| ECDSA Sign (NIST Curve P-256) | ✅           | ✅      |\n| EDDSA Sign (Curve25519)       | ⏳           | ⏳      |\n| ECDH Decrypt                  | ✅           | ✅      |\n| RSA Sign                      | ❌           | ✅      |\n| RSA Decrypt                   | ❌           | ✅      |\n\n## Install and Use\n\nPlease see the [documentation](https://smlx.github.io/piv-agent/).\n\n## Develop\n\n### Prerequisites\n\nInstall build dependencies:\n\n```\n# debian/ubuntu\nsudo apt install libpcsclite-dev\n```\n\n### Build and test\n\n```\nmake\n```\n\n### Build and test manually\n\nThis D-Bus variable is required for `pinentry` to use a graphical prompt:\n\n```\ngo build ./cmd/piv-agent \u0026\u0026 systemd-socket-activate -l /tmp/piv-agent.sock -E DBUS_SESSION_BUS_ADDRESS ./piv-agent serve --debug\n```\n\nThen in another terminal:\n\n```\nexport SSH_AUTH_SOCK=/tmp/piv-agent.sock\nssh ...\n```\n\n### Build and test the documentation\n\n```\ncd docs \u0026\u0026 make serve\n```\n","funding_links":[],"categories":["Software Authenticators"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmlx%2Fpiv-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmlx%2Fpiv-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmlx%2Fpiv-agent/lists"}