Draft of new ipsec.conf text.

-----BEGIN PGP SIGNED MESSAGE-----

Hi all,


Here is a draft of text I propose to add to man ipsec.conf, in order to
explain policy groups. Formatting is not final. I'm looking for feedback
on the text, particularly from DHR. HD's input is also welcome.


Cheers,

Claudia






Add at top:

The optional files under /etc/ipsec.d/policy, including

/etc/ipsec.d/policy/block
/etc/ipsec.d/policy/private
/etc/ipsec.d/policy/private-or-clear
/etc/ipsec.d/policy/clear-or-private
/etc/ipsec.d/policy/clear

contain configuration information to supplement ipsec.conf.
Their contents are not security-sensitive.



Add at end:


POLICY GROUP FILES


The optional files under /etc/ipsec.d/policy are text files. 
Each consists of a list of CIDR blocks, one per line.
White space followed by # followed by anything to the end of the line 
is a comment and is ignored, as are empty lines.

Policy groups are loaded at system start or with
    ipsec setup --rereadgroups

When a policy group is loaded, the system instantiates a connection
of the same name, once for each listed CIDR block. 
That connection must have _right=%group_ or _right=%opportunisticgroup_,
and the system substitutes one of the listed CIDR blocks for _right_.
The system treats the resulting instances as normal connections.

For example, given a suitable connection definition _private_,
and the file /etc/ipsec.d/policy/private with an entry 192.0.2.3,
the system creates a connection instance private#192.0.2.3.
This connection inherits all details from _private_, except that its
right client is 192.0.2.3.


Choosing a connection


When choosing a connection instance, the system prefers the one with
the most specific eroute. It first examines eroute sources, 
and if two or more sources are identical, it compares the eroutes' destinations.
    (Is there a bug here that needs documenting? General vs. instantiated?)

The system therefore only uses a connection instance derived from a policy
group file, if that instance is most specific for the endpoints in question.

If a more specific connection is found, the system attempts to use that 
connection. If that connection is up, the system will use it. If it is routed, 
the system will bring it up. If it is added to the internal database but not 
routed, the system will not use it, but will log a warning.


Implicit Policy Groups

The standard FreeS/WAN install includes several policy groups 
which provide a way of classifying possible clients into security classes. 
These implicit policies apply to the FreeS/WAN host only.

Private is for those the local host talks with encrypted only.
Private-or-clear is for those the local host attempts to talk with 
encrypted, but is willing to talk with in the clear. Clear-or-private
allows talk in the clear, but also allows the remote host to initiate 
encrypted communication. Clear allows only clear communication, while
block allows no communication.

These are implemented by the following implicit connections.


private

The system allows only IPsec secured communication to the listed 
CIDR blocks.

For outbound traffic, the system implements this as follows.

[note to self: I am concerned about the ambiguity in "For outbound/inbound
traffic. May have to explain trigger mechanism for OE to get around this.
May have to explain that anyway.]

If no other connection takes precedence, the system attempts to create an 
IPsec connection opportunistically, by instantiating an instance of the
the _private_ implicit connection for relevant hosts within the listed CIDR
blocks.

For example, if the private file contains the CIDR block 192.0.2.3,
and system has created the instance private#192.0.2.3 where
right=192.0.2.3, the system will again instantiate this instance.
The result is a new connection between the two /32 endpoints which triggered
the opportunistic connection.

If the opportunistic attempt fails, the system blocks traffic.
Outbound blocking is done using eroutes. Inbound blocking is assumed to 
be handled by the firewall, for which we give you no assistance yet.

If no other connection takes precedence, the system accepts requests to 
establish IPsec connections opportunistically for hosts within the listed 
CIDR blocks. 

If no such request occurs, or if the connection attempt
fails, the system blocks traffic as described above.




private-or-clear

The system attempts IPsec secured communication from the host to the 
listed CIDR blocks. On failure, it allows communication without IPsec.

For outbound traffic, the system implements this as follows.

If no other connection takes precedence, the system attempts to create an
IPsec connection opportunistically, by instantiating an instance of the
the _private_ IMPLICIT conn for relevant hosts within the listed
CIDR blocks.

If the opportunistic attempt fails, the system sends traffic without 
IPsec protection.

For inbound traffic, if no other connection takes precedence, the system 
accepts requests to establish IPsec connections opportunistically
for hosts within the listed CIDR blocks. 
If the system has not begun to negotiate such a connection, it accepts 
traffic in the clear.


clear-or-private

The system allows communication without IPsec to the listed CIDR blocks. 
If the peer requests IPsec communication, the system will allow it.
 

If no other connection takes precedence, the system accepts inbound requests 
to establish opportunistic connections for hosts within the listed CIDR blocks.

If no other connection takes precedence, and no suitable connection is up, 
the system sends and accepts traffic in the clear.


clear

The system allows communication to the listed CIDR blocks, but
only without IPsec.

If no other connection takes precedence, the system makes no attempt to 
establish IPsec connections for hosts within these CIDR blocks,
and rejects requests for such connections.


block

The system blocks traffic to and from the listed CIDR blocks.

Outbound blocking is done using eroutes. Inbound blocking is assumed to be 
handled by the firewall, for which we give you no assistance yet.





-----BEGIN PGP SIGNATURE-----
Version: 2.6.3ia
Charset: noconv

iQCVAwUBPlRpi3DIYXPDEHodAQGi2wP/VM/K++i4q7H+HGNCd6oNuj2KUAx1HbVh
dkdV4rvLM7eOd1npZd2yLXO8DlP+LSquD5/IbBDCWIPI+K72ggzfgppW3xCkuXgP
ip72rm0FNuppTf9E7PuRkZJYjm9n5JKeUYpVuO1GFBeTjVilvLtcssT08qhYCCPL
DvhNQxKbin0=
=yvJq
-----END PGP SIGNATURE-----