Readme for the new implementation.

kiss/toml-manager/README.md

@@ -0,0 +1,147 @@
+# 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 server’s 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. Here’s 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 client’s 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.