On-board Cert Generation - Simple

Example Path: examples/SSL/SslOnboardCertGeneration/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.

On-board Cert Generation examples

Three on-board certificate generation examples ship side by side; pick the one that matches how much control you need over the certificate:

• Simple (this example) – hands-off. It relies on automatic generation and turns on ENABLE_AUTOCERT_REGEN (see below) so the device self-heals its certificate: a fresh one is generated automatically when the certificate expires or when its Common Name no longer matches the device IP (for example after a DHCP address change). No user interaction is required. This covers most applications.
• Advanced (<NNDK install>\examples\ssl\SslOnboardCertGeneration\Advanced) – hands-on. A self-signed certificate you drive from a serial-console menu (generate, erase, inspect). Automatic regeneration is deliberately left off so it never overwrites a certificate you made by hand.
• Compiled CA (<NNDK install>\examples\ssl\SslOnboardCertGeneration\CompiledCa) – hands-on, and a step beyond Advanced: instead of self-signing, it signs the generated certificate with a Certificate Authority compiled into the application, and shows how to write your own certificate-generation function. Same serial-console menu; automatic regeneration off.

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, the certificate will update when it expires, creating a new 1 year certificate, and will also be replaced when its Common Name no longer matches the device IP. Generation occurs on next SSL/TLS access.
• When ENABLE_AUTOCERT_REGEN is defined, AUTO_CERT_GEN_CHECK dictates how frequently the 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.

This example turns on ENABLE_AUTOCERT_REGEN so it self-heals a stale certificate – for example one left over from a previously loaded application, or after a DHCP address change. Rather than editing the shared SDK header (nbrtos/include/predef.h), it is enabled per-project via the overload mechanism: see overload/nbrtos/include/predef-overload.h, which predef.h includes last so a project can set defines without modifying the SDK. (AUTO_CERT_GEN_CHECK is defined there too, because the SDK only sets it inside its own ENABLE_AUTOCERT_REGEN block, which is evaluated before the overload is included.) See the examples/OverloadDirectory example for more on this technique.

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:

• nbrtos.h - NetBurner Real-Time Operating System
• crypto/certgen.h - Certificate generation functionality
  
• netinterface.h - Network interface management
• nbtime.h - Time management utilities
• timezones.h - Timezone support

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();

Server Configuration

The secure configuration server is enabled without forcing TLS mode:

EnableSecureConfigServer(false);

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

• NetBurner Discovery: http://discover.netburner.com (requires internet access)

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