{"id":17502070,"url":"https://github.com/itstorque/u2f","last_synced_at":"2025-04-23T03:32:18.785Z","repository":{"id":40550335,"uuid":"477090785","full_name":"itstorque/u2f","owner":"itstorque","description":"U2F key protocol over RawHID","archived":false,"fork":false,"pushed_at":"2022-10-18T19:42:25.000Z","size":5524,"stargazers_count":8,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-29T21:41:22.888Z","etag":null,"topics":["2factor","teensy","u2f","u2f-key","u2f-server"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/itstorque.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security_key_flow_diagram.png","support":null}},"created_at":"2022-04-02T15:14:07.000Z","updated_at":"2024-01-17T16:03:57.000Z","dependencies_parsed_at":"2022-08-09T22:51:13.754Z","dependency_job_id":null,"html_url":"https://github.com/itstorque/u2f","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/itstorque%2Fu2f","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itstorque%2Fu2f/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itstorque%2Fu2f/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itstorque%2Fu2f/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/itstorque","download_url":"https://codeload.github.com/itstorque/u2f/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250365349,"owners_count":21418670,"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":["2factor","teensy","u2f","u2f-key","u2f-server"],"created_at":"2024-10-19T20:37:16.932Z","updated_at":"2025-04-23T03:32:18.745Z","avatar_url":"https://github.com/itstorque.png","language":"C","readme":"# FIDO 2 U2F Protocol\n\nU2F dongle implementation created for and tested on a teensy 3.2 with the addition of a button.\n\n![docs/hardware_key.png](docs/hardware_key.jpeg)\n\n## Project Structure\n\n- [`microcontroller/`](microcontroller): teensy code that is uploaded\n  - [`main/`](microcontroller/main): our implementation\n  - [`crypto/`](microcontroller/crypto): AES128 implmentation from [crypto](https://github.com/OperatorFoundation/Crypto/tree/master/src)\n  - [`sha256/`](microcontroller/sha256): sha256 implementation from [crypto-algorithms](https://github.com/B-Con/crypto-algorithms).\n  - [`uECC/`](microcontroller/uECC): ECDH and ECDSA implementation for 8-bit, 32-bit, and 64-bit processors. See [micro-ecc](https://github.com/kmackay/micro-ecc).\n- [`webauthn-website/`](webauthn-website): test webauthn capable server in python\n- [`helpers/`](helpers): helper script for cert gen and usage page and usage id setup\n- [`docs/`](docs): contains a write-up explaining the implementation and any photos used\n- [`google-u2f-ref-code/`](google-u2f-ref-code): git submodule of google's u2f reference code\n\n### Microcontroller Directory\n\n- [`buffers.h`](microcontroller/main/buffers.h):\nData buffers used to recieve and send data\n\n- [`button.h`](microcontroller/main/button.h):\nCode for user presence confirmation with button\n\n- [`channels.h`](microcontroller/main/channel_manager.h):\nDefinitions that help with channel management\n\n- [`channels.h`](microcontroller/main/channels.h):\nStructs and definitions for channels\n\n- [`communication.h`](microcontroller/main/communication.h):\nMain module that controls HID communication between microcontroller and browser.\n\n- [`counter.h`](microcontroller/main/counter.h):\nEEPROM counter code\n\n- [`debug.h`](microcontroller/main/debug.h):\nMacros that help debugging\n\n- [`encryption.h`](microcontroller/main/encryption.h):\nMain setup for encryption libs and RNG functions\n\n- [`error_handling.h`](microcontroller/main/error_handling.h):\nCommunicating errors within the u2f and sw implementations\n\n- [`keys.h`](microcontroller/main/keys.h):\nKey storage. Ideally this would live on a secure element\n\n- [`main.ino`](microcontroller/main/main.ino):\nRun at start up. Manage and respond to HID communication\n\n- [`message_processing.h`](microcontroller/main/message_processing.h):\nMessage processing for u2f and sw protocols\n\n- [`packets.h`](microcontroller/main/packets.h):\nMain packet manager that follows u2f spec on packets\n\n- [`protocol_helpers.h`](microcontroller/main/protocol_helpers.h):\nHelpers for `protocol.h`\n\n- [`protocol.h`](microcontroller/main/protocol.h):\nU2F protocol implementation\n\n- [`test.h`](microcontroller/main/test.h):\nTest functions for encrypt and decrypt\n\n\n## Implementation\n\n![docs/security_key_flow_diagram.png](docs/security_key_flow_diagram.png)\n\nFor communication protocol, look at [4], [5], [6].\n\n- https://fidoalliance.org/specs/fido-u2f-v1.2-ps-20170411/fido-u2f-raw-message-formats-v1.2-ps-20170411.html#registration-request-message---u2f_register\n- https://fidoalliance.org/specs/u2f-specs-master/fido-u2f-hid-protocol.html#:~:text=With%20a%20packet%20size%20of,%2D%205)%20%3D%207609%20bytes\n- https://fidoalliance.org/specs/fido-v2.0-id-20180227/fido-client-to-authenticator-protocol-v2.0-id-20180227.html\n\n## Microcontroller\n\nOur current implementation is developed and tested on the Teensy 3.2. The hardware limitations\nare requiring RawHID and EEPROM/persistent storage.\n\nAdvised to upgrade USB version to 2.1 by modifying `#define USB_VERSION 0x200` to `#define USB_VERSION 0x210` in \n`/Applications/Arduino.app/Contents/Java/hardware/arduino/avr/cores/arduino/USBCore.h`.\n\nWe use RawHID to communicate. Run the [helpers/setup_hid_iface.sh](helpers/setup_hid_iface.sh)\n[Teensyduino location]\nto setup the teensyduino core lib USB headers. The section `USB_RAWHID` in\n `Teensyduino.app/Contents/Java/hardware/teensy/avr/cores/teensy3/usb_desc.h`\n should redefine the following:\n ```C\n  #define RAWHID_USAGE_PAGE  0xf1d0\n  #define RAWHID_USAGE  0x01\n  ```\nYou can reference\n[helpers/teensy3_core_usb_desc.h](helpers/teensy3_core_usb_desc.h) to see what it should look like.\n\nWe use a button in pull down configuration on pin `19` on a teensy 3.2, this can be changed in `microcontroller/main/button.h`.\n\n### Useful for debugging hardware connected to chrome\n\nChrome pages:\n\n`about://device-log`: see all USB device related events\n\n`about://usb-internals`: simulate connection and disconnection of virtual WebUSB devices\n\n# Debugging U2F\n\nThe test webauthn website in this repository lives at https://u2f-858.herokuapp.com/\n\nOther useful testing websites here:\n- https://webauthn.bin.coffee/  \n- https://demo.yubico.com/webauthn-technical/registration\n- https://akisec.com/demo/\n- https://webauthn.io/\n\n### Resources used for hardware definitions\n\n- List of vendor usb id's: http://www.linux-usb.org/usb.ids\n  - `0x2341` for Arduino\n  - `0x16c0` for Teensyduino\n- USB spec device descriptors: https://www.beyondlogic.org/usbnutshell/usb5.shtml#DeviceDescriptors\n- WebUSB API: https://wicg.github.io/webusb/\n- WebUSB arduino (useful to allow communication with arduino): https://github.com/webusb/arduino\n- Access USB Devices on the Web: https://web.dev/usb/\n- uECC doc: https://github.com/kmackay/micro-ecc/blob/master/examples/ecc_test/ecc_test.ino\n- Message headers: https://fidoalliance.org/specs/fido-u2f-v1.2-ps-20170411/inc/u2f.h\n- SW Command status responses: [ISO-7816]()\n\n## Website Notes!\n\nA website is setup to use webauthn at https://u2f-858.herokuapp.com/\nTo run [`webauthn-website`](webauthn-website) locally, follow intructions in [`webauthn-website/README.md`](webauthn-website/README.md)\n\n## Setting up google-u2f-ref-code submodule\nTo set up the submodule, run:\n```\ngit submodule init\ngit submodule update --init --recursive\n```\n\n## References\n\n[1] J. Lang, A. Czeskis, D. Balfanz, M. Schilder, and S. Srinivas, “Security Keys: Practical Cryptographic Second Factors for the Modern Web,” in Financial Cryptography and Data Security, vol. 9603, J. Grossklags and B. Preneel, Eds. Berlin, Heidelberg: Springer Berlin Heidelberg, 2017, pp. 422–440. doi: 10.1007/978-3-662-54970-4_25. Available: https://css.csail.mit.edu/6.858/2022/readings/u2f-fc.pdf\n\n[2] Reference code for U2F specifications. Google, 2022. Accessed: Apr. 02, 2022. [Online]. Available: https://github.com/google/u2f-ref-code\n\n[3] https://github.com/tonijukica/webauthn.git\n\n[4] https://fidoalliance.org/specs/fido-u2f-v1.2-ps-20170411/fido-u2f-raw-message-formats-v1.2-ps-20170411.html#registration-request-message---u2f_register\n\n[5] https://fidoalliance.org/specs/u2f-specs-master/fido-u2f-hid-protocol.html#:~:text=With%20a%20packet%20size%20of,%2D%205)%20%3D%207609%20bytes\n\n[6] https://fidoalliance.org/specs/fido-v2.0-id-20180227/fido-client-to-authenticator-protocol-v2.0-id-20180227.html\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitstorque%2Fu2f","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fitstorque%2Fu2f","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitstorque%2Fu2f/lists"}