source code documentation

sa.c File Reference

Detailed Description

This module contains the Security Association code.

Author:: Niklaus Schild <n.schild@gmx.ch>

OUTLINE: Here we implement the Security Association concept from RFC 2401. Both SPD and SAD are implemented. At the time we do not support IKE and SA bundling. For having maximum flexibility two physically different tables (SPD and SAD) were implemented. They both provide functions to manipulate the database during run-time, so that a later IKE or SA-bundling could be implemented. The SPD contains the selector fields on which each IP packet needs to be checked. After outbound packets found their SPD entry, they can access the SA via the SA pointer. Inbound packets can access their SA directly by applying the SPI to the SAD (by performing an SAD lookup). Each IPsec enabled device needs to have its own set of SPD and SAD for each, inbound and outbound processing.

IMPLEMENTATION: To be independent of any memory allocation we store the data from the tables in a statically allocated array. Because entries can be added and removed, a more flexible method for creating the table is needed. The table itself is implemented with a doubly linked list. The data is stored in the array records, but the sequence is determined by the linked-list structure.

One database consists of two objects:

database structure: spd_table inbound_spd_table ;
array for storing data: spd_entry inbound_spd_data[size] ;

The 1st object holds the structure of the database (linked-list) while the second one is memory for storing the objects.

NOTES: To create and use a database you should guaranty the following sequence.

ipsec_spd_load_dbs(): to initialize the table
ipsec_spd_add(): to fill up as many records as the size (usually IPSEC_MAX_SA_ENTRIES) permits
ipsec_spd_del(): to remove entries if required
ipsec_spd_lookup(): to check packets for a matching entry
ipsec_spd_release_dbs(): to clean up

This document is part of embedded IPsec
Copyright (c) 2003 Niklaus Schild and Christian Scheurer, HTI Biel/Bienne
All rights reserved.
This file contains code from the OpenSSL Project
portions Copyright (c) 1998-2003 OpenSSL (www.openssl.org)

Definition in file sa.c.

#include <string.h>
#include "ipsec/debug.h"
#include "ipsec/util.h"
#include "ipsec/sa.h"
#include "ipsec/ah.h"
#include "ipsec/esp.h"

Go to the source code of this file.

Data Structures

struct ipsec_in_ip_struct

Typedefs

typedef ipsec_in_ip_struct ipsec_in_ip

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_add_sa (spd_entry *entry, sad_entry *sa)

ipsec_status ipsec_spd_del (spd_entry *entry, spd_table *table)

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

db_set_netif db_sets [IPSEC_NR_NETIFS]

Typedef Documentation

typedef struct ipsec_in_ip_struct ipsec_in_ip

< IPsec in IP structure - used to access headers inside SA

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

This function first gets an empty entry out of the table passed by ipsec_spd_load_dbs().
If a free place was found, then the function arguments are copied to the appropriate place.
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

This function first gets an empty entry out of the table passed by ipsec_spd_load_dbs().
If a free place was found, then the function arguments are copied to the appropriate place.
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

First the function gets a free entry (set of structs) out of the db_sets table.
Then it sets the pointer of this struct members.
On all entries in the table which are not already filled are set to IPSEC_FREE.
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

db_set_netif db_sets[IPSEC_NR_NETIFS]

This structure holds sets of databases used by one network interface. Each successful call of ipsec_spd_load_dbs() will return a pointer to an entry of this structure array. One entry holds pointers to a inbound and outbound SPD and SAD table.
Definition at line 96 of file sa.c.