83 lines
2.5 KiB
Markdown
83 lines
2.5 KiB
Markdown
# TwoStepAuth REST Client
|
|
|
|
A secure, self-hosted web application for making REST API requests, protected by TOTP (Time-based One-Time Password) authentication and multi-layered encryption.
|
|
|
|
## Features
|
|
|
|
* **Two-Step Verification:** Mandatory TOTP (Google Authenticator, Authy, etc.).
|
|
* **Encrypted Storage:** User data is double-encrypted (AES-GCM) using both a Server Key and User-derived keys.
|
|
* **Automatic HTTPS:** Built-in Let's Encrypt (ACME) support.
|
|
* **Dynamic DNS:** Integrated `dy.fi` updater for home servers.
|
|
* **Security Logging:** `fail2ban`-ready logs to block brute-force attempts.
|
|
* **REST Client:** A clean UI to test GET/POST/PUT/DELETE requests with custom headers.
|
|
|
|
## Quick Start
|
|
|
|
### 1. Installation
|
|
```bash
|
|
go mod tidy
|
|
```
|
|
|
|
### 2. Configuration
|
|
The application uses environment variables for sensitive data. Create a `.env` file or export them:
|
|
|
|
```bash
|
|
export SERVER_KEY="your-32-byte-base64-key" # Generated on first run if missing
|
|
export DYFI_DOMAIN="example.dy.fi"
|
|
export DYFI_USER="your-email@example.com"
|
|
export DYFI_PASS="dyfi-password"
|
|
export ACME_EMAIL="admin@example.com"
|
|
export LOG_FILE="/var/log/twostepauth.log"
|
|
```
|
|
|
|
### 3. Add a User
|
|
Run the application in CLI mode to generate a new user and their TOTP QR code:
|
|
```bash
|
|
go run . --add-user=myusername
|
|
```
|
|
*Scan the QR code printed in the terminal with your authenticator app.*
|
|
|
|
### 4. Run the Server
|
|
|
|
**Production (Port 443 with Let's Encrypt):**
|
|
```bash
|
|
sudo go run . --port=443 --domain=example.dy.fi
|
|
```
|
|
|
|
**Development (Localhost with Self-Signed Certs):**
|
|
```bash
|
|
go run . --port=8080
|
|
```
|
|
|
|
## Fail2Ban Integration
|
|
|
|
The app logs `AUTH_FAILURE` events with the source IP. To enable automatic blocking:
|
|
|
|
**Filter (`/etc/fail2ban/filter.d/twostepauth.conf`):**
|
|
```ini
|
|
[Definition]
|
|
failregex = AUTH_FAILURE: .* from IP <HOST>
|
|
```
|
|
|
|
**Jail (`/etc/fail2ban/jail.d/twostepauth.local`):**
|
|
```ini
|
|
[twostepauth]
|
|
enabled = true
|
|
port = 80,443
|
|
filter = twostepauth
|
|
logpath = /var/log/twostepauth.log
|
|
maxretry = 5
|
|
```
|
|
|
|
## Security Architecture
|
|
|
|
1. **Server Key:** Encrypts the entire user database file.
|
|
2. **User Key:** Derived from the User ID and Server Key via PBKDF2; encrypts individual user TOTP secrets.
|
|
3. **Session Security:** Session IDs are encrypted with the Server Key before being stored in a `Secure`, `HttpOnly`, `SameSite=Strict` cookie.
|
|
4. **TLS:** Minimum version TLS 1.2 enforced.
|
|
|
|
## Requirements
|
|
|
|
* Go 1.21+
|
|
* Port 80/443 open (if using Let's Encrypt)
|
|
* Root privileges (if binding to ports < 1024 on Linux) |