A wiki / documentation / tutorial for TOTP in KeePass2Android + some reports

[Phelo972]

Hello,

First of all thanks for this great work resulting in KeePass2Android!

I'm new on things like GitHub so sorry if there is a better way to submit what I'm requesting.

Anyway it would be very useful to write some doc / tutorial for TOTP and its application in KeePass2Android, as I've struggled a lot to find all the infos to use properly TOTP in KeePass2Android.

Here I put (meanwhile) a kind of draft documentation for those who, like me, didn't know anything about all of these before starting with KeePass + some reports for TOTP in KeePass2Android.

---

Changelog:
March 13th, 2021: Added reference to aaFn comment
May 13th, 2020: Added informations from Rookiestyle and reference to Rookiestyle comment
May 6th, 2020: Initial version

TOTP in brief

TOTP stands for Time-based One-Time Password algorithm which is one of the most common way proposed by websites to do a two-factor authentication (2FA).

On these websites, this option will often be mentioned in the 2FA configuration menu as things like "use code generated by an application", "use [Google] Authenticator app".

You're prompted to scan a QR code with the app, which essentially contains a code called "seed", usually with a form like "AZER TYUI OPQS DFGH JKLM", used to generate TOTPs. The seed can be also directly copied if there is no scanning option on the app.

Most common apps:

• Google Authenticator
• Authy
• Microsoft Authenticator
• FreeOTP
• LastPass Authenticator

TOTP in KeePass and benefits

In KeePass (by Dominik Reichl) there are currently 3 plugins wich enables this Authenticator app ability:

• KeePassOTP
• KeeOtp
• KeeTrayTOTP (note the name "TrayTOTP" on this one for later)

The greatest benefits are:

• the seed stays available contrary to the above apps (for which it's more or less hard to backup/restore/switch with another app)
• TOTPs are available wherever the KeePass database is available. But conceptually it's not really 2FA anymore (all things are stored in the same place).

For what I know (I use KeePassOTP), in the configuration which works with KeePass2Android (i.e. not in a separate database), the plugin generates 2 (now 1 in the last update) custom fields in a classic KeePass entry (if a TOTP is set).

• case of 2 fields: one for the seed, one for the technical settings of the TOTP generation (note this also for later)
• case of 1 field: Key Uri Format

These fields enable the plugin to generate TOTPs for the entry.

TOTP in KeePass2Android (+ the reports)

(I'm French so I translate from how it's displayed on the French version of the app)

1. To enable and use TOTP feature in KeePass2Android, three cases to make it work:
   1. (Not recommended) You want to start from KeePass2Android on your phone, not from KeePass by Dominik Reichl on PC. If so check this comment
   2. On KeePass you're using a KeePass plugin which generates 1 field in Key Uri Format* named "otp". If so, jump directly to step 3!
   3. On KeePass you're using a KeePass plugin which generates 2 fields as mentioned above. If so, you need to go to the "app settings" section of settings and then in "TrayTotp" section (like in the KeePass plugin).

* : Make sure that the URI doesn't contain spaces, otherwise KeePass2Android will fail to generate TOTPs as a space is an invalid character. If your URIs have spaces, check this comment.

[1st report: the original TrayTotp plugin doesn't even exist anymore, so naming the section like this is not very clear for newbies, maybe change the name of this section with something more relevant like "2 factor auth. - TOTP"]

2. The 2 parameters "TOTP seed field name" and "TOTP settings field name" have to be filled with the name of the custom fields created by the KeePass plugin.

[2nd report: Bad French translation of "field name", should be "Nom du champ" not "Nom de domaine" (it misled me), also "seed" shouldn't be translated (potentially put "Nom du champ du "seed code" TOTP")] EDIT: I did the job on Crowdin

3. A new custom field named "TOTP" containing the TOTPs will appear in KeePass entries which have a TOTP setup (only in KeePass2Android).
   This field will be also available in the special KeePass2Android one-line keyboard at the end.

[3rd report: Would be great if TOTP button could appear just after the password button !]

[4th report: in case of field in Key Uri Format, KeePass2Android fails to generate the TOTP if there are spaces in the seed inside the Uri, i.e.

otpauth://totp/ACME%20Co:john.doe@email.com?secret=HXDM VJECJJW SRB3HWI ZR4IFUG FTMXBOZ&issuer=ACME%20Co&algorithm=SHA1&digits=6&period=30

instead of

otpauth://totp/ACME%20Co:john.doe@email.com?secret=HXDMVJECJJWSRB3HWIZR4IFUGFTMXBOZ&issuer=ACME%20Co&algorithm=SHA1&digits=6&period=30]

[5th report: I use the KeePass2Android AutoFill plugin, and when I have a TOTP to submit, I have to reopen KeePass2Android to search for the entry and activate the one-line keyboard. So that ruins the AutoFill plugin time gain. Isn't it possible to trigger a "xxx entry is available" notification just after the Autofill plugin action in order to quickly access to the TOTP ?"]

[PhilippC]

Thanks a lot for this suggestion of documentation! Very helpful!
Regarding the bad translation: Please feel free to improve translation errors on https://crowdin.com/project/keepass2android

[Rookiestyle]

KeePass2Android will generate TOTP if the entry contains a field named otp.
This field is expected to contain an otpauth-string, otherwise TOTP generation fails.
My KeePassOTP plugin stores OTP data in this format and due to that no special configuration is required in KeePass2Android.

Some pages display the secret as groups of 4 characters separated by spaces for improved readability.
KeePassOTP accepts these spaces (similar to other plugins and apps like andOTP) and unfortunately also saves them which leads to issues within KeePass2Android as a space is an invalid character.
I'll continue to accept spaces but will remove them during save in the next version.

In the meantime, you can manually remove them.
Either by updating the otp-field in all of the relevant entries or by doing a mass update using XML replace
This XML replace worked in my tests. It is based on https://keepass.info/help/v2/xml_replace.html#repstr
If you go for XML replace please make a backup fiurst - better safe then sorry
Tools -> Database tools -> XML replace...
Select nodes: //Entry/String[Key='otp']/Value
Action: Replace data
Data: Inner text
Find what: <enter a space here>
Replace with: <leave this field empty>

[Phelo972]

Thanks a lot for these clarifications @Rookiestyle !
I edit my post reflecting those.

[bdeeming]

Thank you very much for this, I found this doc very useful - it allowed me to solve my problem (otp value was not in uri format, - for I don't know what reason since it was just one of my entries wasn't, had me stumped for ages until I found this!)

[aaFn]

Hello there, simple question = how to install the KeePass OTC plugin in keepass2android ?

• The https://github.com/rookiestyle/keepassotp only gives a .plgx file, not saying what to do with it for keepass2android
• KeePass OTP doesn't seem available on the Google Play Store

so for now I can't make it work in my keepass2android.

Thank you in advance for any hint / help.

[Rookiestyle]

KeePassOTP is a plugin for KeePass, not a plugin for KeePass2Android.

If you use it within KeePass and decided to go for the OTP storage within the respective entry approach as described in KeePassOTP's wiki, KeePass2Android will generate otp codes as well and no further action is required.

[aaFn]

Hello @Rookiestyle , thanks, this is clear then.

So to set up (T)OTP for a given entry card in a DB managed by keepass2android, we have to:

• do it on KeePass first, and then replicate the DB to our Android device
• or use the complicated method of adding parameters / string chain fields manually, folowing this doc https://github.com/Rookiestyle/KeePassOTP/wiki/KeePassOTP-fields, inside keepass2android, in the entry card

@Phelo972 , you might want to add that in your description at the top ?

Thank you to both, aaFn.

[Rookiestyle]

You can also edit the entry in KeePass2Android and do "Configure TOTP"

[sydbarrett74]

Sorry if I missed it in the thread above, but will this all work if I maintain a separate database within KeePassOTP? (My goal is to maintain 2FA.)

[Rookiestyle]

Sorry if I missed it in the thread above, but will this all work if I maintain a separate database within KeePassOTP? (My goal is to maintain 2FA.)

No, this won't work.

[gpion]

Does someone knopw if there any plan to have OTP management which is built-in in native Keepass for Windows (so dont require any plugin) supported in keepass2android?

[scruel]

What about OTP storage in a separate database?

[jenssey11]

Thanks a lot for this suggestion of documentation! Very helpful! Regarding the bad translation: Please feel free to improve translation errors on https://crowdin.com/project/keepass2android

Hey @PhilippC can you please get ahold of me (jenssey@gmail.com) - my spouse uses one of your apps and he recently passed away.

[PhilippC]

I have added https://github.com/PhilippC/keepass2android/blob/master/docs/Generating-TOTPs.md based on the documentation created here. I added some more details and updated some parts. For the feature requests mentioned above, there are already open tickets, so I am closing this issue.