Glossary

TOTP

When a site asks for six digits, nothing travels: it holds the same key you do and reads the same clock. That is why the code works with no signal, and why a copied key is silent.

TOTP is a one time code that two sides derive from a shared key and the clock, good for one short step.

How the six digits appear

Enrolment happens once. The site shows you a key, you keep a copy of it, and from then on both sides compute the same answer without speaking to each other.

1
The clock becomes a number
Time is cut into steps of thirty seconds and the current step is numbered from a fixed start.
2
The key signs that number
A keyed hash is taken over the step number, so only the holder of the key can produce it.
3
The hash is cut to six digits
Four bytes are picked out of the hash and reduced to the length the site expects.

Why it works with no signal

The two sides never talk. Both hold the key from the day of enrolment, and the only thing they share afterwards is time.

That is also the weak spot. A machine whose clock has drifted produces digits the site has already stopped accepting, and what comes back is the ordinary message about a wrong code.

Where a profile keeps the key

A profile can hold the key of the account it signs into, and the digits appear in the same window where the profile lives. Paste either the bare key a site prints next to its square image or the whole otpauth line that the image carries.

From that line the app takes the issuer, the account name, the length, the step and the algorithm. A link that counts sign-ins instead of seconds is turned away rather than read as though it were this one.

What stands between the key and a copy

The key sits in the profile file inside the app data folder, written for its owner alone and written whole, so an interrupted save leaves one version or the other rather than half of each.

Account passwords and proxy passwords are sealed by the operating system keychain. A one time key is not, so what protects it is the computer it sits on and the folder it sits in.

Often confused with

HOTP
The number being signed is a tally of sign-ins rather than the clock, so those codes wait for you instead of rolling over.
A code by text message
It travels through the phone network, which is why a swapped card takes the account along with it.
Recovery codes
A printed list where every line works once, kept for the day the key itself is gone.
The second step on your own account
That one lives on our server with its own recovery list, and a profile never carries it.

What this does not do

It is not a password manager. A profile holds one key, with no vault, no search across accounts and nowhere to keep the backup codes a site hands you.
The key is not sealed by the keychain. Owner only permissions close the file on macOS and Linux, and on Windows that work is done by the user account the folder sits in.
A lost key stays lost. It never reaches our server, and nothing in the app can rebuild it from the digits it has already produced.
The digits follow this computer's clock. A clock that has drifted makes sites reject them, and no message points at the clock as the reason.

Check it

Every claim above has a file behind it, and most have a stand that fails when the claim stops being true.

The digits match the published vectors of the standard, including a step number past thirty two bits: apps/desktop/src/lib/totp.js · apps/desktop/test/totp.js
The file holding the key is written for its owner alone and whole: apps/desktop/src/lib/secureFile.js · apps/desktop/test/secrets-on-disk.js
A restored profile keeps its length, step and algorithm: apps/desktop/test/config-import-2fa.js
The second step on your own account is single use, and so is each recovery code: apps/server/src/auth/2fa/totp.ts · apps/server/test/two-factor.js

Questions

Does the code go over the network?: No. The digits are computed from the key on this computer, so they appear with the network unplugged.
Can the app read the square image on screen?: Not from a picture. Sites print the key in text beside the image, and that text is what you paste.
What if a site issues eight digits or a sixty second step?: Paste the whole otpauth line, which carries those settings with it. A bare key carries none of them and is read with the common defaults.
Is this the two step sign-in on my own account?: No. That one lives on our server and has its own recovery list, while the key in a profile belongs to the account that profile signs into.
Can two people hold the same key?: Yes, and both of them see the same digits. A key is a shared secret, so handing it over is handing over the second step.

Next to this

See the digits beside the profile

Add a key to one profile, open the menu on its card, and the current code appears in the same window where the profile lives.

Download ARMANOS How the app stores secrets