NanoSSL server integration
With TrustCore SDK NanoSSL server, devices may securely connect to remote peers.
Server integration process overview
This table describes the tasks for integrating a NanoSSL server into devices. Some tasks are optional and may not be relevant for a deployment. To determine whether to perform a particular task, read the beginning of each section.
Synchronous and asynchronous support
The source code distribution of NanoSSL server supports both synchronous and asynchronous message handling.
For socket-based systems (for example, using TCP/IP), synchronous methods should be used (see Synchronous server process flow).
For environments without RTOS, the asynchronous methods must be used (see Asynchronous server process flow).
For everything else (e.g., TCB, event-driven, upcall-based, EAP, and asynchronous stacks), the asynchronous methods should be used (see Implement NanoSSL server).
Synchronous server process flow
This figure shows the NanoSSL synchronous server process flow.
Asynchronous server process flow
This figure shows the NanoSSL asynchronous server process flow.
Build NanoSSL server sample code
To help with integration of a NanoSSL server into devices, a suite of sample code is included in the source distribution (in the ${MSS_SRC_PKG}/src/
examples directory) to quickly build a NanoSSL server and demonstrate its features. It comprises the following files:
ca_mgmt_example.c
— Performs authentication with certificates by using the TrustCore SDK certificate management functions.mocana_example.c
— Initializes TrustCore SDK code.ssl_example.c
— Implements a secure, synchronous HTTP server.ssl_example_async.c
— Implements a secure, asynchronous HTTP server.ssl_loopback_example.c
— Implements asynchronous client-server loop-back communication.
The sample code should be used as a reference and modified as required for inclusion into an application’s source code. The sample code may also be used to verify NanoSSL client-NanoSSL server communication.
Note
The moptions.h
file does not need to be updated to generate this build; however, if a makefile
other than the one provided by DigiCert is used, the following flags need to be added:
__ENABLE_MOCANA_EXAMPLES__
__ENABLE_MOCANA_SSL_SERVER__
The following sections describe tasks that may be performed to generate and run sample NanoSSL server code:
Note
NanoSSL Server samples link to NanoSSL and core libraries. Refer to the FAQs to build the required libraries before proceeding with sample build.
Generate a sample NanoSSL server
To generate a sample NanoSSL server:
Change to the
projects/nanossl
directory:cd projects/nanossl
Run the following command:
./build.sh --clean --debug --suiteb ssl_server
Generate a sample TLS v1.3 NanoSSL server
To generate the TLS v1.3 sample NanoSSL server:
Change to the
projects/nanossl
directory:cd projects/nanossl
Run the following command to build the NanoSSL library with support for TLS v1.3:
./build.sh --clean --debug --suiteb ssl_server
Disable TLS v1.3 and features
By default, TLS v1.3 is enabled when the NanoSSL server is generated.
To disable TLS v1.3 and features:
Change to the
projects/nanossl
directory:cd projects/nanossl
Run the following command to build the NanoCrypto library with TLS v1.3 features disabled:
./build.sh --clean --debug --suiteb ssl_server
Where
<disable-feature>
may be:--disable-0rtt
: Disables the 0-RTT feature.--disable-psk
: Disables the PSK feature.--disable-tls13
: Disables TLS v1.3.
Run the NanoSSL server
To run the sample NanoSSL server:
Run the following NanoSSL server sample code using the applicable command (i.e., using options for TLS or TLS v1.3).
For TLS:
./bin/ssl_server <options>
where additional
<options>
include:?
— Displays the help.-ssl_port <ssl port>
— Specifies the port number of the SSL server.-ssl_servername <ssl server name>
— Specifies the SSL server’s name.-ssl_certpath <path to files>
— Specifies the directory path to the certificate files.-ssl_server_cert <cert name>
— Specifies the name of the server certificate.-ssl_client_keyblob <blob name>
— Specifies the name of the client key BLOB file.
For TLS v1.3:
./bin/ssl_server <options>
where additional
<options>
include:-ssl_max_early_data_size <size>
— Specifies the maximum early data size accepted when using the PSK for connection. This value is sent with the session ticket to the client.
Verify NanoSSL server functionality
To verify and run the NanoSSL server functionality with NanoSSL client, generate the sample NanoSSL client:
Change to the
projects/nanossl
directory:cd projects/nanossl
Run the following command:
./build.sh --clean --debug --suiteb ssl_client
Run the NanoSSL client with the correct IP address, port number and server name to connect to NanoSSL server.
Verify NanoSSL server functionality with a web browser
To verify and run the NanoSSL Server functionality with a web browser:
Start the NanoSSL server with the correct certificate and key. By default, the server IP address is 127.0.0.1 and listens on port 1440.
Open a web browser, which acts as the SSL client, and navigate to https://127.0.0.1/a. The server terminal displays all the debug information, handshake messages, and the HTTPS request from the browser; the web browser displays the data sent by server.
Optionally, request additional data from the server, use the following URLs in the browser:
To tell NanoSSL server to send 100,000 bytes in 1 KB blocks:
https://127.0.0.1/ab
To tell NanoSSL server to send 10 million bytes in 1 KB blocks:
https://127.0.0.1/ag
To tell NanoSSL server to send 100,000 bytes in 16 KB blocks:
https://127.0.0.1/b
To tell NanoSSL client to shut down the NanoSSL server:
https://127.0.0.1/q
Use externally generated private keys with NanoSSL
When generating the certificate, ensure that the Common Name matches the -ssl_servername
option.
For example, to use a generated key and certificate when starting the NanoSSL server:
./ssl_server -ssl_port 1440 -ssl_certpath keystore -ssl_servername www.sslexample.com -ssl_server_cert dsa_cert.der -ssl_server_keyblob dsa_key.pem
To generate a private key for use with NanoSSL:
Generate the RSA key and certificate. For example:
openssl genpkey -out rsa_key.pem -algorithm RSA -outform PEM -pkeyopt rsa_keygen_bits:2048
openssl req -x509 -new -days 3650 -key rsa_key.pem -outform DER -out rsa_cert.der
Generate the DS keypair and certificate. For example:
openssl genpkey -genparam -algorithm DSA -out dsap.pem -pkeyopt dsa_paramgen_bits:2048
openssl genpkey -paramfile dsap.pem -out dsa_key.pem
openssl req -x509 -new -days 3650 -key dsa_key.pem -outform DER -out dsa_cert.der
Generate the ECDSA keypair and certificate. For example:
openssl ecparam -out ec_key.pem -name prime256v1 -genkey
openssl req -new -key ec_key.pem -x509 -nodes -days 365 -outform DER -out ecdsa_cert.der
Generate the p12 file.
openssl pkcs12 -export -inkey [private key filename] -in [certificate filename] -out cert.p12
Implement NanoSSL server
This table lists NanoSSL products and features that may be enabled, the flags required to enable them, and the required callback functions that must be customized and registered. (Both NanoSSL client and server are listed because they share a common code base.)
To integrate a NanoSSL server into an application, add calls to the functions provided by TrustCore SDK for NanoSSL server initialization, socket and connection management, message processing, and NanoSSL server shutdown, as shown in the ${MSS_SRC_PKG}/src/examples/ssl_example.c
sample module.
In particular, the functions and tasks described in below should be performed in the order shown, making calls to either the synchronous or asynchronous methods as appropriate.
Optional NanoSSL server functions
This table lists the optional functions that NanoSSL may also perform.