denozord/strongswan-ext
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first try to update ipsec.conf manual

Browse Source
This commit is contained in:
Martin Willi
2006-12-19 08:32:25 +00:00
parent 6fe03b0af0
commit 532f2347dc
1 changed files with 69 additions and 334 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/starter/ipsec.conf.5
+69 -334
View File
@@ -11,14 +11,7 @@ strongSwan IPsec subsystem.
(The major exception is secrets for authentication;
see
.IR ipsec.secrets (5).)
Its contents are not security-sensitive
.I unless
manual keying is being done for more than just testing,
in which case the encryption/authentication keys in the
descriptions for the manually-keyed connections are very sensitive
(and those connection descriptions
are probably best kept in a separate file,
via the include facility described below).
Its contents are not security-sensitive.
.PP
The file is a text file, consisting of one or more
.IR sections .
@@ -57,11 +50,6 @@ Note also the
parameter (described below) which permits splitting a single logical
section (e.g. a connection description) into several actual sections.
.PP
The first significant line of the file must specify the version
of this specification that it conforms to:
.PP
\fBversion 2\fP
.PP
A section
begins with a line of the form:
.PP
@@ -125,30 +113,6 @@ and there may be more than one
.B also
in a single section,
although it is forbidden to append the same section more than once.)
This allows, for example, keeping the encryption keys
for a connection in a separate file
from the rest of the description, by using both an
.B also
parameter and an
.B include
line.
.PP
Parameter names beginning with
.B x-
(or
.BR X- ,
or
.BR x_ ,
or
.BR X_ )
are reserved for user extensions and will never be assigned meanings
by IPsec.
Parameters with such names must still observe the syntax rules
(limits on characters used in the name;
no white space in a non-quoted value;
no newlines or double quotes within the value).
All other as-yet-unused parameter names are reserved for future IPsec
improvements.
.PP
A section with name
.B %default
@@ -186,10 +150,7 @@ A
section contains a
.IR "connection specification" ,
defining a network connection to be made using IPsec.
The name given is arbitrary, and is used to identify the connection to
.IR ipsec_auto (8)
and
.IR ipsec_manual (8).
The name given is arbitrary, and is used to identify the connection.
Here's a simple example:
.PP
.ne 10
@@ -207,14 +168,15 @@ conn snt
.ft
.fi
.PP
A note on terminology...
In automatic keying, there are two kinds of communications going on:
A note on terminology: There are two kinds of communications going on:
transmission of user IP packets, and gateway-to-gateway negotiations for
keying, rekeying, and general control.
The data path (a set of ``IPsec SAs'') used for user packets is herein
referred to as the ``connection'';
the path used for negotiations (built with ``ISAKMP SAs'') is referred to as
the ``keying channel''.
The path to control the connection is called 'ISAKMP SA' in IKEv1 and
'IKE SA' in the IKEv2 protocol. That what is beeing negotiated, the kernel
level data path, is called 'IPsec SA'.
strongSwan currently uses two separate keying daemons. Pluto handles
all IKEv1 connections, Charon is the new daemon supporting the IKEv2 protocol.
Charon does not support all keywords yet.
.PP
To avoid trivial editing of the configuration file to suit it to each system
involved in a connection,
@@ -252,13 +214,9 @@ and
.B right
reversed.
.PP
Parameters are optional unless marked ``(required)'';
a parameter required for manual keying need not be included for
a connection which will use only automatic keying, and vice versa.
.SS "CONN PARAMETERS: GENERAL"
The following parameters are relevant to both automatic and manual keying.
Unless otherwise noted,
for a connection to work,
Parameters are optional unless marked '(required)'.
.SS "CONN PARAMETERS"
Unless otherwise noted, for a connection to work,
in general it is necessary for the two ends to agree exactly
on the values of these parameters.
.TP 14
@@ -276,6 +234,9 @@ signifying that no IPsec processing should be done at all;
signifying that packets should be discarded; and
.BR reject ,
signifying that packets should be discarded and a diagnostic ICMP returned.
Charon currently supports only the
.BR tunnel
connection type.
.TP
.B left
(required)
@@ -309,22 +270,6 @@ The value
.B %any
signifies an address to be filled in (by automatic keying) during
negotiation.
The value
.B %opportunistic
signifies that both
.B left
and
.B leftnexthop
are to be filled in (by automatic keying) from DNS data for
.BR left 's
client.
The values
.B %group
and
.B %opportunisticgroup
makes this a policy group conn: one that will be instantiated
into a regular or opportunistic conn for each CIDR block listed in the
policy group file with the same name as the conn.
.TP
.B leftsubnet
private subnet behind the left participant, expressed as
@@ -332,7 +277,9 @@ private subnet behind the left participant, expressed as
(actually, any form acceptable to
.IR ipsec_ttosubnet (3));
if omitted, essentially assumed to be \fIleft\fB/32\fR,
signifying that the left end of the connection goes to the left participant only
signifying that the left end of the connection goes to the left participant
only. When using IKEv2, the configured subnet of the peers may differ, the
protocol narrows it to the greates common subnet.
.TP
.B leftnexthop
next-hop gateway IP address for the left participant's connection
@@ -364,7 +311,8 @@ The magic value
.B %direct
signifies a value to be filled in (by automatic keying)
with the peer's address.
Relevant only locally, other end need not agree on it.
Relevant only locally, other end need not agree on it. Currently not supported
in IKEv2.
.TP
.B leftupdown
what ``updown'' script to run to adjust routing and/or firewalling
@@ -377,7 +325,9 @@ including shell metacharacters is unwise.
See
.IR ipsec_pluto (8)
for details.
Relevant only locally, other end need not agree on it.
Relevant only locally, other end need not agree on it. IKEv2 uses the updown
script to insert firewall rules only. Routing is not support and will be
implemented directly into Charon.
.TP
.B leftfirewall
whether the left participant is doing forwarding-firewalling
@@ -395,7 +345,7 @@ Implemented as a parameter to the default
script.
See notes below.
Relevant only locally, other end need not agree on it.
.PP
If one or both security gateways are doing forwarding firewalling
(possibly including masquerading),
and this is specified using the firewall parameters,
@@ -407,51 +357,37 @@ This is done by the default
.I updown
script (see
.IR ipsec_pluto (8)).
.PP
The implementation of this makes certain assumptions about firewall setup,
notably the use of the old
.I ipfwadm
interface to the firewall.
In situations calling for more control,
it may be preferable for the user to supply his own
.I updown
script,
which makes the appropriate adjustments for his system.
.SS "CONN PARAMETERS: AUTOMATIC KEYING"
The following parameters are relevant only to automatic keying,
and are ignored in manual keying.
Unless otherwise noted,
for a connection to work,
in general it is necessary for the two ends to agree exactly
on the values of these parameters.
.TP 14
.TP
.B auto
what operation, if any, should be done automatically at IPsec startup;
currently-accepted values are
.B add
(signifying an
.B ipsec auto
.BR \-\-add ),
,
.B route
(signifying that plus an
.B ipsec auto
.BR \-\-route ),
,
.B start
(signifying that plus an
.B ipsec auto
.BR \-\-up ),
.B manual
(signifying an
.B ipsec
.B manual
.BR \-\-up ),
and
.B ignore
(also the default) (signifying no automatic startup operation).
See the
.B config
.B setup
discussion below.
.
.B add
loads a connection without starting it.
.B route
loads a connection and installs kernel traps. If traffic is detected between
.B leftsubnet
and
.B rightsubnet
, a connection is established.
.B start
loads a connection and brings it up immediatly.
.B ignore
ignores the connection. This is equal to delete a connection from the config
file.
Relevant only locally, other end need not agree on it
(but in general, for an intended-to-be-permanent connection,
both ends should use
@@ -465,6 +401,7 @@ acceptable values are
.B esp
(the default) and
.BR ah .
The IKEv2 daemon currently supports only ESP.
.TP
.B authby
how the two security gateways should authenticate each other;
@@ -477,7 +414,9 @@ for RSA digital signatures (the default),
for either, and
.B never
if negotiation is never to be attempted or accepted (useful for shunt-only conns).
Digital signatures are superior in every way to shared secrets.
Digital signatures are superior in every way to shared secrets. In IKEv2, the
two ends must not agree on this parameter, it is relevant for the own
authentication method only.
.TP
.B compress
whether IPComp compression of content is proposed on the connection
@@ -487,9 +426,7 @@ acceptable values are
.B yes
and
.B no
(the default).
The two ends need not agree.
A value of
(the default). A value of
.B yes
causes IPsec to propose both compressed and uncompressed,
and prefer compressed.
@@ -497,6 +434,7 @@ A value of
.B no
prevents IPsec from proposing compression;
a proposal to compress will still be accepted.
IKEv2 does not support IP compression yet.
.TP
.B dpdaction
controls the use of the Dead Peer Detection protocol (DPD, RFC 3706) where
@@ -546,10 +484,10 @@ no shunt;
.BR drop ,
and
.B reject
have the obvious meanings.
have the obvious meanings. Has no effect in IKEv2 yet.
.TP
.B ikelifetime
how long the keying channel of a connection (buzzphrase: ``ISAKMP SA'')
how long the keying channel of a connection ('ISAKMP/IKE SA')
should last before being renegotiated.
.TP
.B keyexchange
@@ -566,23 +504,13 @@ setting. The default value
currently behaves exactly as
.B ikev1.
.TP
.B keylife
(default set by
.IR ipsec_pluto (8),
currently
.BR 3h ,
maximum
.BR 24h ).
The two-ends-disagree case is similar to that of
.BR keylife .
.TP
.B keyingtries
how many attempts (a whole number or \fB%forever\fP) should be made to
negotiate a connection, or a replacement for one, before giving up
(default
.BR %forever ).
The value \fB%forever\fP
means ``never give up'' (obsolete: this can be written \fB0\fP).
means 'never give up'.
Relevant only locally, other end need not agree on it.
.TP
.B keylife
@@ -639,7 +567,7 @@ parameter is present then the peer must be a member of at least one
of the groups defined by the parameter. Group membership must be certified
by a valid attribute certificate stored in \fI/etc/ipsec.d/acerts\fP thas has been
issued to the peer by a trusted Authorization Authority stored in
\fI/etc/ipsec.d/aacerts\fP.
\fI/etc/ipsec.d/aacerts\fP. Attribute certificates are not supported in IKEv2 yet.
.TP
.B leftid
how
@@ -660,57 +588,11 @@ This is set in \fBconfig setup\fP or by \fIipsec_whack\fP(8)), or, if not set,
it is the IP address in \fB%defaultroute\fP (if that is supported by a TXT record in its reverse domain), or otherwise
it is the system's hostname (if that is supported by a TXT record in its forward domain), or otherwise it is undefined.
.TP
.B leftrsasigkey
the left participant's
public key for RSA signature authentication,
in RFC 2537 format using
.IR ipsec_ttodata (3)
encoding.
The magic value
.B %none
means the same as not specifying a value (useful to override a default).
The value
.B %cert
(the default)
means that the key is extracted from a certificate.
The value
.B %dnsondemand
means the key is to be fetched from DNS at the time it is needed.
The value
.B %dnsonload
means the key is to be fetched from DNS at the time
the connection description is read from
.IR ipsec.conf ;
currently this will be treated as
.B %none
if
.B right=%any
or
.BR right=%opportunistic .
The value
.B %dns
is currently treated as
.B %dnsonload
but will change to
.B %dnsondemand
in the future.
The identity used for the left participant
must be a specific host, not
.B %any
or another magic value.
.B Caution:
if two connection descriptions
specify different public keys for the same
.BR leftid ,
confusion and madness will ensue.
.TP
.B leftrsasigkey2
if present, a second public key.
Either key can authenticate the signature, allowing for key rollover.
.TP
.B leftsourceip
Not supported in IKEv2 yet.
.TP
.B leftsubnetwithin
Not relevant for IKEv2, as subnets are narrowed.
.TP
.B pfs
whether Perfect Forward Secrecy of keys is desired on the connection's
@@ -721,7 +603,9 @@ acceptable values are
.B yes
(the default)
and
.BR no .
.BR no
. IKEv2 always uses PFS for IKE_SA rekeying. PFS for rekeying IPsec SAs is
currently not supported.
.TP
.B rekey
whether a connection should be renegotiated when it is about to expire;
@@ -779,155 +663,26 @@ begin; acceptable values as for
(default
.BR 9m ).
Relevant only locally, other end need not agree on it.
.SS "CONN PARAMETERS: MANUAL KEYING"
The following parameters are relevant only to manual keying,
and are ignored in automatic keying.
Unless otherwise noted,
for a connection to work,
in general it is necessary for the two ends to agree exactly
on the values of these parameters.
A manually-keyed
connection must specify at least one of AH or ESP.
.TP 14
.B spi
(this or
.B spibase
required for manual keying)
the SPI number to be used for the connection (see
.IR ipsec_manual (8));
must be of the form \fB0x\fIhex\fB\fR,
where
.I hex
is one or more hexadecimal digits
(note, it will generally be necessary to make
.I spi
at least
.B 0x100
to be acceptable to KLIPS,
and use of SPIs in the range
.BR 0x100 - 0xfff
is recommended)
.TP 14
.B spibase
(this or
.B spi
required for manual keying)
the base number for the SPIs to be used for the connection (see
.IR ipsec_manual (8));
must be of the form \fB0x\fIhex\fB0\fR,
where
.I hex
is one or more hexadecimal digits
(note, it will generally be necessary to make
.I spibase
at least
.B 0x100
for the resulting SPIs
to be acceptable to KLIPS,
and use of numbers in the range
.BR 0x100 - 0xff0
is recommended)
.TP
.B ike
IKE/ISAKMP SA encryption/authentication algorithm to be used, e.g.
.B aes128-sha1-modp2048
(encryption-integrity-dhgroup).
.TP
.B esp
ESP encryption/authentication algorithm to be used
for the connection, e.g.
.B 3des-md5-96
(must be suitable as a value of
.IR ipsec_spi (8)'s
.B \-\-esp
option);
default is not to use ESP
.TP
.B espenckey
ESP encryption key
(must be suitable as a value of
.IR ipsec_spi (8)'s
.B \-\-enckey
option)
(may be specified separately for each direction using
.B leftespenckey
(leftward SA)
and
.B rightespenckey
parameters)
.TP
.B espauthkey
ESP authentication key
(must be suitable as a value of
.IR ipsec_spi (8)'s
.B \-\-authkey
option)
(may be specified separately for each direction using
.B leftespauthkey
(leftward SA)
and
.B rightespauthkey
parameters)
.TP
.B espreplay_window
ESP replay-window setting,
an integer from
.B 0
(the
.IR ipsec_manual
default, which turns off replay protection) to
.BR 64 ;
relevant only if ESP authentication is being used
.TP
.B leftespspi
SPI to be used for the leftward ESP SA, overriding
automatic assignment using
.B spi
or
.BR spibase ;
typically a hexadecimal number beginning with
.B 0x
.B 3des-md5
(encryption-integrity).
.TP
.B ah
AH authentication algorithm to be used
for the connection, e.g.
.B hmac-md5-96
(must be suitable as a value of
.IR ipsec_spi (8)'s
.B \-\-ah
option);
default is not to use AH
.TP
.B ahkey
(required if
.B ah
is present) AH authentication key
(must be suitable as a value of
.IR ipsec_spi (8)'s
.B \-\-authkey
option)
(may be specified separately for each direction using
.B leftahkey
(leftward SA)
and
.B rightahkey
parameters)
.TP
.B ahreplay_window
AH replay-window setting,
an integer from
.B 0
(the
.I ipsec_manual
default, which turns off replay protection) to
.B 64
.TP
.B leftahspi
SPI to be used for the leftward AH SA, overriding
automatic assignment using
.B spi
or
.BR spibase ;
typically a hexadecimal number beginning with
.B 0x
.B hmac-md5.
.SH "CA SECTIONS"
This are optional sections that can be used to assign special
parameters to a Certification Authority (CA).
parameters to a Certification Authority (CA). These parameters are not
supported in IKEv2 yet.
.TP 10
.B auto
currently can have either the value
@@ -1054,20 +809,6 @@ startup/shutdown log messages,
default
.BR daemon.error .
.TP
.B klipsdebug
how much KLIPS debugging output should be logged.
An empty value,
or the magic value
.BR none ,
means no debugging output (the default).
The magic value
.B all
means full output.
Otherwise only the specified types of output
(a quoted list, names separated by white space) are enabled;
for details on available debugging types, see
.IR ipsec_klipsdebug (8).
.TP
.B plutodebug
how much Pluto debugging output should be logged.
An empty value,
@@ -1112,13 +853,6 @@ dump core?
The empty value (the default) means they are not
allowed to.
.TP
.B manualstart
which manually-keyed connections to set up at startup
(empty, a name, or a quoted list of names separated by white space);
see
.IR ipsec_manual (8).
Default is none.
.TP
.B pluto
whether to start Pluto or not;
Values are
@@ -1244,7 +978,8 @@ Written for the FreeS/WAN project
<http://www.freeswan.org>
by Henry Spencer. Extended for the strongSwan project
<http://www.strongswan.org>
by Andreas Steffen.
by Andreas Steffen. Update to respect IKEv2 specific configuration
by Martin Willi.
.SH BUGS
.PP
When