One-time passwords (OTP)

A one-time password (OTP) is a temporary code used for two-factor authentication (2FA). KeePassium can store and generate time-based one-time passwords, which the most used scheme in modern web.

Storing OTPs in your database is useful as a secure, portable and vendor-independent method.

How OTPs work

This section is a quick overview of how time-based OTPs work.

During the initial setup, the online service and client app (such as KeePassium) exchange a secret. This is a short sequence of characters, randomly generated by the server and send to the client via a QR code. Both server and client store the secret, and this completes the initial setup.

During the daily use, whenever you need to sign in to the server, both server and KeePassium run the following steps:

• Count how much time has passed since 1 January 1970. However, instead of counting every second, we consider longer time intervals, such as 30 seconds. On other words, we calculate the number of half-minutes since the reference date (the count).
• The number of half-minutes is processed by a cryptographic algorithm controlled by the secret value.
• The result is shortened to 6–8 digits for easier typing.

INFO

The time interval, cryptographic algorithm and code length are all configurable parameters that are part of OTP configuration. The full standard is available in RFC6238.

Finally, when you enter the generated OTP in the sign-in form, the server compares it with the code it generated locally. If they match, the server has a strong proof that the client knows the secret — even though they did not exchange the secret during the verification.

OTP setup

There are two ways to configure an OTP in KeePassium: by scanning a QR code or by typing the secret manually.

Using a QR code

This is the easiest and quickest method:

• Open the entry editor
• Tap Set up one-time password (OTP) → Scan QR Code
• Point the camera to the QR code shown by the target website

The configuration will be saved into a custom field named otp, as an otpauth URI (the de facto standard for 2FA QR codes).

Sample QR code with OTP configuration

Using a secret key

Manual setup with the secret key is useful when you run KeePassium on computer and cannot scan QR codes.

• On the target website, select the option to enter the secret key manually
• Copy the secret key to clipboard
• In KeePassium, open the entry editor, tap Set up one-time password (OTP) → Enter manually
• Paste the secret key and tap Done

TIP

Spaces and capitalization don’t matter. Abc and a B C are the same code.

For Steam OTP

Valve’s Steam service has its own TOTP format. KeePassium can generate Steam TOTP codes, too.

Open the Steam entry in your database and create two custom fields:

• TOTP Settings with value 30;S (30 is the refresh interval, and S means that TOTP codes should have Steam-specific format)
• TOTP Seed with the secret key (in Base32 format)

Extracting the Steam secret key is not officially supported by Valve, but possible. The procedure is beyond the scope of this document.

Using OTPs

Once configured, OTP codes appear both in entry list and entry viewer.

OTP in entry list

In the entry list, OTP codes are normally hidden behind the buttons. Tap the button to reveal the OTP and copy it to clipboard.

Once the OTP is about to expire, it starts pulsating with color. You might want to wait for the next code to make sure it would be accepted by the server.

In the entry viewer, OTP codes are shown directly. The small line under the code shows the time left until the code updates. The field with OTP configuration data is hidden in entry viewer. To access that field, start editing the entry.

OTP in entry viewer

Compatibility

OTP codes configured by KeePassium are compatible with KeePassXC and most mobile apps. This works the other way round, too: codes configured in other apps will work in KeePassium as well.

A notable exception is KeePass, which needs the KeePassOTP plugin to understand OTPs configured by other apps.

Troubleshooting

OTP setup button is missing

Your database file uses an old format that does not support custom entry fields. As a solution, upgrade your database to KDBX format.

Generated OTP codes seem invalid

• Make sure the system time on your device is correct. Even a 30-second deviation can make generated codes invalid.
• Check the entered secret key for possible typos. Spaces and capitalization do not matter.