Quick start guide

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_MOCANA_SMP__
  - __ENABLE_MOCANA_CRYPTO_WRAPPER__
  - __ENABLE_MOCANA_TAP__
  - __ENABLE_MOCANA_ASYM_KEY__
  - __ENABLE_MOCANA_64_BIT__
  - __DISABLE_MOCANA_INIT__
- For remote TAP (tap_remote=true), set:
  - __ENABLE_MOCANA_TAP_REMOTE__
  - __ENABLE_MOCANA_TAP_REMOTE_SSL__
- For remote TAP over TCP (tap_remote_tcp), set:
  - __ENABLE_MOCANA_TAP_REMOTE__
- For mutual authentication (mauth=true), set:
  - __ENABLE_MOCANA_SSL_MUTUAL_AUTH_SUPPORT__
- For external TAP (tap_extern=true), set:
  - __ENABLE_MOCANA_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_MOCANA_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_MOCANA_TAP__), add:

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

If TAP is used in remote mode (__ENABLE_MOCANA_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_MOCANA_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_MOCANA_TAP__):

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

And for remote TAP configurations (__ENABLE_MOCANA_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:

For the US Edition:

cd scripts/nanossl/ssl_server/
./build_ssl_server_tap_local.sh

For the Export Edition:

cd scripts/nanossl/ssl_server/
./build_ssl_server_tap_local_export.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/mocana, 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:
For the US Edition:
```
cd scripts/nanossl/ssl_client/
./build_ssl_client_tap_local.sh
```
For the Export Edition:
```
cd scripts/nanossl/ssl_client/
./build_ssl_client_tap_local_export.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/mocana 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/mocana 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/mocana:
```
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:
For the US Edition:
```
cd scripts/nanossl/ssl_server/
./build_ssl_server_tap_remote.sh
```
For the Export Edition:
```
cd scripts/nanossl/ssl_server/
./build_ssl_server_tap_remote_export.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/mocana 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/mocana 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:
For the US Edition:
```
cd scripts/nanossl/ssl_client/
./build_ssl_client_tap_remote.sh
```
For the Export Edition:
```
cd scripts/nanossl/ssl_client/
./build_ssl_client_tap_remote_export.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/mocana 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

Integrating the OpenSSL connector with NanoSSL allows for the use of OpenSSL API calls while leveraging NanoSSL’s robust security features. Follow these steps to integrate the OpenSSL connector in both local and remote modes.

Local mode integration

Build the OpenSSL Connector:
Navigate to the OpenSSL connector script directory. Select the script corresponding to your needs and run it to build the connector:
```
cd scripts/nanossl/openssl_connector/
./build_openssl_connector_tap_local.sh  # For US Edition
./build_openssl_connector_tap_local_export.sh  # For Export Edition
```
Include additional flags as required for your setup, such as:
- --openssl_1_1_1 for building with OpenSSL-1.1.1c support.
- --redefine if building with Node.js compatibility.
- --self_signed to permit self-signed certificates.
- --non_trusted to accept any certificate.
Run the SSL Server:
Start your SSL server to listen for incoming OpenSSL connections.
Execute the OpenSSL Client:
Launch the OpenSSL client with the required command-line options to connect to the server:
```
./openssl_client_tap -c <client_cert>.pem -k <client_key>.pem \
-t ./tpm2.conf -s sslserver.mydomain.net -a <ca_cert>.pem \
-i <server_ip> -p 1440 -v <tap_server_name> -o <tap_server_port>
```
Replace the placeholders with your actual file paths and server details. The -t option points to your TAP configuration file.

Remote mode integration

Build the NanoTAP server:
As with local mode, ensure that the NanoTAP server is correctly built and configured for remote operation:
```
cd mss
./NanoTAP_scripts/nanotap2_build.sh --clean --debug
cp -r bin bin_server
```
Build the OpenSSL connector for remote TAP:
From the OpenSSL connector directory, execute the build script for remote mode:
```
./build_openssl_connector_tap_remote.sh  # For US Edition
./build_openssl_connector_tap_remote_export.sh  # For Export Edition
```
Again, add the same additional flags as needed for local mode.

Operate the OpenSSL client for remote connections:

With the remote TAP server running, connect using the OpenSSL client and specify the TAP server’s remote connection details:

./openssl_client_tap -v <tap_server_name> -o <tap_server_port> \
-c <client_cert>.pem -k <client_key>.pem --servername sslserver.mydomain.net \
--serverip <server_ip> -p 1440 --cacert <ca_cert>.pem -tapconfig ./tpm2.conf

By integrating the OpenSSL connector with your NanoSSL setup, you benefit from OpenSSL’s familiar API while operating within NanoSSL’s secure environment.

Testing EVP functionality

To ensure that the Encryption and Decryption (EVP) functionalities are operating correctly with NanoSSL, follow the steps below to rebuild the necessary libraries with OpenSSL flags and test the EVP operations.

Rebuild with OpenSSL flags:
Navigate to the directory containing the OpenSSL version you’re using. Rebuild the libraries with the OpenSSL flags to address any potential namespace conflicts:
```
cd thirdparty/openssl-1.1.1c/engines/mocana/
```
For remote mode testing, use:
```
make -f Makefile.evptest tap=true tap_remote=true debug=true gdb=true clean all
```
For local mode testing, use:
```
make -f Makefile.evptest tap=true debug=true gdb=true clean all
```
These commands compile the testing applications with the TAP and debug flags set, ensuring that you can run the EVP tests with the correct library versions and debug as necessary.
Run the EVP test application:
After building the test application, set the library path to include the NanoSSL binaries, then execute the test application:
```
export LD_LIBRARY_PATH=<PATH_TO_NANOTAP_BINARIES>:$LD_LIBRARY_PATH
./moc_evp_rsa_dsa_ecdsa_test -p <keyfile.pem> -k TPM2 -s
```
Replace <PATH_TO_NANOTAP_BINARIES> with the actual path to the bin directory containing the NanoTAP and NanoSSL binaries, and <keyfile.pem> with the path to your PEM-formatted key file.
The test application will verify the functioning of RSA, DSA, and ECDSA operations through the EVP interface, confirming that these cryptographic primitives are working as expected within your NanoSSL environment.

Third-party application integration

Integrating NanoSSL with third-party applications enables these applications to utilize TAP asymmetric keys and certificates for secure operations. This section will guide you through configuring NanoSSL for use with third-party applications such as Python scripts or Apache web servers.

Using the local TAP library

Set environment variables:
Define the necessary environment variables to inform the system about the TAP configuration:
```
export MOCANA_TAPCONFIGFILE='/etc/mocana/tpm2.conf'
export MOCANA_TAPPROVIDER='TAP_PROVIDER_TPM2'
```
Build libraries for local TAP usage:
Compile the NanoTAP, NanoCrypto, NanoSSL, and OpenSSL Connector libraries:
For the US Edition:
```
cd scripts/nanossl/openssl_connector/
./build_openssl_connector_tap_local_extern.sh
```
For the Export Edition:
```
cd scripts/nanossl/openssl_connector/
./build_openssl_connector_tap_local_extern_export.sh
```
Include the necessary build flags for OpenSSL connectors as detailed in previous sections.

Using the remote TAP server

Set environment variables for remote TAP:

Point your environment to the remote TAP server by setting the corresponding environment variables:

export MOCANA_TAPSERVERPORT='8277'
export MOCANA_TAPSERVERNAME='ssltest.mocana.com'
export MOCANA_TAPPROVIDER='TAP_PROVIDER_TPM2'
export MOCANA_TAPCCONFIG='/etc/mocana/tapc.conf'

Build libraries for remote TAP server:
Navigate to the OpenSSL connector script directory and initiate the build for remote mode integration:
For the US Edition:
```
cd scripts/nanossl/openssl_connector/
./build_openssl_connector_tap_remote_extern.sh
```
For the Export Edition:
```
cd scripts/nanossl/openssl_connector/
./build_openssl_connector_tap_remote_extern_export.sh
```
Test integration with a third-party app:
Once the environment is set and the libraries are built, you can start the third-party application. Ensure that the application is configured to use the NanoSSL and OpenSSL Connector libraries. Here is an example for starting an application with NanoSSL integration:
```
./third_party_app --use-tap-keys --certs-path /path/to/certs/
```
Replace ./third_party_app with the actual command to run your third-party application, and /path/to/certs/ with the path to your certificates and keys.

In this section: