Modes of operation

The application layer initiates and maintains the TCP socket, listening for incoming client connections. Upon accepting a connection, it may utilize multithreading or subprocesses to manage the TCP session. At this juncture, the NanoSSL library is invoked to perform SSL/TLS handshakes, after which it secures the data exchange by encrypting and decrypting the communication streams.

Figure 1. Synchronous mode control flow

Control flow of an SSL server application when using NanoSSL in asynchronous mode

The synchronous operational mode is tightly integrated with the TCP socket, performing I/O tasks directly:

Tip: While the __ENABLE_MOCANA_SSL_PENDING_DATA_YIELD__ flag exists for CPU yield on multi-threaded platforms, it is recommended to poll SSL_send and SSL_recv alongside their respective pending functions to ensure I/O completion.

Figure 2. Asynchronous mode control flow

control flow of an SSL server application when using NanoSSL in asynchronous mode

Asynchronous mode decouples from the TCP socket’s direct handling, emphasizing memory-based record management:

The choice between blocking and non-blocking sockets operates independently of the synchronous or asynchronous API usage. Blocking sockets are straightforward and can be employed in both modes. Non-blocking sockets are suitable for situations where immediate data availability is not guaranteed, allowing the application to perform alternate tasks and retry as needed. Practices such as using select or poll are common to determine the readiness of data on the TCP socket.

Each mode and socket type offers unique benefits, and the choice should align with the application’s design for optimal performance and security.

When NanoSSL is initialized, the maximum number of connection contexts that it must support is specified. Internally, NanoSSL allocates an array of sslConnectDescr structures to store these contexts. When the application accepts a new TCP connection, it calls a NanoSSL API to allocate an unused context from the array to the connection. If NanoSSL successfully allocates a context, it returns the index of that entry in the array to the caller called a connection instance (connectionInstance). The application layer uses the returned connectionInstance to refer to the connection in subsequent calls to NanoSSL, which stores all state information for that connection in that context. ## Create a Certificate Store

To use an SSL/TLS cipher suite that requires certificate-based authentication, a certificate store must be created for use by NanoSSL. In typical use cases, only the SSL server presents its certificate to be authenticated by the SSL client. Details about certificate store creation are beyond the scope of this document. The CERT_STORE_createStore API is used to create an empty certificate store and then the server certificate (or chain of certificates) and key must be added to the certificate store using the CERT_STORE_addIdentityWithCertificateChain API. This certificate store may then be used to create a connection context as described in Create a Connection Context.

The SSL_ASYNC_acceptConnection API is called first when the application is the server side of the SSL/TLS connection. NanoSSL allocates a connectionInstance as described in Create a NanoSSL Connection Instance. Before this API is invoked, the server must have accepted a client TCP connection (in Linux, this step is typically performed with the accept() system call). The application must also have allocated and populated a certificate store.

The prototype of this function is as follows:

    sbyte4 connectionInstance = SSL_ASYNC_acceptConnection (
    sbyte4 appSocket,
    struct certStore *pCertStore)

The first argument is the socket descriptor which is used to uniquely identify a Nano SSL session. The second argument is the pointer to the certificate store. This function returns a connectionInstance on success and a negative response on failure.

To use the NanoSSL library in asynchronous mode, the SSL_FLAG_ENABLE_SEND_BUFFER and SSL_FLAG_ENABLE_RECV_BUFFER flags must be set using the SSL_setSessionFlags API as follows:

    SSL_setSessionFlags(
    sbyte4 connectionInstance, 
    (SSL_FLAG_ENABLE_SEND_BUFFER | SSL_FLAG_ENABLE_RECV_BUFFER)
    )

This API call is typically called after obtaining the connectionInstance using the SSL_ASYNC_acceptConnection API as described in Create a Connection Context.

The SSL_ASYNC_recvMessage2 API is called by the server application layer to deliver data received over the SSL/TLS TCP socket to NanoSSL for SSL/TLS protocol processing.

The function prototype for this call is as follows:

    status = SSL_ASYNC_recvMessage2(
    sbyte4 connectionInstance,
    ubyte *pFirstRcvdUnreadByte,
    ubyte4 bytesRcvdRemaining,
    ubyte **ppFirstUnusedByte,
    ubyte4 *bytesRemaining)

where:

The server application layer waits to receive a client HELLO message. The server application layer reads data on the TCP socket into a buffer. It then calls SSL_ASYNC_recvMessage2() with pFirstRcvdUnreadByte set to the address of this buffer. The argument bytesRcvdRemaining is the number of bytes in the received buffer. The behavior of this function depends on whether the SSL/TLS handshake is complete or pending. The difference between these 2 cases is explained in SSL/TLS Handshake Phase and Data Transfer Phase.

As shown in Figure 2, the application layer must call the SSL_ASYNC_getRecvBuffer() API to harvest any plaintext data extracted by the previous call to SSL_ASYNC_recvMessage2.

The prototype for this function is as follows:

    sbyte4 SSL_ASYNC_getRecvBuffer(
    sbyte4 connectionInstance,
    ubyte **data,
    ubyte4 *len,
    ubyte4 *pRetProtocol)

where:

The caller must consume (e.g., copy) all data indicated by this function when it returns. See APP_SSL_read for an example of how this API function is used.

The SSL_ASYNC_sendMessage API is used to send application data to the peer and should not be called until the SSL/TLS handshake is complete. The application layer provides a plaintext data buffer, and this function creates an encrypted SSL/TLS record that is ready for transmission.

The prototype for this function is as follows:

    sbyte4 SSL_ASYNC_sendMessage(
    sbyte4 connectionInstance, sbyte *pBuffer,
    sbyte4 bufferSize, sbyte4 *pBytesSent)

where:

This function allocates memory to hold the SSL/TLS record that it creates and stores the record in the connection context. Mocana recommends that the application retrieve the record and send it on the network before invoking this call again to send fresh data. The call to retrieve the record is shown next.

The SSL_ASYNC_getSendBuffer function is used to copy out the SSL/TLS record created by a prior call to SSL_ASYNC_sendMessage.

The prototype for this function is as follows:

    sbyte4 SSL_ASYNC_getSendBuffer(
    sbyte4 connectionInstance,
    ubyte *data,
    ubyte4 *len)

where:

If the value of len after this function returns is greater than 0, then the caller should send out len bytes of the buffer starting at data. Note that the application may retrieve the currently prepared SSL/TLS record in chunks using one or more calls to SSL_ASYNC_getSendBuffer. If len is 0 when the call returns, it indicates that the current SSL/TLS record has been entirely retrieved, and SSL_ASYNC_sendMessage may now be called to send fresh data.

The SSL_ASYNC_getSendBuffer makes a copy of the SSL/TLS record into the buffer supplied by the application layer. To avoid this duplication, a zero-copy version of the above function is available called SSL_ASYNC_getSendBufferZeroCopy. The function prototype is as follows:

    sbyte4 SSL_ASYNC_getSendBufferZeroCopy(
    sbyte4 connectionInstance,
    ubyte **data, ubyte4 *len)

where:

If the above call indicates that there is data available, the application layer should send it out on the network. Because the application layer gets a reference to a buffer managed by NanoSSL, it must indicate to NanoSSL when it is done with this buffer using a call to SSL_ASYNC_freeSendBufferZeroCopy. Note that the application must not modify the returned buffer in any way.

The SSL_ASYNC_freeSendBufferZeroCopy function must be used with the SSL_ASYNC_getSendBufferZeroCopy function to tell NanoSSL that the pointer to the SSL/TLS record is no longer needed and the buffer may be freed.

The prototype for this function is as follows:

    sbyte4 SSL_ASYNC_freeSendBufferZeroCopy(
    sbyte4 connectionInstance,
    ubyte4 numUnusedBytes)

where:

In typical use cases, numUnusedBytes is set to 0 to indicate that the entire SSL/TLS record has been consumed. In this case, NanoSSL frees the memory holding the record. If the caller sets this to a non-zero value, then NanoSSL retains that many bytes of the current record. The application layer retrieves and processes it later, ideally before it prepares another SSL/TLS record to prevent memory leaks and/or data loss.

The DTLS_init API initializes NanoDTLS client/server internal structures. The application should call this function before starting the application servers or client. The prototype for this function is as follows:

    sbyte4 DTLS_init(sbyte4 numServerConnections, sbyte4 numClientConnections);

where:

The DTLS_acceptConnection API should be called first when the application is the server side of the DTLS connection. It causes NanoDTLS to allocate a connectionInstance as described in Create a NanoSSL Connection Instance. Before this API invocation, the server should have accepted a client UDP connection (in Linux, this step is typically done using a call to the accept() system call). The application should also have allocated and populated a certificate store.

This function returns a connectionInstance on success and a negative response on failure.

The prototype of this function is as follows:

    sbyte4 connectionInstance = DTLS_acceptConnection (
    sbyte4 *pPeerDescr,
    struct certStore *pCertStore)

where:

The DTLS_connect API creates a connection descriptor for a secure NanoDTLS connection with a remote server.

The prototype of this function is as follows:

    sbyte4  DTLS_connect(peerDescr *pPeerDescr, 
     ubyte sessionIdLen, 
     ubyte * sessionId, 
     ubyte * masterSecret,
     const sbyte* dnsName, 
     struct certStore* pCertStore);

where:

The DTLS_ioctl API enables dynamic management (enabling and disabling) of selected features for a specific DTLS session's connection instance.

The prototype of this function is as follows:

    sbyte4  DTLS_ioctl(sbyte4 connectionInstance, ubyte4 setting, void *value);

where:

The DTLS_start API begins the process of establishing a secure connection between a client and server by sending a DTLS \c Hello message to a server.

The prototype of the function is as follows:

    sbyte4  DTLS_start(sbyte4 connectionInstance);

where:

The DTLS_sendMessage API call is used to send application data to the peer and should not be called until the DTLS handshake is complete. The application layer provides a plaintext data buffer, and this function creates an encrypted DTLS record that is ready for transmission.

The prototype for this function is as follows:

    sbyte4 DTLS_sendMessage(
    sbyte4 connectionInstance, sbyte *pBuffer,
    sbyte4 bufferSize, sbyte4 *pBytesSent)

where:

This function allocates memory to hold the DTLS record that it creates. It stores the record in the connection context. It is recommended that the application retrieve the record and send it on the network before invoking this call again to send fresh data. Use the DTLS_getSendBuffer API to retrieve the record.

The DTLS_getSendBuffer API is used to copy out the DTLS record created by a prior call to DTLS_sendMessage.

The prototype for this function is as follows:

    sbyte4 DTLS_getSendBuffer(
    sbyte4 connectionInstance,
    ubyte *data,
    ubyte4 *len)

where:

If the value of len after this function returns is greater than 0, then the caller should send out len bytes of the buffer starting at data. Note that the application may retrieve the currently prepared DTLS record in chunks using one or more calls to DTLS_getSendBuffer. If len is 0 when the call returns, it indicates that the current DTLS record has been entirely retrieved. It is now safe to call DTLS_sendMessage to send fresh data.

The DTLS_recvMessage API returns data received over the DTLS UDP socket to NanoSSL for DTLS protocol processing.

The function prototype for this call is as follows:

    status = DTLS_recvMessage(sbyte4 connectionInstance, 
    ubyte *pBytesReceived, 
    ubyte4 numBytesReceived, 
    ubyte **ppRetBytesReceived, 
    ubyte4 *pRetNumRxBytesRemaining);

where:

The operation of this function from a server perspective is as follows. The server application layer waits to receive a client HELLO message. The server application layer reads UDP socket data in a platform specific manner into a buffer. The argument pRetNumRxBytesRemaining is the number of bytes in the received buffer.

As shown in Figure 2, the application layer must call the DTLS_getRecvBuffer() API to harvest any plaintext data extracted by the previous call to DTLS_recvMessage.

The prototype for this function is as follows:

    sbyte4 DTLS_getRecvBuffer(
    sbyte4 connectionInstance,
    ubyte **data,
    ubyte4 *len,
    ubyte4 *pRetProtocol)

where:

The DTLS_getSessionFlags API returns session flags related DTLS connection.

The prototype for this function is as follows:

    sbyte4  DTLS_getSessionFlags(sbyte4 connectionInstance, 
    ubyte4 *pRetFlagDTLS);

where:

The DTLS_getConnectionInstance API returns a connection instance for the specified src-dst connection. The returned connection instance may be used as a parameter in subsequent calls to NanoDTLS server functions.

The prototype for this function is as follows:

sbyte4 DTLS_getConnectionInstance(MOC_IP_ADDRESS srcAddr, ubyte2 srcPort, MOC_IP_ADDRESS peerAddr, ubyte2 peerPort)

where:

The DTLS_verifyClientHelloCookie API uses a server-generated stateless cookie to verify that a known client is located at its claimed IP address, thereby preventing DOS (denial of service) attacks. Before calling this function (but after the successful return of DTLS_acceptConnection()), the DTLS_SET_HELLO_VERIFIED ioctl must be set to ensure that the server’s handshake and record sequence numbers are set correctly using the following call:

    DTLS_ioctl(connectionInstance, DTLS_SET_HELLO_VERIFIED, 1).

The prototype for this function is as follows:

    sbyte4 DTLS_verifyClientHelloCookie(MOC_IP_ADDRESS peerAddr, ubyte *pReceived, ubyte4  length,ubyte *pToSend, ubyte4 *pToSendLen)

where:

The DTLS_getNextConnectionInstance API returns a server’s next open client connection instance. The application calls this API in an iterative fashion to examine all a server’s client connections in turn, performing necessary message processing and communication for each connection.

The prototype for this function is as follows:

    sbyte4 DTLS_getNextConnectionInstance(ubyte4 *pCookie, sbyte4 *pConnectionInstance, const peerDescr **ppRetPeerDescr)

where:

The DTLS_setSessionFlags API sets a session flags related to DTLS connections. The application may call this function after it calls DTLS_connect().

The prototype for this function is as follows:

    sbyte4  DTLS_setSessionFlags(sbyte4 connectionInstance, 
    ubyte4 flagsDTLS);

where:

The context flags are specified by OR-ing the desired bitmask flag definitions, defined in src/ssl/ssl.h: DTLS_FLAG_ENABLE_SRTP_DATA_SEND. To avoid clearing any flags that are already set, application should first call DTLS_getSessionFlags(), then OR the returned value with the desired new flag and only then call DTLS_setSessionFlags().

The DTLS_closeConnection API closes a NanoDTLS session and releases all the resources that are managed by the NanoDTLS client/server.

The prototype for this function is as follows:

    sbyte4 DTLS_closeConnection(sbyte4 connectionInstance);

where:

The DTLS_shutdown API cleans up memory, mutexes, and shuts down the NanoDTLS stack.

The prototype for this function is as follows:

    sbyte4 DTLS_shutdown(void);

The DTLS_releaseTables API releases the NanoDTLS client’s or server’s internal memory tables. It should only be called after a call to DTLS_shutdown(). To resume communication with a device after calling this function, a new connection must be created and then register encryption keys and an X.509 certificate.

The prototype for this function is as follows:

    sbyte4 DTLS_releaseTables(void);

The CERT_STORE_releaseStore API releases (frees) memory used by a TrustCore SDK certificate store, including all its component structures.

The prototype for this function is as follows:

    sbyte4 CERT_STORE_releaseStore(certStorePtr *ppReleaseStore);

where:

This OpenSSL shim-equivalent method negotiates an SSL/TLS session with a client after accepting a connection from a client and has the handle to the accepted socket. The server starts SSL negotiation on the newly accepted socket by calling SSL_ASYNC_acceptConnection() to obtain a connectionInstance and stores it in s->instance, where s is the SSL structure. There are two cases depending on whether the socket is blocking or non-blocking.

    int appSocket = s->fd;
    s->instance = SSL_ASYNC_acceptConnection(appSocket, pCertStore);
    LOOP until: SSL_SOCK_isSecureConnectionEstablished(s->instance) == TRUE:
    Step 1: numBytesRead = ReadFromTcpSocket(tcpSocket, readBuffer, readBufferSize)
    Step 2: SSL_ASYNC_recvMessage2(s->instance, readBuffer, numBytesRead, &pFirstUnusedByte, &bytesRemaining);
    Step 3: SSL_ASYNC_getSendBuffer(s->instance, WriteBuffer, &numBytesToWrite))
    Step 4: numBytesWritten = WriteToTcpSocket(tcpSocket, WriteBuffer, numBytesToWrite)
    END LOOP
    RETURN status

This OpenSSL-based client calls SSL_connect initiates an SSL/TLS session with a server. It first calls SSL_ASYNC_connect() to obtain a connectionInstance and stores it in s->instance, where s is the SSL structure, and then calls SSL_ASYNC_start() to send a CLIENT HELLO message to the server. After this call, it behaves the same as it does for the server side: APP_SSL_connect goes into a loop waiting to receive responses from the server that in turn triggers the handshake state machine to send out responses until the handshake is complete with either a failure or success. As for the server, there are two cases depending on whether the socket is blocking or non-blocking.

    int appSocket = s->fd;
    s->instance = SSL_ASYNC_connect(appSocket, 0, NULL, NULL, NULL, pCertStore);
    /* Next 3 lines generate a CLIENT HELLO and send it out */
    SSL_ASYNC_start(s->instance)
    SSL_ASYNC_getSendBuffer(s->instance, WriteBuffer,&numBytesToWrite))
    numBytesWritten = WriteToTcpSocket(tcpSocket, WriteBuffer, numBytesToWrite)
    LOOP until: SSL_SOCK_isSecureConnectionEstablished(s->instance) == TRUE:
    Step 1: numBytesRead = ReadFromTcpSocket(tcpSocket, readBuffer, readBufferSize)
    Step 2: SSL_ASYNC_recvMessage2(s->instance, readBuffer, numBytesRead, &pFirstUnusedByte, &bytesRemaining);
    Step 3: SSL_ASYNC_getSendBuffer(s->instance, WriteBuffer, &numBytesToWrite))
    Step 4: numBytesWritten = WriteToTcpSocket(tcpSocket, WriteBuffer, numBytesToWrite)
    END LOOP
    RETURN status

An application calls APP_SSL_write to send data on an SSL/TLS session to the peer.

The following pseudocode describes APP_SSL_write:

    int toSend = num;   
    char *pCurPtr = buf;
    LOOP until: toSend == 0
    Step 1: SSL_ASYNC_sendMessage(s->instance, (sbyte *)pCurPtr, (sbyte4)toSend, &bytesSent);
    toSend -= bytesSent;
    pCurPtr+= bytesSent;
    Step 2: SSL_ASYNC_getSendBuffer(s->instance, WriteBuffer, &numBytesToWrite)
    Step 3: numBytesWritten = WriteToTcpSocket(tcpSocket, WriteBuffer, numBytesToWrite)
    END LOOP

In the loop, there are two NanoSSL API calls:

    int toSend = num;
    char *pCurPtr = buf;
    LOOP until: toSend == 0
    Step 1: SSL_ASYNC_sendMessage(s->instance, (sbyte *)pCurPtr, (sbyte4)toSend, 
    &bytesSent);
    toSend -= bytesSent;
    pCurPtr += bytesSent;
    Step 2: SSL_ASYNC_getSendBufferZeroCopy(s->instance, &WriteBuffer, &numBytesToWrite)
    Step 3: numBytesWritten = WriteToTcpSocket(tcpSocket, WriteBuffer, numBytesToWrite)
    Step 4: SSL_ASYNC_freeSendBufferZeroCopy(s->instance, 0)
    END LOOP

The application calls APP_SSL_read to receive data on an SSL/TLS session from the peer.

The following pseudocode describes APP_SSL_read:

    Step 1: numBytesRead = ReadFromTcpSocket(tcpSocket, readBuffer,readBufferSize)
    Step 2: status = SSL_ASYNC_recvMessage2(s->instance, readBuffer, numBytesRead, 
    &pFirstUnusedByte, &bytesRemaining);
    Step 3: if (status > 0) {
    SSL_ASYNC_getRecvBuffer(s->instance, &pReadPtr, &bytesAvail, &protocol);
    COPY upto 'num' bytes from pReadPtr to 'buf'
    IF 'bytesAvail' IS_GREATER_THAN 'num' STORE (bytesAvail - num) locally
    }

The details of this process are as follows: