lwIP SMTP

This module provides the lwIP SMTP integration documentation.

Overview

The documentation for the library can be found at the following link: lwIPSMTP.

Features

• Support authentication methods and send an email via the currently selected server, username and password.
• Support set up TLS connection handling with one-way server authentication or two-way server/client authentication.
• The common ports that used for SMTP:
  • Port 25:
    • Default port for SMTP since the beginning of email.
    • Supports plain, unencrypted SMTP.
  • Port 465:
    • Used for SMTPS (SMTP Secure), where the connection is immediately encrypted using SSL/TLS upon connection.
  • Custom ports: Based on the port of SMTP server.

    Note

    SMTP port usage reference in the RFC8314 documentation.

Configuration

Build Time Configurations for source

The following build time configurations are defined in lwip/lwip/apps/smtp_opts.h:

Configuration	Options	Default	Description
Data Handler Callback on BODY	Enabled Disabled	Disabled	Enable this option to invoke the user-defined callback for SMTP message BODY data.
SMTP Debug	LWIP_DBG_ON LWIP_DBG_OFF	LWIP_DBG_OFF	Set this to 1 to debug SMTP.
Maximum SMTP Server Name Length	Value must be a positive integer value	256	Specifies the maximum length of the SMTP server name.
Maximum SMTP Username Length	Value must be a positive integer value	32	Specifies the maximum length of the SMTP username.
Maximum Password Length	Value must be a positive integer value	32	Specifies the maximum length of the SMTP password.
Copy Authentication Data	Enabled Disabled	Enabled	Enable to copy username and password into internal buffers instead of using pointers to user data. Disabling this if you know the authentication data will not change during the smtp session, which saves some heap space.
Check Email Data	Enabled Disabled	Enabled	Enable to verify SMTP message fields for validity before transmission. Disabling this to save some code space if you know for sure that all data passed to this module conforms to the requirements in the SMTP RFC. WARNING: Use this with care!
AUTH PLAIN Support	Enabled Disabled	Enabled	Enable to support SMTP AUTH PLAIN authentication.
AUTH LOGIN Support	Enabled Disabled	Enabled	Enable to support SMTP AUTH LOGIN authentication.
Memory allocation	Name must be a valid C symbol	mem_malloc	Define the allocation function used for SMTP state machine memory. By default, uses lwIP mem_malloc. Override to FreeRTOS heap for RTOS-based systems.
Memory deallocation	Name must be a valid C symbol	mem_free	Define the free function used for SMTP state machine memory. By default, uses lwIP mem_free. Override to FreeRTOS heap for RTOS-based systems.

Usage Notes

TLS connection

The stack and heap sizes must be properly configured when using the TLS layer with MbedTLS. Depending on the specific configuration and use case, these values may need to be increased from their defaults. For more information on memory requirements, refer to the Memory Usage section in Mbed Crypto H/W Acceleration (rm_psa_crypto).

Note

When using hardware acceleration for the MbedTLS implementation, verify that the target device supports all required mbedCrypto features for the TLS layer of lwIP. Refer to the HW Overview and Features sections in Mbed Crypto H/W Acceleration (rm_psa_crypto) to check hardware support. If any required feature is not supported, configure the corresponding features to use the software crypto implementation instead.

Authetication

The lwIP SMTP module supports the following authentication methods:

• No Authentication: Use smtp_set_auth(NULL, NULL) for servers that don't require authentication.
• Authentication: Use smtp_set_auth(username, password) for username/password authentication.
  • AUTH LOGIN: The username and password are sent separately. The server first asks for the username, then the password.
  • AUTH PLAIN: The username and password are sent together.
  • The client automatically selects PLAIN or LOGIN based on server capabilities.
  • Both methods use Base64 encoding (NOT encryption).

Note

Authentication credentials are sent in plain text (Base64 encoded only) unless TLS is enabled. Base64 can be easily decoded by anyone intercepting network traffic.

Always use TLS when sending credentials:

// INSECURE - Credentials visible on network
smtp_set_tls_config(NULL);
smtp_set_auth("user", "password");

// SECURE - Credentials encrypted
smtp_set_tls_config(tls_config);  // Enable TLS encryption
smtp_set_auth("user", "password");

Examples

Basic Example

This is a basic example of minimal use of the lwIP SMTP APIs in an application.

Note

When using printf with e² studio, build errors may occur. Please refer to https://en-support.renesas.com/knowledgeBase/16979385 and follow Method 2, which is recommended for smooth integration and to avoid build errors.

#if LWIP_ALTCP && LWIP_ALTCP_TLS
 #include "lwip/altcp_tls.h"
 #include "mbedtls/platform.h"
#endif
#include "lwip/timeouts.h"
#include "lwip/init.h"
#include "lwip/netif.h"
#include "lwip/apps/smtp.h"

#define LWIP_SMTP_GW_ADDR    "192.168.10.1"
#define LWIP_SMTP_PORT       (1025)

#if LWIP_ALTCP && LWIP_ALTCP_TLS

/* Example ca certificate, needs to be updated. */
static uint8_t gs_ca_crt[] =
    "-----BEGIN CERTIFICATE-----\n"                                      \
    "MIIDQTCCAimgAwIBAgITBmyfz5m/jAo54vB4ikPmljZbyjANBgkqhkiG9w0BAQsF\n" \
    "ADA5MQswCQYDVQQGEwJVUzEPMA0GA1UEChMGQW1hem9uMRkwFwYDVQQDExBBbWF6\n" \
    "b24gUm9vdCBDQSAxMB4XDTE1MDUyNjAwMDAwMFoXDTM4MDExNzAwMDAwMFowOTEL\n" \
    "MAkGA1UEBhMCVVMxDzANBgNVBAoTBkFtYXpvbjEZMBcGA1UEAxMQQW1hem9uIFJv\n" \
    "b3QgQ0EgMTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBALJ4gHHKeNXj\n" \
    "ca9HgFB0fW7Y14h29Jlo91ghYPl0hAEvrAIthtOgQ3pOsqTQNroBvo3bSMgHFzZM\n" \
    "9O6II8c+6zf1tRn4SWiw3te5djgdYZ6k/oI2peVKVuRF4fn9tBb6dNqcmzU5L/qw\n" \
    "IFAGbHrQgLKm+a/sRxmPUDgH3KKHOVj4utWp+UhnMJbulHheb4mjUcAwhmahRWa6\n" \
    "VOujw5H5SNz/0egwLX0tdHA114gk957EWW67c4cX8jJGKLhD+rcdqsq08p8kDi1L\n" \
    "93FcXmn/6pUCyziKrlA4b9v7LWIbxcceVOF34GfID5yHI9Y/QCB/IIDEgEw+OyQm\n" \
    "jgSubJrIqg0CAwEAAaNCMEAwDwYDVR0TAQH/BAUwAwEB/zAOBgNVHQ8BAf8EBAMC\n" \
    "AYYwHQYDVR0OBBYEFIQYzIU07LwMlJQuCFmcx7IQTgoIMA0GCSqGSIb3DQEBCwUA\n" \
    "A4IBAQCY8jdaQZChGsV2USggNiMOruYou6r4lK5IpDB/G/wkjUu0yKGX9rbxenDI\n" \
    "U5PMCCjjmCXPI6T53iHTfIUJrU6adTrCC2qJeHZERxhlbI1Bjjt/msv0tadQ1wUs\n" \
    "N+gDS63pYaACbvXy8MWy7Vu33PqUXHeeE6V/Uq2V8viTO96LXFvKWlJbYK8U90vv\n" \
    "o/ufQJVtMVT8QtPHRh8jrdkPSHCa2XV4cdFyQzR1bldZwgJcJmApzyMZFo6IQ6XU\n" \
    "5MsI+yMRQ+hDKXJioaldXgjUkK642M4UwtBV8ob2xJNDd2ZhwLnoQdeXeGADbkpy\n" \
    "rqXRfboQnoZsG4q5WTP468SQvvG5\n"                                     \
    "-----END CERTIFICATE-----";
#endif

/* LwIP SMTP example */

/* Declare the result callback function */
static void lwip_smtp_result_example(void * arg, uint8_t smtp_result, uint16_t srv_err, err_t err);

/* Define the result callback function */
static void lwip_smtp_result_example (void * arg, uint8_t smtp_result, uint16_t srv_err, err_t err)

{
    FSP_PARAMETER_NOT_USED(arg);

    printf("Mail sent with results: %d, srv_err: %d, err: %d\n", smtp_result, srv_err, err);
}

void lwip_smtp_example () {
    struct netif netif;

    ip_addr_t ipaddr;
    ip_addr_t netmask;
    ip_addr_t gw;

    /* Initializing lwIP core. */
    lwip_init();

    /* Set ip address of the board. */
    IP4_ADDR(&ipaddr, 192, 168, 10, 4);
    IP4_ADDR(&netmask, 255, 255, 255, 0);
    IP4_ADDR(&gw, 192, 168, 10, 1);

    /* Initialize netif. Please pass rm_lwip_ether_init() function and the instance of rm_lwip_ether to netif_add(). */
    netif_add(&netif, &ipaddr, &netmask, &gw, &g_lwip_ether0_instance, rm_lwip_ether_init, netif_input);

    /* Set netif as default and enable. */
    netif_set_default(&netif);
    netif_set_up(&netif);
    netif_set_link_up(&netif);

#if LWIP_ALTCP && LWIP_ALTCP_TLS

    /* Create a TLS client configuration */
    struct altcp_tls_config * configuration =
        altcp_tls_create_config_client((const u8_t *) gs_ca_crt, sizeof(gs_ca_crt));

    /* Set TLS configuration */
    smtp_set_tls_config(configuration);
#endif

    /* Set the server address */
    smtp_set_server_addr(LWIP_SMTP_GW_ADDR);

    /* Set the server port */
    smtp_set_server_port(LWIP_SMTP_PORT);

    /* Set the authentication data */
    smtp_set_auth("YourUserName", "YourPassword");

    /* Send mail */
    smtp_send_mail("***@YourDomain.com",
                   "***@SomeOtherDomain.com",
                   "Subject",
                   "Email Body",
                   lwip_smtp_result_example,
                   NULL);

    /* Program main loop. */
    while (true)
    {
        sys_check_timeouts();
        R_BSP_SoftwareDelay(1, BSP_DELAY_UNITS_MILLISECONDS);
    }
}