How TOTP works, and how HostSpica Authenticator implements it

The idea in one paragraph

When you add an account to an authenticator app, the service gives you a secret key, usually as a QR code. Both sides now hold the same secret. After that, neither side needs to talk to the other: each one computes the current code from the secret and the clock, and the service checks that your code equals its own. That is why an authenticator works in airplane mode.

The algorithm, step by step

1. Work out the time step: T = floor(unix_time / period). The period is 30 seconds for almost every service, so every 30 seconds T goes up by one.
2. Write T as an 8-byte big-endian number.
3. Compute an HMAC over those 8 bytes, keyed with the secret. The hash is SHA-1 by default; SHA-256 and SHA-512 are also allowed by the RFC.
4. Dynamic truncation (RFC 4226 section 5.3): take the last 4 bits of the HMAC output as an offset, read 4 bytes starting there, and clear the top bit so the result is a positive 31-bit number.
5. Take that number modulo 10 to the power of the digit count (6 by default, 8 is also used) and pad with leading zeros.

Because the HMAC output looks random and the offset moves around, knowing a few codes tells an attacker nothing useful about the secret.

What HostSpica Authenticator runs

The Authenticator code is a direct translation of that list. It uses only javax.crypto.Mac, so there is no OTP library to trust or update. This is the core of it:

fun generate(secret: ByteArray, counter: Long, digits: Int = 6, algorithm: HmacAlgorithm = HmacAlgorithm.SHA1): String {
    val counterBytes = ByteBuffer.allocate(8).putLong(counter).array()
    val mac = Mac.getInstance(algorithm.macName)
    mac.init(SecretKeySpec(secret, algorithm.macName))
    val hash = mac.doFinal(counterBytes)
    val offset = hash[hash.size - 1].toInt() and 0x0F          // dynamic truncation
    val binary = ((hash[offset].toInt() and 0x7F) shl 24) or
        ((hash[offset + 1].toInt() and 0xFF) shl 16) or
        ((hash[offset + 2].toInt() and 0xFF) shl 8) or
        (hash[offset + 3].toInt() and 0xFF)
    return (binary % 10.pow(digits)).toString().padStart(digits, '0')
}

TOTP is then one more line: the counter passed in is (now - 0) / period. The app supports SHA-1, SHA-256 and SHA-512, 6 to 8 digits, and custom periods, because services that deviate from the 30-second default still follow the same RFC. Counter-based HOTP accounts use the same function with a stored counter, and the app can resynchronise a drifted counter by searching a window of the next 10 values for the code you type.

Where the secret lives

The secret is stored encrypted with AES-256-GCM under a key that Android Keystore generates and never lets out of secure hardware. It exists in plain form only for the moment it takes to compute a code. See Keystore key hierarchy for the full picture.

What TOTP does not protect against

Why SHA-1 is still the default

Nearly every service issues SHA-1 TOTP secrets, so apps must support it. The attacks that broke plain SHA-1 collision resistance do not apply to HMAC-SHA1 in the same way, which is why the RFC-based use is still considered acceptable. Where a service offers SHA-256 or SHA-512, our app uses it.