---
title: "Quick start guide"
source_url: https://dev.digicert.com/trustcore-sdk/nanossl/get-started/quick-start-guide.html
---

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

<a id="tap-flags-configuration"></a>

## 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__`

<a id="command-line-setup"></a>

## 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.

<a id="nanossl-server-command-line-parameters"></a>

### 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.

<a id="nanossl-client-command-line-parameters"></a>

### 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.

<a id="nanossl-server-in-local-mode"></a>

## NanoSSL server in local mode

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

1. **Build the libraries and server application:**
   For the **US Edition**:
   ```bash
   cd scripts/nanossl/ssl_server/
   ./build_ssl_server_tap_local.sh
   ```
   For the **Export Edition**:
   ```bash
   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:
   ```bash
   ./build_ssl_server_tap_local.sh --mauth
   ```
2. **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:
   ```bash
   ./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.
3. **Test the server connection:**
   From a remote host, access the server using a web browser or the `curl` command to confirm a successful setup:
   ```bash
   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.

<a id="nanossl-client-in-local-mode"></a>

## 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.

1. **Build the NanoSSL client application:**
   Navigate to the client script directory and initiate the build process:
   For the **US Edition**:
   ```bash
   cd scripts/nanossl/ssl_client/
   ./build_ssl_client_tap_local.sh
   ```
   For the **Export Edition**:
   ```bash
   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.
2. **Start the NanoSSL client:**
   Execute the client application using the command below, making sure to replace placeholder text with actual file names and locations:
   ```bash
   ./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.
3. **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.

<a id="nanossl-server-in-remote-mode"></a>

## NanoSSL server in remote mode

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

1. **Build the NanoTAP server:**
   Start by building the NanoTAP server, ensuring a clean state for the build process:
   ```bash
   ./NanoTAP_scripts/nanotap2_build.sh clean
   ```
   Copy the `bin` directory to `bin_server` after the build is complete:
   ```bash
   cp -r bin bin_server
   ```
2. **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.
3. **Modify hosts file:**
   Update the `/etc/hosts` file to associate the TAP server’s name with the server’s IP address.
4. **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`:
   ```bash
   cd bin_server
   ./nanotap_server_bin
   ```
   If configuration files are in another directory:
   ```bash
   ./nanotap_server_bin --modconfdir=./ --conf=taps.conf
   ```
5. **Build the SSL server with remote TAP:**
   For the US Edition:
   ```bash
   cd scripts/nanossl/ssl_server/
   ./build_ssl_server_tap_remote.sh
   ```
   For the Export Edition:
   ```bash
   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.
6. **Start the NanoSSL server:**
   Launch the SSL server with the necessary parameters:
   ```bash
   ./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.
7. **Edit client hosts file:**
   On the client machine, modify the `/etc/hosts` file to resolve the NanoSSL server’s address.
8. **Test server connectivity:**
   Use a web browser or a tool like `curl` on a remote client to test the connection to the server:
   ```bash
   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.

<a id="nanossl-client-in-remote-mode"></a>

## NanoSSL client in remote mode

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

1. **Build the NanoTAP server:**
   Compile the NanoTAP server to prepare it for remote connections:
   ```bash
   ./NanoTAP_scripts/nanotap2_build.sh clean
   cp -r bin bin_server
   ```
2. **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.
3. **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:
   ```bash
   cd bin_server
   ./nanotap_server_bin
   ```
   If the configuration files are elsewhere:
   ```bash
   ./nanotap_server_bin --modconfdir=./ --conf=taps.conf
   ```
4. **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:
   ```bash
   cd scripts/nanossl/ssl_client/
   ./build_ssl_client_tap_remote.sh
   ```
   For the Export Edition:
   ```bash
   cd scripts/nanossl/ssl_client/
   ./build_ssl_client_tap_remote_export.sh
   ```
5. **Launch the NanoSSL client:**
   Start the SSL client with the correct remote server settings using the following command:
   ```bash
   ./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.

<a id="openssl-connector-integration"></a>

## OpenSSL connector integration

### Models

OpenSSL connector is available in two models:

- Standard Edition
- Community Edition


> **Info**
>
> For access to the Community Edition and related documentation, see the [TrustCore OpenSSL connector repository](https://github.com/digicert/trustcore/blob/main/samples/openssl_connector/BUILD_RUN.md).


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

1. **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:
   ```bash
   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.
2. **Run the SSL Server:**
   Start your SSL server to listen for incoming OpenSSL connections.
3. **Execute the OpenSSL Client:**
   Launch the OpenSSL client with the required command-line options to connect to the server:
   ```bash
   ./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.

<a id="remote-mode-integration"></a>

### Remote mode integration

1. **Build the NanoTAP server:**
   As with local mode, ensure that the NanoTAP server is correctly built and configured for remote operation:
   ```bash
   cd mss
   ./NanoTAP_scripts/nanotap2_build.sh --clean --debug
   cp -r bin bin_server
   ```
2. **Build the OpenSSL connector for remote TAP:**
   From the OpenSSL connector directory, execute the build script for remote mode:
   ```bash
   ./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.
3. **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:
   ```bash
   ./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.

<a id="testing-evp-functionality"></a>

### Test 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.

1. **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:
   ```bash
   cd thirdparty/openssl-1.1.1c/engines/mocana/
   ```
   For remote mode testing, use:
   ```bash
   make -f Makefile.evptest tap=true tap_remote=true debug=true gdb=true clean all
   ```
   For local mode testing, use:
   ```bash
   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.
2. **Run the EVP test application:**
   After building the test application, set the library path to include the NanoSSL binaries, then execute the test application:
   ```bash
   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.

<a id="third-party-application-integration"></a>

## 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.

<a id="using-the-local-tap-library"></a>

### Use the local TAP library

1. **Set environment variables:**
   Define the necessary environment variables to inform the system about the TAP configuration:
   ```bash
   export MOCANA_TAPCONFIGFILE='/etc/mocana/tpm2.conf'
   export MOCANA_TAPPROVIDER='TAP_PROVIDER_TPM2'
   ```
2. **Build libraries for local TAP usage:**
   Compile the NanoTAP, NanoCrypto, NanoSSL, and OpenSSL Connector libraries:
   For the US Edition:
   ```bash
   cd scripts/nanossl/openssl_connector/
   ./build_openssl_connector_tap_local_extern.sh
   ```
   For the Export Edition:
   ```bash
   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.

<a id="using-the-remote-tap-server"></a>

### Use the remote TAP server

1. **Set environment variables for remote TAP:**
   Point your environment to the remote TAP server by setting the corresponding environment variables:
   ```bash
   export MOCANA_TAPSERVERPORT='8277'
   export MOCANA_TAPSERVERNAME='ssltest.mocana.com'
   export MOCANA_TAPPROVIDER='TAP_PROVIDER_TPM2'
   export MOCANA_TAPCCONFIG='/etc/mocana/tapc.conf'
   ```
2. **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:
   ```bash
   cd scripts/nanossl/openssl_connector/
   ./build_openssl_connector_tap_remote_extern.sh
   ```
   For the Export Edition:
   ```bash
   cd scripts/nanossl/openssl_connector/
   ./build_openssl_connector_tap_remote_extern_export.sh
   ```
3. **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:
   ```bash
   ./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.