Whitelist Plugin¶

Purpose¶

The whitelist plugin checks a successfully authenticated peer identity against an in-memory whitelist. Only identities listed are allowed to connect, connection attempts with other identities get rejected using AUTHENTICATION_FAILED.

The plugin is disabled by default and can be enabled by adding

--enable-whitelist

to the ./configure options.

Implementation¶

Any identity successfully authenticated using any authentication method in every authentication round gets checked against a whitelist. Only whitelisted identities get accepted. The whitelist is held in-memory in a hashtable to have good lookup times. The whitelist is volatile and listed identities get lost during a daemon restart.

To manipulate the whitelist, a UNIX socket exports an interface to add/list/remove whitelisted identities. A simple CLI frontend is provided to manipulate the whitelist.

Configuration¶

The plugin is configured using the following strongswan.conf options:

Key	Default	Description
charon.plugins.whitelist.enabled	No	Enable whitelist checking

This enabled option can be changed during runtime using the whitelist enable/disable commands (see below).

Manipulate whitelist¶

The whitelist ipsec utility, invoked by

ipsec whitelist

can be used to manipulate the whitelist while the daemon is running. It supports the following operations:

Command	Description
ipsec whitelist add <identity>	Add a single identity to the whitelist.
ipsec whitelist remove <identity>	Remove a single identity from the whitelist.
ipsec whitelist add-from [<file>]	Add identities read from a newline separated file, by default stdin.
ipsec whitelist remove-from [<file>]	Remove identities read from a newline separated file, by default stdin.
ipsec whitelist flush [<pattern>]	Flush identities from the whitelist, optionally matching an identity with wildcards.
ipsec whitelist list [<pattern>]	List identities whitelisted, optionally matching an identity with wildcards.
ipsec whitelist enable	Enable whitelist checking.
ipsec whitelist disable	Disable whitelist checking.

Socket interface¶

The Socket interface format is defined source:src/libcharon/plugins/whitelist/whitelist_msg.h. The whitelist CLI utility at source:src/libcharon/plugins/whitelist/whitelist.c is a good starting point to integrate whitelist manipulation to your own frontend.