schauausgmbh
83ae6aceca
Initial version of the README.md. Any more details may be added at a later point. Signed-off-by: SCHAUAUS GmbH <2+schauausgmbh@noreply.aaskablackwolf.servehttp.com>
149 lines
7.2 KiB
Markdown
149 lines
7.2 KiB
Markdown
# AES256 Seed Phrase_Encryptor
|
|
|
|
This is a Firmware for ESP32-based boards to encrypt / decrypt seed phrases and other information using AES algorithm with 256bit custom keys.
|
|
|
|
## Warnings
|
|
|
|
- Use only with devices not connected to any network!
|
|
- Do not use terminal application that save history!
|
|
- Use it in safe environments only! (avoid surveillance / oberservation by third parties)!
|
|
- Ensure you keep your keys safe!
|
|
- Always verify the decryption is working with your key!
|
|
- Use it on your own risk!
|
|
- Ensure a proper backup strategy!
|
|
- Keys are never stored on the device! They only live in the RAM and will be lost after reboot or reconnection of the board!
|
|
- Always set a proper encryption key! Never use the encryption operation on the device without a custom key! Otherwise the encryption is useless!
|
|
|
|
## Prerequisites
|
|
|
|
This firmware is making use of:
|
|
- [ESP32 board definition](https://github.com/espressif/arduino-esp32) => install "esp32" by Espressif Systems in the boards manager inside the Arduino IDE
|
|
- [Arduino Cryptography Library](https://rweather.github.io/arduinolibs/crypto.html) => install the library "Crypto" by Rhys Weatherley inside the Arduino IDE
|
|
|
|
## License
|
|
|
|
This firmware is open source licensed under the [EUROPEAN UNION PUBLIC LICENCE (EUPL) v. 1.2](LICENSE).
|
|
You can do with and modify it however you want.
|
|
You cannot hold us liable for any loss or damage caused by the use of this firmware. You will use it on your own risk.
|
|
|
|
## Installation
|
|
|
|
- Download this repository to your computer
|
|
- Install the needed board definitions and libraries
|
|
- select the board that you'd like to use from the tools menu
|
|
- selct the serial port your board is connected to in the tools menu
|
|
- hit the upload button
|
|
- wait for the compilation and upload to complete
|
|
|
|
## Usage
|
|
|
|
### Connection
|
|
|
|
- connect the board to a USB serial console application using the proper baud rate (default: 115200 )
|
|
- send the command `help` via the terminal to your ESP32 board to show all available commands and a brief description to each of them
|
|
- set proper encryption key (see next section)
|
|
|
|
### Set a key for encryption and decryption
|
|
|
|
The first step before any encryption / decryption operation is to set a proper key.
|
|
This can be easily done by two methods:
|
|
1. send the command `key` to the board => a new random key will be generated by the ESP32 and printed on the serial console as 32byte hexadecimal string; ensure you note that key somewhere safe or you will not be able to decrypt your data after a reboot of yoru device!
|
|
2. send the command `key <your 32bit key>` to the board where `<your 32bit key>` needs to be either a plain text string with 32 characters or its 32byte hexadecimal representation
|
|
|
|
### encrypt a seed phrase or data block
|
|
- set a proper key first (see above; only needs to be done once a session)
|
|
- send the command `encrypt <your seed phrase or data block>` to the board where `<your seed phrase or data block>` can be viratually any text or data that can be represented in hexadecimal characters
|
|
- the device will encrypt your data with the set key using the AES symmetric algorithm
|
|
- the encrypted hexadecimal representation will be printed on the serial console => copy it and store it in a trusted place separated from your key
|
|
|
|
### encrypt a seed phrase or data block
|
|
- set a proper key first (see above; only needs to be done once a session)
|
|
- send the command `decrypt <your encrypted data block>` to the board where `<your encrypted data block>` is the hexadecimal representation of your encrypted data
|
|
- the device will decrypt your data with the set key using the AES symmetric algorithm
|
|
- the decrypted data will be print to the serial console in plain text
|
|
|
|
### clear key from memory
|
|
- send the command `clear` to the board
|
|
- the cryptographic key will be removed from the boards RAM
|
|
|
|
### reboot the board
|
|
- send the command `restart` to the board
|
|
- the board will reboot; any key will be removed from RAM
|
|
|
|
### sample log of serial console (never do this in production!) including a safety-check that the decoding is working properly
|
|
|
|
> ```
|
|
> ets Jun 8 2016 00:22:57
|
|
>
|
|
> rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
|
|
> configsip: 0, SPIWP:0xee
|
|
> clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
|
|
> mode:DIO, clock div:1
|
|
> load:0x3fff0030,len:4876
|
|
> ho 0 tail 12 room 4
|
|
> load:0x40078000,len:16532
|
|
> load:0x40080400,len:3500
|
|
> entry 0x400805b4
|
|
>
|
|
> ┌-----------------------------------------------------┐
|
|
> | Encrypt / Decrypt seed phrase with AES256 algorithm |
|
|
> └-----------------------------------------------------┘
|
|
>
|
|
> WARNING: DO NOT USE THIS ON ANY NETWORK CONNECTED DEVICE AND ENSURE THE DECRYPTION IS WORKING PROPERLY!
|
|
> USE IN SECURE ENVIRONMENTS ONLY!
|
|
> This program is offered as it is and no warranties will be granted in any case!
|
|
> Review the source code thoroughly before using it for real application!
|
|
> Available commands:
|
|
> help - print this help to serial console
|
|
> key - generate random HEX key and print it to the serial console
|
|
> key <your 32byte key> - set key (hexadecimal or ascii) for encryption / decryption
|
|
> encrypt <12 or 24 word seed phrase> - encrypts your 12 ord 24 word plain text seed phrase to HEX string
|
|
> decrypt <encrypted HEX string> - decrypts your encrypted HEX string back to clear text seed phrase
|
|
> clear - clear all cryptographic information from memory
|
|
> restart - reboot the device for a fresh restart; any working data will be removed from memory
|
|
>
|
|
> Waiting for command (send "help" for available commands)
|
|
> ```
|
|
|
|
```
|
|
key
|
|
```
|
|
|
|
> ```
|
|
> Operation: setting encryption key
|
|
> No valid key handed over; generating new key:
|
|
> C7 8F D2 F5 90 A6 86 9C 15 0D EC 2D 1E CB 2D 66 02 46 FB 6D EA C3 27 D9 F1 BD A8 E2 79 06 F5 5C
|
|
> Key set for encryption / decryption
|
|
>
|
|
> Waiting for command (send "help" for available commands)
|
|
> ```
|
|
|
|
```
|
|
encrypt this is my unsafe seed phrase consiting of twelf not secret words
|
|
```
|
|
|
|
> ```
|
|
> Operation: encrypting data
|
|
> encrypted data block:
|
|
> 49 04 36 FE DD 5D ED 78 D4 7F EF 1B 82 6F 6C 2A 83 4E 38 8F BB D0 34 F1 59 2F 80 4A FA 46 9B 1B FB 84 B7 28 D3 2A 0C CC C0 7D 73 AF 31 EF CF 34 69 75 22 8F FB 06 48 59 A7 10 43 44 ED 0E F9 71 FA EF B4 EB 24 99 51 44 B2 53 E6 5E 58 EB 07 D1
|
|
>
|
|
> Waiting for command (send "help" for available commands)
|
|
> ```
|
|
|
|
```
|
|
decrypt 49 04 36 FE DD 5D ED 78 D4 7F EF 1B 82 6F 6C 2A 83 4E 38 8F BB D0 34 F1 59 2F 80 4A FA 46 9B 1B FB 84 B7 28 D3 2A 0C CC C0 7D 73 AF 31 EF CF 34 69 75 22 8F FB 06 48 59 A7 10 43 44 ED 0E F9 71 FA EF B4 EB 24 99 51 44 B2 53 E6 5E 58 EB 07 D1
|
|
```
|
|
|
|
> ```
|
|
> Operation: decrypting data
|
|
> decrypted data block:
|
|
> this is my unsafe seed phrase consiting of twelf not secret words
|
|
>
|
|
> Waiting for command (send "help" for available commands)
|
|
> ```
|
|
|
|
## notes on issues and security
|
|
|
|
- Send any findings in the cryptographic library to [the original author of the library](https://github.com/rweather/arduinolibs)
|
|
- any issues on the firmware implementaion: contact us on the [fediverse @schauausgmbh@social.schauaus.at](https://social.schauaus.at/@schauausgmbh) or Matrix @schauausgmbh:matrix.schauaus.at
|
|
- any security issues on the firmware: contact us on Matrix @schauausgmbh:matrix.schauaus.at |