---

File	Date	Author	Commit
doc	2019-09-29	Vinicius de Alencar	[972677] Initial commit
image	2019-09-29	Vinicius de Alencar	[972677] Initial commit
library	2019-09-29	Vinicius de Alencar	[972677] Initial commit
2FA-Auth.sh	2019-09-29	Vinicius de Alencar	[972677] Initial commit
LICENSE	2019-09-29	Vinicius de Alencar	[972677] Initial commit
README	2019-09-29	Vinicius de Alencar	[972677] Initial commit
README.md	2019-09-29	Vinicius de Alencar	[972677] Initial commit

Read Me

=============================================
2FA-Auth - script to generate 2FA access code
=============================================

1. Requirements
2. GnuPG keys
3. Using 2FA-Auth
4. 2FA tokens and codes
5. Exported tokens


---------------
1. Requirements
---------------

What do you need to run 2FA-Auth?

-- Operating System: any GNU/Linux distribution with BASH
-- Essential softwares: GIT, GnuPG and OATHTOOL

2FA-Auth can automatically install GnuPG and OATHTOOL, but if it fails, please,
check how to install these packages according to your distroibution.

This automatic method of package installation involves these package managers:

- APT and APT-GET for Debian-based systems
- DNF, URPMI and YUM for RedHat-based systems
- EMERGE and EQUO for Gentoo-based systems
- PACMAN for Arch-based systems
- ZYPPER for SUSE/openSUSE-based systems

-------------
2. GnuPG keys
-------------

It's really essential to create/import your GnuPG keys in your profile, because
they're going to be used to encrypt/decrypt 2FA tokens. The email used to create
your GnuPG key is your UserID and part of the fingerprint (the last 16 digits or
the last 4 blocks of digits) is your KeyID. If you have no idea on how to use
GnuPG, it's recommended to read these Reddit articles bellow.

[Tutorial for beginners] How to install and use GnuPG on GNU/Linux
https://www.redd.it/creb29/

[Tutorial for beginners] GnuPG: how to export, import, delete and revoke your keys
https://www.redd.it/ct7yjr/

If you need more information about GnuPG, use forums and other sites.


-----------------
3. Using 2FA-AUTH
-----------------

It's really easy to use this project. Open a terminal and type:

$ cd /path/to/2FA-Auth/
$ ./2FA-Auth.sh

Optionally, you can type "./2FA-Auth.sh help" and get a simple help menu.

Running 2FA-Auth for the first time, it's going to look for GnuPG and OATHTOOL,
and it's going to ask you about your GPG IDs (KeyID & UserID) in order to encrypt
decrypt your token(s).

Remember: GnuPG UserID is your e-mail, while GnuPG KeyID is part of your fingerprint.

What you can do with 2FA-Auth?
- Include, exclude, list and export all available services tokens set in your profile;
- Generate "Two-Factor Authentication" login codes (using main menu or with parameters);
- Create and restore a backup with your settings.

Read the PDF file "2FA-Auth/doc/How_to_use_2FA-Auth.pdf" to get more information
on how to use 2FA-Auth.

-----------------------
4. 2FA tokens and codes
-----------------------

Using 2FA code generator programs, like Google Authenticator(R), it's possible
to generate "Two-Factor Authenticator (2FA)" codes that changes every minute, and
these 2FA codes are used with your username and password, in order to provide a
safe login to a site or service which uses Two-Factor Authenticatior.

But, instead of use your cellphone or tablet with 2FA code generator, you can
use your terminal and run "2FA-Auth".

To use 2FA codes generated by 2FA-Auth, follow these steps:
- Access the site/service that uses 2FA, for example, GitHub(R);
- Log in using your username and password, go to Settings/Security and enable the
  "Two-Factor Authentication" option;
- A QR-Code is going to appear in your screen. There's no way to scan this QR-Code
  using 2FA-Auth, so an alpha-numeric code (token) is needed. Depending on the
  site/service, there's a link or button you can click (close to QR-Code) to get
  this token, while other sites, this token appears side-by-side with the QR-Code.
  Just copy (Ctrl-C) this token;
- Run 2FA-Auth and (in the main menu) choose the option "Add a new 2FA token",
  type the site/service name, press <ENTER> and paste (Ctrl-Shift-V) the site's
  token and press <ENTER> again;
- Go back to 2FA-Auth main menu, select the option "Generate 2FA codes in order..."
  and wait a moment because 2FA-Auth is going to generate a 6-digits code for this
  new service you added in 2FA-Auth. Once a 2FA code is generated, copy it, go to
  the site and paste this new generated code into a box/field that says something
  similar to "Input generated code";
  Finally, in the website, click the button "Ok" or "Generate".

From now on, every single time that you log to this site/service, your login will
include 3 fields: username, password and two-factor authenticator. Use 2FA-Auth
to generate the code (use the menu "Generate 2FA codes in order to login...").


------------------
5. Exported tokens
------------------

2FA-Auth has an option which is used to export your token, but why? Because you
can use this token in other 2FA programs/scripts. It's useful when you want to
use diferent programs to generate 2FA codes and log in the same site or service.