esp32-s3

Einfacher Tasten-Protokollierer für Bildungszwecke - simple keylogger program for educational purposes

GERMAN:

Projektbeschreibung

Das Projekt ist ein einfacher Datenlogger, der USB-Tastatureingaben überwachen und auf einer SD-Karte speichern kann. Es verwendet den ESP32-S3 als Hauptcontroller und integriert HID-Tastaturfunktionalität, USB-Host-Fähigkeiten und SD-Karten-Speicherung. Es ist ausdrücklich nicht für illegale oder unethische Aktivitäten bestimmt. In Deutschland ist der unerlaubte (ohne Einverständnis erfolgende) Einsatz von Keyloggern an fremden Computern als Ausspähen von Daten gemäß § 202a des Strafgesetzbuches strafbar. Unternehmen, die Keylogger an den Firmencomputern einsetzen wollen, müssen zuvor die Zustimmung des Betriebsrats einholen. Zudem darf gemäß Ziffer 22 des Anhangs zur Bildschirmarbeitsverordnung „ohne Wissen der Benutzer […] keine Vorrichtung zur qualitativen oder quantitativen Kontrolle verwendet werden“.(https://de.wikipedia.org/wiki/Keylogger)

---

Hardware-Spezifikation

1. Microcontroller:

   • ESP32-S3 mit USB-OTG-Unterstützung.

2. Peripherie:

   • SD-Karte (SPI-Schnittstelle).
   • USB-Tastatur (als Eingabequelle über USB-Host).

3. Pinbelegung:

   • SD-Karten-CS: GPIO 5
   • SD-MOSI: GPIO 11
   • SD-SCK: GPIO 12
   • SD-MISO: GPIO 13

4. Verbindungen:

   • SPI-Interface für SD-Karte.
   • USB-Host für Tastatureingaben.

---

Software-Spezifikation

1. Programmiersprache:

   • C++ (Arduino Framework).

2. Bibliotheken:

   • Arduino.h: Haupt-Arduino-Bibliothek.
   • SD: Für SD-Kartenfunktionalität.
   • SPI: Kommunikation mit der SD-Karte.
   • Adafruit_TinyUSB: USB-HID Funktionalität.
   • usb/usb_host.h: USB-Host-Bibliothek für ESP32-S3.

3. Funktionalität:

   • HID-Tastatur: Verarbeitet Eingaben von der USB-Tastatur.
   • Datenlogging: Speichert Tastatureingaben dauerhaft in einer Datei (log.txt) auf der SD-Karte.
   • USB-Host: Verwaltet die Verbindung zur USB-Tastatur und verarbeitet Ereignisse.
   • Serielle Ausgabe: Zeigt Tastatureingaben und Fehler auf dem seriellen Monitor.

---

Setup-Prozesse

1. Initialisierung von USB-HID:

   • Aktiviert die HID-Funktion für die Kommunikation mit dem PC.

2. Initialisierung des USB-Hosts:

   • Installiert und registriert den USB-Host-Client.

3. Initialisierung der SD-Karte:

   • Überprüft die Verbindung und öffnet die Log-Datei.

4. Callback-Funktion:

   • keyboard_event speichert jede erkannte Tastatureingabe und sendet sie gleichzeitig als HID-Tastendruck an den PC.

---

Betriebsablauf

1. Tastendruck-Erkennung:

   • Erfasst Tastatureingaben über USB.
   • Schreibt die Eingaben in eine Datei auf der SD-Karte.

2. Fehlerbehandlung:

   • Überprüft die SD-Kartenverbindung.
   • Meldet USB-Host-Installations- oder Registrierungsprobleme.

3. Echtzeit-Datenverarbeitung:

   • Alle USB-Host-Ereignisse werden in der Hauptschleife verarbeitet.

---

Dateiausgabe

• Log-Datei: log.txt
  • Format: Alle Tastatureingaben werden fortlaufend gespeichert.

ENGLISH:

Project Description

This project is an simple data logger that monitors USB keyboard input and stores it on an SD card. It uses the ESP32-S3 as the main controller and integrates HID keyboard functionality, USB host capabilities, and SD card storage. It is explicitly not intended for any unauthorized or illegal activities. In Germany, the unauthorized use (without consent) of keyloggers on third-party computers is considered data espionage and is punishable under Section 202a of the Criminal Code. Companies that intend to deploy keyloggers on company computers must first obtain the approval of the works council. Furthermore, according to Item 22 of the appendix to the Screen Work Ordinance, "devices for qualitative or quantitative monitoring must not be used without the knowledge of the users." (https://de.wikipedia.org/wiki/Keylogger)

Hardware Specification

1. Microcontroller:

   • ESP32-S3 with USB-OTG support.

2. Peripherals:

   • SD card (SPI interface).
   • USB keyboard (as input source via USB host).

3. Pin Configuration:

   • SD card CS: GPIO 5
   • SD MOSI: GPIO 11
   • SD SCK: GPIO 12
   • SD MISO: GPIO 13

4. Connections:

   • SPI interface for SD card.
   • USB host for keyboard input.

---

Software Specification

1. Programming Language:

   • C++ (Arduino framework).

2. Libraries:

   • Arduino.h: Main Arduino library.
   • SD: For SD card functionality.
   • SPI: Communication with the SD card.
   • Adafruit_TinyUSB: USB HID functionality.
   • usb/usb_host.h: USB host library for ESP32-S3.

3. Features:

   • HID Keyboard: Processes input from the USB keyboard.
   • Data Logging: Saves keyboard inputs permanently in a file (log.txt) on the SD card.
   • USB Host: Manages the connection to the USB keyboard and processes events.
   • Serial Output: Displays keyboard inputs and errors on the serial monitor.

---

Setup Processes

1. HID USB Initialization:

   • Activates HID functionality for communication with the PC.

2. USB Host Initialization:

   • Installs and registers the USB host client.

3. SD Card Initialization:

   • Verifies the connection and opens the log file.

4. Callback Function:

   • keyboard_event logs each detected keyboard input and simultaneously sends it as a HID keypress to the PC.

---

Operational Flow

1. Keypress Detection:

   • Captures keyboard input via USB.
   • Writes the inputs to a file on the SD card.

2. Error Handling:

   • Checks the SD card connection.
   • Reports USB host installation or registration issues.

3. Real-Time Data Processing:

   • All USB host events are processed in the main loop.

---

File Output

• Log File: log.txt
  • Format: All keyboard inputs are continuously saved.