SSL/TLS Client

Example Path: examples/SSL/sslclient

SSL/TLS Client Example

A NetBurner embedded device application that demonstrates SSL/TLS client connections with automated testing and connection monitoring.

Overview

This application performs automated SSL/TLS client connections to a specified server, tracking both successful and failed connection attempts. It provides real-time status updates through both network messages and serial debug output, making it useful for testing SSL/TLS connectivity and performance analysis.

Features

• Automated SSL/TLS client connections with configurable target server
• Connection attempt tracking (successes and failures)
• Performance timing measurements
• Dual output channels: network messages to server and serial debug
• Comprehensive error reporting with specific SSL error codes
• Built-in retry mechanism with configurable delays
• DNS hostname resolution support

Configuration

Server Settings

Modify the following definitions in main.cpp to configure your target SSL server:

#define SSL_SERVER_NAME "192.168.0.53"  // Server IP address or hostname
#define SSL_SERVER_PORT 4433            // Server port number

Certificate Checking (Optional)

Certificate checking is disabled by default – this example calls SSL_connect() with verifyPeer left at its default of false, so the server's certificate is accepted without being validated against a Certificate Authority list.

To enable certificate verification:

1. Turn on NB_SSL_CLIENT_CERTIFICATE_CHECKING_ENABLED. Do not edit the SDK's nbrtos/include/predef.h directly – that file is shared by every project and your change would be overwritten on an SDK update. Instead use the per-project overload** mechanism: add an overload copy of the header to this project at overload/nbrtos/include/predef-overload.h and define the macro there:

   #define NB_SSL_CLIENT_CERTIFICATE_CHECKING_ENABLED   (1)

   The build automatically includes any *-overload.h headers found under the project's overload/ directory, applying your setting to this project only while leaving the shared SDK header untouched. See the OverloadDirectory example for a complete reference of how the overload folder works. Rebuild the system libraries after enabling the macro.

2. Add your trusted CA certificate(s) to the client context (or pass them to SSL_connect() via its certBuff parameter).
3. Pass verifyPeer = true to SSL_connect() so the server certificate is validated and its common name is checked against SSL_SERVER_NAME.

Application Behavior

Connection Process

1. Initialization: Waits for active network (DHCP) for up to 5 seconds
2. DNS Resolution: Resolves the server hostname to IP address (15-second timeout)
3. SSL Connection: Attempts SSL/TLS connection (20-second timeout)
4. Message Exchange: Sends connection statistics to the server
5. Cleanup: Closes connection and waits before next attempt

Test Parameters

• Maximum Attempts: 50 connection attempts total (successes + failures)
• Connection Timeout: 20 seconds
• DNS Timeout: 15 seconds
• Retry Delay: 0.5 seconds between attempts
• Network Wait: 5 seconds for DHCP

The attempt limit is defined by MAX_ATTEMPTS in main.cpp. Each iteration counts toward the limit whether the connection succeeds or fails, and the running totals of successes and failures are reported after every attempt.

Output Information

For each connection attempt, the application reports:

• Target server and port
• Connection start timestamp
• Success/failure status with error details
• Total connection time in system ticks and seconds
• Running totals of successful and failed attempts

Testing with OpenSSL

You can test the client using OpenSSL's server functionality:

openssl s_server -accept 4433 -cert Server.crt -key Server.key

Replace Server.crt and Server.key with your certificate files. These can be created using:

• NetBurner development tools
• OpenSSL certificate generation commands
• Certificate Authority (CA) issued certificates

Refer to the OpenSSL s_server documentation for additional configuration options.

Error Handling

The application provides detailed error reporting for SSL connection failures:

• SSL_ERROR_FAILED_NEGOTIATION: SSL handshake negotiation failed
• SSL_ERROR_CERTIFICATE_UNKNOWN: Unknown certificate error
• SSL_ERROR_CERTIFICATE_NAME_FAILED: Certificate name verification failed
• SSL_ERROR_CERTIFICATE_VERIFY_FAILED: Certificate verification failed
• Other errors: Generic SSL connection errors

Performance Monitoring

Connection timing is measured and reported for each attempt:

• System tick timestamps for precise timing
• Approximate duration in seconds
• Running statistics for performance analysis

Build Requirements

• NetBurner development environment
• SSL/TLS libraries enabled
• Network stack with DNS resolution support
• Serial debug output capability

Usage Notes

• The application runs until 50 connection attempts (successful or failed) are completed
• After completion, the device must be reset to repeat the test
• Enable system diagnostics for development (remove for production)
• Ensure target server is accessible and properly configured
• Monitor both serial output and network messages for complete status

Development Considerations

• Remove EnableSystemDiagnostics() call for production builds
• Adjust timeout values based on network conditions
• Consider certificate validation requirements for production use
• Monitor memory usage during extended connection testing