www.beck-ipc.com

@CHIP-RTOS - IP Security Data Structures


    IPC@CHIP® Documentation Index

IP Security Data Structures

Here are the data structures used for the IP Security API.   The reader is assumed to have some familiarity with IP Security. For example, the following abbreviations the reader will hopefully already be familiar with:
  • AH - "Authentication Header", Reference: RFC-4302
  • ESP - "Encapsulating Security Payload", Reference: RFC-4303
  • SA - "Security Association", Reference: RFC-4301

IP Security Overview

All constants and data structures are defined in either the IPSEC.H or TCPIPAPI.H header files.

Notes:
  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).
Contents :

  • tIPSEC_ADDR
  • tIPSEC_FILE_HEADER
  • tIPSEC_POLICY_CONTENT
  • tIPSEC_POLICY_PAIR
  • tIPSEC_POLICY_SELECTOR
  • tIPSEC_TKE_PHASE1
  • tIPSEC_TUNNEL


  • tIPSEC_ADDR


    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. By OR'ing in the USE_OUR_IP flag bit (=0x80) to a local side address selector, any of the @CHIP-RTOS-x86 interfaces will be accepted by the respective policy. (This is the flag that the BeckIPSec tool sets for its local side IP filter when the "IPC@Chip IP" option is selected.)

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.07V1.00

    Top of list
    Index page

    tIPSEC_FILE_HEADER


    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.07V1.00

    Top of list
    Index page

    tIPSEC_POLICY_CONTENT


    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.
        IPSEC_AALG_SHA256HMAC - Use SHA256 HMAC algorithm.
        IPSEC_AALG_SHA384HMAC - Use SHA384 HMAC algorithm.
        IPSEC_AALG_SHA512HMAC - Use SHA512 HMAC algorithm.

      When the RuleFlags specify Authentication Header (AH) then this selection must be either MD5, SHA1, SHA256, SHA384 or SHA512.   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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.07V1.00

    Top of list
    Index page

    tIPSEC_POLICY_PAIR


    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
    bContentIndex
    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).

    IPsec_Policy.gif

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.07V1.00

    Top of list
    Index page

    tIPSEC_POLICY_SELECTOR


    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.07V1.00

    Top of list
    Index page

    tIPSEC_TKE_PHASE1


    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.07V1.00

    Top of list
    Index page

    tIPSEC_TUNNEL


    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.07V1.00

    Top of list
    Index page


    End of document