76 lines
No EOL
2.8 KiB
TeX
76 lines
No EOL
2.8 KiB
TeX
\section{API}
|
|
|
|
\subsection{REST Endpoints} \label{api}
|
|
|
|
Managing the firewall rules can be done over a REST API\footnote{\href{https://www.ibm.com/cloud/learn/rest-apis}{What is 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{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.
|
|
|
|
\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.
|
|
|
|
\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. |