wireguard_peer_manager/kiss/toml-manager/README.md
2024-10-23 22:11:01 +03:00

148 lines
4.0 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Encrypted Config file API Service
This project implements a secure, encrypted API service using CherryPy and
Python. The API allows clients to securely interact with config files. It
supports reading, writing and modifying content. Complete files or sections /
topics from the files. The service supports creating backup copies before every
modifying action. The service employs JWE (JSON Web Encryption) tokens for
authentication, along with ECC (Elliptic Curve Cryptography) for key exchange
and AES for encrypting request and response bodies.
I strongly recomend running this behind reverse proxy (like nginx) that
provides TLS communication between the server and client.
## Features
* JWE Token Authentication:
The service uses encrypted JWE tokens for authentication and key exchange.
* ECC for Key Exchange:
The client encrypts a symmetric key using the servers ECC public key,
which is used for AES encryption/decryption.
* AES Encryption:
Both request and response bodies are encrypted using AES with a single use
symmetric key, ensuring data confidentiality.
* Config File Handling:
Supports reading, writing, and updating config files. Initially designed
for WireGuard configs but easily extendable to any config format.
* POST-Only API:
The API only accepts POST requests for all interactions.
* Single API Endpoint:
The entire service operates through a single endpoint, keeping the API
interface minimal and clean.
## Requirements
Python 3.11+
CherryPy
cryptography
requests
Some controllers (file handlers) may have other dependencies.
## Config
config.toml
The config.toml file is used to configure the server, logging, and the paths to
the config files. Heres a sample configuration:
[server]
host = "0.0.0.0"
port = 8000
base_url = '/'
[logging]
log_file = "service.log"
debug = true
[files]
wireguard_wg0 = ["/etc/wireguard/wg0.conf", backup=true]
[client_keys]
public_key = """
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA.....
-----END PUBLIC KEY-----
"""
- server: Defines the host, port and the url where the service will run.
- logging: Configures the log file location and debug mode.
- files: Key/[value] list of config files and their settings.
- client_keys.public_key: The clients ECC public key (used for verifying
signatures and decrypting data).
Ensure the config.toml is in the same directory as your application.
## Sending Requests
All API requests must be sent as POST requests with an encrypted body. The
encryption key is exchanged using the ECC-based JWE token provided in the
Authorization header.
Headers:
Authorization: Must contain the JWE token in the format Bearer <token>.
Request Body:
The body of the request must be encrypted using AES, with the symmetric key
provided inside the JWE token.
Reading a config file:
{
"action": "read_file",
"file": "wireguard_wg0"
}
Writing to a config file:
{
"action": "write_file",
"file": "wireguard_wg0",
"data": {
[Interface]
PrivateKey = PrivateKey123=
Address = 10.10.200.1/32
ListenPort = 51820
[Peer]
PublicKey = PublicKey123=
AllowedIPs = 10.10.200.2/32
}
}
}
## Response Structure Details
Response is json document like:
{
"data": "<encrypted_data>",
"signature": "<base64-encoded signature>"
}
The decrypted data could look like this:
{
"status": 200,
"timestamp": "2024-10-22T10:30:00Z",
"message": "File written successfully"
}
## Error Handling
400 Bad Request: Returned if the request is malformed or the token is invalid.
401 Unauthorized: If the Authorization header or the JWE token is missing or invalid.
403 Forbidden: If the signature validation fails.
500 Internal Server Error: For unexpected errors in processing the request.