From 532f2347dcad6d1dd553886fe4665ada99f30438 Mon Sep 17 00:00:00 2001 From: Martin Willi Date: Tue, 19 Dec 2006 08:32:25 +0000 Subject: [PATCH] first try to update ipsec.conf manual --- src/starter/ipsec.conf.5 | 403 +++++++-------------------------------- 1 file changed, 69 insertions(+), 334 deletions(-) diff --git a/src/starter/ipsec.conf.5 b/src/starter/ipsec.conf.5 index bea2a63714..981b8d33c7 100644 --- a/src/starter/ipsec.conf.5 +++ b/src/starter/ipsec.conf.5 @@ -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 by Henry Spencer. Extended for the strongSwan project -by Andreas Steffen. +by Andreas Steffen. Update to respect IKEv2 specific configuration +by Martin Willi. .SH BUGS .PP When -- 2.47.2