NetBurner 3.5.6
PDF Version
On-board Cert Generation - Simple

On-board Certificate Generation - Simple

A NetBurner embedded application that demonstrates automatic SSL/TLS certificate generation and secure web server functionality.

Overview

This application showcases NetBurner's capability to automatically generate SSL certificates on embedded devices, enabling both HTTP and HTTPS web interfaces. The application sets up a secure web server with automatic certificate creation, time synchronization, and provides multiple access methods for device configuration.

This example shows how to enable auto-generation of self-signed certificates. The certificate will enable secure communication to the system configuration web server and the HTTPS web server of the application. On-board generation of certificates are an alternative to creating your own self-signed certificates and uploading them to your NetBurner device. This simple example should cover most use cases. Please refer to the other examples for additional functionality.

Auto-generated certificates will operate as follows:

  • If enabled and no certificate exists, a certificate will be created on first call to SSL_accept() or SslInitServer().
  • The Common Name (CN) will be the IP address of the device. Alternate names are also supported.
  • The application must ensure it has the correct system time, otherwise the certificate dates will be invalid.
  • Calling the function EnableOnboardCertificateCreation() enables certificate generation.
  • If ENABLE_AUTOCERT_REGEN is defined in predef.h, the certificate will update when it expires, creating a new 1 year certificate. Generation will occur on next SSL/TLS access.
  • If ENABLE_AUTO_CERT_REGEN is defined in predef.h, AUTO_CERT_GEN_CHECK will dictate how frequently a certificate is checked for expiration. The default value is one minute.
  • The certificate will update if the IP address changes to handle environments such as DHCP address assignments.

If the system time is incorrect, the certificate will be invalid.

Additional Examples:

Examples of a HTTPS server with a compiled-in certificate:

  • <NNDK install>\examples\ssl\sslserver
  • <NNDK install>\examples\ssl\SslWebDemo

Examples of uploading a certificate/key pair manually:

  • <NNDK install>\examples\ssl\HttpsDualCert
  • <NNDK install>\examples\ssl\HttpsUploadCert

Example of handling additional timezones

  • <NNDK install>\examples\TimeFunctions

Features

  • Automatic Certificate Generation: Creates SSL certificates on-board without manual intervention
  • Dual Protocol Support: Serves both HTTP (port 80) and HTTPS (port 443) simultaneously
  • Time Synchronization: Uses NTP for accurate time setting (required for certificate validity)
  • Timezone Support: Configurable timezone with automatic daylight savings calculation
  • System Diagnostics: Built-in diagnostic capabilities for development and troubleshooting
  • Multiple Access Methods: Provides various ways to access the device via web interfaces

Hardware Requirements

  • NetBurner embedded device with network connectivity
  • Active network connection for NTP time synchronization
  • Internet access (optional, for discover.netburner.com service)

Software Dependencies

This application uses the NetBurner NNDK (NetBurner Network Development Kit) and requires the following libraries:

Configuration

Time Zone Setup

The application defaults to Pacific Standard Time (PST). To change the timezone, modify the parameter in main.cpp:

setSystemTime("PST"); // Change "PST" to your desired timezone
Note
Refer to TimeFunctions example for timezone handling

Supported timezone abbreviations include: PST, MST, CST, EST, and others defined in the NetBurner timezone database.

Certificate Configuration

Certificate generation is automatically enabled via:

EnableOnboardCertificateCreation();
EnableOnboardCertificateCreation
void EnableOnboardCertificateCreation(CertGenReturnCode(*createCertFunc)(CertGenData &cGenData)=SSL_CreateNewSelfSignedCert)
Enables the ability for the module to automatically generate self-signed certificates for use in SSL/...

Server Configuration

The secure configuration server is enabled without forcing TLS mode:

EnableSecureConfigServer(false);
EnableSecureConfigServer
void EnableSecureConfigServer(bool bSec_Only)
Enable the minimal http config server to operate over TLS.

Access Methods

Once running, the device provides several access points:

Web Interfaces

  • HTTP Application: http://[device-ip]
  • HTTPS Application: https://[device-ip]
  • HTTP System Config: http://[device-ip]:20034
  • HTTPS System Config: https://[device-ip]:20034

Discovery Service

Time Synchronization

The application requires accurate time for certificate generation and validation:

  1. NTP Synchronization (Primary): Automatically attempts to sync with NTP pool servers
  2. Manual Entry (Fallback): If NTP fails, prompts for manual time entry via serial console

Manual Time Entry

If NTP synchronization fails, the application will prompt for manual time entry through the serial debug port. You'll be asked to provide:

  • Year (YYYY format)
  • Month (1-12)
  • Day of month (1-31)
  • Hour (0-23)
  • Minute (0-59)
  • Seconds (0-59)
  • GMT or Local time preference

Usage

  1. Build and Deploy: Compile using NetBurner development tools and deploy to target hardware
  2. Network Connection: Ensure device has active network connectivity
  3. Monitor Serial Output: Connect to serial debug port to monitor startup and get IP address
  4. Access Web Interface: Use any of the provided URLs to access the device
  5. Certificate Verification: HTTPS connections will use the automatically generated certificate

Serial Interface

The application provides an interactive serial interface:

  • Displays IP address and access links on startup
  • Shows time synchronization status
  • Press any key to redisplay connection information
  • Provides manual time entry interface if needed

Development Notes

  • System diagnostics are enabled by default (EnableSystemDiagnostics()) - consider removing for production builds
  • The application waits up to 5 seconds for network connectivity before proceeding
  • Certificate generation happens automatically during startup
  • Time synchronization is critical for SSL certificate validity

Troubleshooting

Common Issues

  1. Certificate Warnings: Browsers may show security warnings for self-signed certificates - this is normal behavior
  2. NTP Sync Failure: Check network connectivity and firewall settings if NTP synchronization fails
  3. Time Zone Issues: Verify timezone abbreviation is supported in NetBurner's timezone database
  4. Network Access: Ensure device IP is accessible from client machines

Debug Information

Monitor the serial debug output for:

  • Network connectivity status
  • NTP synchronization results
  • Certificate generation status
  • IP address assignments
  • Error messages and diagnostics