{"id":19607060,"url":"https://github.com/bookingcom/yubistack","last_synced_at":"2025-04-27T19:33:08.208Z","repository":{"id":57691108,"uuid":"270987984","full_name":"bookingcom/yubistack","owner":"bookingcom","description":"A golang implementation of Yubico TOTP stack","archived":false,"fork":false,"pushed_at":"2023-03-23T16:56:13.000Z","size":114,"stargazers_count":6,"open_issues_count":1,"forks_count":1,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-05T03:02:47.621Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/bookingcom.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-06-09T11:48:04.000Z","updated_at":"2024-07-17T22:13:32.000Z","dependencies_parsed_at":"2024-06-20T01:40:41.713Z","dependency_job_id":null,"html_url":"https://github.com/bookingcom/yubistack","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bookingcom%2Fyubistack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bookingcom%2Fyubistack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bookingcom%2Fyubistack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bookingcom%2Fyubistack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bookingcom","download_url":"https://codeload.github.com/bookingcom/yubistack/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251196452,"owners_count":21550955,"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":[],"created_at":"2024-11-11T10:08:37.273Z","updated_at":"2025-04-27T19:33:07.843Z","avatar_url":"https://github.com/bookingcom.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"Yubistack\n=========\n\nThis is a Golang implementation of the Yubico second factor authentication stack.\nYubistack aimed to perform Yubikey (see [wiki](https://en.wikipedia.org/wiki/YubiKey)) token validation.\n\nYou can check [Yubico website](https://www.yubico.com) for information about what is a\n[Yubikey](https://www.yubico.com/getstarted/meet-the-yubikey/) or\n[how to get one](https://www.yubico.com/support/shipping-and-buying-information/).\n\nGetting started\n---------------\n\nIn order to be able to develop on this project and run the various examples you\nneed to have the following tool installed in your environment:\n\n- [git](https://git-scm.com/)\n- [go toolchain](https://golang.org/doc/install), starting from version 1.11\nas the project is using the newly introduced\n[modules feature](https://github.com/golang/go/wiki/Modules).\n- [make](https://www.gnu.org/software/make/)\n\nIn order to run the examples you will additionally require:\n\n- [sqlite](https://www.gnu.org/software/make/)\n- [curl](https://curl.haxx.se/)\n\nDue to the fact that this program manipulate sensible data (yubikeys aes key)\nit is highly recommended to use the samples data provided in order to avoid\npotential leaks.\n\nA good way to start using this project is to run the examples from the\n[examples](./examples) directory. There is a make target `make examples` which\nwill run those in proper order.\n\nAnother entrypoint would be to check the [test](./test) directory, which contains\nprograms to benchmark the yubistack authentication flow.\n\nBuild and run\n--------------\n\nYou can run a simple development server by issuing the following commands:\n\n- clone this repository: `git clone gitlab.booking.com/pps/yubistack`\n- build the YK-Val module: `make ykval`\n- generate a proper configuration: `./examples/ykval/run.sh --only-config`\n- run it with `./ykval --config=./examples/ykval/ykval.toml`\n\nOnce this is running you can test if it works using this `curl` example:\n`curl -k -s https://localhost:8081/wsapi/verify?otp=dteffujehknhfjbrjnlnldnhcujvddbikngjrtgh\u0026id=1\u0026nonce=gsgiiftz8lc8lxaa\u0026timestamp=1\u0026hash=4qh8RI0V2gsUSRXdBKQSmcMzivzCPJ8gc1iYdwIpx78=`\n\n\n```bash\n# First create and populate a sqlite3 databases\ncat assets/sql/sqlite/ykksm.sql examples/ykval/ykksm.sql | sqlite3 ykksm.db\ncat assets/sql/sqlite/ykval.sql examples/ykval/ykval.sql | sqlite3 ykval.db\necho \"UPDATE yubikeys SET modified=$(date +%s)\" | sqlite3 ykval.db\n\n# You can now start the server\ngo run cmd/yubistack/main.go --config examples/ykval/config.toml\n\n# Once this is done you can try to authenticate\nhttp -vv \"http://localhost:8080/wsapi/verify?otp=dteffujehknhfjbrjnlnldnhcujvddbikngjrtgh\u0026id=1\u0026nonce=gsgiiftz8lc8lxaa\u0026timestamp=1\"\n```\n\nModular components\n-------------------\n\nFollowing Yubico implementation the Yubistack project is built around three\ncomponents:\n\n- ykksm: is the Yubikey Key Storage Module (YK-KSM), it holds the AES keys of\n\tthe yubikeys and is responsible for the crypto part of the authentication protocol.\n- ykval: is the Yubikey Validation module (YK-VAL), this module is responsible\n\tfor validating tokens and handle the consensus flow.\n- ykauth: is the last module responsible for authentication of the user.\n\tit supports adding a PIN in front of a token and validating it against a\n\tdatabase, it then delegates token  validation to the ykval module.\n\nFor more information about the architecture design, the protocol and how\neverything is plug together in Yubistack, check out the [design documentation](./docs/design.md).\n\n\nBackground and Yubico API differences\n-------------------------------------\n\nYubistack project was started in an attempt to bring reliability and security to our\ncritical infrastructure. At Booking.com we are enhancing security by requiring  second\nfactor authentication. Employees can use Yubikeys to issue a token we then validate to\nprovide access.\n\nYubico is already providing a reference implementation on their GitHub. However,\nwe did not consider it suitable for various reasons: the setup was not clear,\nwe could not easily discern how things fit together, it was not easy to integrate\nit within our infrastructure (metrics, logs, and packaging), the\ndocumentation was lacking, and we needed a more capable API.\n\nYou can see a more detailed description of the choices we made in\n[the design documentation](./docs/design.md)\n\nLicence\n-------\n\nApache-2.0 License, see [LICENSE](./LICENSE)\n\nAcknowledgment\n--------------\n\nThis software was originally developed at [Booking.com](http://www.booking.com).\nWith approval from [Booking.com](http://www.booking.com), this software was released\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbookingcom%2Fyubistack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbookingcom%2Fyubistack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbookingcom%2Fyubistack/lists"}