@CHIP-RTOS - IP Security Data Structures

IP Security Data Structures

• AH - "Authentication Header", Reference: RFC-4302
  
• ESP - "Encapsulating Security Payload", Reference: RFC-4303
  
• SA - "Security Association", Reference: RFC-4301
  

1. Byte alignment is required within all data structures used within the API.
   
2. The phrase "network byte order" means big endian (like Motorola machines, unlike Intel).

This data structure is used to specify the IP address information used by the IP Security Policy selectors.

typedef struct sIPSEC_ADDR
{
    unsigned char Usage ;

    unsigned char Family ;
    unsigned char IpAddr1[16] ;
    unsigned char IpAddr2[16] ;

    unsigned int  Port ;

} tIPSEC_ADDR ;

Comments

Usage

The lower two bits of this byte provide an enumerator which specifies how this IP address information should be applied.   It must be set to one of the following constant values:

IPSEC_WILD_ADDR:    This will match all IP addresses.   This can be used for catch all remaining packets when applying the IPSEC_FLAG_BYPASS policy.   The contents of all IP addresses within this structure are ignored when this enumerator is used.

IPSEC_SINGLE_ADDR:    This value is used when only a single IP address in IpAddr1 is provided.   The content of IpAddr2 is ignored in this case.

IPSEC_RANGE_ADDR:    This value is used when a range of IP addresses is to be used for policy selection. The address range starts at IpAddr1 and ends at IpAddr2, inclusive.

IPSEC_NETMASK_ADDR:    This value is used when a netmask is to be used for policy selection. The IpAddr1 address specifies the network address and IpAddr2 specifies the netmask.

The uppermost two bits (IPSEC_IP1_DOMAIN and IPSEC_IP2_DOMAIN masks) are used as flags by the BeckIPSec Windows PC policy editor tool to designate that a domain name has been stored in the string pool found at the end of the policy file.   These two bits are ignored by the system.

Family

Set to either AF_INET for IPv4 or AF_INET6 for IPv6 addresses.

IpAddr1

This is either a four byte IPv4 or 16 byte IPv6 address, in network byte order.   For the IPv4 case, the trailing 12 bytes are ignored.   Depending on the Usage member, this IP address is either void, a single IP address, the start of a range of IP addresses or a network address.

IpAddr2

This is either a four byte IPv4 or 16 byte IPv6 address, in network byte order.   For the IPv4 case, the trailing 12 bytes are ignored.   Depending on the Usage member, this IP address is either void, the end of a range of IP addresses or a network mask.

Port

Optionally, a specific IP port can be specified for which this security policy should be applied.   This port number is not in network byte order!   Set this member to IPSEC_WILD_PORT if selection by port number is not desired.

Related Topics

API function IPsec_Add_Policy() - Install IPsec policies

tIPSEC_POLICY_SELECTOR - Data structure

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.07	V1.00

This data structure is used internally by the IPsec_Store_Policy API.   It is include here in order that a specification of the IP security's binary policy file can be stated.   These binary files are used by the POLICY_FILE entry in the CHIP.INI file to restore IP security policies at system startup time and by the IPsec_Restore_Policy() API at run time.

#define IPSEC_SANE_HEADER        (0xA345)
#define IPSEC_FILE_VERSION       (1)

typedef struct sIPSEC_FILE_HEADER
{
    unsigned int  Sanity_Check ;
    unsigned int  File_Version ;
    unsigned int  SelectorCount ;
    unsigned int  ContentCount ;
    unsigned int  PairCount ;
    unsigned int  PresharedKeyCount ;
}
tIPSEC_FILE_HEADER ;

Comments

All data in the file is byte aligned with no padding.   Following the header are SelectorCount tIPSEC_POLICY_SELECTOR data structures.

These are then followed by ContentCount tIPSEC_POLICY_CONTENT data structures.

These are followed by PairCount tIPSEC_POLICY_PAIR data structures.

These are followed by PresharedKeyCount zero terminated ASCII strings.   Each of these strings contains both an IP address and preshared key string concatenated with a semicolon in same format used for the PRESHARED_KEY CHIP.INI entries.

If the policy file was created by the BeckIPSec Windows PC tool, then the block of preshared key strings may be followed by a sequence of zero terminated ASCII strings representing IP domain names.   This block of information in the file is ignored by the RTOS.   The sequence of these domain names match the sequence that the IPSEC_IP1_DOMAIN and IPSEC_IP2_DOMAIN flags appear in the Usage bytes of the tIPSEC_ADDR structures and HAVE_DOMAIN_NAME flags bits in the FamilyLocal and FamilyRemote bytes of the tIPSEC_TUNNEL structures.

The total file size must not exceed 64 Kbyte.

Sanity_Check

This signature must be set to 0xA345 in order for the file to be accepted by the system.

File_Version

This entry indicates the format of this file, for compatibility with future changes.   The current setting is 1.

SelectorCount

This count indicates the number of tIPSEC_POLICY_SELECTOR structures.   These data structures follow the header immediately.

ContentCount

This count indicates the number of tIPSEC_POLICY_CONTENT structures.   These data structures follow the tIPSEC_POLICY_SELECTOR data structures immediately.

PairCount

This count indicates the number of tIPSEC_POLICY_PAIR structures.   These data structures follow the tIPSEC_POLICY_CONTENT data structures immediately.

PresharedKeyCount

This count indicates the number of IP address/preshared key string combinations.   These zero terminated strings follow the tIPSEC_POLICY_PAIR data structures immediately.  Note that a single zero termination byte is present at the end of each IP address/preshared key specifier.   These two fields are delimited with a semicolon, ';'.

Related Topics

API function IPsec_Store_Policy() - Create file

API function IPsec_Restore_Policy() - Load IPsec policies

POLICY_FILE - CHIP.INI entry

PRESHARED_KEY - CHIP.INI entry

tIPSEC_POLICY_SELECTOR - Data structure

tIPSEC_POLICY_CONTENT - Data structure

tIPSEC_POLICY_PAIR - Data structure

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.07	V1.00

This data structure is used to specify the content of an IP Security policy.   Each sIPSEC_POLICY_CONTENT may specify either AH or ESP, but not both.   More than one structure is required when both protocols are desired.

typedef struct sIPSEC_POLICY_CONTENT    // For user API
{
    // AH | ESP, tunnel|transport, policy|packet determination
    unsigned int            RuleFlags ;
    // ESP may also have authentication algorithm
    unsigned char           AuthAlg ;
    unsigned char           EncryptAlg ;
    unsigned long           LifeSeconds ;
    unsigned long           LifeKbytes ;
    struct sIPSEC_TUNNEL    Tunnel ;
    unsigned int            _spare_ ;  // reserved (set to zero)

}  tIPSEC_POLICY_CONTENT ;

Comments

The tIPSEC_POLICY_CONTENT structure is used to specify the host end points for an IP Security Tunnel.

RuleFlags

This is a bit field used to designate various specifics about the policy.   One and only one of the following four flags must be set to specify the basic action to be taken on a selected group of IP packets:

IPSEC_FLAG_AH:    Use Authentication Headers.

IPSEC_FLAG_ESP:    Apply Encapsulating Security Payload.

IPSEC_FLAG_BYPASS:    Allow the packets to pass through without any IP security action taken on them.

IPSEC_FLAG_DISCARD:    Discard any IP packets that match this policy's selectors.

A policy is invalid unless exactly one of the above flags is set.

A further policy option is whether to use IP Security tunnel mode between a local and remote security gateway, or to use simply a transport mode directly between this computer and another host.   This decision is specified by one of the following two flags:

IPSEC_FLAG_TUNNEL:    Selects tunnel mode between two security gateways.   When this option is selected, the gateways must be specified using the Tunnel member of this data structure.

IPSEC_FLAG_TRANSPORT:    Selects transport mode.

Finally, there are the following miscellaneous options which can be OR'ed into the RuleFlags to avoid sharing SA under various conditions.

IPSEC_FLAG_RIP_PACKET:    Indicates that each remote IP needs its own SA.   Prohibit sharing.

IPSEC_FLAG_LIP_PACKET:    Indicates that each local IP needs its own SA.   Prohibit sharing.

IPSEC_FLAG_LPT_PACKET:    Indicates that each local port needs its own SA.   Prohibit sharing.

IPSEC_FLAG_PROTO_PACKET:    Indicates that each protocol needs its own SA.   Prohibit sharing.

AuthAlg

This enumerator selects the "Hash Message Authentication Code" (HMAC).    The enumeration values are:


IPSEC_AALG_NULL - Null algorithm (ESP only).
IPSEC_AALG_MD5HMAC - Use MD5 HMAC algorithm.
IPSEC_AALG_SHA1HMAC - Use SHA1 HMAC algorithm.


When the RuleFlags specify Authentication Header (AH) then this selection must be either MD5 or SHA1.   For ESP, the NULL option is also available to indicate that authentication is not desired for the Encapsulated Security Payload header.

EncryptAlg

This enumerator selects the encryption algorithm used with ESP.   This field only applies when the IPSEC_FLAG_ESP flag is set.   The valid enumeration values are:


IPSEC_EALG_NULL - Null algorithm (transparent, perhaps useful for test).
IPSEC_EALG_BLOWFISHCBC - Use Blowfish algorithm ( fastest cipher with 448 bit key).
IPSEC_EALG_DESCBC - Use DES algorithm (weak encryption).
IPSEC_EALG_3DESCBC - Use 3DES algorithm.
IPSEC_EALG_AESCBC - Use AES algorithm with 128 bit key.
IPSEC_EALG_AESCBC_192 - Use AES algorithm with 192 bit key.
IPSEC_EALG_AESCBC_256 - Use AES algorithm with 256 bit key.


The Blowfish cipher will by default use the maximum key length permitted for this cipher method, which is 448 bits. (IKE negotiation with peer could override this default.)

LifeSeconds

Specifies the lifetime in seconds of the IPsec SA's generated according to this policy content.   Set this to zero for the default value of 12 hours.   Internally, this value will be confined to be within the range 120 seconds minimum up to maximum one year.

LifeKbytes

Specifies the lifetime in kilo-bytes of the IPsec SA's generated according to this policy content.   Set this to zero for the default value of 64 Mbyte.   Internally, this value will be confined to be within the range 10 kbyte minimum up to 4 Gbyte maximum.

Tunnel

This structure is used to specify the security gateway IP addresses for tunnel mode.   This field is only used when the IPSEC_FLAG_TUNNEL option flag is set.

Related Topics

API function IPsec_Add_Policy() - Install IPsec policies

tIPSEC_TUNNEL - Data structure

IKE console command - Lists established SA

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.07	V1.00

This data structure is used by the IPsec_Add_Policy() API to map policy selectors to IP security policies.

typedef struct sIPSEC_POLICY_PAIR
{
    unsigned int        iSelectorIndex ;
    unsigned char       bContentIndex ;
    unsigned char       bDirection ;

} tIPSEC_POLICY_PAIR ;

Comments

The selectors and content referred to here are the arguments to the IPsec_Add_Policy() API.

iSelectorIndex

This index designates a tIPSEC_POLICY_SELECTOR structure within the selectors array of structures.

bContentIndex

This index designates a tIPSEC_POLICY_CONTENT structure within the content array of structures.

bDirection

This value is an enumerator used to designate the direction of IP packet traffic to which this policy should be applied.   It can be set to any one of the following three settings.

IPSEC_INBOUND:    This policy will be applied to inbound IP traffic that matches the selection criteria.

IPSEC_OUTBOUND:    This policy will be applied to outbound IP traffic that matches the selection criteria.

IPSEC_BOTH_DIRECTION:    This policy will be applied to IP traffic in either direction that matches the selection criteria.

The relationships between the IP security policy data structures provided by the tIPSEC_POLICY_PAIR are illustrated in the diagram below.   Policy bundles are formed where consecutive tIPSEC_POLICY_PAIR contain the same iSelectorIndex values.   A policy bundle would be used, for example, when both AH and ESP protocols are to be applied.   The protocol transform indicated by the first referenced tIPSEC_POLICY_CONTENT in the bundle is applied to outgoing packets first (inner header), followed by the protocol headers for the subsequent transforms in the bundle.

Note that when both ESP and AH protocols are used, the ESP is normally the inner protocol (listed first in the tIPSEC_POLICY_CONTENT array) and the AH protocol is the outer header (listed after ESP).   This normal ordering of headers is a requirement for interfacing to Microsoft Windows (unless you know of someway to rig Windows otherwise).

Related Topics

API function IPsec_Add_Policy() - Install IPsec policies

tIPSEC_POLICY_CONTENT - Data structure

tIPSEC_POLICY_SELECTOR - Data structure

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.07	V1.00

This data structure is used to select IP security policy based on IP packet address information.

typedef struct sIPSEC_POLICY_SELECTOR
{
    struct sIPSEC_ADDR    Local ;
    struct sIPSEC_ADDR    Remote ;
    unsigned char         Protocol ;
    unsigned char         _pad_ ;       // reserved (set to 0)

} tIPSEC_POLICY_SELECTOR ;

Comments

Local

This tIPSEC_ADDR type structure specifies the IP information for the local side, to be used for policy selection.   A single IP address, a range of IP addresses or a network and netmask can be specified here.

Remote

This tIPSEC_ADDR type structure specifies the IP information for the remote side.   A single IP address, a range of IP addresses or a network and netmask can be specified here.

Protocol

Optionally, the IP protocol can be used for policy selection.   Set this member to IPSEC_WILD_PROTOCOL to ignore IP protocol during policy selection.

Related Topics

API function IPsec_Add_Policy() - Install IPsec policies

tIPSEC_ADDR - Data structure

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.07	V1.00

This data structure is used to specify a transform to be used in IKE's phase 1 proposals.

typedef struct sIPSEC_TKE_PHASE1
{
    unsigned int    eEncryptAlg ;
    unsigned int    eHashAlg ;
    unsigned int    eAuthMethod ;
    unsigned int    iDH_Group ;
    unsigned long   lLifeKbytes ;
    unsigned long   lLifeSeconds ;

} tIPSEC_TKE_PHASE1 ;

Comments

This data structure is used by the IPsec_IKE_Phase1_Set() API.

eEncryptAlg

This enumerator specifies the encryption algorithm to be used.   The options available here are:


IPSEC_IKE_DES_CBC = 1:  Selects DES with Cipher Block Chaining.
IPSEC_IKE_3DES_CBC = 5:  Selects 3DES with Cipher Block Chaining.
IPSEC_IKE_AES_CBC = 7:  Selects AES ("Advanced Encryption Standard" per RFC 3602) with Cipher Block Chaining.

eHashAlg

This enumerator specifies the hash algorithm to be used.   The options available here are:


IPSEC_IKE_MD5 = 1:  Selects MD5.
IPSEC_IKE_SHA1 = 2:  Selects SHA1.

eAuthMethod

This enumerator specifies the authentication method to be used.   The options available here are:


IPSEC_IKE_PRESHARED_KEY = 1
IPSEC_IKE_RSA_SIG = 3

iDH_Group

The Diffie-Hellman group to use.   Valid values are 1, 2, 5 or 14.

lLifeKbytes

Lifetime of Security Association (SA) in kilo-bytes.   Valid values are between 10 and 2097152 (=0x200000), inclusive.   Values outside this range will replaced by the default value of 32768 kByte inside the IPsec_IKE_Phase1_Set() call.   No error code is returned to indicate this out of bounds parameter.

lLifeSeconds

Lifetime of SA in seconds.   Valid values are between 240 to 63072000 seconds (=2 years), inclusive.   Values outside this range are replaced by the default value 86400 seconds (= 1 day) inside the IPsec_IKE_Phase1_Set() call.    No error code is returned to indicate this out of bounds parameter.

Related Topics

API function IPsec_IKE_Phase1_Set() - Add transform

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.07	V1.00

This data structure is used to specify the IP addresses of the end points used for IP Security tunnel mode.   These may be either IPv4 or IPv6.

typedef struct sIPSEC_TUNNEL
{
    // All IP addresses here are in network byte order.
    // Length:  IPv4 - 4 bytes (trailing 12 ignored)
    //          IPv6 - 16 bytes
    unsigned char FamilyLocal ;  // AF_INET (IPv4) or AF_INET6 (IPv6)
    unsigned char IpLocal[16] ;  // IP address of our side of tunnel.

    unsigned char FamilyRemote ; // AF_INET (IPv4) or AF_INET6 (IPv6)
    unsigned char IpRemote[16] ; // IP address of other end of tunnel.

} tIPSEC_TUNNEL ;

Comments

The tIPSEC_TUNNEL structure is used to specify the host end points for an IP Security Tunnel.   The local side of the tunnel must be the IPC@CHIP®.   The USE_OUR_IP flag bit in the FamilyLocal member is recommended for this purpose.

Note that the BeckIPSec policy editor tool may OR in a 0x40 bit into either the FamilyLocal or FamilyRemote bytes here if the respective IP address was entered by domain name.   In this case the domain name will be listed in the ASCII string bucket appended to the end of the policy file.   This extra bit flag will be ignored by the system.

FamilyLocal

Set to either AF_INET for IPv4 or AF_INET6 for IPv6.   Also, the USE_OUR_IP flag can be OR'ed in here with either of the family indicators to signal that the the IPC@CHIP®'s own IP address should be used in place of IpLocal.   This designation is recommended here.

IpLocal

This is either a four byte IPv4 or 16 byte IPv6 address, in network byte order.   For the IPv4 case, the trailing 12 bytes are ignored.   If the USE_OUR_IP flag is set in the FamilyLocal member, then this value is ignored.

FamilyRemote

Set to either AF_INET for IPv4 or AF_INET6 for IPv6.

IpRemote

This is either a four byte IPv4 or 16 byte IPv6 address, in network byte order.   For the IPv4 case, the trailing 12 bytes are ignored.

Related Topics

API function IPsec_Add_Policy() - Install IPsec policies

tIPSEC_POLICY_CONTENT - Data structure

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.07	V1.00