esp-firewall/documentation/api/api.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 the following and can be retrieved by visiting the API (e.g. \verb|http://10.93.0.224:8080/api|) of the device.

\lstset{style=json}
\begin{lstlisting}
[
    {
        "endpoint": "http://10.93.0.246:8080/api/firewall/rules",
        "description": "Get all Firewall Rules",
        "method": "GET"
    },
    {
        "endpoint": "http://10.93.0.246:8080/api/firewall/rules/<key>",
        "description": "Get Firewall Rule by key",
        "method": "GET"
    },
    {
        "endpoint": "http://10.93.0.246:8080/api/firewall/rules",
        "description": "Create Firewall Rule",
        "method": "POST"
    },
    {
        "endpoint": "http://10.93.0.246:8080/api/firewall/rules/<key>",
        "description": "Update Firewall Rule by key",
        "method": "PUT"
    },
    {
        "endpoint": "http://10.93.0.246:8080/api/firewall/rules/<key>",
        "description": "Delete Firewall Rule by key",
        "method": "DELETE"
    }
]
\end{lstlisting}

\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}

Available protocols are \verb|TCP, UDP & ALL|

Available targets are \verb|ACCEPT & DROP|

\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}

Available protocols are \verb|TCP, UDP & ALL|

Available targets are \verb|ACCEPT & DROP|

\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 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. 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}
    #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.