Integration overview

Start by adding the NanoSec software to your application’s development environment. For detailed instructions on building the necessary components of the TrustCore SDK, refer to the Building TrustCore SDK Components section.

If your operating system doesn’t have a pre-configured TrustCore SDK port, you will need to edit the appropriate abstraction files to port the SDK to your operating system. For guidance, see Porting TrustCore SDK Code.

Decide which products (like IKE and IPsec) and functions (such as debugging and examples) to include in the TrustCore SDK executable. This is done by setting the appropriate compilation flags. For instance, to integrate the IKE server, define the __ENABLE_MOCANA_IKE_SERVER__ flag. For more details, check the sections under Building TrustCore SDK Components, specifically Compilation Flags and Enabling NanoSec MOBIKE Support.

Create the executables and loadable modules. Verify that the TrustCore SDK code can execute on the operating system as described in Building TrustCore SDK Components.

Integrate calls within your application’s code for TrustCore SDK initialization and shutdown. Set up threads for any required TrustCore SDK server components as outlined in NanoSec IKE Integration.

Include calls to TrustCore SDK NanoSec functions for keying, authentication, message processing, and, optionally, certificate management. See NanoSec IPsec Integration for more details.

Add calls to customize IKE configuration for authentication information and application callbacks as described in Dynamic Configuration.

Set up security policies and, if necessary, add manual keying between a device and its peer. For more information, refer to Provisioning.

To maximize the performance of your integration, follow the tuning guidelines provided in Tuning NanoSec IPsec.

Begin by integrating common code initialization and shutdown routines. Add the relevant calls in your application as demonstrated in the /src/examples/mocana_example.c sample module. For further details, see TrustCore SDK Code Initialization –link–.

Add calls within your application to handle NanoSec’s IKE functionalities. This includes initialization, communication, message processing, and the proper shutdown of IKE operations. For further details, see NanoSec IKE Integration –link– and Enabling NanoSec MOBIKE Support –link–.

Enable IPsec operations such as initialization, packet fragmentation, reassembly, and processing. Integrate the corresponding NanoSec function calls within your application’s code as detailed in NanoSec IPsec Integration –link–.

If your application does not already manage certificates, incorporate TrustCore SDK’s certificate management functions to handle certificate validation. For further details, see Using Certificates –link–.

Ensure that your application adheres to the correct shutdown sequence for both IPsec and IKE by integrating the appropriate shutdown calls within your code. For best practices and detailed steps, see Shutdown Sequence –link–.

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

NanoSec IKE includes full support for MOBIKE with no need for additional application coding. Simply follow these guidelines:

To cleanly stop and shut down IPsec and IKE, the following calls should be made in this order:

The figure below shows how IPsec fits within a typical IP stack. Integrating NanoSec involves making a few minor changes to the IP stack.

Figure 1. Packet flow using IPsec within typical IP stack

To integrate NanoSec IPsec, insert two small code blocks near the bottom of an IP stack. As shown in Figure 10 above, IPsec is inserted between the lowest layer (the native packet fragmentation layer) and the IP routing layer.

To insert a bump in the stack:

If an outbound packet requires applying IPsec security protection, the packet may grow slightly because of HMAC (hash message authentication code, which provides data integrity protection) and message padding (for block ciphers encryption); therefore, before calling IPSEC_apply, either ensure that the IP packet’s buffer being processed is large enough (typically 65 bytes of padding for transport mode, and 85 bytes for tunnel mode), or pass in a buffer to use if the packet buffer grows. In the latter case, the original IP packet buffer being processed should be discarded to avoid a memory leak.

Although not as efficient in terms of CPU and memory usage as the recommended BITS integration, NanoSec can be integrated with binary TCP/IP stacks. In this case, NanoSec IPsec code sits between the interface device driver and the binary TCP/IP stack, as shown in Figure 11 below, and provides IP fragmentation and reassembly code. This method is useful in the following situations:

Figure 2. Packet flow using IPsec below a binary IP stack

For BBS implementations, fragmentation should not be performed by the TCP/IP stack. Either disable its fragmentation layer or set its MTU (maximum transmission unit) to the maximum packet size. If the MTU is set to the maximum packet size, the TrustCore SDK stack fragments the secured IP packets to the appropriate MTU size for the network interface.

To process outgoing packets, the BSP (board support package) output driver needs to be customized to add the following calls:

To process incoming packets, customize the BSP input interface to add the following calls:

For BITS implementations, the packet filtering mechanism provided by the target platform can be used instead of modifying the TCP/IP stack directly. For example, on Linux, packets can be intercepted by netfilter hooks.