lwip_https_client_freertos#
Overview#
The lwip_https_client_freertos demo application demonstrates downloading of a web page over SSL connection using HTTP GET method.
Upon start, the example obtains IP address and DNS information from DHCP, resolves IP address of a server and establishes a secure connection with it. Then it downloads and displays the web resource and closes the secure connection.
Four major third party components are used to achieve the functionality:
lwIP TCP/IP stack for TCP/IP connectivity,
mbedTLS for securing the connection,
coreHTTP library for HTTP protocol,
FreeRTOS for operating system.
The resource to download is defined by EXAMPLE_HOST, EXAMPLE_PORT and EXAMPLE_PATH macros. EXAMPLE_MAX_REQUEST_LENGTH and EXAMPLE_MAX_RESPONSE_LENGTH might need to be increased if downloading other resource.
List of certification authority certificates used for validation of the server’s certificate are stored in app_ca_bundle.c in g_app_ca_bundle.
On some hardware platforms, this example overrides the list of SSL cipher suites offered by the client to the server. It is done by defining the list in MBEDTLS_SSL_CIPHERSUITES macro. This list needs to have common items with the list of cipher suites offered by the server to the client, otherwise the two will not be able to communicate. The list of server’s ciphersuites can be examined for example by nmap utility:
$ nmap --script ssl-enum-ciphers -p 443 httpbin.org
Starting Nmap 7.80 ( https://nmap.org ) at 2024-12-04 18:20 CET
Nmap scan report for httpbin.org (3.223.200.11)
Host is up (0.11s latency).
Other addresses for httpbin.org (not scanned): 34.224.200.202
rDNS record for 3.223.200.11: ec2-3-223-200-11.compute-1.amazonaws.com
PORT STATE SERVICE
443/tcp open https
| ssl-enum-ciphers:
| TLSv1.0:
| ciphers:
| TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA (secp256r1) - A
| TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA (secp256r1) - A
| TLS_RSA_WITH_AES_128_CBC_SHA (rsa 2048) - A
| TLS_RSA_WITH_AES_256_CBC_SHA (rsa 2048) - A
| TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (secp256r1) - A
| TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 (secp256r1) - A
| TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (secp256r1) - A
| TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 (secp256r1) - A
| TLS_RSA_WITH_AES_128_GCM_SHA256 (rsa 2048) - A
| TLS_RSA_WITH_AES_128_CBC_SHA256 (rsa 2048) - A
| TLS_RSA_WITH_AES_256_GCM_SHA384 (rsa 2048) - A
| TLS_RSA_WITH_AES_256_CBC_SHA256 (rsa 2048) - A
| compressors:
| NULL
| cipher preference: server
| TLSv1.1:
| ciphers:
| TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA (secp256r1) - A
| TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA (secp256r1) - A
| TLS_RSA_WITH_AES_128_CBC_SHA (rsa 2048) - A
| TLS_RSA_WITH_AES_256_CBC_SHA (rsa 2048) - A
| TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (secp256r1) - A
| TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 (secp256r1) - A
| TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (secp256r1) - A
| TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 (secp256r1) - A
| TLS_RSA_WITH_AES_128_GCM_SHA256 (rsa 2048) - A
| TLS_RSA_WITH_AES_128_CBC_SHA256 (rsa 2048) - A
| TLS_RSA_WITH_AES_256_GCM_SHA384 (rsa 2048) - A
| TLS_RSA_WITH_AES_256_CBC_SHA256 (rsa 2048) - A
| compressors:
| NULL
| cipher preference: server
| TLSv1.2:
| ciphers:
| TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (secp256r1) - A
| TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 (secp256r1) - A
| TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA (secp256r1) - A
| TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (secp256r1) - A
| TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 (secp256r1) - A
| TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA (secp256r1) - A
| TLS_RSA_WITH_AES_128_GCM_SHA256 (rsa 2048) - A
| TLS_RSA_WITH_AES_128_CBC_SHA256 (rsa 2048) - A
| TLS_RSA_WITH_AES_128_CBC_SHA (rsa 2048) - A
| TLS_RSA_WITH_AES_256_GCM_SHA384 (rsa 2048) - A
| TLS_RSA_WITH_AES_256_CBC_SHA256 (rsa 2048) - A
| TLS_RSA_WITH_AES_256_CBC_SHA (rsa 2048) - A
| compressors:
| NULL
| cipher preference: server
|_ least strength: A
Nmap done: 1 IP address (1 host up) scanned in 8.88 seconds
If the server is public on internet, the online service such as https://www.ssllabs.com/ssltest/index.html can be used to get the information like supported ciphersuites, certification paths and protocol details.
The output of mbedTLS debug messages to the console can be enabled by the following:
define MBEDTLS_DEBUG_C macro in mbedTLS configuration file or on a project level,
redefine MBEDTLS_DEBUG_THRESHOLD macro to a value between 0 (no output) to 4 (verbose output),
optinally define MBEDTLS_SSL_DEBUG_ALL macro in mbedTLS configuration file or on a project level,
and rebuild the project.
Prepare the Demo#
Connect a USB cable between the PC host and the OpenSDA(or USB to Serial) USB port on the target board.
Open a serial terminal on PC for OpenSDA serial(or USB to Serial) device with these settings:
115200 baud rate
8 data bits
No parity
One stop bit
No flow control
Insert the Ethernet Cable into the target board’s RJ45 port and connect it to a router (which must be connect to the internet).
Download the program to the target board.
Either press the reset button on your board or launch the debugger in your IDE to begin running the demo.
Running the demo#
When the demo runs successfully, the terminal will display similar information:
*********************************************************** lwIP HTTPS client example *********************************************************** Initializing PHY... Getting IPv4 address from DHCP... IPv4 Address : 192.168.10.2 IPv4 Subnet mask : 255.255.255.0 IPv4 Gateway : 192.168.10.1 IPv6 Address0 : - IPv6 Address1 : - IPv6 Address2 : - DNS Server0 : 192.168.10.1 DNS Server1 : 192.168.10.1 *********************************************************** Resolving host httpbin.org... Connecting to 3.223.200.11:443... Performing SSL/TLS handshake... SSL: Protocol: TLSv1.2, cipher suite: TLS-ECDHE-RSA-WITH-AES-128-GCM-SHA256 SSL: Record expansion: 29 SSL: Peer certificate information: >>> cert. version : 3 >>> serial number : 0B:D1:35:8F:80:E2:54:A2:DD:CF:A2:09:08:77:03:05 >>> issuer name : C=US, O=Amazon, CN=Amazon RSA 2048 M02 >>> subject name : CN=httpbin.org >>> issued on : 2024-08-20 00:00:00 >>> expires on : 2025-09-17 23:59:59 >>> signed using : RSA with SHA-256 >>> RSA key size : 2048 bits >>> basic constraints : CA=false >>> subject alt name : >>> dNSName : httpbin.org >>> dNSName : *.httpbin.org >>> key usage : Digital Signature, Key Encipherment >>> ext key usage : TLS Web Server Authentication, TLS Web Client Authentication >>> certificate policies : ??? NetworkCtx: Connection established. GET /get IPv6 address update, valid addresses: IPv6 Address0 : FE80::5627:8DFF:FEED:B45E IPv6 Address1 : - IPv6 Address2 : - Response code: 200 Response body: { "args": {}, "headers": { "Host": "httpbin.org", "User-Agent": "lwip_https_client_example", "X-Amzn-Trace-Id": "Root=1-674de416-2c41247879c1582c304aef20" }, "origin": "46.135.36.251", "url": "https://httpbin.org/get" } NetworkCtx: Connection closed.
Supported Boards#
MIMXRT1060-EVKB
Hardware requirements
Mini/micro USB cable
RJ45 Network cable
MIMXRT1060-EVKB board
Router or other device with DHCP server capability and internet connectivity.
Personal Computer
Board settings
No special settings are required.
MIMXRT1170-EVKB
Hardware requirements
Mini/micro USB cable
Network cable RJ45 standard
MIMXRT1170-EVKB board
Router or other device with DHCP server capability and internet connectivity
Personal Computer
Board settings
This example uses 1G port(J4) as default. If want to test 100M port(J3), please set the macro BOARD_NETWORK_USE_100M_ENET_PORT to 1.
MIMXRT1060-EVKC
Hardware requirements
Mini/micro USB cable
RJ45 Network cable
MIMXRT1060-EVKC board
Router or other device with DHCP server capability and internet connectivity.
Personal Computer
Board settings
No special settings are required.
MIMXRT1040-EVK
Hardware requirements
Mini/micro USB cable
RJ45 Network cable
MIMXRT1040-EVK board
Router or other device with DHCP server capability and internet connectivity.
Personal Computer
Board settings
No special settings are required.
EVK-MIMXRT1064
Hardware requirements
Mini/micro USB cable
RJ45 Network cable
EVK-MIMXRT1064 board
Router or other device with DHCP server capability and internet connectivity.
Personal Computer
Board settings
No special settings are required.
MIMXRT1160-EVK
Hardware requirements
Mini/micro USB cable
Network cable RJ45 standard
MIMXRT1160-EVK board
Router or other device with DHCP server capability and internet connectivity.
Personal Computer
Board settings
This example uses 1G port(J4) as default. If want to test 100M port(J3), please set the macro BOARD_NETWORK_USE_100M_ENET_PORT to 1.
MIMXRT1180-EVK
Hardware requirements
Mini/micro USB cable
Network cable RJ45 standard
MIMXRT1180-EVK board
Router or other device with DHCP server capability and internet connectivity.
Personal Computer
Board settings
This example uses Ethernet RJ45 port J32.
FRDM-IMXRT1186
Hardware requirements
Type-C USB cable
Network cable RJ45 standard
FRDM-IMXRT1186 board
Router or other device with DHCP server capability and internet connectivity.
Personal Computer
Board settings
Short jumpers J12 (1-2) and J13 (2-3) and connect network cable to J56A.
FRDM-MCXA577
Hardware requirements
Type-C USB cable
RJ45 Network cable (for 100BASE-TX mode)
10BASE-T1S network adapter and cable (optional for 10BASE-T1S mode)
FRDM-MCXA577 board
Personal Computer
Board settings
Short position 2-3 on J29.
Use with 10BASE-T1S Ethernet
The example uses 100BASE-TX Ethernet over RJ45 by default. If you want to use the internal 10BASE-T1S digital PHY, redefine BOARD_NETWORK_USE_TENBASET_PHY from board.h to 1 and rebuild. Connect to a PC with a 10BASE-T1S network adapter instead of RJ45 and enable PLCA on a PC with the following parameters: - node ID: 0 (PLCA coordinator) - node count: 8 - TO timer: 32 BT - burst count: 0 - burst timer: 128 BT
FRDM-MCXN947
Hardware requirements
Type-C USB cable
RJ45 Network cable
FRDM-MCXN947 board
Personal Computer
Board settings
Connect JP13 2-3 pin. Populate R274 to sync reference clock.
FRDM-MCXN947T
Hardware requirements
Type-C USB cable
RJ45 Network cable
FRDM-MCXN947T board
Personal Computer
Board settings
Connect JP13 2-3 pin. Populate R274 to sync reference clock.
FRDM-MCXE247
Hardware requirements
USB-C cable
Network cable RJ45 standard
FRDM-MCXE247 board
Router or other device with DHCP server capability and internet connectivity.
Personal Computer
Board settings
Before running this demo, please study the flash partitioning required by the ELA_CSEC module. Correct partitioning of the flash is also showcased in the ela_csec driver example. This partitioning step is NOT done by the lwIP examples which use mbedTLS and must be completed before running these examples in order to utilize the underlying ELA_CSEC acceleration.