Skip to main content

Configure NanoSec IKE

This section describes how to configure the NanoSec stack using automatic keys, how to populate the SADB (security association database), and how to request IKE services to establish an SA (security association).

Phase 1 Key Exchange Modes

IKE SAs can be established in either of two key exchange modes:

  • Main mode key exchange: Uses six messages (three round trips).

  • Aggressive mode key exchange: Uses half the number of messages used by main mode key exchange. Although identity protection is not provided, thereby making aggressive mode key exchange less desirable, this mode is the only exchange possible in remote access situations where the address of the initiator cannot be known by the responder and both parties require the use of preshared key authentication.

Aggressive mode is faster, but main mode is more flexible. To use aggressive mode, the __ENABLE_IKE_AGGRESSIVE_MODE__ compiler flag must be defined.

IKE Configuration Data Structure (ikeSettings)

The ikeSettings data structure defined in ike.h is used for IKE automatic keying and SA configuration. Which products and features that have been included by defining the appropriate flags in moptions.h determine the fields and callback functions that are present in this structure. Each included callback function should be customized for an application and then registered by assigning it to the appropriate structure function pointer(s).

The default values for the following basic settings are suitable for most systems:

IKE_ikeSettings()->ikeBufferSize = 2048;

IKE_ikeSettings()->ikeTimeoutNegotiation = 15;

IKE_ikeSettings()->ikeTimeoutEvent = 60;

The IKE version (IKEv1 or IKv2, which is applicable when the host acts as the initiator) should be specified by setting the following:

IKE_ikeSettings()->ikeVersion = 1;    /* 1=IKEv1, 2=IKEv2 */

Additionally, values should be specified for the following SA (security association) settings:

  • Phase 1 SA Lifetimes: Set the proposed expiration and maximum lifetimes (in seconds) to use as the initiator and responder:

    • Initiator: When the application is the IKE initiator, it proposes an expiration time (the value of ikeP1LifeSecs) to the responder. The responder may accept it or propose a shorter expiration time (which the NanoSec IKE initiator accepts.

    • Responder: When the application is the IKE responder, it checks whether the initiator’s proposed expiration time is shorter than or equal to the maximum lifetime (the value of ikeP1LifeSecsMax). If it is, then the time is accepted; if it is not, the NanoSec IKE responder proposes its maximum lifetime, which the initiator may accept or reject.

The default values for the lifetime settings are as follows:

IKE_ikeSettings()->ikeP1LifeSecs = 3600;

IKE_ikeSettings()->ikeP1LifeSecsMax = 86400;

To propose an infinite lifetime (i.e., no expiration), set ikeP1LifeSecs to 0.

  • Phase 2 SA Lifetimes: Set the proposed expiration and maximum lifetimes (in seconds) to use as the initiator and responder:

    • Initiator: When the application is the IKE initiator, it proposes an expiration time (the value of ikeP2LifeSecs) to the responder. The responder may accept it or propose a shorter expiration time, which the NanoSec IKE initiator accepts.

    • Responder: When the application is the IKE responder, it checks whether the initiator’s proposed expiration time is shorter than or equal to the maximum lifetime (the value of ikeP2LifeSecsMax). If it is, then the time is accepted; if it is not, then the TrustCore SDK NanoSec IKE responder proposes its maximum lifetime, which the initiator may accept or reject.

The default values for the lifetime settings are as follows:

IKE_ikeSettings()->ikeP2LifeSecs = 28800;

IKE_ikeSettings()->ikeP2LifeSecsMax = 86400;

To propose an infinite lifetime (that is, no expiration), set ikeP2LifeSecs to 0.

  • Exchange Modes: Set the Perfect Forward Security (PFS)

    IKE_ikeSettings()->ikeP2PFS = -1;  /* Use the same group as Phase 1*/

    Setting ikeP2PFS to 0 specifies No Perfect Forward Security, in which case keying material from the Phase 1 DH exchange is used. Other valid settings are groups 1, 2, 5 and 14.

  • IKEv2 Redirect: Set the redirect mechanism for IKEv2 that enables a VPN gateway to redirect the VPN client to another gateway.

    IKE_ikeSettings()->redirectGwAddr = <redirect-ip-addr>

To enable this feature, the __ENABLE_IKE_REDIRECT__ flag must be defined in moptions.h.

This feature is a redirect mechanism for IKEv2 that enables a VPN gateway to redirect the VPN client to another peer server or gateway. If both endpoints of the IKE connection support redirection, redirects are supported for SA_INIT and during key authorized exchanges. For more information about IKEv2 redirect, refer to RFC 6586, Redirect Mechanism for the Internet Key Exchange Protocol Version 2 (IKEv2), http://tools.ietf.org/html//rfc5685.

  • IKE Server Callback Functions: Register the application-specific callback functions for IKE to invoke. These callbacks must be customized for the application; refer to the sample code in examples/ike_example.c for details.

    IKE_ikeSettings()->funcPtrIkeXchgSend = IKE_SAMPLE_ikeXchgSend;

/* Sends an exchange message to a peer's IKE server. */

IKE_ikeSettings()->funcPtrIkeEvtSend = IKE_SAMPLE_ikeEvtSend;

/* Sends an event message to the host IKE server.

(The IPsec instance does this to request new SAs). */

IKE_ikeSettings()->funcPtrIkeGetHostAddr = IKE_SAMPLE_ikeGetHostAddr;

/* Retrieves IP addressof the (local) host IKE server. */

IKE Host Status Change Handler Types

An application can handle IKE host status changes by implementing the ikeSettings‑>funcPtrIkeStatHdlr callback function. The table below lists the status changes that cause the callback function to be invoked, along with their corresponding function parameter values.

Table 1. Predefined Constants

Name

Value

telnet

23

http

80

localhost

127.0.0.1


In this section: