{"id":22253490,"url":"https://github.com/nitrokey/nitrokey-hotp-verification","last_synced_at":"2025-06-14T13:02:40.336Z","repository":{"id":55044766,"uuid":"133981858","full_name":"Nitrokey/nitrokey-hotp-verification","owner":"Nitrokey","description":"A command line C app to validate HOTP codes on Heads","archived":false,"fork":false,"pushed_at":"2025-01-08T14:19:15.000Z","size":491,"stargazers_count":11,"open_issues_count":6,"forks_count":9,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-06-14T13:01:58.916Z","etag":null,"topics":["c","nitrokey","nitrokey-3","nitrokey-pro","nitrokey-stick-devices","nitrokey-storage","oath-hotp"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Nitrokey.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,"zenodo":null}},"created_at":"2018-05-18T16:59:10.000Z","updated_at":"2025-01-08T14:19:20.000Z","dependencies_parsed_at":"2024-05-17T11:33:51.486Z","dependency_job_id":"0a2e3566-ef90-4c0b-ac22-b6ab8497260a","html_url":"https://github.com/Nitrokey/nitrokey-hotp-verification","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/Nitrokey/nitrokey-hotp-verification","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nitrokey%2Fnitrokey-hotp-verification","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nitrokey%2Fnitrokey-hotp-verification/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nitrokey%2Fnitrokey-hotp-verification/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nitrokey%2Fnitrokey-hotp-verification/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Nitrokey","download_url":"https://codeload.github.com/Nitrokey/nitrokey-hotp-verification/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nitrokey%2Fnitrokey-hotp-verification/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259820792,"owners_count":22916544,"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":["c","nitrokey","nitrokey-3","nitrokey-pro","nitrokey-stick-devices","nitrokey-storage","oath-hotp"],"created_at":"2024-12-03T07:18:40.258Z","updated_at":"2025-06-14T13:02:40.264Z","avatar_url":"https://github.com/Nitrokey.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Nitrokey HOTP Verification Tool\n\nNitrokey [HOTP](https://tools.ietf.org/html/rfc4226) Verification Tool is a command line application, which communicates with a HOTP USB Security Dongle (over HIDAPI/libusb or CCID) to configure HOTP secrets and to verify HOTP codes. The Dongle being used needs to support HOTP verification, which is - at the time of writing - supported by Nitrokey Pro, Nitrokey Storage, Nitrokey 3 and Librem Key.\n\nThis solution is meant to allow one to verify the authenticity of his computer. During the boot process, the user will be asked to insert his HOTP USB Security Dongle device, which would then compare the on-device generated HOTP code and the one sent by the computer under verification. Afterward the Nitrokey indicates the verification result by LED animation:\n- OTP codes are equal - success =\u003e green LED blinking;\n- OTP codes are different - failure =\u003e red LED blinking quicker.\n\n\n## Requirements\nThis tool uses [HIDAPI](https://github.com/Nitrokey/hidapi) library to communicate with the Nitrokey device. It is a light wrapper over the `libusb` API and requires `usb-1.0` library at the link time.\n\nFor HID use this tool also reads from `/dev/urandom` to generate a session secret for the device-authorization purposes used in libnitrokey.\n\nThe USB HOTP Security Dongle device needs to support HOTP verification.\n\nThe CCID interface is implemented to support Nitrokey 3, which uses [Secrets App](https://github.com/Nitrokey/trussed-secrets-app) for its OTP handling.\n\n## Compilation\n\n### CMake\nThis tool uses CMake for compilation as its main driver. Please run:\n\n```bash\nmkdir build \u0026\u0026 cd build\ncmake .. \u0026\u0026 make\n```\nTo list compilation options please use:\n```bash\n$ cmake -LH ..\n-- Configuring done\n-- Generating done\n-- Build files have been written to: /home/sz/work/nitrokey-hotp-verification/build-clang\n-- Cache values\n// Add information about source code version from Git repository\nADD_GIT_INFO:BOOL=ON\n\n// Print debug information to stdout\nADD_LOG:BOOL=OFF\n\n// Choose the type of build, options are: None(CMAKE_CXX_FLAGS or CMAKE_C_FLAGS used) Debug Release RelWithDebInfo MinSizeRel.\nCMAKE_BUILD_TYPE:STRING=Debug\n\n// Install path prefix, prepended onto install directories.\nCMAKE_INSTALL_PREFIX:PATH=/usr/local\n\n// Link application against system HIDAPI library\nUSE_SYSTEM_HIDAPI:BOOL=OFF\n\n```\nExample compilation flags use:\n```bash\ncmake .. -DADD_GIT_INFO=OFF -DCMAKE_BUILD_TYPE=Release\n```\n\n### Makefile\nTo support reproducible build within Heads, additional build method using Gnu Make was added. To run:\n\n```bash\nmake\n```\n\n- At the moment `hidapi` library will always be bundled statically.\n- It is possible to provide `libusb` flags with `LIBUSB_FLAGS` and `LIBUSB_LIB`, otherwise it will be taken from the `pkg-config`.\n- Cross-compilation can be achieved overwriting standard build variables.\n- To disable embedding Git version it suffices to set `GITVERSION` to none.\n- Additional helper command was added to quickly compute SHA256 sum for Heads inclusion, and could be executed with `make github_sha`.\n\n\n### Meson\nMeson was added as a backup method in case, when build reproducibility could not be achieved with Gnu Makefile. It is not configurable. Usage:\n```bash\nmeson builddir\ncd builddir \u0026\u0026 ninja\n```\n\n## Usage\nBefore each device-related command a connection attempt will be done. If the Nitrokey Pro will not be detected immediately, the tool will monit for its insertion and will wait for 40 seconds (probing each 0.5s), quitting if connection would not be possible.\n  \nParameters in triangular braces `\u003c\u003e` are required, while these in square ones `[]` are optional.\n\n#### Setting HOTP secret\nTo set a new HOTP secret to be verified on the device please run:\n```bash\n./nitrokey_hotp_verification set \u003cBASE32 HOTP SECRET\u003e \u003cADMIN PIN\u003e [COUNTER]\n```\nwhere:\n- `BASE32 HOTP SECRET` is a new base32 HOTP secret, with up to 160 bits of length;\n- `ADMIN PIN` is a current Admin PIN of the device. Nitrokey 3 allows to skip providing it by accepting empty string as an argument: `\"\"`;\n- `COUNTER` is an optional argument holding an initial value for the HOTP counter to be set on the device.\n\n#### Verifying HOTP code\nTo verify the HOTP code please run `check` command as in:\n```bash\n./nitrokey_hotp_verification check \u003cHOTP CODE\u003e\n```\nwhere:\n`HOTP CODE` is a 6-digits HOTP code to verify\n\nIn case where the code is verified on the device, the green LED will blink 5 times. Otherwise, the red LED will blink 5 times, twice as fast as the green.\n\nVerification of 8-digits codes is available as an option through build configuration in [settings.h](settings.h). Responsible flag is configured on device during the HOTP secret setup phase and cannot be changed (until another secret rewrite) in the current implementation.\n\nSolution contains means to avoid desynchronization between the host's and device's counters.\nDevice calculates up to 9 values ahead of its current counter to find the matching code (in total it calculates HOTP code for 10 subsequent counter positions). In case:\n- no code would match - the on-device counter will not be changed;\n- code would match, but with some counter's offset (up to 9) - the on-device counter will be set to matched code-generated HOTP counter and incremented by 1;\n- code would match, and the code matches counter without offset - the counter will be incremented by 1.\n\nDevice will stop verifying the HOTP codes in case, when the difference between the host and on-device counters will be greater or equal to 10.\n\nThis allows to boot the system without USB Security Dongle 9 times, until it would lose synchronization and would need to be set up again.\n\n#### Identifying the device\nTo show information about the connected device please use:\n```bash\n$ ./nitrokey_hotp_verification info\n# which results should be similar to:\nHOTP code verification application, version 1.4\nConnected device status:\n Card serial: 0x5F11\n Firmware: v0.9\n Card counters: Admin 3, User 3\n```\nTo show only the card's serial please run:\n```bash\n$ ./nitrokey_hotp_verification id\n```\n\n#### AES key regeneration\nTool supports AES key regeneration call, which should be called after each GnuPG factory-reset operation for Nitrokey Pro, Librem Key and Nitrokey Storage devices. Example call:\n\n```bash\n./nitrokey_hotp_verification regenerate 12345678\n```\n\n#### Complete example\n```bash\n# set 160-bit secret with RFC's test secret \"12345678901234567890\"\n./nitrokey_hotp_verification set GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ 12345678\n./nitrokey_hotp_verification check 755224\n./nitrokey_hotp_verification check 287082\n./nitrokey_hotp_verification check 359152\n\n# show response to a wrong code\n./nitrokey_hotp_verification check 111111\n\n```\n\n#### Help screen\n```bash\nHOTP code verification application, version 1.4\nAvailable commands:\n ./nitrokey_hotp_verification id\n ./nitrokey_hotp_verification info\n ./nitrokey_hotp_verification version\n ./nitrokey_hotp_verification check \u003cHOTP CODE\u003e\n ./nitrokey_hotp_verification regenerate \u003cADMIN PIN\u003e\n ./nitrokey_hotp_verification set \u003cBASE32 HOTP SECRET\u003e \u003cADMIN PIN\u003e [COUNTER]\n\n```\n\n#### Exit codes\nIn case the tool would encounter any critical issues, it will print error message and return to the OS with a proper exit code value. Meaning of the exit values could be checked with the following table: \n\n| Error code name          | Exit code | Meaning                                                                                                                               |\n|--------------------------|:---------:|---------------------------------------------------------------------------------------------------------------------------------------|\n| EXIT_NO_ERROR            |     0     | Operation was completed successfully or HOTP code was confirmed to be valid                                                           |\n| EXIT_CONNECTION_ERROR    |     1     | Could not connect to the Nitrokey Pro device                                                                                          |\n| EXIT_WRONG_PIN           |     2     | Could not authorize the user with the user given PIN                                                                                  |\n| EXIT_OTHER_ERROR         |     3     | Unknown error                                                                                                                         |\n| EXIT_INVALID_HOTP_CODE   |     4     | Entered HOTP code was calculated to be invalid                                                                                        |\n| EXIT_UNKNOWN_COMMAND     |     5     | Device does not support HOTP verification command in this firmware                                                                    |\n| EXIT_SLOT_NOT_PROGRAMMED |     6     | On-device slot was not programmed with HOTP secret yet                                                                                |\n| EXIT_BAD_FORMAT          |     7     | Either entered HOTP code for validation or base32 secret to set was in improper format (too long or consisting of invalid characters) |\n| EXIT_CONNECTION_LOST     |     8     | Connection to the device was lost during the process                                                                                  |\n| EXIT_INVALID_PARAMS      |    100    | Application could not parse command line arguments                                                                                    |\n\n## Tests\nSolution was tested against 160-bits test vectors available at [RFC_HOTP-test-vectors.txt](RFC_HOTP-test-vectors.txt). \n\n#### Environment\n- Ubuntu 18.04\n- gcc (Ubuntu 7.3.0-16ubuntu3) 7.3.0\n- libusb-1.0 package version: 2:1.0.21-2\n- CMake 3.10.2\n\nCode analysers:\n- Valgrind-3.13.0\n- Cppcheck 1.82\n- Clang tools package version: 1:5.0.1-4\n\n#### Code correctness\nCode was tested against Valgrind, Clang static checker (scan-build) and Cppcheck. Compilation is run with all warnings enabled (flags `-Wall -Wextra`).\n\n#### Unit tests\nWith `-DCOMPILE_TESTS=TRUE` compilation switch it is possible to compile tests, which are checking the solution against RFC specification. Details are available at [tests/test_hotp.cpp](tests/test_hotp.cpp). To run them please issue:\n```bash\n./test_hotp\n```\nTests could be run selectively - see `--help` switch to learn more.\n\n**Warning:** before running the tests please make sure to use a not production device to avoid important data removal. Tests use default Admin PIN: `12345678`. \n\n#### Size\nIn a Release build, with statically linked HIDAPI, application takes 50kB of storage (42kB stripped).\n\n#### Build reproducibility\nBuild reproducibility was tested with Repro-test tool. Docker files for Ubuntu and Fedora are provided for tests on both systems. See https://reproducible-builds.org/ for more details.\nFollowing commands will build Docker environments, execute tool builds and show final SHA256 hashes of the binaries:\n```bash\nmake -f Makefile-repro.mk repro-build\nmake -f Makefile-repro.mk repro-run\n```\n\n## Development\nWhen `NDEBUG` is set, the log messages are not printed out.\n\n## License\nCode is licensed under GPLv3, excluding `base32.{h,c}` files. The latter are downloaded from [tpmtopt](https://github.com/osresearch/tpmtotp) project and seem to be licensed under [MIT](https://choosealicense.com/licenses/mit/) license.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnitrokey%2Fnitrokey-hotp-verification","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnitrokey%2Fnitrokey-hotp-verification","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnitrokey%2Fnitrokey-hotp-verification/lists"}