9 ms·
Behind the 6-digit code: Building HOTP and TOTP from scratch
- 3eb7988a1663 1y agoIt is a bit terse, but there is a 20-line Python implementation which cleared up the ideas for me: https://github.com/susam/mintotp https://github.com/susam/mintotp
- easterncalculus 1y agoI love this one. The neat thing about TOTP is that while the algorithm itself is simple, the algorithms it depends on are also relatively simple, at least for cryptography. For HMAC you just need SHA1, and that can be implemented relatively easily without much more code. As a learning exercise it's quite good.
- lifthrasiir 1y agoIt is even shorter without boilerplates: def hotp(key, counter, digits=6, digest='sha1'): key = base64.b32decode(key.upper() + '=' * ((8 - len(key)) % 8)) counter = struct.pack('>Q', counter) mac = hmac.new(key, counter, digest).digest() offset = mac[-1] & 0x0f binary = struct.unpack('>L', mac[offset:offset+4])[0] & 0x7fffffff return str(binary)[-digits:].zfill(digits) def totp(key, time_step=30, digits=6, digest='sha1'): return hotp(key, int(time.time() / time_step), digits, digest)
- notpushkin 1y agoEver so slightly easier to read (IMO) if you inline arguments: def hotp(key: bytes, counter: int, digits: int = 6, digest: Literal["sha1", "sha256", "sha512"] = "sha1"): mac = hmac.digest( key=base64.b32decode(key.upper() + "=" * ((8 - len(key)) % 8)), msg=struct.pack(">Q", counter), digest=digest, ) offset = mac[-1] & 0x0F binary: int = struct.unpack(">L", mac[offset : offset + 4])[0] & 0x7FFFFFFF return str(binary)[-digits:].zfill(digits) And Pyright doesn’t yell at this version because no type-changing variables here: https://basedpyright.com/?typeCheckingMode=all&code=JYWwDg9gTgLgBAIwIYGcCmA2ALAKFJWOACxCQGM9xp4UYoBXMmSg%2BGUNHHAEzQDNiEGGAAUAazQBPAFxxaUADRwyEegDsYaKLOAal3YAHNgMFDo1wAvHAz6jaWrPlW4AchREkARlcBKaThwQXASki7I6NgAdAgAzABMvCq84lJR9GBgWiK%2BcADUbpaucABUcCIiABxwALRwADZoaqmSvrkApHCVbYHBKuqaUC7yjDBRYORiIq4AfACKrkr9Glq%2BvUGkZC4k5FFqaADuLUuqK4pwBoYOML5Rl9c563AQfHzo8NabANo1XgC6cAAZHAAAwADxBfCeCF0SCgYWsIyY6TUEzIU1mABlFnBvi83mgYNJ8e88lg-r4viCAcDwQB2V6M15PKCE%2BhQNRyOgiGFqOGtH6XExmP5RABefGA9XqIiFpjWPH4cBgQlEoSU7BAaAA%2BrQ0GBLLEQXZjKZLLYLvZaEUPN4-AFgnBWTB2ZyiKrjnBdDARJq0FE-Tk4AB6ZUcXWaMC%2BE3Ck3XXxAA https://basedpyright.com/?typeCheckingMode=all&code=JYWwDg9g... --- This is actually really helpful. I’m using Pass [1], which requires oathtool for OTP support [2]. I’m currently on a Mac without admin rights (so no Homebrew for me), and compiling oathtool is a PITA. I’ve wanted to put together a pure Python replacement for a while now, but with this it can be a single-file script: https://gist.github.com/notpushkin/7ac32ddf35a0c73bc6f181a1b5dffa4f https://gist.github.com/notpushkin/7ac32ddf35a0c73bc6f181a1b... [1]: https://www.passwordstore.org/ https://www.passwordstore.org/ [2]: https://github.com/tadfisher/pass-otp#requirements https://github.com/tadfisher/pass-otp#requirements
- LtWorf 1y agoWhy not do an integer division?
- SkiFire13 1y agoThose `>Q` and `>L` just make it more confusing for me, they just feel like a different language in the language...
- lucb1e 1y agoPerhaps you could contribute a version in a language that uses more descriptive names, something like BitPacker.WriteInt64 for >Q if I'm guessing correctly what that means (I'd equally need to check the docs to know what format these letters represent, but I don't find it too confusing when you know it's simply some binary / byte array version of the same thing)
- woadwarrior01 1y agoThey are well documented and essentially are a DSL with the Python struct module for specifying memory representations of packed structures. https://docs.python.org/3/library/struct.html#format-characters https://docs.python.org/3/library/struct.html#format-charact...
- jillesvangurp 1y agoI adapted code for Java back in the day from here: https://github.com/j256/two-factor-auth/blob/master/src/main/java/com/j256/twofactorauth/TimeBasedOneTimePasswordUtil.java https://github.com/j256/two-factor-auth/blob/master/src/main... A bit longer but most of it is just boilerplate Java stuff to deal with polymorphism and a base32 implementation. I recall, stripping most of that away in our internal adapted version of that. Key points: - generate a 16 character base32 secret and stuff it in a totp link. otpauth://totp/Alice:alice@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Alice - stuff that in a QR code and show it to the user so they point their phone authenticator app at it to store the secret. We used a js library for this. - store the secret with the user account in a secure way (we used aes encryption for this) - when verifying, use the secret, a timestamp in seconds after the epoch divided by 30 (simple normalization step applied on the client as well) and use the user provided number to construct a sha1 hmac and grab the last digits and prepend with zeros. The calculated string should be the same as what the user typed from their token app as long as their clock is in sync. - we actually implemented a grace period by calculating the before and after code as well so the user isn't screwed over if the number rotates while they were tapping out the code. While relatively easy to implement, we ran into a lot of friction rolling this out to normal users. Basically non technical people find this stuff super confusing and we had to hand hold quite a few people through the process and we also had to deal with people that lost their secret, or kept on using the wrong code (for a different account). The UX of this stuff is just terrible. Be prepared to deal with a lot of support overhead if you choose to roll this out. A non trivial percentage of users will manage to lock themselves out of their accounts.
- deleted 1y ago[deleted]
- lhayward450 1y ago[dead]
- notpushkin 1y ago> Also in some examples like Facebook's password recovery, this secret clock is not shared with the user directly but rather server's generated one-time password is sent via a trusted medium, such as an email to the user. I’m pretty sure Facebook just makes up a random number and stores it?
- SoftTalker 1y agoYes if you’re sending the number to the user, might as well just be random that’s a lot easier. Clocks and secrets only needed if the user is providing a number generated on the remote side.
- dogacel 1y agoGood catch. In my mind storing that random number is similar to storing a plain-text password, thus I thought they were generating TOTPs. Let's hear from others how they implemented it.
- SoftTalker 1y agoIt would be, but you could still store an expiration time, and limit the number of attempts to use the code. Considering you're probably sending it to the user insecurely anyway (via email or text message), that's probably safe enough.
- dogacel 1y agoThanks for all your insights, I have updated the post to outline this as a "theoretical" use-case rather than a practical one. I also revised it to include random number approach.
- notpushkin 1y agoPerhaps you could also highlight how in usual TOTP implementations (“scan this code with your authenticator app”) there’s no channel to MITM? I think it’s one of the key pros of TOTP vs, say, SMS as a second factor.
- yuliyp 1y agoFacebook's login/account recovery codes are not TOTP/HOTP, but are random numbers. Also, the author struggled to check their implementation. One can easily compare an implementation of many websites by grabbing the QR codes they use for login and importing into your favorite authenticator app and also decoding the QR code to get the secret. In theory your code should produce the same codes at the same time as the app.
- dogacel 1y agoHi, > Also, the author struggled to check their implementation. One can easily compare an implementation of many websites by grabbing the QR codes they use for login and importing into your favorite authenticator app and also decoding the QR code to get the secret. Can you clarify this? It's been some time since I have written the code, AFAIK it was working fine. Did you see any discrepencies when you tested the implementation against a real authenticator app?
- yuliyp 1y agoI was responding to the statement at the bottom of the article: "however I have struggled to find a website that help me check my implementation as their secret-key representations were not standardized. Thus, I have published my own short demo app to showcase." The Google Authenticator QR codes end up being a fairly standardized secret key representation.
- dogacel 1y agoEven though QR codes are standardized, the original RFCs do not use QR codes. That's what I tried to mean, you can't find apps that use plain-text secrets.
- Erikun 1y agoBoth RFC:s have test vectors you can use to write tests as well.
- nikolayasdf123 1y agoyep, it is just couple lines of code and nice math behind it
- ucarion 1y agoSix-digit verification codes for something like a "forgot password" flow are OTPs -- they're only good for one login -- but they are not HOTP/TOTPs. HOTP/TOTP has a registration step, where you copy a server-generated secret to your phone through a QR-code-encoded otpauth:// URI (https://github.com/google/google-authenticator/wiki/Key-Uri-Format https://github.com/google/google-authenticator/wiki/Key-Uri-...). That doesn't happen in a "forgot password" flow. Incidentally, if you think of TOTP as being HMAC(unix mod 30, secret), one idea would be to do public key crypto instead of symmetric HMAC stuff. That's basically what a security key is. If you additionally made it so that you couldn't phish the security key -- by having the OS + web browser know which apps can ask for which security keys -- you'd have reinvented WebAuthn. P.S.: Make you sure you have stuffing protection in place against these kinds of six-digit-code auth schemes. A million possibilities is often acceptable for a secondary factor, but it's useless if attackers can just try all million codes. Since they're in the thread, nice article 'dogacel! I've never seen an article on this that also took the time to dig into HMAC internals and that gnarly DT function.
- dogacel 1y agoAll very valuable comments! Actually I had a small edit on the "forget password" flow. I agree that an asymmetric key makes much sense. Secret key can be left at the user device while server only contains the public key. That sounds much more secure. I will dig deeper! True about the stuffing proteciton, I actually want to do further reading on how TOTP is secured from random attacks. Statistically you are expected to crack 1 account in every 1 million attempts in 6 digits codes. Those numbers look pretty huge in the context of security, and a bot-net can potentially brute force couple hundred accounts every day.
- anilakar 1y ago> HOTP/TOTP has a registration step, where you copy a server-generated secret to your phone through a QR-code-encoded otpauth:// URI RFC4226 and RFC6238 do not specify anything but the actual algorithm(s), which is exactly what OP implemented.
- dfox 1y ago
- DarkCrusader2 1y agoAnother post which describes the TOTP concisely - https://drewdevault.com/2022/10/18/TOTP-is-easy.html https://drewdevault.com/2022/10/18/TOTP-is-easy.html
- coppsilgold 1y agoIt's often a good idea to set up TOTP on accounts just because they may treat you differently due to having 2FA enabled. It would be harder to lose a gmail account to their "security" systems if you add TOTP to it for example. In the case of gmail adding it is a hassle involving devtools to emulate a hardware key first then add TOTP and then delete the hardware 2FA. Some password managers such as KeepassXC have TOTP incorporated into them and you can have it available right next to the password. It may defeat the purpose of 2FA under some assumptions.
- dogacel 1y agoI personally use 1Password with hardware keys where possible. > It may defeat the purpose of 2FA True, I think this as a mid-step of smooth transition from plain-text passwords to secure keys. You kinda get the benefit of both. Also those apps are secured much better than a traditional password manager as browser auto-fill for example.
- coppsilgold 1y ago> I think this as a mid-step of smooth transition from plain-text passwords to secure keys. This is not what I meant. Storing the TOTP next to the password means you don't really have 2FA as it's a single point of failure. Still better than nothing especially when the objective is what I stated in the first paragraph.
- encom 1y agoWell I started reading, but then the page was blurred and blocked by a popup, so I only made it about a third down.
- dogacel 1y agoA simple click on a random place on screen should discard it. I wanted to connect with my readers so I have added that subscribe popup recently. As I have figured nobody subscribed to my newsletter yet :( Let me know if it doesn't work. Also would be glad if you can give browser / platform.
- smw 1y agoI figured it out, but why not at least put an x to close in a corner so it behaves something like a normal popup?
- encom 1y agoPersonally, I'm never going to subscribe to any newsletter ever. If I like someones content enough, I might bookmark the page or subscribe via RSS. However, currently the page rudely interrupts before I've even finished reading. I've (probably) never visited your site before. I don't know if I like the content or not. If I reach the bottom of the page, there's fair chance I might. A notice at the bottom like "If you liked this, maybe you'll like my newsletter". It's far less disruptive and way more polite. I hated popups in the 90's, same as I do now. It's an immediate bounce for me. >browser / platform Vivaldi / Linux (Debian)
- deleted 1y ago[deleted]
- ur-whale 1y agohttps://github.com/pcarrier/gauth https://github.com/pcarrier/gauth
- thatkid02 1y agoAnd I put it like this https://medium.com/@thatkid02/javascript-2-factor-authentication-but-one-timepass-word-number-18a6ed433908 https://medium.com/@thatkid02/javascript-2-factor-authentica...
- deleted 1y ago[deleted]
- ryandv 1y agoNice. I recommend RFC 4226 and RFC 6238 for those wanting to get their feet wet in reading RFCs and other specifications; they were the first RFCs I implemented (with others), and one of the first Rust projects I worked on.
- rothfuss 1y agoThanks for the read, I learnt something about HOTP/TOTP today. I would like to know why the clocks are all weird though - the numbers aren't in the right places. Were the images in this blog post "AI" generated?
- dogacel 1y agoNope not AI generated, I have used excalidraw. Only the cover page is AI generated. Clock drawing was an asset, I didn't really spent time trying to match the time on clock to the time mentioned by the actors.
- ajsnigrutin 1y agoWhat is it with modern web design... can't even read a third of the page, and they already want my email to subscribe...
- dogacel 1y agoClicking anywhere else discards it. I have removed the popup anyway, seems like most people don't like it.
- Steve6 1y agoVery helpful article. I recently went down the TOTP rabbit hole and this article would have been great. I run a suite of servers and setup scripts that go with them. I can create users and secret keys easily enough using our APIs, but I needed a way to generate TOTP codes on the fly. I got it working on my machine, but sharing it with others was a bit difficult because really the only "logic" was generating the secrets while everything else was static data and storing responses from the APIs. I ended up making my own API to generate TOTP codes from secrets, <https://totpapi.com https://totpapi.com>. I try to make it clear it should only be used for testing, but it makes this kind of thing much easier for me. Maybe it will help someone else as well. :)
- unethical_ban 1y agoI always thought it odd that companies would spend so much money on services like Symantec VIP, with their proprietary BS and high costs, when someone could implement TOTP in 15 minutes as an internal service. It's a little more complicated now with push notifications and more complex flows, but for generic TOTP?
- dogacel 1y agoAgree and disagree, Deciding on how to store the credentials is still a hard task. Even storing the secret. Ideally it shouldn't stay as a plain text in your database. If you use cloud, something like KMS can be used for additional security. Also you should still consider replay attacks, rate limits etc. I agree in the sense that TOTP is hard to implement, no it is not. I hope this article helped people understand how TOTP works.
- gbraad 1y agoA while back I created a fallback for use from my dotfiles that can be used from the command line: https://github.com/gbraad-dotfiles/upstream/blob/02deb3ef922913a322f2b39a3defd1ccba881adb/zsh/.zshrc.d/secrets.zsh#L237-L282 https://github.com/gbraad-dotfiles/upstream/blob/02deb3ef922... using zsh, openssl and xxd This is not the first attempt I made. That was about 11 years ago with https://github.com/gbraad-apps/gauth https://github.com/gbraad-apps/gauth using JavaScript as an application that would work on a Nokia Symbian/Maemo phone and as a webapp.
- coolThingsFirst 1y ago> Like the traditional password authentication approach, the user and the authority (server) still needs to agree on a common secret key. Not sure what you mean by this, the server checks the hashed version of the password.
- coolThingsFirst 1y agoWhat is HMAC i still dont understand this part? Is it RSA encrytion?
- dogacel 1y agoNo, RSA is asymetric, where it has a public/private key pair. HMAC is symetric, it only has a secret and it can be used to hash values one-way.
- calvinmorrison 1y agohere's my small totp generator i use written in perl https://git.ceux.org/totp-perl.git/tree/totp.pl https://git.ceux.org/totp-perl.git/tree/totp.pl
- sksxihve 1y agoOn a side note, does anyone know why banks still rely on sms 2fa codes instead of TOTP? Is there some regulatory issue that makes it more difficult?
- UncleMeat 1y agoEverybody with a phone has SMS baked in. SMS also has a recovery process if you drop your phone in the toilet. Ultimately, this improved user experience outweighs the security benefit to TOTP for many organizations. TOTP also doesn't stop the biggest threat that SMS faces: phishing. Saving you from sim-swap attacks is just not a particular huge increase in security posture. My bank at least offers TOTP as an option, but the huge majority of people are going to enroll with SMS.
- Rygian 1y agoMy two banks require additional approval via push notification to the phone app. No SMS involved. (In France.)
- dogacel 1y agoSome banks in Switzerland give customers a device that generates TOTP codes.
- jqpabc123 1y agoI implemented TOTP as a command line app doing lookup and generation by pulling secrets from a locally encrypted password file. And before someone asks, the decrypt key is only stored in my head and the app fails silently after a significant delay if the decrypt fails. What I don't get is how HOTP is anything but a fail waiting to happen if used across an unreliable network. Maybe this explains why I have yet to encounter a real world deployment of HOTP.
- GoblinSlayer 1y agoIn my experience HOTP works fine, why not. The real world deployment is a replacement for sms otp.
- dogacel 1y agoClient and server can potentially agree on the counter with a handshake.
- jqpabc123 1y agoHow does such a handshake agreement get triggered? How does the server know that the handshake request is not malicious? 2FA that is resettable on demand (without 2FA) effectively voids the whole concept does it not? With HOTP, the counter is the shared secret --- but a dynamic and potentially unstable one. One failed request or one missed response and the counters on client and server are no longer in sync. Hence, a failure waiting to happen on an unreliable network.
- dogacel 1y agoWhy counter is the shared secret? In TOTP time is the counter and it is obviously not secret, so there is no reason to think the counter would be secret as well. Clients can sync their counter to match the server.
- jqpabc123 1y agoIn TOTP, time exists independent of both client and server and as you point out, is no secret to either. In HOTP, the secret counter is not independent and must remain synchronized between client and server. A counter that can be synchronized on demand is kinda superfluous --- not really secret and not terribly relevant either. All else being equal, an attacker can sync up just as easily as a legitimate client so why bother with the counter? I expect HOTP exists somewhere out there in the real world but I have yet to encounter it. Every 2FA I have actual experience with has been TOTP.