# ESP8266 Firewall with API

## Example

Clone this repository and open the folder `esp8266example` in Visual Studio Code.

### Credentials

After git is finished, add the WiFi credentials, username and password for basic auth by creating a `theSecrets.h` file based on the example that can be found in the `include` folder.

### Compile and upload

Finally compile and upload with the [official platformIO plugin](https://marketplace.visualstudio.com/items?itemName=platformio.platformio-ide)

## API

Following endpoints can be used with the firewall (see `https://<IP_OF_ESP8266>:8080/api`):

```json
[
  {
    "endpoint": "https://10.93.0.246:8080/api/firewall/rules",
    "description": "Get all Firewall Rules",
    "method": "GET"
  },
  {
    "endpoint": "https://10.93.0.246:8080/api/firewall/rules/<key>",
    "description": "Get Firewall Rule by key",
    "method": "GET"
  },
  {
    "endpoint": "https://10.93.0.246:8080/api/firewall/rules",
    "description": "Create Firewall Rule",
    "method": "POST"
  },
  {
    "endpoint": "https://10.93.0.246:8080/api/firewall/rules/<key>",
    "description": "Update Firewall Rule by key",
    "method": "PUT"
  },
  {
    "endpoint": "https://10.93.0.246:8080/api/firewall/rules/<key>",
    "description": "Delete Firewall Rule by key",
    "method": "DELETE"
  }
]
```

Endpoints that show the rules and that can modify the rules are protected by basic auth. Username and password need to be set as described [here](https://github.com/flohoss/esp8266_firewall_api#credentials).

### Get rules

```sh
curl -u username:password \
https://10.93.0.246:8080/api/firewall/rules
```

```json
// HTTP/1.1 200 OK
// Content-Type: application/json; charset=utf-8
// Content-Length: 109
// Connection: keep-alive
// Keep-Alive: timeout=2000
[
  {
    "key": "1",
    "ip": "10.93.0.211",
    "port_from": "8080",
    "port_to": "8080",
    "protocol": "TCP",
    "target": "ACCEPT"
  }
]
```

### Get rule

```sh
curl -u username:password \
https://10.93.0.246:8080/api/firewall/rules/1
```

```json
// HTTP/1.1 200 OK
// Content-Type: application/json; charset=utf-8
// Content-Length: 107
// Connection: keep-alive
// Keep-Alive: timeout=2000
{
  "key": "1",
  "ip": "10.93.0.211",
  "port_from": "8080",
  "port_to": "8080",
  "protocol": "TCP",
  "target": "ACCEPT"
}
```

### Create rule

```sh
curl -X POST -u username:password \
https://10.93.0.246:8080/api/firewall/rules?ip=10.93.0.200&port_from=10&port_to=50&protocol=UDP&target=ACCEPT
```

```json
// HTTP/1.1 201 Created
// Content-Type: application/json; charset=utf-8
// Content-Length: 104
// Connection: keep-alive
// Keep-Alive: timeout=2000
{
  "key": "2",
  "ip": "10.93.0.200",
  "port_from": "10",
  "port_to": "50",
  "protocol": "UDP",
  "target": "ACCEPT"
}
```

Available protocols are TCP, UDP & ALL

Available targets are ACCEPT & DROP

### Update rule

```sh
curl -X PUT -u username:password \
https://10.93.0.246:8080/api/firewall/rules/2?ip=10.93.0.100&port_from=20&port_to=100&protocol=ALL&target=DROP
```

```json
// HTTP/1.1 200 OK
// Content-Type: application/json; charset=utf-8
// Content-Length: 103
// Connection: keep-alive
// Keep-Alive: timeout=2000
{
  "key": "2",
  "ip": "10.93.0.100",
  "port_from": "20",
  "port_to": "100",
  "protocol": "ALL",
  "target": "DROP"
}
```

Available protocols are TCP, UDP & ALL

Available targets are ACCEPT & DROP

### Delete rule

```sh
curl -X DELETE -u username:password \
https://10.93.0.246:8080/api/firewall/rules/2
```

```json
// HTTP/1.1 200 OK
// Content-Type: application/json; charset=utf-8
// Content-Length: 36
// Connection: keep-alive
// Keep-Alive: timeout=2000
{
  "message": "firewall rule deleted"
}
```