From 4f2608e34ea836b50b49a01b3655d2cf96b0782f Mon Sep 17 00:00:00 2001
From: Florian Hoss <flhoit00@hs-esslingen.de>
Date: Tue, 19 Jul 2022 11:51:23 +0200
Subject: [PATCH] More docu

---
 ESPFirewall/lib/Firewall/docs/api/api.tex | 70 +++++++++++++++++++++++
 ESPFirewall/lib/Firewall/docs/main.tex    | 33 ++++++++++-
 2 files changed, 102 insertions(+), 1 deletion(-)
 create mode 100644 ESPFirewall/lib/Firewall/docs/api/api.tex

diff --git a/ESPFirewall/lib/Firewall/docs/api/api.tex b/ESPFirewall/lib/Firewall/docs/api/api.tex
new file mode 100644
index 0000000..279d983
--- /dev/null
+++ b/ESPFirewall/lib/Firewall/docs/api/api.tex
@@ -0,0 +1,70 @@
+\section{API} \label{api}
+
+Managing the firewall rules can be done over a rest api. Available routes are following and can be retrieved by visiting the API (e.g. \verb|https://10.93.0.224:8080/api|) of the device.
+
+\lstset{style=json}
+\begin{lstlisting}
+[
+    {
+        "endpoint": "https://10.93.0.224:8080/api/firewall/rules",
+        "description": "Get all Firewall Rules",
+        "method": "GET"
+    },
+    {
+        "endpoint": "https://10.93.0.224:8080/api/firewall/rules/<key>",
+        "description": "Get Firewall Rule by key",
+        "method": "GET"
+    },
+    {
+        "endpoint": "https://10.93.0.224:8080/api/firewall/rules",
+        "description": "Create Firewall Rule",
+        "method": "POST"
+    },
+    {
+        "endpoint": "https://10.93.0.224:8080/api/firewall/rules/<key>",
+        "description": "Delete Firewall Rule by key",
+        "method": "DELETE"
+    }
+]
+\end{lstlisting}
+
+\subsection{Create firewall rule}
+
+To create a firewall rule with a POST request, query parameter for each field are required:
+
+\verb|?ip=10.93.0.211&port_from=22&port_to=80&protocol=TCP&target=REJECT|
+
+The response will be the created rule with its parameter.
+
+\lstset{style=json}
+\begin{lstlisting}
+    {
+        "key": "1",
+        "ip": "10.93.0.211",
+        "port_from": "22",
+        "port_to": "80",
+        "protocol": "TCP",
+        "target": "REJECT"
+    }
+\end{lstlisting}
+
+Available protocols are \verb|TCP, UDP & ALL|
+
+Available targets are \verb|REJECT, ACCEPT & DROP|
+
+\newpage
+
+\subsection{Authentication}
+
+To authenticate the API uses basic auth. Communication is therefor encrypted to protect the process from eavesdropping. Setting the username and password is done via the constructor of the api class. To create the api class to setup the firewall rules a firewall class instance is needed.
+
+\lstset{style=c++}
+\begin{lstlisting}
+    #include "Firewall.hpp"
+    #include "API.hpp"
+
+    firewall = new fw::Firewall();
+    firewallApi = new fw::API(firewall, cert, key, username, password);
+\end{lstlisting}
+
+After this all endpoints shown in section \ref{api} will be protected.
\ No newline at end of file
diff --git a/ESPFirewall/lib/Firewall/docs/main.tex b/ESPFirewall/lib/Firewall/docs/main.tex
index 8885d3c..72b7b8a 100644
--- a/ESPFirewall/lib/Firewall/docs/main.tex
+++ b/ESPFirewall/lib/Firewall/docs/main.tex
@@ -29,13 +29,43 @@
 \lstdefinestyle{c++}{
    language=C++,
    directivestyle={\color{codepurple}},
-   emph={firewall_rule_t,uint8_t},
+   emph={firewall_rule_t,uint8_t,fw,Firewall,API},
    emphstyle={\color{codegreen}},
 }
 \lstdefinestyle{platform-io}{
    emph={platformio,esp32,esp8266,arduino},
    emphstyle={\color{codegreen}},
 }
+\definecolor{delim}{RGB}{20,105,176}
+\definecolor{numb}{RGB}{106, 109, 32}
+\definecolor{string}{rgb}{0.64,0.08,0.08}
+\lstdefinestyle{json}{
+   rulecolor=\color{black},
+   showspaces=false,
+   showtabs=false,
+   breaklines=true,
+   postbreak=\raisebox{0ex}[0ex][0ex]{\ensuremath{\color{gray}\hookrightarrow\space}},
+   breakatwhitespace=true,
+   basicstyle=\ttfamily\small,
+   upquote=true,
+   morestring=[b]",
+   stringstyle=\color{string},
+   literate=
+    *{0}{{{\color{numb}0}}}{1}
+     {1}{{{\color{numb}1}}}{1}
+     {2}{{{\color{numb}2}}}{1}
+     {3}{{{\color{numb}3}}}{1}
+     {4}{{{\color{numb}4}}}{1}
+     {5}{{{\color{numb}5}}}{1}
+     {6}{{{\color{numb}6}}}{1}
+     {7}{{{\color{numb}7}}}{1}
+     {8}{{{\color{numb}8}}}{1}
+     {9}{{{\color{numb}9}}}{1}
+     {\{}{{{\color{delim}{\{}}}}{1}
+     {\}}{{{\color{delim}{\}}}}}{1}
+     {[}{{{\color{delim}{[}}}}{1}
+     {]}{{{\color{delim}{]}}}}{1},
+}
 
 \setuptoc{toc}{totoc}
 
@@ -89,6 +119,7 @@
     \listoffigures
     \include{firststeps/firststeps}
     \include{storage/storage}
+    \include{api/api}
 
     \printbibliography[title=Bibliography]