##
Towards a test-suite for TOTP codes
Towards a test-suite for TOTP codes – Terence Eden’s Blog
Because I'm a massive nerd, I *actually try to read* specification documents. As I've ranted *ad nauseam* before, the current TOTP<a href="#fn:totp" class="footnote-ref" title="Time-based One Time Passwords. Not the TV show you remember from your youth, grandad." role="doc-noteref">0</a> spec is [irresponsibly obsolete](
The least secure TOTP code possible – Terence Eden’s Blog
).
The three major implementations of the spec - [Google](
GitHub
Key Uri Format
Open source version of Google Authenticator (except the Android app) - google/google-authenticator
), [Apple](
Apple Developer Documentation
Securing Logins with iCloud Keychain Verification Codes | Apple Developer Documentation
Use time-based codes generated on-device for a secure authentication experience.
), and [Yubico](
) - all subtly disagree on how it should be implemented. Every other MFA app has their own idiosyncratic variants. The [official RFC is infuriatingly vague](
IETF Datatracker
RFC 6238: TOTP: Time-Based One-Time Password Algorithm
This document describes an extension of the One-Time Password (OTP) algorithm, namely the HMAC-based One-Time Password (HOTP) algorithm, as defined...
). That's no good for a security specification. Multiple implementations are great, multiple interpretations are not.
So I've [built a nascent test suite](
) - you can use it to see if your favourite app can correctly implement the TOTP standard.
[](
)
Please do contribute tests and / or feedback.
Here's what the standard *actually* says - see if you can find apps which don't implement it correctly.##
[Background](#background )Time-based One Time Passwords are based on HOTP - HMAC-Based One-Time Password.
HOTP uses counters; a new password is regularly generated. TOTP uses time as the counter. At the time of writing this post, there have been about 1,740,800,000 seconds since the UNIX Epoc. So a TOTP with an period of 30 seconds is on counter (1,740,800,000 ➗ 30) = 58,026,666. Every 30 seconds, that counter increments by one.###
[Number of digits](#number-of-digits )How many digits should your 2FA token have? Google says 6 or 8. YubiCo graciously allows 7. Why those limits? Who knows!?
[The HOTP specification gives an *example* of 6 digits](
IETF Datatracker
RFC 4226: HOTP: An HMAC-Based One-Time Password Algorithm
This document describes an algorithm to generate one-time password values, based on Hashed Message Authentication Code (HMAC). A security analysis ...
). The example generates a code of 0x50ef7f19 which, in decimal, is 1357872921. It then takes the last 6 digits to produce the code 872921.
The TOTP RFC say:
> Basically, the output of the HMAC-SHA-1 calculation is truncated to obtain user-friendly values > [> 1.2. Background](
IETF Datatracker
RFC 6238: TOTP: Time-Based One-Time Password Algorithm
This document describes an extension of the One-Time Password (OTP) algorithm, namely the HMAC-based One-Time Password (HOTP) algorithm, as defined...
)
But doesn't say how far to truncate.
There's nothing I can see in the spec that *prevents* an implementer using all 10. The HOTP spec, however, *does* place a minimum requirement - but no maximum:
> Implementations MUST extract a 6-digit code at a minimum and possibly 7 and 8-digit code. Depending on security requirements, Digit = 7 or more SHOULD be considered in order to extract a longer HOTP value. > [> RFC 4226 - 5.3. Generating an HOTP Value](
IETF Datatracker
RFC 4226: HOTP: An HMAC-Based One-Time Password Algorithm
This document describes an algorithm to generate one-time password values, based on Hashed Message Authentication Code (HMAC). A security analysis ...
)
(As a minor point, the first digit is restricted to 0-2, so being 10 digits long isn't significantly stronger than 9 digits.)
Is a 4 digit code acceptable? The security might be weaker, but the usability is greater. Most apps will allow a *one* digit code to be returned. If no digits are specified, what should the default be?###
[Algorithm](#algorithm )The given algorithm in the HOTP spec is SHA-1.
> In order to create the HOTP value, we will use the HMAC-SHA-1 algorithm > [> RFC 4226 - 5.2. Description](
IETF Datatracker
RFC 4226: HOTP: An HMAC-Based One-Time Password Algorithm
This document describes an algorithm to generate one-time password values, based on Hashed Message Authentication Code (HMAC). A security analysis ...
)
As we now know, SHA-1 has some fundamental weaknesses. The spec comments (perhaps somewhat naïvely) about SHA-1:
> The new attacks on SHA-1 have no impact on the security of HMAC-SHA-1. > [> RFC 4226 - B.2. HMAC-SHA-1 Status](
IETF Datatracker
RFC 4226: HOTP: An HMAC-Based One-Time Password Algorithm
This document describes an algorithm to generate one-time password values, based on Hashed Message Authentication Code (HMAC). A security analysis ...
)
I daresay that's accurate. But the TOTP authors disagree and allow a for some different algorithms to be used. The specification for HMAC says:
> HMAC can be used with > *any*> iterative cryptographic hash function, e.g., MD5, SHA-1 [Emphasis added] > [> RFC 2104 - HMAC: Keyed-Hashing for Message Authentication](
IETF Datatracker
RFC 2104: HMAC: Keyed-Hashing for Message Authentication
This document describes HMAC, a mechanism for message authentication using cryptographic hash functions. HMAC can be used with any iterative crypto...
)
So most TOTP implementation allow SHA-1, SHA-256, and SHA-512.
> TOTP implementations MAY use HMAC-SHA-256 or HMAC-SHA-512 functions […] instead of the HMAC-SHA-1 function that has been specified for the HOTP computation > [> RFC 6238 - TOTP: Time-Based One-Time Password Algorithm](
IETF Datatracker
RFC 6238: TOTP: Time-Based One-Time Password Algorithm
This document describes an extension of the One-Time Password (OTP) algorithm, namely the HMAC-based One-Time Password (HOTP) algorithm, as defined...
)
But the HOTP spec goes on to say:
> Current candidates for such hash functions include SHA-1, MD5, RIPEMD-128/160. These different realizations of HMAC will be denoted by HMAC-SHA1, HMAC-MD5, HMAC-RIPEMD > [> RFC 2104 - Introduction](
IETF Datatracker
RFC 2104: HMAC: Keyed-Hashing for Message Authentication
This document describes HMAC, a mechanism for message authentication using cryptographic hash functions. HMAC can be used with any iterative crypto...
)
So, should your TOTP app be able to handle an MD5 HMAC, or even SHA3-384? Will it? If no algorithm is specified, what should the default be?###
[Period](#period )As discussed, this is what increments the counter for HOTP. The [Google Spec](
GitHub
Key Uri Format
Open source version of Google Authenticator (except the Android app) - google/google-authenticator
) says:
> The period parameter defines a period that a TOTP code will be valid for, in seconds. The default value is 30.
The TOTP RFC says:
> We RECOMMEND a default time-step size of 30 seconds > [> 5.2. Validation and Time-Step Size](
IETF Datatracker
RFC 6238: TOTP: Time-Based One-Time Password Algorithm
This document describes an extension of the One-Time Password (OTP) algorithm, namely the HMAC-based One-Time Password (HOTP) algorithm, as defined...
)
It doesn't make sense to have a negative number of second. But what about one second? What about a thousand? Lots of apps artificially restrict TOTP codes to 15, 30, or 60 seconds. But there's no specification to define a maximum or minimum value.
A user with mobility difficulties or on a high-latency connection probably wants a 5 minute validity period. Conversely, machine-to-machine communication can probably be done with a single-second (or lower) time period.###
[Secret](#secret )Google says the secret is
> an arbitrary key value encoded in Base32 according to RFC 3548. The padding specified in RFC 3548 section 2.2 is not required and should be omitted.
Whereas Apple says it is:
> An arbitrary key value encoded in Base32. Secrets should be at least 160 bits.
Can a shared secret be a single character? What about a thousand? Will padding characters cause a secret to be rejected or can they be safely stripped?###
[Label](#label )The label allows you to have multiple codes for the same service. For example Big Bank:Personal Account and Big Bank:Family Savings. The Google spec is slightly confusing:
> The issuer prefix and account name should be separated by a literal or url-encoded colon, and optional spaces may precede the account name. Neither issuer nor account name may themselves contain a colon.
What happens if they are *not* URl encoded? What about Matrix accounts which use a colon in their account name? Why are spaces allowed to precede the account name? Is there any practical limit to the length of these strings?
If no label is specified, what should the default be?###
[Issuer](#issuer )Google says this parameter is:
> **Strongly Recommended**> The issuer parameter is a string value indicating the provider or service this account is associated with, URL-encoded according to RFC 3986. If the issuer parameter is absent, issuer information may be taken from the issuer prefix of the label. If both issuer parameter and issuer label prefix are present, they should be equal.
Apple merely says:
> The domain of the site or app. The password manager uses this field to suggest credentials when setting up a new code generator.
Yubico equivocates with
> The issuer parameter is recommended, but it can be absent. Also, the issuer parameter and issuer string in label should be equal.
If it isn't a domain, will Apple reject it? What happens if the issuer and the label don't match?##
[Next Steps](#next-steps )<li>If you're a user, <a href="
https://codeberg.org/edent/TOTP_Test_Suite">please contribute tests</a> or give feedback.</li><li>If you're a developer, please check your app conforms to the specification.</li><li>If you're from Google, Apple, Yubico, or another security company - wanna help me write up a proper RFC so this doesn't cause issues in the future?</li><li id="fn:totp" role="doc-endnote"><p>Time-based One Time Passwords. Not the TV show you remember from your youth, grandad. <a href="#fnref:totp" class="footnote-backref" role="doc-backlink">↩︎</a></p></li>
#2fa #CyberSecurity #HTOP #MFA #OpenSource #totp
