{"id":25812580,"url":"https://github.com/daisvke/ft_otp","last_synced_at":"2025-02-28T01:54:34.413Z","repository":{"id":209529833,"uuid":"723123429","full_name":"daisvke/ft_otp","owner":"daisvke","description":"This program allows you to securely store an initial password in an encrypted file and generate a new TOTP (Time-based One-Time Password) every time it is requested. It provides both a CLI and a GUI version.","archived":false,"fork":false,"pushed_at":"2025-02-06T08:41:29.000Z","size":31215,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-06T09:35:33.077Z","etag":null,"topics":["cpp","cryptography","ecole42","ft-otp","otp-generator","qrcode-generator","qt","security","totp","totp-generator"],"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/daisvke.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":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-11-24T18:44:41.000Z","updated_at":"2025-02-06T08:41:33.000Z","dependencies_parsed_at":"2023-12-17T00:26:54.854Z","dependency_job_id":"2150be3f-71b9-4a0e-8d94-62edebb67986","html_url":"https://github.com/daisvke/ft_otp","commit_stats":null,"previous_names":["daisvke/ft_otp"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daisvke%2Fft_otp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daisvke%2Fft_otp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daisvke%2Fft_otp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daisvke%2Fft_otp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/daisvke","download_url":"https://codeload.github.com/daisvke/ft_otp/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241087104,"owners_count":19907383,"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":["cpp","cryptography","ecole42","ft-otp","otp-generator","qrcode-generator","qt","security","totp","totp-generator"],"created_at":"2025-02-28T01:54:33.926Z","updated_at":"2025-02-28T01:54:34.392Z","avatar_url":"https://github.com/daisvke.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ft_otp\n\n## Description\nThis program allows you to securely store an initial secret in an encrypted file and generate a new TOTP (Time-based One-Time Password) every time it is requested. It generates a QR code containing the secret to be shared with other applications.\u003cbr /\u003e\nIt provides both a CLI (Command Line Interface) and a GUI (Graphical User Interface) version made with Qt Creator.\n\n---\n\n## Requirements\n### 1. **Crypto++ Library**\nUsed for performing HMAC-SHA1 operations.\n```bash\n# Install on Ubuntu\nsudo apt install libcrypto++X libcrypto++-dev libcrypto++-utils libcrypto++-doc\n# Install on Termux\npkg install cryptopp\n```\n\n### 2. **Qrencode**\nUsed for producing QR codes.\n```bash\n# Install on Ubuntu\nsudo apt install libqrencode-dev\n# Install on Termux\npkg install libqrencode\n```\n\n### 3. **PNG Library**\nUsed for QR code generation.\n```bash\n# Install on Ubuntu\nsudo apt install libpng-dev\n# Install on Termux\npkg install libpng\n```\n\n### Secret Key\n- The `keys` folder contains a set of valid and invalid keys (for testing purposes). \n  - Valid keys: `key.hex`, `key.base32`.\n- The secret key file **must not end with a newline character**. To ensure this:\n  ```bash\n  echo -n \u003ckey_string\u003e \u003e \u003ckey_file\u003e\n  ```\n- Keys must:\n  - Be in **Hex** or **Base32** format.\n  - Contain at least **64 characters**.\n\n---\n\n## Commands\n\n### CLI\n#### Installation:\n```bash\ncd cli\nmake\n```\n\n#### Usage:\n```bash\n./ft_otp [OPTIONS] \u003ckey_file\u003e\n\nOptions:\n  -g, --generate     Generate and save the encrypted key\n  -k, --key          Generate a password using the provided key\n  -q, --qrcode       Generate a QR code containing the key (requires -g)\n  -v, --verbose      Enable verbose output\n  -h, --help         Show this help message and exit\n```\n\n#### Examples:\n1. **Generate and save an encrypted key with a QR code:**\n   ```bash\n   ./ft_otp -gk \u003ckey_file\u003e\n   ```\n   - The key is stored in an encrypted file named `ft_otp.key` using AES encryption.\n\n2. **Generate a TOTP password:**\n   ```bash\n   ./ft_otp -k ft_otp.key\n   ```\n   - The program generates a temporary password based on the provided encrypted key.\n\n3. **Verify the TOTP code using `oathtool`:**\n   ```bash\n   oathtool --totp $(cat keys/key.hex) -v    # Hex key\n   oathtool --totp -b $(cat keys/key.base32) -v   # Base32 key\n   ```\n\n#### Testing\n```bash\n# With a Hex key\nmake \u0026\u0026 ./ft_otp -g keys/key.hex \u0026\u0026 ./ft_otp ft_otp.key -k\n\n# With a Base32 key\nmake \u0026\u0026 ./ft_otp -g keys/key.base32 \u0026\u0026 ./ft_otp ft_otp.key -k\n\n# With a Bad key\nmake \u0026\u0026 ./ft_otp -g keys/key.base32hex \u0026\u0026 ./ft_otp ft_otp.key -k\n```\n\n##### Predefined Makefile recipes:\n```bash\nmake hex    # Run with a Hex key\nmake b32    # Run with a Base32 key\nmake bad    # Run with an invalid key\nmake tests  # Run all tests\n```\n\n\u003cimg src=\"screenshots/cli.png\" alt=\"CLI Screenshot\" /\u003e\n\n---\n\n## QR Code Generation for TOTP Secrets\nThis program can generate a QR code containing the secret to be shared with other applications.\u003cbr /\u003e\nQR codes simplify sharing TOTP secrets by encoding them in a scannable format.\n\n#### To compare with the QR code standards:\n1. **Generate a QR Code:**\n   ```bash\n   qrencode -o qrcode.png $(cat keys/key.hex)\n   ```\n2. **Read the QR Code:**\n   ```bash\n   zbarimg qrcode.png\n   ```\n\n---\n\n## Technical Notes\n\n### How It Works\n\n#### 1. QR Code Dimensions and Scaling:\n- The QR code is generated with scaled-up resolution for better readability.\n\n#### 2. PNG File Creation:\n- **libpng** is used to create a grayscale PNG file.\n  - **Black pixels** represent QR code modules (`0x00`).\n  - **White pixels** fill the rest (`0xFF`).\n\n#### 3. Key URI Format:\n- We use a TOTP URI in the following format:\n  ```\n  otpauth://totp/\u003cPROJECT_NAME\u003e:\u003cUSER_EMAIL\u003e?secret=\u003cSECRET\u003e\u0026issuer=\u003cPROJECT_NAME\u003e\n  ```\n  - Example:\n    ```\n    otpauth://totp/MyService:myuser@example.com?secret=BASE32SECRET\u0026issuer=MyService\n    ```\n\n#### 4. Steps for QR Code Generation:\n- A TOTP URI is dynamically created using the provided secret and project name.\n- The URI is encoded into a QR code using the **qrencode** library.\n- The resulting QR code is saved as a PNG file in the current directory and can be also printed on the terminal.\n\n---\n\n### Decoding Base32 to Raw Bytes\n\nIn the process of TOTP generation, Base32 decoding is mandatory to get the intermediate key value in the right format.\u003cbr /\u003e\nInitially, Base32 decoding was attempted with `Base32Decoder`:\n\n```cpp\nBase32Decoder decoder;\ndecoder.Put((byte*)key.data(), key.size());\ndecoder.MessageEnd();\nsize_t size = decoder.MaxRetrievable();\ndecodedKey.resize(size);\ndecoder.Get(decodedKey, size);\n```\n\nHowever, the decoded output did not match the output of `oathtool --totp -b $(cat key.base32) -v`.  \nThis led to the hypothesis that differences in the existence of a padding (`=`) in our original key might cause discrepancies, but adding or removing padding didn’t affect either implementation.\n\n#### Findings:\nThe key difference between our implementation (`decodeBase32RFC4648()`) and `oathtool` likely stems from strict adherence to [RFC 4648](https://datatracker.ietf.org/doc/html/rfc4648#section-6). Specifically:\n- The `Base32Decoder` used by our code followed the **Differential Unicode Domain Encoding (DUDE)** standard, which employs a different character set.\n\n#### DUDE Decoder's Character Set:\nThe character set used by DUDE differs from the Base32 standard:\n```\n// DUDE Decoder's set of characters\nstatic const char base32[] = {\n  97, 98, 99, 100, 101, 102, 103, 104, 105, 106, 107,     // a-k\n  109, 110,                                               // m-n\n  112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122,  // p-z\n  50, 51, 52, 53, 54, 55, 56, 57                          // 2-9\n};\n```\nHowever, RFC 4648 decoding is only using `2-7` as numerical values.\u003cbr /\u003e\nThis mismatch between the DUDE and RFC 4648 Base32 decoding caused inconsistencies in the generated TOTP.\n\n## Graphic User Interface\n\n\u003cimg src=\"screenshots/gui.png\" /\u003e\n\n### Install Qt Creator\n* We used Qt Creator (Qt6) in order to create the GUI.\n* Install the latest open source free version of Qt from the \u003ca href=\"https://www.qt.io/download-qt-installer-oss\"\u003eofficial website\u003c/a\u003e.\n\n### Build project using CMake\n#### Install CMake\nIn addition to the packages downloaded by the online Qt installer, we had to install the following packages to make CMake work:\n```bash\nsudo apt-get install cmake\nsudo apt-get install qtbase5-dev\nsudo apt-get install qtdeclarative5-dev\n```\nIt should be noted that we only found the Qt5 packages for our system but Qt6 versions would've been best suited.\n\n#### Building \u0026 Cleaning\n```bash\ncd gui\n# Remove the existing build folder if any\nrm -rf build\n# Create a new build folder in which the project will be built\nmkdir build\ncd build\n# Generate into the build folder the build files using the CMake configuration files in the parent folder \ncmake ..\n# Build the project\ncmake --build .\n\n# Or to build inside the gui/ folder, simply do:\nsudo make install\n\n# Clean (to be executed from 'gui/' folder)\nmake clean\nrm CMakeCache.txt CMakeFiles\n```\n\n### Running\nThis repository already contains a binary of the GUI.\n```\ncd gui\n./ft_otp_gui\n```\n\n### Endianness\nTOTP requires the timestamp in **big-endian format** (most significant byte first). Incorrect endianness will produce invalid codes.  \nTo verify system endianness:\n```bash\nlscpu | grep Order    # Output: Byte Order: Little Endian\n```\n\n---\n\n### Algorithm for TOTP\n#### Differences Between HOTP and TOTP:\n- **HOTP**: Based on a counter.\n  ```\n  HOTP = Truncate(HMAC(secret, counter))\n  ```\n- **TOTP**: Based on time.\n  ```\n  TOTP = Truncate(HMAC(secret, time_step))\n  ```\n\n#### Key Format:\n- Always 6 digits.\n\n---\n\n## Troubleshooting\n\n### Missing Standard C++ Library Development Files\nError:\n```\nfatal error: 'iostream' file not found\n```\nSolution:\n```bash\nsudo apt install build-essential clang libc++-14-dev libstdc++-12-dev\n```\n\n---\n\n## References\n- [Crypto++ Advanced Encryption Standard (AES)](https://www.cryptopp.com/wiki/Advanced_Encryption_Standard)\n- [HOTP RFC 4226](https://www.ietf.org/rfc/rfc4226.txt)\n- [TOTP RFC 6238](https://datatracker.ietf.org/doc/html/rfc6238#section-4)\n- [Base32 RFC 4648](https://datatracker.ietf.org/doc/html/rfc4648#section-6)\n- [Key URI Format (Google Authenticator)](https://github.com/google/google-authenticator/wiki/Key-Uri-Format)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaisvke%2Fft_otp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdaisvke%2Fft_otp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaisvke%2Fft_otp/lists"}