NetBurner 3.5.6
PDF Version
HTTPS Upload Cert

NetBurner SSL Certificate Upload Application

Overview

This NetBurner embedded application provides a comprehensive SSL/TLS certificate management system with web-based certificate upload functionality. The application enables users to replace default compiled-in certificates with their own SSL/TLS certificates and private keys through a secure web interface, supporting modern HTTPS connectivity for embedded devices.

Key Features

Certificate Management

  • Web-based Upload Interface: User-friendly web forms for uploading SSL/TLS certificates and private keys
  • Multiple Certificate Sources: Support for library default, compiled-in default, and user-installed certificates
  • Certificate Validation: Automatic validation of certificate and private key pairs before installation
  • PEM Format Support: Handles Privacy-Enhanced Mail (PEM) encoded certificates and keys
  • Certificate Authority Management: Support for multiple CA certificates for client verification

File System Integration

  • EFFS-STD File System: Uses NetBurner's Enhanced Flash File System Standard for persistent storage
  • On-chip Flash Storage: Certificates stored in protected flash memory
  • Atomic Updates: Safe certificate installation with automatic rollback on failure
  • File Size Limits: 3KB maximum for certificates, 4KB maximum for private keys

Network and Security

  • Dual Stack Support: Full IPv4 and IPv6 HTTPS connectivity
  • NetBIOS Integration: Automatic device name publishing
  • NTP Time Synchronization: Required for proper certificate validation
  • Debug Console: Serial interface for system monitoring and configuration

Supported Platforms

  • MOD5441X: 32MB parallel flash with 128KB sectors
  • NANO54415: 8MB SPI flash with 4KB sectors
  • SB800EX: 8MB SPI flash with 4KB sectors
  • MODM7AE70: 2MB parallel flash with 8KB sectors
  • SBE70LC: 2MB parallel flash with 8KB sectors

Application Architecture

Core Components

Main Application (main.cpp)

The main application handles system initialization and provides the primary user interface:

  • System Initialization: Network configuration, SSL service startup, and file system mounting
  • NTP Time Sync: Automatic time synchronization using configurable timezone (default PST/PDT)
  • Debug Interface: Serial console with commands for system management
  • NetBIOS Configuration: Automatic device name publishing based on MAC address
  • Certificate Scanning: Automatic CA certificate discovery and validation

Certificate Management (certificatekey.cpp)

Handles all certificate-related operations:

  • Certificate and key file upload processing
  • Validation of certificate/key pairs
  • CA certificate management (up to 20 certificates)
  • Web interface functions for certificate display and status

SSL User Interface (ssluser.cpp)

Provides certificate retrieval and management functions:

  • Default certificate management
  • PEM format handling and conversion
  • Certificate source switching between library default, compiled default, and user-installed

File System (effsStdFlashDrv.cpp, FileSystemUtils.cpp)

Platform-specific flash drivers and utilities:

  • Hardware abstraction for different flash types (parallel vs SPI)
  • File system operations (read, write, delete, format)
  • Error handling and reporting

File System Structure

/
cert.crt # Active SSL certificate (max 3KB)
cert.key # Corresponding private key (max 4KB)
CACert0.crt # Certificate Authority cert #0
CACert1.crt # Certificate Authority cert #1
... # Additional CA certs (up to CACert19.crt)

Web Interface

The main configuration page (https.html) provides:

  • Certificate Status Display: Shows current certificate source (Default vs User Installed)
  • Upload Forms: Separate forms for certificate and key file uploads
  • Certificate Information: View current certificate details and validity
  • Factory Reset: Option to restore default certificates
  • Network Information: Display of HTTP and HTTPS access addresses

Debug Console Commands

Available via serial interface:

  • 0 - Turn off debug messages
  • 1 - Turn on debug messages
  • D - Reset to factory default parameters
  • F - Show file system information and statistics
  • G - Format file system (WARNING: Erases all data)
  • N - Display current NV settings
  • T - Display current system time
  • B - Force system reboot

Certificate Requirements

Supported Formats

  • Encoding: PEM (Privacy-Enhanced Mail) format only
  • Key Types: RSA, DSA, and ECDSA keys supported
  • Certificate Chain: Multiple CA certificates supported for client verification

Size Limitations

  • Certificate Files: Maximum 3KB in PEM format
  • Private Key Files: Maximum 4KB in PEM format
  • CA Certificates: Maximum 3KB each, up to 20 total

Configuration

Network Settings

  • Device Naming: Automatic device name based on MAC address
  • DHCP Support: Automatic IP address assignment
  • Dual Stack: IPv4/IPv6 support for maximum compatibility

SSL/TLS Settings

  • Certificate Sources: Configurable between library default, compiled default, and user-installed
  • Client Verification: Optional client certificate verification using CA certificates
  • Peer Verification: Configurable peer certificate validation

Security Features

Certificate Validation

  • Automatic verification of certificate and private key pairs
  • Certificate format and structure validation
  • Certificate chain verification for CA certificates
  • Expiration date checking (requires accurate system time)

Secure Storage

  • Protected flash memory storage for certificates and keys
  • Atomic update operations prevent corruption during uploads
  • Automatic rollback to default certificates on validation failure
  • Memory protection and cleanup for sensitive data

Getting Started

Initial Setup

  1. Build and Deploy: Compile for your target NetBurner platform
  2. Network Connection: Connect device to network (DHCP recommended)
  3. Initial Access: Browse to device IP address via HTTP
  4. Time Synchronization: Verify NTP time sync (required for certificate validation)

Certificate Installation

  1. Access Web Interface: Navigate to https.html page
  2. Upload Certificate: Use the certificate upload form (PEM format, max 3KB)
  3. Upload Private Key: Use the key upload form (PEM format, max 4KB)
  4. Verification: System automatically validates certificate/key pair
  5. HTTPS Access: Test secure connectivity using HTTPS

CA Certificate Management

  1. Upload CA Certificates: Use CA certificate upload form
  2. Client Verification: Enable client certificate verification if needed
  3. Multiple CAs: Upload additional CA certificates as required (max 20)

Troubleshooting

Common Issues

Certificate Upload Problems

  • File Size Errors: Verify certificate < 3KB and key < 4KB in PEM format
  • Certificate Validation Failures: Ensure certificate and key are properly paired and in valid PEM format
  • Upload Timeouts: Large files may timeout; check network connectivity and file size limits
  • Invalid File Format: Only PEM-encoded certificates and keys are supported

Time Synchronization Issues

  • NTP Failures: Check network connectivity, DNS resolution, and firewall settings
  • Certificate Validation Errors: Accurate system time required for certificate expiry checking
  • Timezone Problems: Use tzsetchar() for proper timezone configuration

Browser Connection Issues

  • Self-Signed Certificate Warnings: Install CA certificate in browser or use proper CA-signed certificates
  • HTTPS Connection Failures: Verify certificate installation and SSL service startup
  • IPv6 Connectivity: Ensure proper IPv6 configuration if using IPv6 addresses

File System Problems

  • Flash Corruption: May require file system format and factory reset
  • Insufficient Space: Check available flash memory before certificate upload
  • Mount Failures: Verify flash hardware and driver configuration

Recovery Options

Factory Reset Procedures

  • Debug Command: Use serial command 'D' to reset to factory defaults
  • Web Interface: Use factory reset option on configuration page
  • NV Settings Reset: Clears user certificates and restores default configuration
  • File System Impact: May require file system format depending on corruption level

File System Recovery

  • Format Command: Use debug command 'G' to format file system (WARNING: Erases all data)
  • Automatic Recovery: System detects corruption and attempts automatic recovery
  • Manual Recovery: Delete specific certificate files via FTP or debug interface

Certificate Recovery

  • Default Fallback: System automatically uses compiled-in certificates on errors
  • Library Defaults: Use SslUserSetDefault() to restore NetBurner default certificates
  • Backup Restoration: Restore certificates from backup files if available

Debug and Monitoring

Serial Console Diagnostics

  • Debug Level Control: Commands '0' and '1' to control debug message verbosity
  • File System Status: Command 'F' shows detailed file system information
  • Network Status: Command 'N' displays current NV settings
  • Time Verification: Command 'T' shows current system time

Log Analysis

  • SSL Errors: Look for certificate validation failures in debug output
  • File System Errors: Check for flash read/write/erase failures
  • Network Issues: Monitor for DHCP, DNS, or NTP synchronization problems
  • Memory Issues: Watch for allocation failures during file uploads

Performance Monitoring

  • Flash Wear: Monitor bad block count and wear leveling statistics
  • Memory Usage: Check heap usage during certificate operations
  • Network Performance: Monitor connection establishment times for HTTPS
  • Certificate Chain Length: Verify CA certificate chain length for client verification

Platform-Specific Issues

MOD5441X Parallel Flash

  • Address Conflicts: Verify COMPCODEFLAGS settings in makefile
  • Flash Programming: Check parallel flash programming voltage levels
  • Sector Alignment: Ensure proper 128KB sector boundary alignment

NANO54415/SB800EX SPI Flash

  • SPI Interface: Verify SPI clock frequency and signal integrity
  • RAM Mirror: Monitor RAM usage for file system mirror
  • Write Performance: SPI flash writes slower than parallel flash

MODM7AE70/SBE70LC On-Chip Flash

  • Background Erase: Disable background erase feature in NBEclipse
  • Fixed Address: Enable "Locate Application at Fixed Address in Flash"
  • Library Linking: Ensure StdFFile.a library is properly linked

Development Notes

Memory Management

  • Dynamic memory allocation for file uploads with automatic cleanup
  • Buffer size limits prevent memory exhaustion
  • Careful handling of certificate data to prevent memory leaks

Error Handling

  • Comprehensive error checking for all file operations
  • Graceful degradation on certificate validation failures
  • User feedback through both web interface and debug console
  • Automatic recovery mechanisms for corrupted installations

Browser Compatibility

Modern browsers require valid certificates and may reject self-signed certificates. For development:

  • Install the Certificate Authority certificate in the browser
  • Use NetBurner SDK certificate generation scripts (makeca, makeserver)
  • Consider using proper CA-signed certificates for production deployment

Version Information

  • Application Version: 01.00.0000
  • Supported OS: NetBurner RTOS 3.x
  • File System: EFFS-STD (Enhanced Flash File System Standard)
  • SSL/TLS: NetBurner SSL library with OpenSSL compatibility