embedded IPsec source code documentation

Main Page | Alphabetical List | Data Structures | File List | Data Fields | Globals | Related Pages

sa.h File Reference

Detailed Description

Header of Security Association management code.

Author:
Niklaus Schild <n.schild@gmx.ch>
This document is part of embedded IPsec
Copyright (c) 2003 Niklaus Schild and Christian Scheurer, HTI Biel/Bienne
All rights reserved.

Definition in file sa.h.

#include "ipsec/types.h"
#include "ipsec/util.h"
#include "ipsec/ipsec.h"

Go to the source code of this file.

Data Structures

struct  db_set_netif_struct
struct  sa_entry_struct
struct  sad_table_struct
struct  spd_entry_struct
struct  spd_table_struct

Defines

#define IPSEC_MAX_SAD_ENTRIES   (10)
#define IPSEC_MAX_SPD_ENTRIES   (10)
#define IPSEC_FREE   (0)
#define IPSEC_USED   (1)
#define POLICY_APPLY   (0)
#define POLICY_BYPASS   (1)
#define POLICY_DISCARD   (2)
#define IPSEC_TUNNEL   (1)
#define IPSEC_TRANSPORT   (2)
#define IPSEC_DES   (1)
#define IPSEC_3DES   (2)
#define IPSEC_IDEA   (3)
#define IPSEC_HMAC_MD5   (1)
#define IPSEC_HMAC_SHA1   (2)
#define IPSEC_NR_NETIFS   (1)
#define SPD_ENTRY(s1, s2, s3, s4, sn1, sn2, sn3, sn4, d1, d2, d3, d4, dn1, dn2, dn3, dn4, proto, src_port, dest_port, policy, sa_ptr)
#define SAD_ENTRY(d1, d2, d3, d4, dn1, dn2, dn3, dn4, spi, proto, mode, enc_alg, ek1, ek2, ek3, ek4, ek5, ek6, ek7, ek8, ek9, ek10, ek11, ek12, ek13, ek14, ek15, ek16, ek17, ek18, ek19, ek20, ek21, ek22, ek23, ek24, auth_alg, ak1, ak2, ak3, ak4, ak5, ak6, ak7, ak8, ak9, ak10, ak11, ak12, ak13, ak14, ak15, ak16, ak17, ak18, ak19, ak20)
#define EMPTY_SAD_ENTRY
#define EMPTY_SPD_ENTRY

Typedefs

typedef sa_entry_struct sad_entry
typedef spd_entry_struct spd_entry
typedef spd_table_struct spd_table
typedef sad_table_struct sad_table
typedef db_set_netif_struct db_set_netif

Functions

db_set_netif * ipsec_spd_load_dbs (spd_entry *inbound_spd_data, spd_entry *outbound_spd_data, sad_entry *inbound_sad_data, sad_entry *outbound_sad_data)
ipsec_status ipsec_spd_release_dbs (db_set_netif *dbs)
spd_entry * ipsec_spd_get_free (spd_table *table)
spd_entry * ipsec_spd_add (__u32 src, __u32 src_net, __u32 dst, __u32 dst_net, __u8 proto, __u16 src_port, __u16 dst_port, __u8 policy, spd_table *table)
ipsec_status ipsec_spd_del (spd_entry *entry, spd_table *table)
ipsec_status ipsec_spd_add_sa (spd_entry *entry, sad_entry *sa)
spd_entry * ipsec_spd_lookup (ipsec_ip_header *header, spd_table *table)
void ipsec_spd_print_single (spd_entry *entry)
void ipsec_spd_print (spd_table *table)
sad_entry * ipsec_sad_get_free (sad_table *table)
sad_entry * ipsec_sad_add (sad_entry *entry, sad_table *table)
ipsec_status ipsec_sad_del (sad_entry *entry, sad_table *table)
sad_entry * ipsec_sad_lookup (__u32 dest, __u8 proto, __u32 spi, sad_table *table)
void ipsec_sad_print_single (sad_entry *entry)
void ipsec_sad_print (sad_table *table)
__u32 ipsec_sad_get_spi (ipsec_ip_header *header)
ipsec_status ipsec_spd_flush (spd_table *table, spd_entry *def_entry)
ipsec_status ipsec_sad_flush (sad_table *table)

Variables

 mode
 enc_alg
 auth_alg

Define Documentation

#define EMPTY_SAD_ENTRY
 

Value:

{ 0, 0, 0, 0, 0, 0, \
                                                  0, 0, 0, 0, 0, 0, \
< helps to statically configure the SAD entries

Definition at line 177 of file sa.h.

#define EMPTY_SPD_ENTRY
 

Value:

{ 0, 0, 0, 0, 0, 0, \
                                                  0, IPSEC_FREE }
empty, unconfigured SPD entry

Definition at line 188 of file sa.h.

#define IPSEC_3DES   (2)
 

Defines 3DES as the encryption algorithm for an ESP packet

Definition at line 63 of file sa.h.

#define IPSEC_DES   (1)
 

Defines DES as the encryption algorithm for an ESP packet

Definition at line 62 of file sa.h.

#define IPSEC_FREE   (0)
 

Tells you that an SPD entry is free

Definition at line 52 of file sa.h.

#define IPSEC_HMAC_MD5   (1)
 

Defines HMAC-MD5 as the authentication algorithm for an AH or an ESP packet

Definition at line 66 of file sa.h.

#define IPSEC_HMAC_SHA1   (2)
 

Defines HMAC-SHA1 as the authentication algorithm for an AH or an ESP packet

Definition at line 67 of file sa.h.

#define IPSEC_IDEA   (3)
 

Defines IDEA as the encryption algorithm for an ESP packet

Definition at line 64 of file sa.h.

#define IPSEC_MAX_SAD_ENTRIES   (10)
 

Defines the size of SPD entries in the SPD table.

Definition at line 49 of file sa.h.

#define IPSEC_MAX_SPD_ENTRIES   (10)
 

Defines the size of SAD entries in the SAD table.

Definition at line 50 of file sa.h.

#define IPSEC_NR_NETIFS   (1)
 

Defines the number of network interfaces. This is used to reserve space for db_netif_struct's

Definition at line 69 of file sa.h.

#define IPSEC_TRANSPORT   (2)
 

Defines TRANSPORT mode as the mode the packet must be processed

Definition at line 60 of file sa.h.

#define IPSEC_TUNNEL   (1)
 

Defines TUNNEL mode as the mode the packet must be processed

Definition at line 59 of file sa.h.

#define IPSEC_USED   (1)
 

Tells you that an SPD entry is used

Definition at line 53 of file sa.h.

#define POLICY_APPLY   (0)
 

Defines that the policy for this SPD entry means: apply IPsec

Definition at line 55 of file sa.h.

#define POLICY_BYPASS   (1)
 

Defines that the policy for this SPD entry means: bypass IPsec

Definition at line 56 of file sa.h.

#define POLICY_DISCARD   (2)
 

Defines that the policy for this SPD entry means: the packet must be discarded

Definition at line 57 of file sa.h.

#define SAD_ENTRY (  d1,
d2,
d3,
d4,
dn1,
dn2,
dn3,
dn4,
spi,
proto,
mode,
enc_alg,
ek1,
ek2,
ek3,
ek4,
ek5,
ek6,
ek7,
ek8,
ek9,
ek10,
ek11,
ek12,
ek13,
ek14,
ek15,
ek16,
ek17,
ek18,
ek19,
ek20,
ek21,
ek22,
ek23,
ek24,
auth_alg,
ak1,
ak2,
ak3,
ak4,
ak5,
ak6,
ak7,
ak8,
ak9,
ak10,
ak11,
ak12,
ak13,
ak14,
ak15,
ak16,
ak17,
ak18,
ak19,
ak20   ) 
 

Value:

IPSEC_IP4_ADDR_2(d1, d2, d3, d4), \
                        IPSEC_IP4_ADDR_2(dn1, dn2, dn3, dn4), \
                        IPSEC_HTONL(spi), \
                        proto, \

Definition at line 164 of file sa.h.

#define SPD_ENTRY (  s1,
s2,
s3,
s4,
sn1,
sn2,
sn3,
sn4,
d1,
d2,
d3,
d4,
dn1,
dn2,
dn3,
dn4,
proto,
src_port,
dest_port,
policy,
sa_ptr   ) 
 

Value:

IPSEC_IP4_ADDR_NET(s1, s2, s3, s4), \
                        IPSEC_IP4_ADDR_NET(sn1, sn2, sn3, sn4), \
                        IPSEC_IP4_ADDR_NET(d1, d2, d3, d4), \
                        IPSEC_IP4_ADDR_NET(dn1, dn2, dn3, dn4), \
                        proto, IPSEC_HTONS(src_port), IPSEC_HTONS(dest_port), policy, sa_ptr, 0, 0, \
                        IPSEC_USED
helps to statically configure the SPD entries

Definition at line 150 of file sa.h.

Typedef Documentation

typedef struct db_set_netif_struct db_set_netif
 

typedef struct sa_entry_struct sad_entry
 

Security Association Database entry

Definition at line 71 of file sa.h.

typedef struct sad_table_struct sad_table
 

typedef struct spd_entry_struct spd_entry
 

This type hold all values used for one SPD entry

Definition at line 101 of file sa.h.

typedef struct spd_table_struct spd_table
 

Function Documentation

sad_entry* ipsec_sad_add (  sad_entry *  entry,
sad_table *  table
) 
 

Adds an Security Association to an SA table.

The SA entries are added to a statically allocated array of SAD structs. The size is defined by IPSEC_MAX_SAD_ENTRIES, so there cannot be added more entries added as this constant. The order of the entries within the table is not the same as the order within the array. The "table functionality" is implemented in a linked-list, so one must follow the links of the structure to get to the next entry.

Implementation

  1. This function first gets an empty entry out of the table passed by ipsec_spd_load_dbs().
  2. If a free place was found, then the function arguments are copied to the appropriate place.
  3. Then the linked-list is re-linked.

Parameters:
entry pointer to the SA structure which will be copied into the table
table pointer to the table where the SA is added
Returns:
A pointer to the added entry when adding was successful

NULL when the entry could not have been added (no free entry or duplicate)

Todo:
right now there is no special order implemented, maybe this is needed

Todo:
this part needs to be rewritten when an order is introduced

Definition at line 796 of file sa.c.

ipsec_status ipsec_sad_del (  sad_entry *  entry,
sad_table *  table
) 
 

Deletes an Security Association from an SA table.

This function is simple. If the pointer is within the range of the table, then the entry is cleared. If the pointer does not match, nothing happens.

Parameters:
entry Pointer to the SA entry which needs to be deleted
table Pointer to the SA table
Returns:
IPSEC_STATUS_SUCCESS entry was deleted properly

IPSEC_STATUS_FAILURE entry could not be deleted because not found, or invalid pointer

Todo:
right now there is no special order implemented, maybe this is needed

Definition at line 870 of file sa.c.

ipsec_status ipsec_sad_flush (  sad_table *  table  ) 
 

Flushes an SAD table.

Parameters:
table pointer to the SAD table
Returns:
IPSEC_STATUS_SUCCESS if the flush was successful

Definition at line 1104 of file sa.c.

sad_entry* ipsec_sad_get_free (  sad_table *  table  ) 
 

Gives back a pointer to the next free entry from the given SA table.

Todo:
this function should probably be static
Parameters:
table pointer to the SA table
Returns:
pointer to the free entry if one was found

NULL if no free entry was found

Definition at line 756 of file sa.c.

__u32 ipsec_sad_get_spi (  ipsec_ip_header *  header  ) 
 

Returns the SPI from an IPsec header out of an IP packet.

Parameters:
header pointer to the IP header having an IPsec header as payload
Returns:
the SPI if one could be extracted

0 if no SPI could be extracted (not IPsec packet)

Definition at line 1040 of file sa.c.

sad_entry* ipsec_sad_lookup (  __u32  dest,
__u8  proto,
__u32  spi,
sad_table *  table
) 
 

Gives back a pointer to a SA matching the SA selectors.

For incoming packets the IPsec packet must be checked against the inbound SAD and for outgoing packets the packet must be checked against the outbound SAD.

Implementation It simply loops over all entries and returns the first match.

Parameters:
dest destination IP address
proto IPsec protocol
spi Security Parameters Index
table pointer to the SAD table
Returns:
pointer to the SA entry if one matched

NULL if no matching entry was found

Definition at line 940 of file sa.c.

void ipsec_sad_print (  sad_table *  table  ) 
 

Prints a SAD table.

Parameters:
table pointer to the SAD table which will be printed
Returns:
void

Definition at line 1014 of file sa.c.

void ipsec_sad_print_single (  sad_entry *  entry  ) 
 

Prints a single SA entry.

Parameters:
entry pointer to the SA entry which will be printed
Returns:
void

Definition at line 975 of file sa.c.

spd_entry* ipsec_spd_add (  __u32  src,
__u32  src_net,
__u32  dst,
__u32  dst_net,
__u8  proto,
__u16  src_port,
__u16  dst_port,
__u8  policy,
spd_table *  table
) 
 

Adds a Security Policy to an SPD table.

The SPD entries are added to a statically allocated array of SPD structs. The size is defined by IPSEC_MAX_SPD_ENRIES, so there cannot be added more entries added as this constant. The order of the entries within the table is not the same as the order within the array. The "table functionality" is implemented in a linked-list, so one must follow the links of the structure to get to the next entry.

Implementation

  1. This function first gets an empty entry out of the table passed by ipsec_spd_load_dbs().
  2. If a free place was found, then the function arguments are copied to the appropriate place.
  3. Then the linked-list is re-linked.

Parameters:
src IP source address
src_net Netmask for the source address
dst IP destination address
dst_net Netmask for the destination address
proto Transport protocol
src_port Source Port
dst_port Destination Port
policy The policy defining how the packet matching the entry must be processed
table Pointer to the SPD table
Returns:
A pointer to the added entry when adding was successful

NULL when the entry could not have been added (no free entry or duplicate)

Todo:
right now there is no special order implemented, maybe this is needed

Todo:
this part needs to be rewritten when an order is introduced

Definition at line 428 of file sa.c.

ipsec_status ipsec_spd_add_sa (  spd_entry *  entry,
sad_entry *  sa
) 
 

Adds a Security Association to a Security Police.

Parameters:
entry pointer to the SPD entry where the SA should be added
sa a pointer to the SA which is added to the SPD
Returns:
IPSEC_STATUS_SUCCESS the entry was added successfully

Definition at line 496 of file sa.c.

ipsec_status ipsec_spd_del (  spd_entry *  entry,
spd_table *  table
) 
 

Deletes an Security Policy from an SPD table.

This function is simple. If the pointer is within the range of the table, then the entry is cleared. If the pointer does not match, nothing happens.

Parameters:
entry Pointer to the SPD entry which needs to be deleted
table Pointer to the SPD table
Returns:
IPSEC_STATUS_SUCCESS entry was deleted properly

IPSEC_STATUS_FAILURE entry could not be deleted because not found, or invalid pointer

Todo:
right now there is no special order implemented, maybe this is needed

Todo:
probably the SA should also be deleted

Definition at line 523 of file sa.c.

ipsec_status ipsec_spd_flush (  spd_table *  table,
spd_entry *  def_entry
) 
 

Flushes an SPD table and sets a new default entry. The default entry allows to keep a door open for IKE.

Parameters:
table pointer to the SPD table
def_entry pointer to the default entry
Returns:
IPSEC_STATUS_SUCCESS if the flush was successful

IPSEC_STATUS_FAILURE if the flush failed

Definition at line 1078 of file sa.c.

spd_entry* ipsec_spd_get_free (  spd_table *  table  ) 
 

Gives back a pointer to the next free entry from the given SPD table.

Todo:
this function should probably be static
Parameters:
table pointer to the SPD table
Returns:
pointer to the free entry if one was found

NULL if no free entry was found

Definition at line 375 of file sa.c.

db_set_netif* ipsec_spd_load_dbs (  spd_entry *  inbound_spd_data,
spd_entry *  outbound_spd_data,
sad_entry *  inbound_sad_data,
sad_entry *  outbound_sad_data
) 
 

This function initializes the database set, allocated in a per-network manner.

The data which is passed by the pointers should not be used by other functions except the ones of the SA-module. The data passed can be viewed as a place where the SA-module can store its data (Security Policies or Security Associations). The tables which are passed to the function can already be filled up with static configuration data. You can use the SPD_ENTRY and the SAD_ENTRY macro to do this in a nice way.

Implementation

  1. First the function gets a free entry (set of structs) out of the db_sets table.
  2. Then it sets the pointer of this struct members.
  3. On all entries in the table which are not already filled are set to IPSEC_FREE.
  4. In the last and most ugly part of this function tables are linked together so that the linked list is setup properly.

Parameters:
inbound_spd_data pointer to a table where inbound Security Policies will be stored
outbound_spd_data pointer to a table where outbound Security Policies will be stored
inbound_sad_data pointer to a table where inbound Security Associations will be stored
outbound_sad_data pointer to a table where outbound Security Associations will be stored
Returns:
pointer to the initialized set of DB's if the setup was successful

NULL if loading failed

Definition at line 136 of file sa.c.

spd_entry* ipsec_spd_lookup (  ipsec_ip_header *  header,
spd_table *  table
) 
 

Returns an pointer to an SPD entry which matches the packet.

Inbound packets must be checked against the inbound SPD and outbound packets must be checked against the outbound SPD.

Implementation

This function checks all the selector fields of the SPD table. The port numbers are only checked if the protocol is TCP or UDP. An entry which has a value of 0 is the same as the '*' which means everything.

Parameters:
header Pointer to an IP packet which is checked
table Pointer to the SPD inbound/outbound table
Returns:
Pointer to the matching SPD entry

NULL if no entry matched

Todo:
port checking should be implemnted also

Definition at line 597 of file sa.c.

void ipsec_spd_print (  spd_table *  table  ) 
 

Prints a Security Policy Database.

Parameters:
table pointer to the SPD table
Returns:
void

Definition at line 726 of file sa.c.

void ipsec_spd_print_single (  spd_entry *  entry  ) 
 

Prints a single SPD entry.

Parameters:
entry pointer to the SPD entry
Returns:
void

Definition at line 656 of file sa.c.

ipsec_status ipsec_spd_release_dbs (  db_set_netif *  dbs  ) 
 

This function is used to release the structure allocated in ipsec_spd_load_dbs(). The tables which were allocated in ipsec_spd_load_dbs() can now be freely used.

Parameters:
dbs pointer to the set of databases got by ipsec_spd_load_dbs() which has to be released
Returns:
IPSEC_STATUS_SUCCESS if release was successful

IPSEC_STATUS_FAILURE if release was not successful

Definition at line 336 of file sa.c.

Variable Documentation

auth_alg
 

Definition at line 169 of file sa.h.

enc_alg
 

Definition at line 169 of file sa.h.

mode
 

Definition at line 169 of file sa.h.

Copyright 2003 by Christian Scheurer and Niklaus Schild