wolfSentry

https://github.com/wolfssl/wolfsentry
Admin
wolfSentry is an embedded firewall and IDPS (Intrusion Detection and Prevention System) with dynamic...
Tokens:34,188
Snippets:285
Trust Score:9.4
Update:7 months ago
Show doc for...
Tokens:
Raw
### Start Notification Daemon

Source: https://github.com/wolfssl/wolfsentry/blob/master/examples/notification-demo/log_server/README.md

Shell command to start the `udp_to_dbus` notification daemon in a separate terminal. This daemon receives logs from the `log_server`.

```shell
# start the notification daemon in another terminal (see examples/notification-demo/udp_to_dbus)
# (change working directory to examples/notification-demo/udp_to_dbus)
./udp_to_dbus
```

--------------------------------

### Run Log Server

Source: https://github.com/wolfssl/wolfsentry/blob/master/examples/notification-demo/log_server/README.md

Shell commands to start the `log_server` HTTPS server. It can optionally be configured with an alternate address for the notification server.

```shell
# start the echo server
./log_server

# or if using the notification daemon, optionally provide an alternate address for it, e.g.:
./log_server --kv-string notification-server-addr=10.0.4.4
```

--------------------------------

### Build Wolfsentry

Source: https://github.com/wolfssl/wolfsentry/blob/master/examples/notification-demo/udp_to_dbus/README.md

Commands to build and install the wolfSentry project. This is a prerequisite for building the UDP to DBUS notification daemon.

```shell
cd wolfsentry
make
make install
```

--------------------------------

### Curl: Connect and Show Logs

Source: https://github.com/wolfssl/wolfsentry/blob/master/examples/notification-demo/log_server/README.md

Example `curl` command to connect to the HTTPS server and display the connection logs. Requires client certificate and key, and CA certificate for mutual authentication.

```shell
# For the below client invocations, change working directory to examples/notification-demo/log_server.

# Note these examples assume a modern curl.  If necessary, build and install it -- see https://curl.se/

# Connect from `curl` and dump the logs
curl --cert ./certs/client-ecc384-cert.pem --key ./certs/client-ecc384-key.pem --cacert ./certs/ca-ecc-cert.pem --resolve www.wolfssl.com:10443:127.0.0.1 https://www.wolfssl.com:10443/show-log
```

--------------------------------

### Initialize wolfSentry and Network Services in main.c

Source: https://github.com/wolfssl/wolfsentry/blob/master/examples/STM32-LWIP/README.md

Includes necessary headers and initializes wolfSentry, echo, and ping services within the FreeRTOS default task. This code should be placed in the `StartDefaultTask()` function in `main.c` after the user code begin block.

```c
/* USER CODE BEGIN Includes */

#include "echo.h"
#include "ping.h"
/* USER CODE END Includes */
```

```c
  /* USER CODE BEGIN 5 */
  printf("Sentry init\n");
  sentry_init();
  printf("Echo init\n");
  echo_init();
  printf("Ping init\n");
  ping_init();
  /* USER CODE END 5 */
```

--------------------------------

### Curl: Connect and Reset Logs

Source: https://github.com/wolfssl/wolfsentry/blob/master/examples/notification-demo/log_server/README.md

Example `curl` command to connect to the HTTPS server and reset the connection logs. Requires client certificate and key, and CA certificate for mutual authentication.

```shell
# Connect from `curl` and reset the logs
curl --cert ./certs/client-ecc384-cert.pem --key ./certs/client-ecc384-key.pem --cacert ./certs/ca-ecc-cert.pem --resolve www.wolfssl.com:10443:127.0.0.1 https://www.wolfssl.com:10443/reset-log
```

--------------------------------

### Run UDP to DBUS Demo

Source: https://github.com/wolfssl/wolfsentry/blob/master/examples/notification-demo/udp_to_dbus/README.md

Command to execute the UDP to DBUS notification daemon. This starts the application that listens for wolfSentry notifications and forwards them to DBUS.

```shell
./udp_to_dbus
```

--------------------------------

### Example Filter Installation Routines for Other Protocols

Source: https://github.com/wolfssl/wolfsentry/blob/master/lwip/README.md

Similar to TCP, filter installation routines are available for other network layers and protocols. Replace 'tcp' with the desired protocol such as 'ethernet', 'ip4', 'ip6', 'icmp', 'icmp6', or 'udp' to configure filtering for those layers.

```c
// Example for IP4
void ip4_filter(ip4_filter_fn cb);
void ip4_filter_mask(packet_filter_event_mask_t mask);
void ip4_filter_arg(void *arg);

// Example for UDP
void udp_filter(udp_filter_fn cb);
void udp_filter_mask(packet_filter_event_mask_t mask);
void udp_filter_arg(void *arg);
```

--------------------------------

### Integrate wolfSentry and Echo Server in main.c

Source: https://github.com/wolfssl/wolfsentry/blob/master/examples/STM32-LWIP-WOLFSSL/README.md

Includes necessary headers and initializes the wolfSentry and echo server functionalities within the STM32CubeIDE's default task. It sets up a connection queue and handles the TLS handshake, data reading, and writing process for incoming HTTPS connections.

```c
/* USER CODE BEGIN Includes */

#include "echo.h"
#include "sentry.h"

```

```c
  /* USER CODE BEGIN 5 */
  printf("Start!\r\n");
  printf("Sentry init\n");
  sentry_init();
  printf("Echo init\n");
  echo_ssl();

  connQueue = xQueueCreate( 10, sizeof( struct thread_data* ) );
  echo_init();

  /* Infinite loop */
  for(;;)
  {
		BaseType_t qRet = pdFALSE;
		struct thread_data tdata;
		while (qRet != pdTRUE) {
		  qRet = xQueueReceive( connQueue, &( tdata ), ( TickType_t ) 10 );
		}
		char buff[256];
		int ret;
		int retry = 10;
		struct tcp_pcb *pcb = tdata.pcb;
		WOLFSSL *ssl = tdata.ssl;

		fprintf(stderr, "Queue item running\r\n");
		do {
			if (pcb->state == CLOSE_WAIT) {
				fprintf(stderr, "Client immediately hung-up\n");
				goto close_wait;
			}
			ret = wolfSSL_accept(ssl);
			if ((wolfSSL_want_read(ssl) || wolfSSL_want_write(ssl))) {
				osDelay(500);
				retry--;
			} else {
				retry = 0;
			}
		} while (retry);
		if (ret != WOLFSSL_SUCCESS) {
			fprintf(stderr, "wolfSSL_accept ret = %d, error = %d\n",
				ret, wolfSSL_get_error(ssl, ret));
			goto ssl_shutdown;
		} else {
			fprintf(stderr, "Handshake done!\n");
		}

		memset(buff, 0, sizeof(buff));
		if (ret == WOLFSSL_SUCCESS) {
			retry = 10;
			do {
				ret = wolfSSL_read(ssl, buff, sizeof(buff));
				if ((wolfSSL_want_read(ssl) || wolfSSL_want_write(ssl))) {
					osDelay(500);
					retry--;
				} else {
					retry = 0;
				}
			} while (retry);
			if (ret == -1) {
				fprintf(stderr, "ERROR: failed to read\n");
				goto ssl_shutdown;
			}
			else
			{
				fprintf(stderr, "Sending response\n");
				if ((ret = wolfSSL_write(ssl, response, strlen(response))) != strlen(response)) {
					fprintf(stderr, "ERROR: failed to write\n");
				}
			}
		}

ssl_shutdown:
		retry = 10;
		do {
			ret = wolfSSL_shutdown(ssl);
			if (ret == SSL_SHUTDOWN_NOT_DONE) {
				osDelay(500);
				retry--;
			} else {
				break;
			}
		} while (retry);

close_wait:
		fprintf(stderr, "Connection closed\n");
		wolfSSL_free(ssl);
  }
  /* USER CODE END 5 */

```

--------------------------------

### Build UDP to DBUS Daemon

Source: https://github.com/wolfssl/wolfsentry/blob/master/examples/notification-demo/udp_to_dbus/README.md

Command to build the UDP to DBUS notification daemon after wolfSentry has been built and installed. This compiles the application that relays notifications.

```shell
make
```

--------------------------------

### Curl: Show Logs with Readonly Authorization

Source: https://github.com/wolfssl/wolfsentry/blob/master/examples/notification-demo/log_server/README.md

Example `curl` command to connect and show logs using a client certificate with 'readonly' authorization. This demonstrates role-based access control.

```shell
# Connect from `curl` and show logs with readonly authorization:
curl --cert ./certs/server-cert.pem --key ./certs/server-key.pem --cacert ./certs/ca-ecc-cert.pem --resolve www.wolfssl.com:10443:127.0.0.1 https://www.wolfssl.com:10443/show-log
```

--------------------------------

### Run the Linux wolfIP + wolfSentry Demo (Shell)

Source: https://github.com/wolfssl/wolfsentry/blob/master/examples/Linux-wolfIP/README.md

This command executes the demo application. It requires root privileges due to the use of TAP interfaces. The demo initializes wolfSentry, installs packet filters, and sets up a wolfIP instance on a TAP interface.

```shell
sudo ./wolfip-wolfsentry-demo
```

--------------------------------

### Curl: Show Logs with Different Readonly CA

Source: https://github.com/wolfssl/wolfsentry/blob/master/examples/notification-demo/log_server/README.md

Example `curl` command to connect and show logs using a client certificate issued by a different CA, demonstrating flexibility in CA configuration for role-based access.

```shell
# Use a different valid cert issued by the readonly CA to connect from `curl` and show logs:
curl --cert ./certs/entity-no-ca-bool-cert.pem --key ./certs/entity-no-ca-bool-key.pem --cacert ./certs/ca-ecc-cert.pem --resolve www.wolfssl.com:10443:127.0.0.1 https://www.wolfssl.com:10443/show-log
```

--------------------------------

### Build Log Server HTTPS Server

Source: https://github.com/wolfssl/wolfsentry/blob/master/examples/notification-demo/log_server/README.md

Commands to build the `log_server` HTTPS server. This is the main demo application that accepts and processes TLS connections.

```shell
cd examples/notification-demo/log_server
make
```

--------------------------------

### Build WolfSSL with WolfSentry

Source: https://github.com/wolfssl/wolfsentry/blob/master/examples/notification-demo/log_server/README.md

Commands to configure and build wolfSSL with the wolfSentry option enabled. This enables the TLS webserver functionality.

```shell
cd wolfssl
./configure --enable-wolfsentry --enable-opensslextra [--enable-intelasm]
make
make install
```

--------------------------------

### Configure wolfSentry Options for STM32 LWIP

Source: https://github.com/wolfssl/wolfsentry/blob/master/examples/STM32-LWIP/README.md

Defines essential configurations for wolfSentry when used with FreeRTOS and LWIP on STM32. It enables necessary macros like FREERTOS and WOLFSENTRY_LWIP, and disables features like protocol names and POSIX memalign to suit the embedded environment. Uncomment WOLFSENTRY_SINGLETHREADED if not using multi-threading to remove semaphore dependencies.

```c
#ifndef WOLFSENTRY_OPTIONS_H
#define WOLFSENTRY_OPTIONS_H

#define FREERTOS
//#define WOLFSENTRY_SINGLETHREADED
#define WOLFSENTRY_LWIP
#define WOLFSENTRY_NO_PROTOCOL_NAMES
#define WOLFSENTRY_NO_POSIX_MEMALIGN
#endif /* WOLFSENTRY_OPTIONS_H */
```

--------------------------------

### Install lwIP Filter Callbacks with Wolfsentry

Source: https://github.com/wolfssl/wolfsentry/blob/master/doc/freertos-lwip-app.md

Installs filter callbacks for the lwIP network stack to enable Wolfsentry to inspect and control network traffic. This function takes masks for various protocols (Ethernet, IP, ICMP, TCP, UDP) to specify which traffic should be filtered. The `WOLFSENTRY_CONTEXT_ARGS_OUT_EX` macro is used for context passing.

```c
#define LWIP_ALL_EVENTS (
        (1U << FILT_BINDING) |
        (1U << FILT_DISSOCIATE) |
        (1U << FILT_LISTENING) |
        (1U << FILT_STOP_LISTENING) |
        (1U << FILT_CONNECTING) |
        (1U << FILT_ACCEPTING) |
        (1U << FILT_CLOSED) |
        (1U << FILT_REMOTE_RESET) |
        (1U << FILT_RECEIVING) |
        (1U << FILT_SENDING) |
        (1U << FILT_ADDR_UNREACHABLE) |
        (1U << FILT_PORT_UNREACHABLE) |
        (1U << FILT_INBOUND_ERR) |
        (1U << FILT_OUTBOUND_ERR))

    ret = wolfsentry_install_lwip_filter_callbacks(
        WOLFSENTRY_CONTEXT_ARGS_OUT_EX(wolfsentry_lwip_ctx),

#if LWIP_ARP || LWIP_ETHERNET
        LWIP_ALL_EVENTS, /* ethernet_mask */
#else
        0,
#endif
#if LWIP_IPV4 || LWIP_IPV6
        LWIP_ALL_EVENTS, /* ip_mask */
#else
        0,
#endif
#if LWIP_ICMP || LWIP_ICMP6
        LWIP_ALL_EVENTS, /* icmp_mask */
#else
        0,
#endif
#if LWIP_TCP
        LWIP_ALL_EVENTS, /* tcp_mask */
#else
        0,
#endif
#if LWIP_UDP
        LWIP_ALL_EVENTS /* udp_mask */
#else
        0
#endif
        );
    if (ret < 0) {
        printf("wolfsentry_install_lwip_filter_callbacks: "
               WOLFSENTRY_ERROR_FMT "\n", WOLFSENTRY_ERROR_FMT_ARGS(ret));
    }
```

--------------------------------

### Assign MAC Filter Callback to netif Input in ethernetif.c (C)

Source: https://github.com/wolfssl/wolfsentry/blob/master/examples/STM32-LWIP-WOLFSSL/README.md

This code snippet modifies the `ethernetif_init()` function in `ethernetif.c` to assign the custom `filter_input` callback to the network interface's input handler. This ensures that all incoming packets are processed by the MAC address filter before being passed to the standard LWIP input functions. This change should be placed after the `#if LWIP_ARP` directive.

```c
    netif->input = filter_input;
```

--------------------------------

### Build wolfSentry API Documentation (HTML)

Source: https://github.com/wolfssl/wolfsentry/blob/master/README.md

Generates the HTML version of the full API reference manual for wolfSentry using Doxygen. Ensure Doxygen is installed before running this command.

```makefile
make doc-html
```

--------------------------------

### Enable TCP Packet Hook in lwipopts.h

Source: https://github.com/wolfssl/wolfsentry/blob/master/examples/STM32-LWIP/README.md

Configures LWIP options in `lwipopts.h` to enable TCP input packet hooking for filtering. This involves including the `echo.h` header and defining `LWIP_HOOK_TCP_INPACKET_PCB` to point to the `sentry_tcp_inpkt` function. This hook allows wolfSentry to inspect incoming TCP packets.

```c
#include "echo.h"
#define LWIP_HOOK_TCP_INPACKET_PCB sentry_tcp_inpkt
```

--------------------------------

### Build the Linux wolfIP + wolfSentry Demo (Shell)

Source: https://github.com/wolfssl/wolfsentry/blob/master/examples/Linux-wolfIP/README.md

This command builds the demo application. It first compiles a local static library for wolfIP and then links the demo executable against it and the wolfSentry library. The WOLFIP_PATH can be overridden if the wolfIP source is located elsewhere.

```shell
cd wolfsentry/examples/Linux-wolfIP
make            # override WOLFIP_PATH=/path/to/wolfip if needed
```

--------------------------------

### Build wolfSentry Library for FreeRTOS/lwIP (Makefile)

Source: https://github.com/wolfssl/wolfsentry/blob/master/doc/freertos-lwip-app.md

This command demonstrates how to build the wolfSentry library (`libwolfsentry.a`) for an ARM Cortex M7 processor using FreeRTOS and lwIP. It requires specifying the host, runtime environment, and paths to the FreeRTOS and lwIP distributions.

```makefile
make HOST=arm-none-eabi EXTRA_CFLAGS='-mcpu=cortex-m7' RUNTIME=FreeRTOS-lwIP FREERTOS_TOP="$FREERTOS_TOP" LWIP_TOP="$LWIP_TOP"
```

--------------------------------

### Curl: Failed Mutual Auth (Self-Signed Client Cert)

Source: https://github.com/wolfssl/wolfsentry/blob/master/examples/notification-demo/log_server/README.md

Example `curl` command demonstrating a failed mutual authentication due to a self-signed client certificate. This will result in an authentication error.

```shell
# Failed mutual auth example -- self-signed client cert:
curl --cert ./certs/client-cert-ext.pem --key ./certs/client-key.pem --cacert ./certs/ca-ecc-cert.pem --resolve www.wolfssl.com:10443:127.0.0.1 https://www.wolfssl.com:10443/show-log
```

--------------------------------

### Initialize wolfSentry with Dynamic Policies (C)

Source: https://github.com/wolfssl/wolfsentry/blob/master/doc/freertos-lwip-app.md

This C code snippet shows how to initialize wolfSentry within a FreeRTOS application. It includes defining custom error IDs, including necessary headers, setting up a static context, and configuring event parameters. The essential calls are `wolfsentry_init()`, `wolfsentry_config_json_oneshot()`, and `wolfsentry_install_lwip_filter_callbacks()`.

```c
#define WOLFSENTRY_SOURCE_ID WOLFSENTRY_SOURCE_ID_USER_BASE
#define WOLFSENTRY_ERROR_ID_USER_APP_ERR0 (WOLFSENTRY_ERROR_ID_USER_BASE-1)
 /* user-defined error IDs count down starting at WOLFSENTRY_ERROR_ID_USER_BASE (which is negative). */

#include <wolfsentry/wolfsentry_json.h>
#include <wolfsentry/wolfsentry_lwip.h>

static struct wolfsentry_context *wolfsentry_lwip_ctx = NULL;

static const struct wolfsentry_eventconfig demo_config = {
#ifdef WOLFSENTRY_HAVE_DESIGNATED_INITIALIZERS
        .route_private_data_size = 64,
        .route_private_data_alignment = 0,         /* default alignment -- same as sizeof(void *). */
        .max_connection_count = 10,                /* by default, don't allow more than 10 simultaneous
                                                    * connections that match the same route.
                                                    */
        .derogatory_threshold_for_penaltybox = 4,  /* after 4 derogatory events matching the same route,
                                                    * put the route in penalty box status.
                                                    */
        .penaltybox_duration = 300,                /* keep routes in penalty box status for 5 minutes.
                                                    * denominated in seconds when passing to
                                                    * wolfsentry_init().
                                                    */
        .route_idle_time_for_purge = 0,            /* 0 to disable -- autopurge doesn't usually make
                                                    * much sense as a default config.
                                                    */
        .flags = WOLFSENTRY_EVENTCONFIG_FLAG_COMMENDABLE_CLEARS_DEROGATORY, /* automatically clear
                                                    * derogatory count for a route when a commendable
                                                    * event matches the route. */
        .route_flags_to_add_on_insert = 0,
        .route_flags_to_clear_on_insert = 0,
        .action_res_filter_bits_set = 0,
        .action_res_filter_bits_unset = 0,
        .action_res_bits_to_add = 0,
        .action_res_bits_to_clear = 0
#else
        64,
        0,
        10,
        4,
        300,
        0,
        WOLFSENTRY_EVENTCONFIG_FLAG_COMMENDABLE_CLEARS_DEROGATORY,
        0,
        0,
        0,
        0,
        0,
        0
#endif
    };

/* This routine is to be called once by the application before any direct calls
 * to lwIP -- i.e., before lwip_init() or tcpip_init().
 */
wolfsentry_errcode_t activate_wolfsentry_lwip(const char *json_config, int json_config_len)
{
    wolfsentry_errcode_t ret;
    char err_buf[512]; /* buffer for detailed error messages from
                        * wolfsentry_config_json_oneshot().
                        */

    /* Allocate a thread state struct on the stack.  Note that the final
     * semicolon is supplied by the macro definition, so that in single-threaded
     * application builds this expands to nothing at all.
     */
    WOLFSENTRY_THREAD_HEADER_DECLS

    if (wolfsentry_lwip_ctx != NULL) {
        printf("activate_wolfsentry_lwip() called multiple times.\n");
        WOLFSENTRY_ERROR_RETURN(ALREADY);
    }

#ifdef WOLFSENTRY_ERROR_STRINGS
    /* Enable pretty-printing of the app source code filename for
     * WOLFSENTRY_ERROR_FMT/WOLFSENTRY_ERROR_FMT_ARGS().
     */
    ret = WOLFSENTRY_REGISTER_SOURCE();
    WOLFSENTRY_RERETURN_IF_ERROR(ret);

    /* Enable pretty-printing of an app-specific error code. */
    ret = WOLFSENTRY_REGISTER_ERROR(USER_APP_ERR0, "failure in application code");
    WOLFSENTRY_RERETURN_IF_ERROR(ret);
#endif

    /* Initialize the thread state struct -- this sets the thread ID. */
    WOLFSENTRY_THREAD_HEADER_INIT_CHECKED(WOLFSENTRY_THREAD_FLAG_NONE);

    /* Call the main wolfSentry initialization routine.

```

--------------------------------

### Curl: Role-Based Authorization Failure

Source: https://github.com/wolfssl/wolfsentry/blob/master/examples/notification-demo/log_server/README.md

Example `curl` command demonstrating a role-based authorization failure. This occurs when a client attempts an action (like resetting logs) that their assigned role does not permit.

```shell
# Role-based authorization failure example
curl --cert ./certs/server-cert.pem --key ./certs/server-key.pem --cacert ./certs/ca-ecc-cert.pem --resolve www.wolfssl.com:10443:127.0.0.1 https://www.wolfssl.com:10443/reset-log
```

--------------------------------

### Install lwIP Filter Callbacks with Wolfsentry

Source: https://context7.com/wolfssl/wolfsentry/llms.txt

Installs wolfSentry filter callbacks into the lwIP TCP/IP stack for automatic packet filtering. This function configures callbacks for various network events across different protocol layers.

```c
#include <wolfsentry/wolfsentry_json.h>
#include <wolfsentry/wolfsentry_lwip.h>

#define LWIP_ALL_EVENTS (                       \
        (1U << FILT_BINDING) |                  \
        (1U << FILT_LISTENING) |                \
        (1U << FILT_CONNECTING) |               \
        (1U << FILT_ACCEPTING) |                \
        (1U << FILT_CLOSED) |                   \
        (1U << FILT_REMOTE_RESET) |             \
        (1U << FILT_RECEIVING) |                \
        (1U << FILT_SENDING) |                  \
        (1U << FILT_ADDR_UNREACHABLE) |         \
        (1U << FILT_PORT_UNREACHABLE))

wolfsentry_errcode_t setup_lwip_filtering(
    WOLFSENTRY_CONTEXT_ARGS_IN)
{
    wolfsentry_errcode_t ret;

    /* Install callbacks for all protocols */
    ret = wolfsentry_install_lwip_filter_callbacks(
        WOLFSENTRY_CONTEXT_ARGS_OUT,
        LWIP_ALL_EVENTS,  /* ethernet_mask */
        LWIP_ALL_EVENTS,  /* ip_mask */
        LWIP_ALL_EVENTS,  /* icmp_mask */
        LWIP_ALL_EVENTS,  /* tcp_mask */
        LWIP_ALL_EVENTS); /* udp_mask */

    if (ret < 0) {
        printf("lwIP callback install failed: " WOLFSENTRY_ERROR_FMT "\n",
               WOLFSENTRY_ERROR_FMT_ARGS(ret));
    }

    return ret;
}

```

--------------------------------

### Curl: Failed Mutual Auth (Invalid Extended Key Usage)

Source: https://github.com/wolfssl/wolfsentry/blob/master/examples/notification-demo/log_server/README.md

Example `curl` command demonstrating a failed mutual authentication. The client certificate is issued by a valid CA but lacks the required 'client auth' extended key usage.

```shell
# Failed mutual auth example -- valid issuer but invalid use -- "Ext Key Use server/client auth not set":
curl --cert ./certs/server-ecc384-cert.pem --key ./certs/server-ecc384-key.pem --cacert ./certs/ca-ecc-cert.pem --resolve www.wolfssl.com:10443:127.0.0.1 https://www.wolfssl.com:10443/show-log
```

--------------------------------

### TCP Filter Installation Routines

Source: https://github.com/wolfssl/wolfsentry/blob/master/lwip/README.md

These routines are used to install callback functions for filtering TCP packets. You can set a callback function, a mask for events to filter, and an argument to be passed to the callback. The specific callback function's argument structure depends on the protocol.

```c
void tcp_filter(tcp_filter_fn cb);
void tcp_filter_mask(packet_filter_event_mask_t mask);
void tcp_filter_arg(void *arg);
```
Tokens:
Raw