How-to guide

[vertigo220]

This is as much a help request as it is a feature request. Maybe it's just me, but coming from Authy, where you just scan a barcode (something I just learned isn't recommended) or manually enter the string provided by the service the 2FA is being set up for and then you're done, I'm having a tough time figuring out how to use this. In contrast to the very simple setup of Authy, Aegis requires much more info to be entered and choices to be made, and I have no idea what to put and choose. It would be ideal to have a guide, both in the app and here, on the different fields and what they mean and which options are generally preferred.

• Name: I assume this would just be whatever label you want to assign, e.g. Email
• Issuer: I assume this would be the site, e.g. Google, Firefox, etc, but it's unclear if it needs to be in any particular format or if it's even necessary. One site I found (https://github.com/google/google-authenticator/wiki/Key-Uri-Format) says it's "strongly recommended" but I don't really follow the logic. AFAICT, as long as the labels are unique enough, this isn't needed, but I could be way off.
• TOTP/HOTP/Steam: I know TOTP is the most common, and from what I can tell it's more secure, so I assume it's the recommended one to use unless HOTP is necessary for some reason. Steam is obvious, of course, though I suppose it's possible some users might not know what it is, so still wouldn't be a bad idea to give a quick explanation on it as well.
• SHA1/SHA256/SHA512: I know SHA1 is bad/broken for encryption purposes, and 512 is better than 256, but a) not everyone will know this, b) from what I can tell SHA1 should be fine for OTP, at least TOTP, and c) it's not clear if you can use any of them for any service, or how it would affect the keys provided vs expected.*
• Digits / Time: These ones are obvious, though, as with the hash, it's not clear if/how it would affect the keys.*
• Secret: I assume this is the long string provided by the service in place of a barcode.

*I don't have an in-depth understanding of how OTP codes are generated and work, obviously, and I always thought that each service has its own, specific way of doing it. So for example, I assumed that if you set up 2FA on Google/Facebook/whatever, the barcode or key would determine how it's calculated, so the generator and the website would always match. Based on that logic, if you change the hash, digit length, or timeout, they wouldn't match. I hesitated for a bit to set up a 2FA because of this, but having been a while since I've set one up, in doing so now I see it has you enter the code from the generator to complete setup, so I'm guessing it determines what various settings you used based on that?

[alexbakker]

When you scan a QR code, Aegis reads its contents and fills the OTP type, hashing algorithm, digits and secret fields for you automatically. You're not supposed to change them. Changing them would result in incorrect one-time passwords.

The "Issuer" field is set to the name of the service the OTP is for and the "Name" field is usually set to the username/email address used to log into that service. They're not required to be in any particular format.

I think most of the confusion can be eliminated by hiding the advanced fields by default for new entries, unless the user chose "Enter manually". What do you think?

[vertigo220]

I was actually using the manual entry option, which is why I was confused about the fields. Are you saying they show even when scanning a barcode? I've just become accustomed to manually entering the long string provided when setting up 2FA vs scanning barcodes because the scanner in Authy hasn't worked for me for a long time. But then the other day I read an article about how the barcodes contain a lot of superfluous info that could make it easier for someone to access the protected accounts if they were to gain access to the 2FA app, and therefore it recommended against using them and instead to do it manually. For example, scanning a barcode for email, it might actually include the email address, so if the 2FA app were compromised, an attacker would have not only the code, but the account it goes to. Based on what you said, this would be the "Name" field.

The problem I'm having is that with Authy, even doing manual entry all you need to do is enter the code provided and you're done. With Aegis, it presents you with all these other fields, which is not only confusing but I worry it presents the possibility to set it up improperly, which would cause the user to lock themselves out due to not being able to generate a code that the server expects. And it seems you're confirming that is possible, so hopefully I didn't lock myself out of the one I set up the other day (I chose one that if that did happen, it wouldn't be hugely disastrous, but it would still be inconvenient).