Keepassxc: Provide Documentation for Critical Features

[pmetzger]

I've been trying to figure out how to use a number of features that the release notes say are there (say, acting as a TOTP app, and figuring out what the ssh-agent stuff does) but I've been unable to do so. The program is very nice, but it's difficult to use the features you guys are apparently working quite hard on without more documentation explaining how to use them. Even a paragraph on the Wiki describing each starred new features would be a help.

[phoerious]

We have a pretty extensive FAQ section. https://keepassxc.org/docs/#faq

[pmetzger]

Your FAQ has no sections on either of the topics listed above. I had already read it and all other documentation, including the entire Wiki, before filing my report.

If you can find any documentation whatsoever on your web site or in github for either topic please let me know the URL, but I've used google with the site: directive and have found none in either location.

If you want to close this I cannot stop you, but the problem is entirely real, and it is a bug, at least in so far as you've worked hard to create features for your users to use, but there is no information on how to use them.

[pmetzger]

BTW, so far as I can tell, the lack of documentation applies to essentially every starred feature in your release notes over the last many months. I read the release notes with interest, thought many of the features sounded interesting, and haven't found anything explaining the bulk of them. I checked the FAQ, the Quick Start guide, and the Wiki.

[droidmonkey]

Please list the precise documentation that you would find useful in a bulleted list on your first post. This feedback is critical to us spending the right time on the right problems. Most of the app is self explanatory, but I do agree the more advanced feature are still difficult for the first timers.

[affinityv]

The documentation is far from impressive or even useful. I find myself referring to keepass documentation for some things, even for something as simple as the list of valid like auto-type "keys" and "replacements".

[hifi]

@pmetzger For the record, FAQ section for SSH Agent was merged two days ago so you might have missed it. I tried to explain everything but if you find it doesn't explain the usage well enough, please ask specific questions so I can update the FAQ. Thanks!

[TheZ3ro]

We need to set-up a repo or a wiki for documentation so users can help us writing some

[phoerious]

There is a dedicated section about SSH agent https://keepassxc.org/docs/#faq-ssh-agent-how
and also some information about TOTP in the 2FA section.

[redm123]

I just tried KeePassXC for the first time today (have been using KeePassX up to now) and found the same lack of information. Of course I checked the FAQ before. Questions I asked myself in no particular order:

• what the heck is this auto-type thing? and then how does it work?
• what is this SSH Agent feature? how does it work? (yes this is somewhat answered in the FAQ, but not really clear). I understand it as: I can put my SSH private keys into KeePassXC and it will take care of unlocking them and adding them to the running SSH agent?
• How do I get my SSH keys into KeePassXC? I don't see a button or whatever anywhere ...
• when opening a database what is the "Key File" entry good for? how does it work? where do I get such a keyfile from?
• what are TOTPs for? (Try to avoid acronyms…) what exactly does this mean? 2FA like Google Authenticator I would guess? what am I supposed to enter when setting it up? what is “Key” and where do I get it from?

[hifi]

Auto-Type writes your usernames and passwords to other windows based on the window name using a global hotkey shortcut you configure. For example I login to Steam with it without needing to manually copy and paste the username and password.

SSH Agent feature does exactly what you figured. It can store and unlock your keys from within the database and feed them to a running agent. You need to first enable it in the settings to get the configuration options for entries. After enabling the feature, you can add keys as attachments to entries or use keys directly off your disk.

Key files are a composite to your passphrase that increase the security if your database when it is stored somewhere else than the database itself. You can use any file as a key.

TOTPs are exactly what you thought, they are the exact same thing Google Authenticator uses so time based one-time passwords. Many services require a second factor and TOTPs are usually the ones used with "soft" authenticators like Google Authenticator or any other application (like KeePassXC) that can provide the same functionality.

[pmetzger]

@hifi Great answers. But, it would be nice to have them in the documentation, along with enough information that naive people can set them up.

[TheZ3ro]

I was putting up a new section in the website for real documentation (not specific FAQ). I will continue when I'm free. Anyway this is a "duplicate" of #696

[redm123]

@hifi Thanks for your answers. Now found the SSH Agent stuff, well hidden ;) Setup is a bit flaky, but in the end I got it to work.
For TOTPs some hints how to get hold of the key would help. I'm sure I can somehow dig this out of the internet, but some hints in the documentation would make this easier.

Other than that I only agree with @pmetzger. And @TheZ3ro, I agree, "real" documentation is probably better suited to explain the general idea of features and how they work than the FAQ. Which should be left for questions and problems that still come up.

[tomhundt]

I had this problem trying to figure out what "Safely save database files" meant. Finally resorted to browsing the issues list and source code to find out. Thankfully, there are devs here who listen and support the software!

[pmetzger]

@droidmonkey You seem to have closed this issue in #3409, but that seems to have included no changes to documentation, and thus is not something that fixes this problem. Perhaps that was a mistake? I would ask that this be reopened.

[droidmonkey]

PDF documentation is part of 2.5.0 which documents critical features

[pmetzger]

That might be true, but if so, it's not as a result of PR #3409. Which commit added the documentation? I can then check if it covers the problems in this PR.

[droidmonkey]

That pr fixed opening it, it's there since PR #3274

[pmetzger]

That pr fixed opening it, it's there since PR #3274

I'm sorry, but I can't parse that? Can you rephrase it?

[droidmonkey]

The documentation in the app was added in #3274 and I fixed the act of opening that documentation in the accessibility pr.