NetBurner 3.5.6
PDF Version
SSL/TLS Client Certificate

SSL Client Certificate Example

Overview

This application demonstrates how to implement an SSL/TLS client with client certificate authentication using the NetBurner platform. The example shows how to establish secure connections to an SSL server that requires client certificates for authentication.

Program Description

The SSL Client Certificate Example demonstrates three key concepts:

  1. SSL Client Connections - How to establish SSL/TLS connections from a NetBurner device
  2. Client Certificate Loading - How to load and use client certificates compiled into the application
  3. Certificate-Based Authentication - How to authenticate with servers that require client certificates

How It Works

The application performs the following operations:

  1. Network Initialization - Initializes the network stack and waits for DHCP configuration
  2. SSL Setup - Initializes SSL and configures client certificate credentials
  3. Connection Loop - Repeatedly attempts to connect to the specified SSL server
  4. Status Reporting - Tracks and reports successful and failed connection attempts

Key Features

Connection Process

  • Connects to SSL server on port 4433
  • Uses embedded client certificate and private key for authentication
  • Sends connection statistics to both the server and debug console
  • Handles various SSL error conditions with detailed error reporting

Error Handling

The application provides detailed error reporting for common SSL failures:

  • SSL_ERROR_FAILED_NEGOTIATION - SSL handshake negotiation failed
  • SSL_ERROR_CERTIFICATE_UNKNOWN - Certificate not recognized
  • SSL_ERROR_CERTIFICATE_NAME_FAILED - Certificate name validation failed
  • SSL_ERROR_CERTIFICATE_VERIFY_FAILED - Certificate verification failed

File Structure

main.cpp # Main application logic
clientcert.cpp # Embedded client certificate data
clientkey.cpp # Embedded private key data

Configuration

Target Server

Modify the SSL_SERVER_IP definition in main.cpp to specify your target SSL server:

#define SSL_SERVER_IP "192.168.1.100" // Replace with your server IP

Certificates

The client certificate and private key are embedded as C arrays in the application:

  • Certificate: 672 bytes in PEM format
  • Private key: 310 bytes in PEM format (EC parameters and private key)

Important Distinctions

This example demonstrates client certificate authentication, which is different from standard certificate authority (CA) validation:

CA Certificate Checking

  • Client validates server certificate against known Certificate Authorities
  • Requires modification to predef.h to enable
  • Standard SSL/TLS client behavior

Client Certificate Authentication

  • Client sends its own certificate to the server for authentication
  • Server validates the client certificate
  • Provides mutual authentication (both parties verify each other)
  • This is what this example demonstrates

Usage

  1. Setup: Configure the target server IP address
  2. Compile: Build the application with the embedded certificates
  3. Deploy: Flash to NetBurner device
  4. Run: The application will wait for network initialization, then prompt for connection attempts
  5. Interact: Press any key to initiate connection attempts, press 'C' to retry after failures

Requirements

  • NetBurner development platform with SSL/TLS support
  • SSL server configured to request and validate client certificates
  • Network connectivity (DHCP recommended)

Output

The application provides real-time feedback including:

  • Connection attempt notifications
  • Success/failure statistics
  • Detailed error codes for troubleshooting
  • Performance timing information

Security Notes

  • Client certificates provide strong authentication but must be properly managed
  • Private keys should be protected and not exposed in production environments
  • Consider using secure storage mechanisms for production deployments
  • Ensure proper certificate lifecycle management (expiration, revocation, etc.)

Troubleshooting

Common issues and solutions:

  • Connection timeouts: Verify server IP and network connectivity
  • Certificate errors: Ensure server is configured to accept the client certificate
  • SSL negotiation failures: Check SSL/TLS version compatibility
  • Network issues: Verify DHCP configuration and routing