NanoSSL overview

This documentation describes NanoSSL, its features, important design considerations, and guidance for application programmers incorporating NanoSSL into their devices’ C/C++ application source code.

APIs

NanoSSL is implemented by the following ANSI-C APIs:

• Common code base: Functions common to all TrustCore SDK components; defined in ${MSS_SRC_PKG}/src/common/mocana.h.
• Certificate management: Functions for authentication; defined in ${MSS_SRC_PKG}/src/crypto/ca_mgmt.h.
• Common SSL code base: Functions common to all NanoSSL clients, both synchronous and asynchronous; defined in ${MSS_SRC_PKG}/src/ssl/ssl.h.
• Synchronous client: Functions to implement synchronous communication between a NanoSSL client and an SSL server; defined in ${MSS_SRC_PKG}/src/ssl/ssl.h.
• Asynchronous client: Functions to implement asynchronous communication between a NanoSSL client and an SSL server; defined in ${MSS_SRC_PKG}/src/ssl/ssl.h.
• Synchronous server: Functions to implement synchronous communication between a NanoSSL server and an SSL client; defined in ${MSS_SRC_PKG}/src/ssl/ssl.h.
• Asynchronous server: Functions to implement asynchronous communication between a NanoSSL server and an SSL client; defined in ${MSS_SRC_PKG}/src/ssl/ssl.h.

Compilation flags

This table lists the NanoSSL compilation flags. There is only one required flag for the client and one required flag for the server. The remaining NanoSSL flags are optional for the basic synchronous NanoSSL client or server.

For a complete list of compilation flags and their descriptions, refer to the NanoSSL API Reference.

Functions

This table lists the NanoSSL API functions and shows whether they are used for synchronous and/or asynchronous clients and/or servers.

Callback functions

The sslSettings structure contains function pointers for the following callback functions, which are fully documented in the NanoSSL API Reference:

• Synchronous/Asynchronous client/server
  • funcPtrAlertCallback
  • funcPtrAlertHandshakeCallback
  • funcPtrSSLHandelTimeout
• Synchronous/Asynchronous client
  • funcPtrChoosePSK
  • funcPtrMutualAuthCertificateVerify
• Synchronous/Asynchronous server
  • funcPtrGetClientPSK
  • funcPtrLookupPSK
  • funcPtrVersionCallback
• Asynchronous client
  • funcPtrClientOpenStateCallback
  • funcPtrClientRenewalCallback
  • funcPtrClientStartTimer
• Asynchronous server
  • funcPtrOpenStateCallback
  • funcPtrRenewalCallback
  • funcPtrStartTimer

Enabling NanoSSL and NanoTLS products and features lists the NanoSSL products and features that may be enabled, the flags required to enable them, and their required callback functions that need to be customized and registered. (Both NanoSSL client and server are listed because they share a common code base.)

Setting variables

This table lists the variables that must be set.

Enabling NanoSSL and NanoDTLS products and features

This table lists the 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.

Session-specific callback function

The SSLSocket structure contains function pointers for callback functions that are associated with a session (i.e., each session may set the function pointers to a different function):

• Synchronous/asynchronous client/server:
  • funcPtrGetCertAndStatusCallback — Set using SSL_setCertAndStatusCallback().
  • funcPtrAlpnCallback — Set using SSL_setAlpnCallback().
  • funcPtrInvalidCertCallback — Set using:

    MSTATUS SSL_setInvalidCertCallback(sbyte4 connectionInstance, (MSTATUS (*funcPtrInvalidCertCallback)(sbyte4 connectionInstance, MSTATUS validationstatus));
    

    Note

    This function requires the build flag `__ENABLE_MOCANA_SSL_INVALID_CERTIFICATE_CALLBACK__`.
    
    To ignore the certificate error, the callback should return the status `>= 0`.
    

• Synchronous/asynchronous server:
  • funcPtrVersionCallback — Set using SSL_setVersionCallback().
• Synchronous/asynchronous client:
  • funcPtrVersionCallback — Set using SSL_setVersionCallback().

This table describes the purpose of these function pointers, which are also fully documented in the NanoSSL API Reference.

Session-specific settings

Session settings may be applied using the following methods:

• SSL_ioctl
• SSL_setSessionFlags

SSL_ioctl flags

This table lists the flags that may be configured to call the SSL_ioctl function.

SSL_setSession flags

This table lists the session authentication flags for the SSL_setSessionFlags API. For more information about this API, refer to the NanoSSL API Reference.

Common TrustCore SDK initialization

Applications should perform the common TrustCore SDK initialization and shutdown work, as shown in the ${MSS_SRC_PKG}/src/examples/mocana_example.c sample module. In particular, make the following function calls and perform the following procedures:

• MOCANA_initMocana — Initialize the TrustCore SDK common code base (logging, random number generator, and so on).
• MOCANA_initLog — Optionally, register a callback function to the TrustCore SDK logging system.
• Create threads for all required TrustCore SDK component servers (e.g., the NanoSec IKE server).
• Implement a status-checking loop that runs and sleeps as long as an application running flag is true.
• MOCANA_freeMocana — Release memory that was allocated by MOCANA_initMocana.