Quick start guide

8 minute read

This guide will walk you through integrating DigiCert® NanoSSL and OpenSSL connector into your development environment.

TAP flags configuration

Select your TAP operations mode and set the required build and compile flags as follows:

Build Flags:
- Local Mode: --tap
- Secure Remote (SSL): --tap-remote
- Unencrypted Remote (TCP): --tap-remote --tap-remote-tcp
- Mutual Authentication: --mauth
- External TAP Applications: --tap-extern
Compile Flags:
- For local TAP (tap=true), set:
  - __ENABLE_DIGICERT_SMP__
  - __ENABLE_DIGICERT_CRYPTO_WRAPPER__
  - __ENABLE_DIGICERT_TAP__
  - __ENABLE_DIGICERT_ASYM_KEY__
  - __ENABLE_DIGICERT_64_BIT__
  - __DISABLE_DIGICERT_INIT__
- For remote TAP (tap_remote=true), set:
  - __ENABLE_DIGICERT_TAP_REMOTE__
  - __ENABLE_DIGICERT_TAP_REMOTE_SSL__
- For remote TAP over TCP (tap_remote_tcp), set:
  - __ENABLE_DIGICERT_TAP_REMOTE__
- For mutual authentication (mauth=true), set:
  - __ENABLE_DIGICERT_SSL_MUTUAL_AUTH_SUPPORT__
- For external TAP (tap_extern=true), set:
  - __ENABLE_DIGICERT_TAP_EXTERN__

Command line setup

Setting up NanoSSL with TAP is managed via command line arguments that correlate with specific build flags. This setup allows for flexibility and precision in configuring the server or client for various operational modes.

NanoSSL server command line parameters

For a default SSL server configuration, use the following parameters:

-h | ? : Display help information.
-ssl_port <port> : Specify the SSL server port.
-ssl_servername <server_name> : Define the SSL server name.
-ssl_certpath <path_to_files> : Path to the certificate and key files.
-ssl_server_cert <cert_name> : Name of the server certificate file.
-ssl_server_keyblob <blob_name> : Name of the server key blob file.

When __ENABLE_DIGICERT_SSL_MUTUAL_AUTH_SUPPORT__ is set, use:

-ssl_ca_cert <cert_name> : Specify the CA certificate name for mutual authentication.

For configurations with TAP enabled (__ENABLE_DIGICERT_TAP__), add:

-tap_config_file <tap configuration file> : The TAP configuration file path.

If TAP is used in remote mode (__ENABLE_DIGICERT_TAP_REMOTE__):

-tap_server_name <tap_server_name> : The TAP server’s name.
-tap_server_port <tap_server_port> : The TAP server’s port.

In cases where TLS 1.3 with PSK and 0-RTT is used, additional parameters include:

ssl_max_early_data_size <size> : Defines the max early data size when using PSK for connections.

NanoSSL client command line parameters

For the default SSL client configuration, the parameters are similar to the server setup:

-h | ? : Display help information.
-ssl_ip <IP> : IP address of the SSL server.
-ssl_port <port> : Port number of the SSL server.
-ssl_servername <server_name> : Name of the SSL server.
-ssl_certpath <path_to_files> : Path to the certificate and key files.

With mutual authentication (__ENABLE_DIGICERT_SSL_MUTUAL_AUTH_SUPPORT__):

-ssl_client_cert <cert_name> : Name of the client certificate file.
-ssl_client_keyblob <blob_name> : Name of the client key blob file.

For TAP configurations (__ENABLE_DIGICERT_TAP__):

-tap_config_file <tap config file> : Path to the TAP configuration file.

And for remote TAP configurations (__ENABLE_DIGICERT_TAP_REMOTE__):

-tap_server_name <tap_server_name> : Name of the remote TAP server.
-tap_server_port <tap_server_port> : Port number of the remote TAP server.

For TLS 1.3 specific configurations, use:

-ssl_external_psk : To specify the use of an external PSK for TLS 1.3.
-ssl_early_data <early_data> : To specify early data content to be sent for TLS 1.3 with 0-RTT.

Each command line argument must match the corresponding compile flag to ensure proper operation. Be sure to replace placeholder values with actual server names, IP addresses, port numbers, and file paths as needed for your specific environment.

NanoSSL server in local mode

Setting up your NanoSSL server with NanoTAP in local mode involves a few steps:

Build the libraries and server application:
```
cd scripts/nanossl/ssl_server/
./build_ssl_server_tap_local.sh
```
(Optional) To enable mutual authentication, append the --mauth flag to your build command:
```
./build_ssl_server_tap_local.sh --mauth
```
Start the server: Run the following command to start the server, replacing <cert_name>, <blob_name>, and <path_to_tpm2.conf> with your actual file names and paths:
```
./ssl_server -ssl_server_cert <cert_name>.cert.der \
-ssl_server_keyblob <blob_name>.key.pem -ssl_servername sslserver.mydomain.net \
-ssl_port 1440 -tap_config_file <path_to_tpm2.conf>
```
Note: If your TPM configuration files are not located in /etc/digicert, specify the correct path with the -tap_config_file argument.
Test the server connection: From a remote host, access the server using a web browser or the curl command to confirm a successful setup:
```
curl -k -vvvv https://sslserver.mydomain.net:1440/
```
Use the actual server address in place of sslserver.mydomain.net.

These steps will get your NanoSSL server up and running in local mode and ready for secure communication.

NanoSSL client in local mode

To configure the NanoSSL client to work with NanoTAP in local mode, follow the instructions below. This setup allows the client to authenticate and communicate securely with the NanoSSL server.

Build the NanoSSL client application: Navigate to the client script directory and initiate the build process:
```
cd scripts/nanossl/ssl_client/
./build_ssl_client_tap_local.sh
```
If mutual authentication is needed, make sure you’ve included the --mauth flag when building the server component, as shown previously in the server setup.
Start the NanoSSL client: Execute the client application using the command below, making sure to replace placeholder text with actual file names and locations:
```
./ssl_client -ssl_servername sslserver.mydomain.net -ssl_port 1440 \
-ssl_server_cert titan_ca.der -ssl_client_cert sslclient.mydomain.net.cert.der \
-ssl_client_keyblob sslclient.mydomain.net.key.pem -ssl_ip localhost \
-tap_config_file ./tmp2.conf
```
The -ssl_server_cert argument points to the CA certificate that issued the server’s certificate, while -ssl_client_cert and -ssl_client_keyblob are your client’s certificate and private key, respectively. Use the -tap_config_file to point to the TAP configuration file if it’s not located in the /etc/digicert directory.
Test the client connection: Ensure that the client can successfully establish a connection with the server. If you’re on the same machine as the server or within a network that allows you to use the server’s hostname, the example provided will work. Otherwise, replace localhost with the server’s IP address or resolvable hostname. Upon running the client application, you should see output indicating the establishment of a secure connection, the SSL handshake’s success, and any data received from the server.

This setup process is designed to be executed quickly, ensuring that developers can get their local mode SSL client operational with minimal fuss.

NanoSSL server in remote mode

Configure your NanoSSL Server to operate with NanoTAP in remote mode by following these steps:

Build the NanoTAP server: Start by building the NanoTAP server, ensuring a clean state for the build process:
```
./NanoTAP_scripts/nanotap2_build.sh clean
```
Copy the bin directory to bin_server after the build is complete:
```
cp -r bin bin_server
```
Configuration file placement: Make sure that tpm2.conf, cred.tpm2, taps.conf, and tapc.conf are located in the /etc/digicert directory. If this directory does not exist, move these files to your bin_server directory.
Modify hosts file: Update the /etc/hosts file to associate the TAP server’s name with the server’s IP address.
Start the NanoTAP server: Navigate to the bin_server directory to run the NanoTAP server. Use the appropriate command based on where your configuration files are located: If configuration files are in /etc/digicert:
```
cd bin_server
./nanotap_server_bin
```
If configuration files are in another directory:
```
./nanotap_server_bin --modconfdir=./ --conf=taps.conf
```
Build the SSL server with remote TAP:
```
cd scripts/nanossl/ssl_server/
./build_ssl_server_tap_remote.sh
```
If mutual authentication is needed, make sure you’ve included the --mauth flag when building the server component, as shown previously in the server setup.

Start the NanoSSL server: Launch the SSL server with the necessary parameters:

./ssl_server -tap_server_name ssltest.mydomain.net -tap_server_port 8277 \
-ssl_server_cert sslserver.mydomain.net.cert.der \
-ssl_server_keyblob sslserver.mydomain.net.key.pem -ssl_port 1440 \
-ssl_servername sslserver.mydomain.net -ssl_ca_cert titan_ca.der \
-tap_config_file ./

Point to the correct TAP configuration file path if not in the default directory.

Edit client hosts file: On the client machine, modify the /etc/hosts file to resolve the NanoSSL server’s address.
Test server connectivity: Use a web browser or a tool like curl on a remote client to test the connection to the server:
```
curl -k -vvvv https://sslserver.mydomain.net:1440/
```
Ensure that the domain name and port match your server’s configuration.

By completing these steps, your NanoSSL server will be ready to handle connections in remote mode.

NanoSSL client in remote mode

To configure and run the NanoSSL Client with NanoTAP in remote mode, follow these instructions:

Build the NanoTAP server: Compile the NanoTAP server to prepare it for remote connections:
```
./NanoTAP_scripts/nanotap2_build.sh clean
cp -r bin bin_server
```
Place configuration files: Confirm that the necessary configuration files (tpm2.conf, cred.tpm2, taps.conf, and tapc.conf) are located in the /etc/digicert directory. If this directory doesn’t exist, move the configuration files to the bin_server directory.
Start the NanoTAP server: Begin running the NanoTAP server. The command varies depending on the location of your configuration files: If the configuration files are within the /etc/digicert directory:
```
cd bin_server
./nanotap_server_bin
```
If the configuration files are elsewhere:
```
./nanotap_server_bin --modconfdir=./ --conf=taps.conf
```
Build the NanoSSL client for remote TAP: Navigate to the SSL client directory and initiate the build script for your respective edition:
```
cd scripts/nanossl/ssl_client/
./build_ssl_client_tap_remote.sh
```
Launch the NanoSSL client: Start the SSL client with the correct remote server settings using the following command:
```
./ssl_client -ssl_servername sslserver.mydomain.net -ssl_port 1440 \
-ssl_server_cert titan_ca.der -ssl_client_cert sslclient.mydomain.net.cert.der \
-ssl_client_keyblob sslclient.mydomain.net.key.pem -ssl_ip <server_ip> \
-tap_server_name ssltest.mydomain.net -tap_server_port 8277
```
Replace <server_ip> with the actual IP address of your SSL server. If the TAP configuration file is not in the /etc/digicert directory, specify the correct path using the -tap_config_file argument.

By completing these steps, your NanoSSL client will be configured to securely connect to the NanoSSL server in remote mode. Test the setup to ensure secure communications are established correctly.

OpenSSL connector integration

Models

OpenSSL connector is available in two models:

Standard Edition
Community Edition

For access to the Community Edition and related documentation, see the TrustCore OpenSSL connector repository.

Integrating the OpenSSL connector with NanoSSL allows the existing OpenSSL-based applications to use NanoSSL as the underlying SSL/TLS implementation without changing their OpenSSL API calls.

The OpenSSL connector supports three integration modes:

Software - NanoSSL provides the SSL/TLS implementation and cryptographic operations directly. There is no involvement of a TAP hardware
Local TAP - Cryptographic key operations are delegated to NanoTAP on the same host as the application (for example, a local TPM)
Remote TAP - NanoTAP runs as a separate server. Applications send key operations to the server on the same host

These can also be linked into third-party applications, such as Python or cURL.

For build steps, command-line flags, file paths, and related documentation, see the OpenSSL Connector Build and Run Instructions.

Was this page helpful?

Provide feedback

Need more help?

Account and platform

Certificates and PKI

Signing

Devices and IoT

Other resources