Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/allanoricil/esp32-mfa-authenticator
ESP32 MFA Authenticator
https://github.com/allanoricil/esp32-mfa-authenticator
2fa authenticator esp32 mfa totp
Last synced: about 1 month ago
JSON representation
ESP32 MFA Authenticator
- Host: GitHub
- URL: https://github.com/allanoricil/esp32-mfa-authenticator
- Owner: AllanOricil
- License: mit
- Created: 2024-02-22T17:28:04.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2024-12-30T19:28:48.000Z (about 1 month ago)
- Last Synced: 2024-12-30T20:21:32.989Z (about 1 month ago)
- Topics: 2fa, authenticator, esp32, mfa, totp
- Language: C
- Homepage: https://allanoricil.github.io/esp32-mfa-authenticator/
- Size: 2.51 MB
- Stars: 64
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
 [](code_of_conduct.md) [](https://github.com/AllanOricil/esp32-mfa-totp-generator/actions/workflows/ci.yaml)
# ESP32 MFA Authenticator
This is a personal project that I created to help me to get MFA TOTPs without using my phone.
Other motives:
- it is not safe to store both the password and the MFA secret in the same place, like in a password manager. It creates a single point of failure.
- it is not safe to store secrets on a device that you use when going out.
- it is not safe to store MFA secrets for my personal and professional life in the same place.
- if my phone is stolen or lost, I would have to re-register MFA for all services.
- secrets are decoupled from the device, and this allows me to easily switch to another one when necessary. I just need to insert the SD card containing my services onto another device flashed with the same code.
- not all services that I use support fido keys or passkeys.
- yubikey is expensive where I live, and I would need a lot.
- I wanted to learn how MFA works.
- I wanted to learn how ESP32 works.
## 🌐 Install
You can flash your ESP32-CYD board with the latest build using this [site](https://allanoricil.github.io/esp32-mfa-authenticator).
> [!IMPORTANT]
> Read the site and the github workflows source codes to verify that the build artifact is, in fact, the one from the latest release published in this repository.
> [!NOTE]
> This site was based on https://esphome.github.io/esp-web-tools/
## 🎬 Demos
## ⚙️ Parts
- `ESP32-2432S028`
- 3D printed black case
- Acrillic case
> [!TIP]
> You can buy this board from Aliexpress clicking on any of these affiliate links: [USD](https://s.click.aliexpress.com/e/_mNCBRAA) [BRL](https://s.click.aliexpress.com/e/_mOtZaxM)
> [!TIP]
> You can buy this acrillic case from Aliexpress clicking on any of these affiliate links: [USD](https://s.click.aliexpress.com/e/_mLYVthc) [BRL](https://s.click.aliexpress.com/e/_m0Tt9wq)
> [!TIP]
> The 3D model for the black case was taking from this [link](https://makerworld.com/en/models/137424#profileId-149549)
## 💵 Total Project Cost
| Part | Cost |
| --------------------- | -------- |
| ESP32-2432S028 | 9.25 USD |
| 3D printed black case | 12.7 USD |
| Acrillic case | 2.5 USD |
> [!NOTE]
> The above list doesn't consider expenses with taxes and shipping.
> [!NOTE]
> Prices were taking in February 2024.
## 💻 Dev Environment Requirements
| dependency | version |
| -------------------------------- | --------- |
| python | >= v3.9 |
| node | >= v18.18 |
| npm | >= v10.2 |
| vscode | >= v1.87 |
| platform.io ide vscode extension | >= v3.3 |
| docker | >= v25.0 |
> [!IMPORTANT]
> Don't forget to install a [driver to allow your OS to recognize esp32](https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers)
> [!IMPORTANT]
> Node and npm, its package manager, are required because several development tools are used in this project. Among these tools are those that enforce the "conventional commits" standard. This standard is a lightweight convention on top of commit messages, offering an easy set of rules for creating an explicit commit history.
> [!TIP]
> If platform.io extension does not recognize your board after clicking on `Upload`, `Upload and Monitor` or `Monitor` buttons, it means the driver was not properly setup. In MacOS, after installing the driver from Sillicon Labs, I had to restart the system before mac could identify the board.
## 🔌 Boot and Reset Requirements
- 2.4Ghz WiFi signal with internet connection, in order to sync the board's clock with the [NTP server](https://ntp.org/).
- SD card with `config.yml` and `services.yml` files in the root, as shown below:
### ⚙️ config.yml
```yml
# [REQUIRED] configure the credentials used to connect to a wifi network
wifi:
# [REQUIRED] (text) wifi connection password
password: test
# [REQUIRED] (text) wifi id
ssid: test
# [REQUIRED] configure authentication for the board
authentication:
# [OPTIONAL] (number) [default 3] board is locked and requires a hard reset, after N wrong unlock attempts
unlock_attempts: 3
pin:
# [OPTIONAL] (text) pin code composed of numbers only and HMAC-SHA256 hashed
hash: 7dbd45736c57090dd62a7e1c8db1a08c353b4a836f2c6b43fd1dd3f1e747ea59
# [OPTIONAL] (text) key used to hash pin code
key: TUwNzIxF5lJncAJVMkmb4EiSP9vm0OyF
# [OPTIONAL] configure display settings
display:
# [OPTIONAL] (number) [default 10] if provided, the display will turn off after n seconds have passed
sleep_timeout: 10
# [OPTIONAL] configure touch settings
touch:
# [OPTIONAL] (bool=false|0) calibrate touch sensor if true or 1
calibrate: 0
# [OPTIONAL] configure the management app
manager:
# [OPTIONAL] configure authentication for the management app. The management app is enabled only if username, password, key are set.
authentication:
# [REQUIRED] (text) username to start a session
username: admin
# [REQUIRED] (text) HMAC-SHA256 hashed password to start a session
password: 7dbd45736c57090dd62a7e1c8db1a08c353b4a836f2c6b43fd1dd3f1e747ea59
# [REQUIRED] (text) 32 characters key used to hash the password
key: TUwNzIxF5lJncAJVMkmb4EiSP9vm0OyF
# [OPTIONAL] (number) [default 5] amount of minutes for the session duration
session_length: 5
```
> [!IMPORTANT]
> Upon the initial boot, it is imperative to undergo the calibration process at least once, as outlined in the `How to build` section below.
> [!TIP]
> Once the boot process is finished, remove the SD card from the board, and store it somewhere safe. Before rebooting, or if you want to add new secrets, remember to put it back in the board.
> [!NOTE]
> A pink screen appears to indicate that both `config.yml` and `services.yml` have been parsed and loaded into memory.
### 🔒 services.yml
```yml
# [REQUIRED] (list) stores a list of services
services:
# [REQUIRED] (text) unique name for a service in a group. It must not exceed 60 characters.
- name: abc
# [REQUIRED] (text) Base32 encoded secret for the service.
secret: abc
# [OPTIONAL] (number) [default 0] it must be an integer between 0 and 255. It is used to group services and determine their priority. Services with smaller group numbers are rendered first. For instance, services assigned to group 100 will be rendered before those in group 255. In a services file, you can have up to 100 services.
group: 0
```
## 📖 Guides
### 📚 How to navigate and control the board
- Change groups: Swipe left or right to navigate between different groups.
- Lock: Tap twice on the screen to lock the board.
- Wake up: Tap once to wake up the board.
### 📚 How to build using PlatformIO CLI
Install PlatformIO's official CLI using this [tutorial](https://platformio.org/install/cli), and then follow the next steps:
1. Run `platformio device list` and annotate the device port of your board.
> [!TIP]
> You can discover which port belongs to your board by comparing the outputs of this command when your board is connected and when it is not.
2. Run `./scripts/dev.sh --port ${DEVICE_PORT} --env ${ENV}` to build and flash the code into your board
> [!IMPORTANT]
> Remember to substitue `${DEVICE_PORT}` with the value you got in step 1.
> [!IMPORTANT]
> Remember to substitute `${ENV}` by `prod` or `dev`. The only difference between both environments is the log level. In `prod` logs are disabled, while in `dev` all logs are visible.
### 📚 How to listen to the serial port using PlatformIO CLI
To listen to the serial port using PlatformIO CLI you can use the following commnad:
```bash
platformio device monitor
```
### 📚 How to register a Service
Services are registered in a file called `services.yml` that must be located in the root of an SD card. For example:
```yml
services:
- name: aws:root:[email protected]
secret: encoded-secret
group: 0
- name: aws:staging:[email protected]
secret: encoded-secret
group: 0
- name: aws:production:[email protected]
secret: encoded-secret
group: 0
- name: aws:1234565:[email protected]
secret: encoded-secret
group: 1
- name: aws:6785910:[email protected]
secret: encoded-secret
group: 1
- name: aws:7815795:[email protected]
secret: encoded-secret
group: 1
- name: github
secret: encoded-secret
group: 2
- name: docker
secret: encoded-secret
group: 2
- name: npm
secret: encoded-secret
group: 2
```
> [!IMPORTANT]
> At present, you can register up to 100 services divided across 10 groups.
> [!IMPORTANT]
> The service name must not exceed 60 characters.
> [!IMPORTANT]
> The service group must be between 0 and 255. If you don't set a value, it will default to 0.
> [!IMPORTANT]
> Secrets must be stored unencrypted and encoded using Base32. All MFA services I tried already provide secrets in Base32 encoding. If you find one that does not, ensure the secret is Base32 encoded before adding it to the file.
> [!IMPORTANT]
> The service name acts as a unique key within a group. If two services share the same key within the same group, the last one listed in the file will be the one used because it was the last service to be added in the db.
### 📚 How to verify if TOTP codes are correct
1. Go to
2. Paste/type your encoded base 32 secret in the secret field, and then compare the TOTP code shown with the one you are seeing on the ESP32's screen.
### 📚 How to recalibrate the touch sensor
1. Open your `config.yml` file.
2. Add the following property at the root level:
```yml
touch:
calibrate: true
```
3. Insert the SD card with the updated `config.yml` into your board.
4. Press the `RST` button on the board to reboot it.
5. Wait for the calibration screen to appear, as shown below:
6. Follow the on-screen instructions to complete the calibration process.
7. Once the calibration is finished, update `config.yml` again:
```yml
touch:
calibrate: false
```
8. Save the file, insert the SD card back into the board, and reboot by pressing the `RST` button.
9. Confirm that the calibration screen no longer appears.
10. Your touchscreen is now calibrated and ready to use! 🎉
> [!NOTE]
> The calibration state will initiate upon the initial boot of the board, regardless of the content stored in `config.yml`, if no calibration is found in [SPIFFS](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/storage/spiffs.html).
> [!IMPORTANT]
> The pin screen won't work if you did not calibrate the touch sensor.
### 📚 How to update `config.yml` from a browser
When the board is connected to your local network, a settings page, similarly to the one found in routers, can be used to update the `config.yml` in the SD card without the need of inserting it on a different computer. You can access this settings page at `http://${LOCAL_NETWORK_DEVICE_IP}/esp32/settings`.
> [!IMPORTANT]
> At the moment, all secrets in this form must be set before submiting it. If you fail to do it, all secrets in your `config.yml` will be overwritten by `*****`.
> [!IMPORTANT]
> For security purposes, none of the secrets are exposed by the board's webserver. If you inspect the page using your browser dev tools, you will noticed that all secrets are fetched as `*****`. In the future, after implementing HTTPS, you will be to manage those secrets from the browser, but only after providing a PIN number of using your fingerprint.
### 📚 How to setup PIN number
#### Option 1
1. Use this [website](https://acte.ltd/utils/randomkeygen) to create a strong secret that is exactly 32 characters long. Copy the value from `Encryption key 256`, which has exactly 32 characters
2. Open this [website](https://www.devglan.com/online-tools/hmac-sha256-online) to hash your pin number. Add you pin number as plain text, in the first input. You must use numbers only because the UI doesn't support letters or symbols, and it must contain at least 6 digits and no more than 20 digits.
3. Copy the generated hash. It must be 64 characters long.
4. In your config.yml
- set `hash` with the generated hash you got in step 3
- set `key` with the secret you got in step 1
```yml
authentication:
pin:
hash: 7dbd45736c57090dd62a7e1c8db1a08c353b4a836f2c6b43fd1dd3f1e747ea59
key: TUwNzIxF5lJncAJVMkmb4EiSP9vm0OyF
unlock_attempts: 3
```
#### Option 2
1. Use this [website](https://acte.ltd/utils/randomkeygen) to create a strong secret that is exactly 32 characters long. Copy the value from `Encryption key 256`, which has exactly 32 characters
2. Open a terminal and run the following comand to hash your pin number. Don't forget to substitute `"YOUR_PIN_NUMBER"` and `"YOUR_32_CHARACTERS_LONG_SECRET"`. The PIN must consist only of digits and must be between 6 and 20 digits in length.
```bash
echo -n "YOUR_PIN_NUMBER" | openssl dgst -sha256 -hmac "YOUR_32_CHARACTERS_LONG_SECRET" | awk '{print $2}'
```
3. Copy the generated hash. It must be 64 characters long.
4. In your config.yml
- set `hash` with the generated hash you got in step 3
- set `key` with the secret you got in step 1
```yml
authentication:
pin:
hash: 7dbd45736c57090dd62a7e1c8db1a08c353b4a836f2c6b43fd1dd3f1e747ea59
key: TUwNzIxF5lJncAJVMkmb4EiSP9vm0OyF
unlock_attempts: 3
```
### 📚 How to setup the Password for the Management App
The steps to generate the password for the management app are the same as those used to set up the PIN. Once the password is created, add the following properties to your `config.yml`:
```yml
manager:
authentication:
username: admin
password: 7dbd45736c57090dd62a7e1c8db1a08c353b4a836f2c6b43fd1dd3f1e747ea59
key: TUwNzIxF5lJncAJVMkmb4EiSP9vm0OyF
```
## 🎯 Roadmap
### ✅ Display multiple TOTP codes
People often use multiple services that require MFA TOTP codes with high frequency because of their short living sessions.
### ✅ Unlock with PIN Code
It is not secure to have unencrypted secrets stored without protection
### ✅ Manage board settings using a browser
Users can manage their board settings using a browser. Once the board is connected to the local network, open a browser and type `{IP_ADDRESS}/esp32/settings`.
> [!IMPORTANT]
> At the moment, secrets must be re-entered before submiting the form. If you don't re-type the secrets, they will be stored as `*******` in the SD card, and this will break the boot.
### ✅ Display turns off automatically after N seconds without user interaction
After booting, the display turns off automatically if it doesn't receive touch events after N seconds. N is a configurable in the `config.yml`.
### ✅ Organize Services into Groups
Services can be organized into groups.
### ✅ Lock board after N wrong unlock attempts
Improve the validation function to block access to the board after few wrong attempts happened. With this enhancement, brute forcing all possible combinations won't be possible.
### 🔜 Unlock with fingerprint
Instead of typing a pin code, it will be possible to unlock the board using a fingerprint. The goal is to ease the access to the TOTP codes, while maintaining them secure. It will also work globally or by group.
## 💖 Become a Sponsor
If this device has made your life easier, consider supporting its development by clicking the button below.
