From f705ce2f390674073028b5f804f99089db30124f Mon Sep 17 00:00:00 2001 From: Florian Hoss Date: Wed, 27 Jul 2022 12:32:17 +0200 Subject: [PATCH] Include API curl commands --- ESPFirewall/lib/Firewall/docs/api/api.tex | 135 +++++++++++++++--- .../lib/Firewall/docs/titlepage/titlepage.tex | 1 + 2 files changed, 113 insertions(+), 23 deletions(-) diff --git a/ESPFirewall/lib/Firewall/docs/api/api.tex b/ESPFirewall/lib/Firewall/docs/api/api.tex index cb5b629..63b2b4a 100644 --- a/ESPFirewall/lib/Firewall/docs/api/api.tex +++ b/ESPFirewall/lib/Firewall/docs/api/api.tex @@ -35,39 +35,128 @@ Managing the firewall rules can be done over a REST API\footnote{\href{https://w ] \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| +Available targets are \verb|ACCEPT & DROP| \newpage +\subsection{Get rules} + +\begin{verbatim} +curl -u username:password http://10.93.0.246:8080/api/firewall/rules +\end{verbatim} + +\lstset{style=json} +\begin{lstlisting} +// HTTP/1.1 200 OK +// Content-Type: application/json; charset=utf-8 +// Content-Length: 109 +[ + { + "key": "1", + "ip": "10.93.0.211", + "port_from": "8080", + "port_to": "8080", + "protocol": "TCP", + "target": "ACCEPT" + } +] +\end{lstlisting} + +\subsection{Get rule} + +\begin{verbatim} +curl -u username:password http://10.93.0.246:8080/api/firewall/rules/1 +\end{verbatim} + +\lstset{style=json} +\begin{lstlisting} +// HTTP/1.1 200 OK +// Content-Type: application/json; charset=utf-8 +// Content-Length: 107 +{ + "key": "1", + "ip": "10.93.0.211", + "port_from": "8080", + "port_to": "8080", + "protocol": "TCP", + "target": "ACCEPT" +} +\end{lstlisting} + +\subsection{Create rule} + +\begin{verbatim} +curl -X POST -u username:password \ +http://10.93.0.246:8080/api/firewall/rules + ?ip=10.93.0.200&port_from=10&port_to=50&protocol=UDP&target=ACCEPT +\end{verbatim} + +\lstset{style=json} +\begin{lstlisting} +// HTTP/1.1 201 Created +// Content-Type: application/json; charset=utf-8 +// Content-Length: 104 +{ + "key": "2", + "ip": "10.93.0.200", + "port_from": "10", + "port_to": "50", + "protocol": "UDP", + "target": "ACCEPT" +} +\end{lstlisting} + +\subsection{Update rule} + +\begin{verbatim} +curl -X PUT -u username:password \ +http://10.93.0.246:8080/api/firewall/rules/2 + ?ip=10.93.0.100&port_from=20&port_to=100&protocol=ALL&target=DROP +\end{verbatim} + +\lstset{style=json} +\begin{lstlisting} +// HTTP/1.1 200 OK +// Content-Type: application/json; charset=utf-8 +// Content-Length: 103 +{ + "key": "2", + "ip": "10.93.0.100", + "port_from": "20", + "port_to": "100", + "protocol": "ALL", + "target": "DROP" +} +\end{lstlisting} + +\subsection{Delete rule} + +\begin{verbatim} +curl -X DELETE -u username:password \ +http://10.93.0.246:8080/api/firewall/rules/2 +\end{verbatim} + +\lstset{style=json} +\begin{lstlisting} +// HTTP/1.1 200 OK +// Content-Type: application/json; charset=utf-8 +// Content-Length: 36 +{ + "message": "firewall rule deleted" +} +\end{lstlisting} + \subsection{HTTPS} \label{https} -To connect to the esp over HTTPS (Hypertext Transfer Protocol Secure) the Webserver can be setup to use certificates that need to be included in the constructor as seen in section \ref{authentication}. This only works for the esp8266 with the Arduino library, can be added as an external library (\verb|esp32_https_server_combat|\footnote{\href{https://github.com/fhessel/esp32_https_server_compat}{https://github.com/fhessel/esp32\_https\_server\_compat}}) for the esp32 if needed. +To connect to the ESP over HTTPS (Hypertext Transfer Protocol Secure) the Webserver can be setup to use certificates that need to be included in the constructor as seen in section \ref{authentication}. This only works for the esp8266 with the Arduino library but can be added as an external library (\verb|esp32_https_server_combat|\footnote{\href{https://github.com/fhessel/esp32_https_server_compat}{https://github.com/fhessel/esp32\_https\_server\_compat}}) for the esp32 if needed. + +\newpage \subsection{Authentication} \label{authentication} -To authenticate the API uses basic auth. Communication should therefore be encrypted to protect the process from eavesdropping. Example certificates for the esp8266 are included in the repository and encryption can be added to the esp32 as described in section \ref{https}. 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. +To authenticate the API uses basic auth. Communication should therefore be encrypted to protect the process from eavesdropping. Another solution would be to setup the rules in a private network and setup the esp without the API enabled. Therefore the rules will still apply, but cannot be changed over the network. Example certificates for the esp8266 are included in the repository and encryption can be added to the esp32 as described in section \ref{https}. 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} diff --git a/ESPFirewall/lib/Firewall/docs/titlepage/titlepage.tex b/ESPFirewall/lib/Firewall/docs/titlepage/titlepage.tex index 5285816..8900582 100644 --- a/ESPFirewall/lib/Firewall/docs/titlepage/titlepage.tex +++ b/ESPFirewall/lib/Firewall/docs/titlepage/titlepage.tex @@ -24,5 +24,6 @@ \vfill \raggedright{} \HRule{13pt}{1pt} \\ + \titleemph{Git:} \href{https://github.com/flohoss/esp32\_firewall\_api}{https://github.com/flohoss/esp32\_firewall\_api} \\ \titleemph{Professor:} Prof. Dr. rer. nat. Tobias Heer \end{titlepage} \ No newline at end of file