https://shkspr.mobi/blog/2025/03/towards-a-test-suite-for-totp-codes/

Photo of Terence Eden. He has a beard and is smiling. Terence Eden's
Blog Mastodon. LinkedIn. GitHub. Email. Feed.  [?] Theme: [ /    ]
2025-03-02

Towards a test-suite for TOTP codes

@edent[a]2fa CyberSecurity HTOP MFA Open Source totp * 4 comments * 
1,250 words * read ~2,601 times.

---------------------------------------------------------------------
 

Because I'm a massive nerd, I actually try to read specification
documents. As I've ranted ad nauseam about the current TOTP^0 spec
being irresponsibly obsolete.

The three major implementations of the spec - Google, Apple, 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. 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.

Screenshot showing a QR code and numeric codes.

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

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

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. 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

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

(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

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

As we now know, SHA-1 has some fundamental weaknesses. The spec
comments (perhaps somewhat naively) 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

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

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

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

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

As discussed, this is what increments the counter for HOTP. The
Google Spec 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

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

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

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

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

  * If you're a user, please contribute tests or give feedback.
  * If you're a developer, please check your app conforms to the
    specification.
  * 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?

---------------------------------------------------------------------

 0. Time-based One Time Passwords. Not the TV show you remember from
    your youth, grandad. -[?]

---------------------------------------------------------------------

Share this post on...

  * Mastodon
  * Facebook
  * LinkedIn
  * BlueSky
  * Threads
  * Reddit
  * HackerNews
  * Lobsters
  * WhatsApp
  * Telegram

Interactive Relationship Graph

4 thoughts on "Towards a test-suite for TOTP codes"

 1. 2025-03-02 13:43
    [85ebfe3e]

    [mastodon] Ted.h says:

    @blog Do any of the errata listed (https://www.rfc-editor.org/
    errata_search.php?rfc=6238&rec_status=15&presentation=table) help
    with the issues you see? There was a thread on the security area
    list (saag@ietf.org) on this back in August of 2023 (https://
    mailarchive.ietf.org/arch/browse/saag/?q=rfc%206238) which may
    have touched on this.

    If not, a new erratum might help trigger discussion and/or an
    update.

    | Reply to original comment on mastodon.social
     1. 2025-03-02 13:48
        [37df032a]

        [mastodon] Terence Eden says:

        @ted_h @blog thanks! That's an interesting set of links. I'll
        check them out.

        | Reply to original comment on mastodon.social
 2. 2025-03-02 19:39
    []

    [news] news.ycombinator.com said on news.ycombinator.com:

    Towards a test-suite for TOTP codes | Hacker News
    Reply | Reply to original comment on news.ycombinator.com
 3. 2025-03-02 20:55
    [938e6310]

    [wandering] Gavin Chait; said on wandering.shop:

    @Edent Wow, this is awesome, thanks  I'm refactoring my base
    stack auth and this will be really, really helpful. And I had
    absolutely no idea the standard was _this_ borked.

    Reply | Reply to original comment on wandering.shop
 4. [svg]

    More comments on Mastodon.

What are your reckons? Cancel reply

All comments are moderated and may not be published immediately. Your
email address will not be published.

         [                                             ] 
         [                                             ] 
         [                                             ] 
         [                                             ] 
         [                                             ] 
         [                                             ] 
         [                                             ] 
Comment: [                                             ] 
[                    ]

Allowed HTML: <a href="" title=""> <abbr title=""> <acronym title="">
<b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q
cite=""> <s> <strike> <strong> <p> <pre> <br> <img src="" alt=""
title="" srcset="">

Your Name (required): [                              ] Your Email
(required): [                    ] Your Website (optional):
[                    ]

[Post Comment] 

To respond on your own website, write a post which contains a link to
this post - then enter the URl of your page here.
Learn more about WebMentions.

[                    ]

[Ping me!]

 Search

Search for: [                    ] [Search]
[?] Explore The Archives

  * 2025
      + January  17 posts 

        February  20 posts 

        March  2 posts 

        April  

        May  

        June  

        July  

        August  

        September  

        October  

        November  

        December  

  * 2024
      + January  31 posts 

        February  29 posts 

        March  31 posts 

        April  30 posts 

        May  31 posts 

        June  30 posts 

        July  19 posts 

        August  18 posts 

        September  18 posts 

        October  29 posts 

        November  31 posts 

        December  30 posts 

  * 2023
      + January  31 posts 

        February  28 posts 

        March  31 posts 

        April  30 posts 

        May  31 posts 

        June  30 posts 

        July  31 posts 

        August  31 posts 

        September  30 posts 

        October  31 posts 

        November  30 posts 

        December  31 posts 

  * 2022
      + January  30 posts 

        February  23 posts 

        March  15 posts 

        April  19 posts 

        May  19 posts 

        June  19 posts 

        July  19 posts 

        August  18 posts 

        September  12 posts 

        October  8 posts 

        November  30 posts 

        December  31 posts 

  * 2021
      + January  31 posts 

        February  28 posts 

        March  31 posts 

        April  30 posts 

        May  31 posts 

        June  30 posts 

        July  31 posts 

        August  31 posts 

        September  30 posts 

        October  31 posts 

        November  30 posts 

        December  31 posts 

  * 2020
      + January  31 posts 

        February  29 posts 

        March  31 posts 

        April  30 posts 

        May  31 posts 

        June  30 posts 

        July  31 posts 

        August  31 posts 

        September  30 posts 

        October  31 posts 

        November  30 posts 

        December  31 posts 

  * 2019
      + January  31 posts 

        February  12 posts 

        March  17 posts 

        April  12 posts 

        May  12 posts 

        June  10 posts 

        July  7 posts 

        August  5 posts 

        September  6 posts 

        October  14 posts 

        November  30 posts 

        December  17 posts 

  * 2018
      + January  8 posts 

        February  4 posts 

        March  6 posts 

        April  14 posts 

        May  5 posts 

        June  6 posts 

        July  6 posts 

        August  13 posts 

        September  14 posts 

        October  8 posts 

        November  30 posts 

        December  4 posts 

  * 2017
      + January  12 posts 

        February  9 posts 

        March  8 posts 

        April  4 posts 

        May  10 posts 

        June  5 posts 

        July  5 posts 

        August  6 posts 

        September  3 posts 

        October  4 posts 

        November  30 posts 

        December  

  * 2016
      + January  10 posts 

        February  10 posts 

        March  11 posts 

        April  9 posts 

        May  8 posts 

        June  9 posts 

        July  6 posts 

        August  9 posts 

        September  4 posts 

        October  2 posts 

        November  30 posts 

        December  14 posts 

  * 2015
      + January  8 posts 

        February  11 posts 

        March  10 posts 

        April  4 posts 

        May  9 posts 

        June  3 posts 

        July  7 posts 

        August  9 posts 

        September  10 posts 

        October  2 posts 

        November  30 posts 

        December  4 posts 

  * 2014
      + January  13 posts 

        February  13 posts 

        March  15 posts 

        April  14 posts 

        May  8 posts 

        June  7 posts 

        July  9 posts 

        August  5 posts 

        September  5 posts 

        October  1 post 

        November  30 posts 

        December  20 posts 

  * 2013
      + January  25 posts 

        February  17 posts 

        March  15 posts 

        April  18 posts 

        May  11 posts 

        June  14 posts 

        July  6 posts 

        August  14 posts 

        September  6 posts 

        October  4 posts 

        November  30 posts 

        December  15 posts 

  * 2012
      + January  14 posts 

        February  8 posts 

        March  13 posts 

        April  15 posts 

        May  10 posts 

        June  16 posts 

        July  8 posts 

        August  8 posts 

        September  6 posts 

        October  6 posts 

        November  30 posts 

        December  30 posts 

  * 2011
      + January  13 posts 

        February  11 posts 

        March  12 posts 

        April  12 posts 

        May  8 posts 

        June  8 posts 

        July  6 posts 

        August  5 posts 

        September  11 posts 

        October  7 posts 

        November  30 posts 

        December  17 posts 

  * 2010
      + January  6 posts 

        February  15 posts 

        March  12 posts 

        April  13 posts 

        May  4 posts 

        June  3 posts 

        July  15 posts 

        August  8 posts 

        September  11 posts 

        October  10 posts 

        November  30 posts 

        December  9 posts 

  * 2009
      + January  1 post 

        February  5 posts 

        March  3 posts 

        April  7 posts 

        May  12 posts 

        June  8 posts 

        July  10 posts 

        August  10 posts 

        September  12 posts 

        October  22 posts 

        November  31 posts 

        December  15 posts 

  * 2008
      + January  2 posts 

        February  

        March  2 posts 

        April  3 posts 

        May  2 posts 

        June  

        July  1 post 

        August  3 posts 

        September  1 post 

        October  3 posts 

        November  2 posts 

        December  1 post 

  * 2007
      + January  

        February  

        March  

        April  

        May  

        June  

        July  

        August  

        September  

        October  

        November  4 posts 

        December  5 posts 

  * 2006
      + January  

        February  

        March  

        April  1 post 

        May  

        June  

        July  

        August  

        September  

        October  

        November  1 post 

        December  

  * 2005
      + January  

        February  

        March  1 post 

        April  

        May  

        June  

        July  

        August  

        September  1 post 

        October  

        November  

        December  

  * 2004
      + January  

        February  

        March  

        April  

        May  5 posts 

        June  3 posts 

        July  1 post 

        August  

        September  

        October  

        November  

        December  

  * 2003
      + January  

        February  

        March  2 posts 

        April  

        May  

        June  

        July  

        August  

        September  

        October  

        November  

        December  

  * 2002
      + January  

        February  1 post 

        March  

        April  3 posts 

        May  

        June  

        July  

        August  

        September  

        October  

        November  

        December  

  * 2001
      + January  

        February  

        March  

        April  

        May  

        June  

        July  1 post 

        August  

        September  

        October  1 post 

        November  

        December  

  * 2000
      + January  

        February  

        March  1 post 

        April  

        May  

        June  

        July  

        August  

        September  

        October  1 post 

        November  1 post 

        December  

  * 1999
      + January  

        February  

        March  

        April  

        May  

        June  

        July  

        August  

        September  1 post 

        October  

        November  

        December  1 post 

  * 1998
      + January  

        February  

        March  

        April  

        May  1 post 

        June  

        July  

        August  

        September  

        October  

        November  

        December  

  * 1997
      + January  1 post 

        February  

        March  

        April  

        May  

        June  

        July  

        August  

        September  

        October  

        November  

        December  

  * 1995
      + January  

        February  

        March  1 post 

        April  

        May  1 post 

        June  

        July  

        August  

        September  

        October  

        November  

        December  

  * 1993
      + January  

        February  

        March  

        April  

        May  

        June  1 post 

        July  

        August  

        September  

        October  

        November  

        December  

  * 1987
      + January  

        February  

        March  

        April  

        May  

        June  

        July  

        August  

        September  

        October  

        November  

        December  1 post 

Subscribe by Email

[                                        ] 
[                    ]
[Subscribe]
  * (c) Terence Eden
  * Contact Me
  * Subscribe
  * Citations
  * Support My Blog
  * Library
  * On This Day
  * Link Rot
  * Trending Posts
  * About Me

ISSN 2753-1570 MMXXV *