HTTPS GET Request

SSL HTTPS GET Example

Overview

This application demonstrates how to create an SSL/TLS client that can retrieve web pages from HTTPS servers using the NetBurner RTOS platform. The example shows basic secure HTTP communication over SSL/TLS connections.

Description

The SSL HTTPS GET Example is a command-line application that allows users to:

• Connect to HTTPS servers by hostname
• Establish secure SSL/TLS connections on port 443
• Send HTTP GET requests to retrieve web page content
• Display the response data in a terminal interface

Key Features

• DNS Resolution: Resolves hostnames to IP addresses using the built-in DNS client
• SSL/TLS Support: Establishes secure connections with certificate verification
• Interactive Interface: Command-line prompt for entering server hostnames
• Error Handling: Comprehensive error reporting for SSL connection failures
• Network Diagnostics: Optional system diagnostics for debugging

Prerequisites

Important Certificate Requirements:**

You must either:

1. Include a CA (Certificate Authority) certificate list in your project, OR
2. Recompile the cryptolib with NB_SSL_CLIENT_CERTIFICATE_CHECKING_ENABLED defined in sslclient.cpp

Without proper certificate configuration, SSL connections may fail with certificate verification errors.

Usage

1. Build and Deploy: Compile and deploy the application to your NetBurner device
2. Run Terminal: Start the MTTTY serial terminal application
3. Network Setup: Ensure the device has obtained a DHCP address (5-second timeout)
4. Enter Hostname: When prompted, enter an HTTPS server name (e.g., www.google.com)
5. View Results: The application will display the retrieved web page content

Example Session

Enter the destination HTTPS server name: www.google.com
 
Getting [www.google.com]
 
www.google.com = 172.217.164.100
 
We connected
Read 1024 bytes
[HTTP/1.1 200 OK
Content-Type: text/html
...]

Application Flow

1. Initialization: Network stack initialization and DHCP address acquisition
2. User Input: Prompts for HTTPS server hostname
3. DNS Lookup: Resolves hostname to IP address
4. SSL Connection: Establishes secure connection on port 443
5. HTTP Request: Sends GET / request to the server
6. Response Handling: Reads and displays up to 20KB of response data
7. Cleanup: Closes connection and repeats for next request

Error Handling

The application provides detailed error messages for common SSL connection failures:

• SSL_ERROR_FAILED_NEGOTIATION: SSL handshake failed
• SSL_ERROR_CERTIFICATE_UNKNOWN: Server certificate not recognized
• SSL_ERROR_CERTIFICATE_NAME_FAILED: Certificate hostname mismatch
• SSL_ERROR_CERTIFICATE_VERIFY_FAILED: Certificate verification failed
• DNS resolution failures

Technical Details

Buffer Specifications

• Receive Buffer: 20KB capacity for response data
• Display Limit: First 512 bytes shown in terminal output
• Hostname Buffer: 255 character maximum length

Network Configuration

• Protocol: HTTPS over SSL/TLS
• Port: 443 (standard HTTPS port)
• Timeout: 400 ticks for SSL connection attempts
• Retry Logic: Automatic retry on initial connection failure

Dependencies

• NetBurner RTOS
• SSL/TLS crypto library
• DNS resolution system
• Network I/O subsystem

Debugging

The application includes optional network debugging capabilities when compiled with the _DEBUG flag. System diagnostics are enabled by default but should be removed for production deployments.

Limitations

• Maximum response size: 20KB
• Single-threaded operation
• Basic HTTP GET requests only
• No support for HTTP authentication
• Limited certificate validation options