NetBurner 3.5.8
PDF Version
HTTPS GET Request

Example Path: examples/SSL/SslGetHttps

SSL HTTPS GET Example

Overview

This application demonstrates how to build an SSL/TLS client that retrieves web pages from HTTPS servers on the NetBurner platform. It resolves a hostname with the built-in DNS client, opens a secure connection on port 443 with SSL_connect(), sends an HTTP GET request, and prints the start of the server's response to the serial debug port.

Description

The SSL HTTPS GET Example is an interactive, serial-driven application that lets you:

  • Connect to HTTPS servers by hostname (or dotted-quad IP address)
  • Establish a secure SSL/TLS connection on port 443
  • Send an HTTP GET request and read the response
  • View the response data on the serial terminal

Key Features

  • DNS Resolution: Resolves hostnames to IP addresses with GetHostByName()
  • SSL/TLS Client: Opens an encrypted connection with SSL_connect()
  • Interactive Prompt: Reads the target hostname from the serial console
  • Error Decoding: Translates SSL_connect() failure codes into readable messages
  • Connect Retry: Automatically retries once if the first connection attempt fails

Certificate Verification

By default this example does not verify the server's certificate. The 4-argument form of SSL_connect() used here leaves its verifyPeer parameter at its default value of false, so the connection is encrypted but the server's identity is accepted without checking it against a Certificate Authority list. This keeps the example simple and lets it connect to any public HTTPS server.

To validate the server certificate instead, call SSL_connect() with verifyPeer = true and make a CA certificate list available to the client (see the SSL/TLS Client Verify Peer - Basic and SSL/TLS Client Certificate examples). With verification enabled, a connection to a server whose certificate cannot be validated will fail with one of the SSL_ERROR_CERTIFICATE_* codes listed below.

Usage

  1. Build and Deploy: Compile and load the application onto your NetBurner device
  2. Open a Terminal: Connect to the device's serial debug port (for example with MTTTY)
  3. Wait for Network: The device waits up to 5 seconds for a DHCP address at startup
  4. Enter a Hostname: At the prompt, type an HTTPS server name (for example www.example.com)
  5. View the Response: The first portion of the server's response is printed to the terminal

Example Session

Enter the destination HTTPS server name: www.example.com
Getting [www.example.com]
www.example.com = 172.66.147.243
We connected
N response = -1
Read 836 bytes
[HTTP/1.1 200 OK
Date: Sat, 06 Jun 2026 22:43:45 GMT
Content-Type: text/html
Transfer-Encoding: chunked
Connection: close
Server: cloudflare
...
<!doctype html><html lang="en"><head><title>Example Domain</title>...]
close
int close(int fd)
Close the specified file descriptor and free the associated resources.

The N response = -1 line is normal: it is printed once when the server closes the connection and SSLReadWithTimeout() returns a negative value, which ends the read loop.

Application Flow

  1. Initialization: Initialize the network stack and wait for a DHCP address
  2. User Input: Prompt for an HTTPS server hostname
  3. DNS Lookup: Resolve the hostname to an IP address
  4. SSL Connection: Open a secure connection on port 443 (retried once on failure)
  5. HTTP Request: Send a GET request to the server
  6. Response Handling: Read the response and print the first portion to the terminal
  7. Repeat: Close the connection and prompt for the next hostname

Error Handling

SSL_connect() returns a negative error code on failure. The example decodes the most common SSL-specific codes:

  • SSL_ERROR_FAILED_NEGOTIATION: SSL/TLS handshake failed
  • SSL_ERROR_CERTIFICATE_UNKNOWN: Server certificate not recognized
  • SSL_ERROR_CERTIFICATE_NAME_FAILED: Certificate common name did not match
  • SSL_ERROR_CERTIFICATE_VERIFY_FAILED: Certificate could not be verified against the CA list

A DNS lookup failure is reported separately, prompting you to check the DNS server configuration.

Technical Details

Buffers

  • Receive Buffer: 20 KB for the response data
  • Display Limit: Only the first 512 bytes are printed to the terminal
  • Hostname Buffer: 255 characters maximum

Network Configuration

  • Protocol: HTTPS over SSL/TLS
  • Port: 443 (standard HTTPS port)
  • Connect Timeout: 400 ticks per SSL_connect() attempt

Dependencies

Limitations

  • Maximum response size captured: 20 KB
  • Single-threaded, one request at a time
  • Basic GET requests only; no HTTP authentication
  • Certificate verification is disabled by default (see above)