NetBurner 3.5.6
PDF Version
SSL/TLS Client Verify Peer - Basic

SSL/TLS Client Verify Peer - Basic

Overview

This application demonstrates how to implement SSL/TLS client connections with peer certificate verification using embedded CA (Certificate Authority) lists. The program establishes secure connections to HTTPS servers and validates their certificates against a trusted root certificate.

Features

  • SSL/TLS Client Connection: Establishes secure connections to HTTPS servers on port 443
  • Certificate Verification: Validates server certificates using embedded CA certificates
  • Interactive Domain Testing: Allows users to test connections to any domain
  • NTP Time Synchronization: Automatically synchronizes system time for accurate certificate validation
  • Comprehensive Error Handling: Provides detailed SSL error reporting

Application Components

Core Files

  • main.cpp: Main application logic with SSL connection handling
  • caList.h: Contains embedded DigiCert High Assurance EV Root CA certificate for GitHub
  • ServerCert.cpp: Auto-generated server certificate data (binary format)
  • ServerKey.cpp: Auto-generated EC private key data (binary format)

Key Functionality

SSL Connection Process

  1. Prompts user for domain name input
  2. Resolves domain to IP address using DNS
  3. Establishes SSL connection with certificate verification enabled
  4. Sends basic HTTP GET request
  5. Reads and displays server response
  6. Provides detailed error information on connection failures

Time Synchronization

  • Uses NTP (Network Time Protocol) to set system time
  • Connects to pool.ntp.org for time synchronization
  • Ensures accurate certificate validity period checking

Usage Instructions

Running the Application

  1. Start the Application: The program initializes network connections and synchronizes time
  2. Access Debug Menu: Press any key to display available commands
  3. Test SSL Connection: Press 'C' to initiate an SSL connection test
  4. Enter Domain: Type the domain name you want to test (e.g., github.com, google.com)
  5. View Results: The application will display connection status and any errors

Sample Session

Commands :
C: Attempt SSL Connection
[Press 'C']
Enter the domain you would like to connect to: github.com
Attempting to connect to: github.com:443 (140.82.114.4)
Good SSL connection
Read 1024 bytes
Read 512 bytes
Connection closed with response: 0
Read 1536 total bytes
connect
int connect(const IPADDR &ipAddress, uint16_t remotePort, uint32_t timeout)
Establish a TCP connection to a remote host.
Definition tcp.h:1547

Certificate Verification

The application uses a hardcoded DigiCert High Assurance EV Root CA certificate to verify connections. This certificate is specifically configured for GitHub connections but can validate any server using certificates signed by this CA.

Supported Error Types

  • SSL_ERROR_FAILED_NEGOTIATION: SSL handshake failed
  • SSL_ERROR_CERTIFICATE_UNKNOWN: Certificate not recognized
  • SSL_ERROR_CERTIFICATE_NAME_FAILED: Certificate name mismatch
  • SSL_ERROR_CERTIFICATE_VERIFY_FAILED: Certificate validation failed

Technical Details

Dependencies

  • NBRTOS: Real-time operating system
  • DNS: Domain name resolution
  • TCP: Network communication
  • SSL/TLS: Secure socket layer implementation
  • NTP: Network time protocol

Memory Usage

  • RX Buffer: 20KB buffer for reading server responses
  • Certificate Storage: Embedded certificates stored in program memory
  • Domain Buffer: 255 character buffer for domain name input

Network Configuration

  • SSL Port: 443 (HTTPS)
  • Connection Timeout: 60 seconds
  • Read Timeout: 5 seconds per operation
  • NTP Timeout: 10 seconds for time synchronization

Security Considerations

Certificate Validation

  • Peer verification is enabled for all connections
  • Uses embedded root CA certificates for trust chain validation
  • Validates certificate names against requested domains
  • Checks certificate validity periods (requires accurate system time)

Limitations

  • Only includes DigiCert root CA certificate
  • Cannot verify certificates from other CAs without modification
  • No certificate revocation checking (CRL/OCSP)

Development Notes

Customization

To add support for additional CAs:

  1. Obtain the root CA certificate in PEM format
  2. Add certificate data to caList.h
  3. Update certificate length and data arrays
  4. Recompile the application

Error Handling

The application provides comprehensive error reporting for:

  • DNS resolution failures
  • Network connection issues
  • SSL handshake problems
  • Certificate validation errors

Example Use Cases

  • Security Testing: Verify SSL configuration of web servers
  • Certificate Validation: Test certificate chain validity
  • Network Diagnostics: Debug SSL connection issues
  • Educational Purposes: Learn SSL/TLS implementation details

Build Requirements

  • NBRTOS development environment
  • Network-enabled target hardware
  • Internet connectivity for DNS and NTP
  • Sufficient memory for SSL operations and certificate storage