{"id":23207153,"url":"https://github.com/shampoofactory/the_kings_head","last_synced_at":"2025-10-11T03:52:49.553Z","repository":{"id":267691970,"uuid":"869628815","full_name":"shampoofactory/the_kings_head","owner":"shampoofactory","description":"Toy Time-Based One-Time password authenticator","archived":false,"fork":false,"pushed_at":"2024-12-12T14:16:06.000Z","size":354,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-05T11:17:05.367Z","etag":null,"topics":["totp","totp-authenticator","toy-project","x86-64-assembly-nasm"],"latest_commit_sha":null,"homepage":"","language":"C","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/shampoofactory.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","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":"2024-10-08T16:04:24.000Z","updated_at":"2024-12-12T14:16:10.000Z","dependencies_parsed_at":"2024-12-11T21:41:25.412Z","dependency_job_id":"abf65af1-0b8c-46dc-877b-712139a4d644","html_url":"https://github.com/shampoofactory/the_kings_head","commit_stats":null,"previous_names":["shampoofactory/the_kings_head"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/shampoofactory/the_kings_head","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shampoofactory%2Fthe_kings_head","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shampoofactory%2Fthe_kings_head/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shampoofactory%2Fthe_kings_head/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shampoofactory%2Fthe_kings_head/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shampoofactory","download_url":"https://codeload.github.com/shampoofactory/the_kings_head/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shampoofactory%2Fthe_kings_head/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279006105,"owners_count":26084026,"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","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["totp","totp-authenticator","toy-project","x86-64-assembly-nasm"],"created_at":"2024-12-18T17:17:56.779Z","updated_at":"2025-10-11T03:52:49.539Z","avatar_url":"https://github.com/shampoofactory.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# the_kings_head\n\nToy TOTP (Time-Based One-Time password) authenticator with an x86-64 assembly language (System V ABI) backend.\n\nThis project is a learning exercise in cryptography and x86-64 assembly language.\n\nIt should NOT be considered fit for use in any capacity.\n\nIt should NOT be used in place of a genuine authenticator app.\n\n\n## Overview\n\nThis project comprises two executables `totpfoo` and `totpgen`, both powered by the library backend `libtkh`.\n\n`totpfoo` is a stand-alone authenticator. It is compiled with a single set of encrypted TOTP parameters. A user-supplied password is required for authentication, decryption and TOTP code generation.\n\n`totpgen` generates encrypted TOTP parameters used in the compilation of `totpfoo`.\n\nThe library backend `libkth` is written in x86-64 assembly language (System V ABI).\n\nThe project was developed and tested on an Ubuntu 24-04 box.\n\nThe project will NOT work with Windows.\n\n\n## System requirements\n\nSystem requirements:\n- x86-64 cpu with AVX, AVX2, AES-NI and SHA extensions (the majority of CPUs post 2020).\n- Linux\n\nLibraries:\n- cunit\n- gcc\n- nasm\n\nOn Ubuntu:\n```\n$ sudo apt install libcunit1 libcunit1-doc libcunit1-dev nasm build-essential gcc\n```\n\n## TOTP authenticator usage\n\nThe default toy TOTP parameters are:\n```\nSECRET ASCII: 12345678901234567890\n      BASE32: GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ\nDIGITS: 8\nPERIOD: 30\nALGORITHM: SHA1\n```\n\nThe default toy TOTP password is:\n```\nSaturnV\n```\n\nBuild `totpfoo` with `make`, the executable relative path is `build/bin/`:\n```\n$ make totp\n```\n\nGenerate a toy TOTP code using the password:\n```\n$ ./build/bin/totpfoo SaturnV\n```\n\nThis assumes that the system clock is accurate.\n\nAs the toy default parameters are not secret, the TOTP output codes can be tested via an online generator using said parameters.\n\nhttps://piellardj.github.io/totp-generator/?secret=GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ\u0026digits=8\u0026period=30\u0026algorithm=SHA-1\n\nNB. Do NOT divulge any private keys online in this manner. Keep private keys secret.\n\n\n## TOTP authenticator generator usage\n\nNB. This is a toy TOTP generator, it should NOT be used in place of a genuine authenticator app.\n\nThe default toy TOTP parameters are defined in `totp-gen.c#main`.:\n\n`totp_gen` \n```C\n    // TOTP PARAM\n    char *key = \"12345678901234567890\";\n    uint32_t key_len = strlen(key);\n    uint32_t n_digits = 8;\n    uint32_t period = 30;\n\n    // PBKDF2 ENCRYPT PARAM\n    char *pass = \"SaturnV\";\n    uint64_t iter = 1000000;\n```\n\nSet the parameters as required and choose a strong password.\n\nBuild `totp_gen` with `make`, the executable relative path is `build/bin/`:\n```\n$ make totp_gen\n```\nOverwrite the default `totp_blk` parameters:\n```\n$ ./build/bin/totpgen \u003e res/totp/totp_blk.hex\n```\nBuild `totp_foo` with `make`, the executable relative path is `build/bin/`:\n```\n$ make totp\n```\n\n## Tests\n\nTests are automatically run during builds, but can be invoked separately:\n```\n$ make test\n...\nSuite: AESOFB\n  Test: AES256_OFB ...passed\n  Test: AES256_OFB_SMALL ...passed\nSuite: SHA1\n  Test: HMAC_SHA1_1 ...passed\n  Test: HMAC_SHA1_2 ...passed\n  Test: HMAC_SHA1_3 ...passed\n  Test: HMAC_SHA1_4 ...passed\n  Test: HMAC_SHA1_5 ...passed\n  Test: HMAC_SHA1_6 ...passed\n  Test: HMAC_SHA1_7 ...passed\nSuite: SHA1\n  Test: PBKDF2_HMAC_SHA1_E ...passed\n  Test: PBKDF2_HMAC_SHA1_0 ...passed\n  Test: PBKDF2_HMAC_SHA1_1 ...passed\n  Test: PBKDF2_HMAC_SHA1_2 ...passed\n  Test: PBKDF2_HMAC_SHA1_3 ...passed\n  Test: PBKDF2_HMAC_SHA1_4 ...passed\n  Test: PBKDF2_HMAC_SHA1_5 ...passed\n  Test: PBKDF2_HMAC_SHA1_6 ...passed\nSuite: SHA1\n  Test: SHA1_S ...passed\n  Test: SHA1_L ...passed\n  Test: SHA1_Permutations ...passed\nSuite: SHA1\n  Test: TOTP_SHA1_1 ...passed\n  Test: TOTP_SHA1_2 ...passed\n  Test: TOTP_SHA1_3 ...passed\n  Test: TOTP_SHA1_4 ...passed\n  Test: TOTP_SHA1_5 ...passed\n  Test: TOTP_SHA1_6 ...passed\n```\n\n## Parameter block encryption\n\nThe encrypted toy TOTP parameter block `totp_blk.hex` is defined as:\n\n```C\ntypedef struct __attribute__((packed))\n{\n    uint8_t salt[AES256_KEY_LEN];\n    uint8_t hmac[SHA1_MD_LEN];\n    uint32_t iter;\n    uint8_t param_enc[sizeof(TotpParam)];\n} TotpBlk;\n\n```\n\nParameter block encryption scheme:\n\n![](images/block.png)\n\n```\nFUNCTIONS:\nENC = AES256 OFB\nKDF = PBKDF2\nMAC = HMAC SHA1\n```\n```\n\nDATA:\nCIPHERTEXT = encrypted TOTP parameters\nITER = KDF iteration count\nKMAC = 256 bit derived HMAC key *\nKENC = 256 bit derived cipher key *\nPASSWORD = user-supplied password **\nPLAINTEXT = TOTP parameters\nSALT = 256 bit *\nTAG = HMAC DIGEST\n\n* Assuming a random salt, derived key collision is improbable with identical passwords.\n** Assumes a strong brute-force attack resistant password.\n```\n\n\n## X86-64 components\n\nX86-64 (System V ABI) components:\n- AES256 OFB\n- SHA1\n- HMAC SHA1\n- PBKDF HMAC SHA1\n- TOTP\n\nThe assembly language components are written in NASM syntax.\n\nThe x86_64 codebase assumes: AVX, AVX2, AES-NI and SHA extensions.\n\nERMSB support is desirable, but not essential, as `rep movsb` is used for short memory copies.\n\n\n## License\n\nLicensed under either of\n\n * Apache License, Version 2.0\n   ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)\n * MIT license\n   ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)\n\nat your option.\n\n\n## Resources\n\nIntel® Advanced Encryption Standard (AES) New Instructions Set\n\u003cbr /\u003e\nhttps://www.intel.com/content/dam/doc/white-paper/advanced-encryption-standard-new-instructions-set-paper.pdf\n\nIntel® SHA Extensions\n\u003cbr /\u003e\nhttps://www.intel.com/content/dam/develop/external/us/en/documents/intel-sha-extensions-white-paper-402097.pdf\n\nAdvanced Encryption Standard (AES)\n\u003cbr /\u003e\nhttps://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.197-upd1.pdf\n\nNIST Recommendation for Block Cipher Modes of Operation, Methods and Techniques\n\u003cbr /\u003e\nhttps://nvlpubs.nist.gov/nistpubs/legacy/sp/nistspecialpublication800-38a.pdf\n\nHMAC: Keyed-Hashing for Message Authentication\n\u003cbr /\u003e\nhttps://www.ietf.org/rfc/rfc2104.txt \n\nTest Cases for HMAC-MD5 and HMAC-SHA-1\n\u003cbr /\u003e\nhttps://www.ietf.org/rfc/rfc2202.txt \n\nPKCS #5: Password-Based Cryptography Specification Version 2.0\n\u003cbr /\u003e\nhttps://www.ietf.org/rfc/rfc2898.txt\n\nHOTP: An HMAC-Based One-Time Password Algorithm\n\u003cbr /\u003e\nhttps://www.ietf.org/rfc/rfc4226.txt\n\nPKCS #5: Password-Based Key Derivation Function 2 (PBKDF2) Test Vectors\n\u003cbr /\u003e\nhttps://www.ietf.org/rfc/rfc6070.txt\n\nTOTP: Time-Based One-Time Password Algorithm\n\u003cbr /\u003e\nhttps://www.ietf.org/rfc/rfc6238.txt\n\nNIST Cryptographic Algorithm Validation Program\n\u003cbr /\u003e\nhttps://csrc.nist.gov/projects/cryptographic-algorithm-validation-program/block-ciphers\nhttps://csrc.nist.gov/projects/cryptographic-algorithm-validation-program/secure-hashing\n\nAuthenticated encryption\n\u003cbr /\u003e\nRetrieved: 1st November 2024\n\u003cbr /\u003e\nhttps://en.wikipedia.org/wiki/Authenticated_encryption\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshampoofactory%2Fthe_kings_head","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshampoofactory%2Fthe_kings_head","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshampoofactory%2Fthe_kings_head/lists"}