1: .TH IPSEC.CONF 5 "2012-06-26" "@PACKAGE_VERSION@" "strongSwan"
2: .SH NAME
3: ipsec.conf \- IPsec configuration and connections
4: .SH DESCRIPTION
5: The optional
6: .I ipsec.conf
7: file
8: specifies most configuration and control information for the
9: strongSwan IPsec subsystem.
10: The major exception is secrets for authentication;
11: see
12: .IR ipsec.secrets (5).
13: Its contents are not security-sensitive.
14: .PP
15: The file is a text file, consisting of one or more
16: .IR sections .
17: White space followed by
18: .B #
19: followed by anything to the end of the line
20: is a comment and is ignored,
21: as are empty lines which are not within a section.
22: .PP
23: A line which contains
24: .B include
25: and a file name, separated by white space,
26: is replaced by the contents of that file.
27: If the file name is not a full pathname,
28: it is considered to be relative to the directory containing the
29: including file.
30: Such inclusions can be nested.
31: Only a single filename may be supplied, and it may not contain white space,
32: but it may include shell wildcards (see
33: .IR sh (1));
34: for example:
35: .PP
36: .B include
37: .B "ipsec.*.conf"
38: .PP
39: The intention of the include facility is mostly to permit keeping
40: information on connections, or sets of connections,
41: separate from the main configuration file.
42: This permits such connection descriptions to be changed,
43: copied to the other security gateways involved, etc.,
44: without having to constantly extract them from the configuration
45: file and then insert them back into it.
46: Note also the
47: .B also
48: parameter (described below) which permits splitting a single logical
49: section (e.g. a connection description) into several actual sections.
50: .PP
51: A section
52: begins with a line of the form:
53: .PP
54: .I type
55: .I name
56: .PP
57: where
58: .I type
59: indicates what type of section follows, and
60: .I name
61: is an arbitrary name which distinguishes the section from others
62: of the same type.
63: All subsequent non-empty lines
64: which begin with white space are part of the section.
65: Sections of the same type that share the same name are merged.
66: .PP
67: Lines within the section are generally of the form
68: .PP
69: \ \ \ \ \ \fIparameter\fB=\fIvalue\fR
70: .PP
71: (note the mandatory preceding white space).
72: There can be white space on either side of the
73: .BR = .
74: Parameter names are specific to a section type.
75: .PP
76: An empty
77: .I value
78: stands for the system default value (if any) of the parameter,
79: i.e. it is roughly equivalent to omitting the parameter line entirely. This may
80: be useful to clear a setting inherited from a
81: .B %default
82: section or via
83: .B also
84: parameter (see below).
85: A
86: .I value
87: may contain single spaces (additional white space is reduced to one space).
88: To preserve white space as written enclose the entire
89: .I value
90: in double quotes (\fB"\fR); in such values double quotes themselves may be
91: escaped by prefixing them with
92: .B \\\\
93: characters. A double-quoted string may span multiple lines by ending them with
94: .B \\\\
95: characters (following lines don't have to begin with white space, as that will
96: be preserved). Additionally, the following control characters may be encoded in
97: double-quoted strings: \\n, \\r, \\t, \\b, \\f.
98: .PP
99: Numeric values are specified to be either an ``integer''
100: (a sequence of digits) or a ``decimal number''
101: (sequence of digits optionally followed by `.' and another sequence of digits).
102: .PP
103: There is currently one parameter which is available in any type of
104: section:
105: .TP
106: .B also
107: the value is a section name; the parameters of that section are inherited by
108: the current section. Parameters in the current section always override inherited
109: parameters, even if an
110: .B also
111: follows after them.
112: The specified section must exist and must have the same section type; it doesn't
113: if it is defined before or after the current section.
114: Nesting is permitted, and there may be more than one
115: .B also
116: in a single section (parameters from referenced sections are inherited and
117: overridden in the order of these
118: .B also
119: parameters).
120: .PP
121: A section with name
122: .B %default
123: specifies defaults for sections of the same type. All parameters in it, are
124: inherited by all other sections of that type.
125: .PP
126: Currently there are three types of sections:
127: a
128: .B config
129: section specifies general configuration information for IPsec, a
130: .B conn
131: section specifies an IPsec connection, while a
132: .B ca
133: section specifies special properties of a certification authority.
134: .SH "CONN SECTIONS"
135: A
136: .B conn
137: section contains a
138: .IR "connection specification" ,
139: defining a network connection to be made using IPsec.
140: The name given is arbitrary, and is used to identify the connection.
141: Here's a simple example:
142: .PP
143: .ne 10
144: .nf
145: .ft B
146: .ta 1c
147: conn snt
148: left=192.168.0.1
149: leftsubnet=10.1.0.0/16
150: right=192.168.0.2
151: rightsubnet=10.1.0.0/16
152: keyingtries=%forever
153: auto=add
154: .ft
155: .fi
156: .PP
157: A note on terminology: There are two kinds of communications going on:
158: transmission of user IP packets, and gateway-to-gateway negotiations for
159: keying, rekeying, and general control.
160: The path to control the connection is called 'ISAKMP SA' in IKEv1
161: and 'IKE SA' in the IKEv2 protocol. That what is being negotiated, the kernel
162: level data path, is called 'IPsec SA' or 'Child SA'.
163: strongSwan previously used two separate keying daemons, \fIpluto\fP and
164: \fIcharon\fP. This manual does not discuss \fIpluto\fP options anymore, but
165: only \fIcharon\fP that since strongSwan 5.0 supports both IKEv1 and IKEv2.
166: .PP
167: To avoid trivial editing of the configuration file to suit it to each system
168: involved in a connection,
169: connection specifications are written in terms of
170: .I left
171: and
172: .I right
173: participants,
174: rather than in terms of local and remote.
175: Which participant is considered
176: .I left
177: or
178: .I right
179: is arbitrary;
180: for every connection description an attempt is made to figure out whether
181: the local endpoint should act as the
182: .I left
183: or
184: .I right
185: endpoint. This is done by matching the IP addresses defined for both endpoints
186: with the IP addresses assigned to local network interfaces. If a match is found
187: then the role (left or right) that matches is going to be considered local.
188: If no match is found during startup,
189: .I left
190: is considered local.
191: This permits using identical connection specifications on both ends.
192: There are cases where there is no symmetry; a good convention is to
193: use
194: .I left
195: for the local side and
196: .I right
197: for the remote side (the first letters are a good mnemonic).
198: .PP
199: Many of the parameters relate to one participant or the other;
200: only the ones for
201: .I left
202: are listed here, but every parameter whose name begins with
203: .B left
204: has a
205: .B right
206: counterpart,
207: whose description is the same but with
208: .B left
209: and
210: .B right
211: reversed.
212: .PP
213: Parameters are optional unless marked '(required)'.
214: .SS "CONN PARAMETERS"
215: Unless otherwise noted, for a connection to work,
216: in general it is necessary for the two ends to agree exactly
217: on the values of these parameters.
218: .TP
219: .BR aaa_identity " = <id>"
220: defines the identity of the AAA backend used during IKEv2 EAP authentication.
221: This is required if the EAP client uses a method that verifies the server
222: identity (such as EAP-TLS), but it does not match the IKEv2 gateway identity.
223: .TP
224: .BR aggressive " = yes | " no
225: whether to use IKEv1 Aggressive or Main Mode (the default).
226: .TP
227: .BR ah " = <cipher suites>"
228: comma-separated list of AH algorithms to be used for the connection, e.g.
229: .BR sha1-sha256-modp1024 .
230: The notation is
231: .BR integrity[-dhgroup] .
232: For IKEv2, multiple algorithms (separated by -) of the same type can be included
233: in a single proposal. IKEv1 only includes the first algorithm in a proposal.
234: Only either the
235: .B ah
236: or
237: .B esp
238: keyword may be used, AH+ESP bundles are not supported.
239:
240: There is no default AH cipher suite since by default ESP is used.
241: The daemon adds its extensive default proposal to the configured value. To
242: restrict it to the configured proposal an
243: exclamation mark
244: .RB ( ! )
245: can be added at the end.
246:
247: If
248: .B dh-group
249: is specified, CHILD_SA/Quick Mode setup and rekeying include a separate
250: Diffie-Hellman exchange (refer to the
251: .B esp
252: keyword for details).
253: .TP
254: .BR also " = <name>"
255: includes conn section
256: .BR <name> .
257: .TP
258: .BR auth " = <value>"
259: was used by the
260: .B pluto
261: IKEv1 daemon to use AH integrity protection for ESP encrypted packets, but is
262: not supported in charon. The
263: .B ah
264: keyword specifies algorithms to use for integrity protection with AH, but
265: without encryption. AH+ESP bundles are not supported.
266: .TP
267: .BR authby " = " pubkey " | rsasig | ecdsasig | psk | secret | never | xauthpsk | xauthrsasig"
268: how the two security gateways should authenticate each other;
269: acceptable values are
270: .B psk
271: or
272: .B secret
273: for pre-shared secrets,
274: .B pubkey
275: (the default) for public key signatures as well as the synonyms
276: .B rsasig
277: for RSA digital signatures and
278: .B ecdsasig
279: for Elliptic Curve DSA signatures.
280: .B never
281: can be used if negotiation is never to be attempted or accepted (useful for
282: shunt-only conns).
283: Digital signatures are superior in every way to shared secrets.
284: IKEv1 additionally supports the values
285: .B xauthpsk
286: and
287: .B xauthrsasig
288: that will enable eXtended AUTHentication (XAUTH) in addition to IKEv1 main mode
289: based on shared secrets or digital RSA signatures, respectively.
290: This parameter is deprecated, as two peers do not need to agree on an
291: authentication method in IKEv2. Use the
292: .B leftauth
293: parameter instead to define authentication methods.
294: .TP
295: .BR auto " = " ignore " | add | route | start"
296: what operation, if any, should be done automatically at IPsec startup;
297: currently-accepted values are
298: .BR add ,
299: .BR route ,
300: .B start
301: and
302: .B ignore
303: (the default).
304: .B add
305: loads a connection without starting it.
306: .B route
307: loads a connection and installs kernel traps. If traffic is detected between
308: .B leftsubnet
309: and
310: .BR rightsubnet ,
311: a connection is established.
312: .B start
313: loads a connection and brings it up immediately.
314: .B ignore
315: ignores the connection. This is equal to deleting a connection from the config
316: file.
317: Relevant only locally, other end need not agree on it.
318: .TP
319: .BR closeaction " = " none " | clear | hold | restart"
320: defines the action to take if the remote peer unexpectedly closes a CHILD_SA
321: (see
322: .B dpdaction
323: for meaning of values).
324: A
325: .B closeaction should not be
326: used if the peer uses reauthentication or uniqueids checking, as these events
327: might trigger the defined action when not desired.
328: .TP
329: .BR compress " = yes | " no
330: whether IPComp compression of content is proposed on the connection
331: (link-level compression does not work on encrypted data,
332: so to be effective, compression must be done \fIbefore\fR encryption);
333: acceptable values are
334: .B yes
335: and
336: .B no
337: (the default). A value of
338: .B yes
339: causes the daemon to propose both compressed and uncompressed,
340: and prefer compressed.
341: A value of
342: .B no
343: prevents the daemon from proposing or accepting compression.
344: .TP
345: .BR dpdaction " = " none " | clear | hold | restart"
346: controls the use of the Dead Peer Detection protocol (DPD, RFC 3706) where
347: R_U_THERE notification messages (IKEv1) or empty INFORMATIONAL messages (IKEv2)
348: are periodically sent in order to check the
349: liveliness of the IPsec peer. The values
350: .BR clear ,
351: .BR hold ,
352: and
353: .B restart
354: all activate DPD and determine the action to perform on a timeout. With
355: .B clear
356: the connection is closed with no further actions taken.
357: .B hold
358: installs a trap policy, which will catch matching traffic and tries to
359: re-negotiate the connection on demand.
360: .B restart
361: will immediately trigger an attempt to re-negotiation the connection.
362: The default is
363: .B none
364: which disables the active sending of DPD messages.
365: .TP
366: .BR dpddelay " = " 30s " | <time>"
367: defines the period time interval with which R_U_THERE messages/INFORMATIONAL
368: exchanges are sent to the peer. These are only sent if no other traffic is
369: received. In IKEv2, a value of 0 sends no additional INFORMATIONAL
370: messages and uses only standard messages (such as those to rekey) to detect
371: dead peers.
372: .TP
373: .BR dpdtimeout " = " 150s " | <time>
374: defines the timeout interval, after which all connections to a peer are deleted
375: in case of inactivity. This only applies to IKEv1, in IKEv2 the default
376: retransmission timeout applies, as every exchange is used to detect dead peers.
377: .TP
378: .BR inactivity " = <time>"
379: defines the timeout interval, after which a CHILD_SA is closed if it did
380: not send or receive any traffic. The inactivity counter is reset during CHILD_SA
381: rekeying. This means that the inactivity timeout must be smaller than the
382: rekeying interval to have any effect.
383: .TP
384: .BR eap_identity " = <id>"
385: defines the identity the client uses to reply to an EAP Identity request.
386: If defined on the EAP server, the defined identity will be used as peer
387: identity during EAP authentication. The special value
388: .B %identity
389: uses the EAP Identity method to ask the client for an EAP identity. If not
390: defined, the IKEv2 identity will be used as EAP identity.
391: .TP
392: .BR esp " = <cipher suites>"
393: comma-separated list of ESP encryption/authentication algorithms to be used
394: for the connection, e.g.
395: .BR aes128-sha256 .
396: The notation is
397: .BR encryption-integrity[-dhgroup][-esnmode] .
398: For IKEv2, multiple algorithms (separated by -) of the same type can be included
399: in a single proposal. IKEv1 only includes the first algorithm in a proposal.
400: Only either the
401: .B ah
402: or
403: .B esp
404: keyword may be used, AH+ESP bundles are not supported.
405:
406: Defaults to
407: .BR aes128-sha256 .
408: The daemon adds its extensive default proposal to this default
409: or the configured value. To restrict it to the configured proposal an
410: exclamation mark
411: .RB ( ! )
412: can be added at the end.
413:
414: .BR Note :
415: As a responder, the daemon defaults to selecting the first configured proposal
416: that's also supported by the peer. This may be changed via
417: .BR strongswan.conf (5)
418: to selecting the first acceptable proposal sent by the peer instead. In order to
419: restrict a responder to only accept specific cipher suites, the strict flag
420: .RB ( ! ,
421: exclamation mark) can be used, e.g: aes256-sha512-modp4096!
422:
423: If
424: .B dh-group
425: is specified, CHILD_SA/Quick Mode rekeying and initial negotiation use a
426: separate Diffie-Hellman exchange using the specified group. However, for IKEv2,
427: the keys of the CHILD_SA created implicitly with the IKE_SA will always be
428: derived from the IKE_SA's key material. So any DH group specified here will only
429: apply when the CHILD_SA is later rekeyed or is created with a separate
430: CREATE_CHILD_SA exchange. Therefore, a proposal mismatch might not immediately
431: be noticed when the SA is established, but may later cause rekeying to fail.
432:
433: Valid values for
434: .B esnmode
435: are
436: .B esn
437: and
438: .BR noesn .
439: Specifying both negotiates Extended Sequence Number support with the peer,
440: the default is
441: .B noesn.
442: .TP
443: .BR forceencaps " = yes | " no
444: force UDP encapsulation for ESP packets even if no NAT situation is detected.
445: This may help to surmount restrictive firewalls. In order to force the peer to
446: encapsulate packets, NAT detection payloads are faked.
447: .TP
448: .BR fragmentation " = " yes " | accept | force | no"
449: whether to use IKE fragmentation (proprietary IKEv1 extension or IKEv2
450: fragmentation as per RFC 7383). Acceptable values are
451: .B yes
452: (the default),
453: .BR accept ,
454: .B force
455: and
456: .BR no .
457: If set to
458: .BR yes ,
459: and the peer supports it, oversized IKE messages will be sent in fragments. If
460: set to
461: .BR accept ,
462: support for fragmentation is announced to the peer but the daemon does not send
463: its own messages in fragments. If set to
464: .B force
465: (only supported for IKEv1) the initial IKE message will already be fragmented
466: if required. Finally, setting the option to
467: .B no
468: will disable announcing support for this feature.
469:
470: Note that fragmented IKE messages sent by a peer are always accepted
471: irrespective of the value of this option (even when set to
472: .BR no ).
473: .TP
474: .BR ike " = <cipher suites>"
475: comma-separated list of IKE/ISAKMP SA encryption/authentication algorithms
476: to be used, e.g.
477: .BR aes128-sha256-modp3072 .
478: The notation is
479: .BR encryption-integrity[-prf]-dhgroup .
480: If no PRF is given, the algorithms defined for integrity are used for the PRF.
481: The prf keywords are the same as the integrity algorithms, but have a
482: .B prf
483: prefix (such as
484: .BR prfsha1 ,
485: .B prfsha256
486: or
487: .BR prfaesxcbc ).
488: .br
489: In IKEv2, multiple algorithms and proposals may be included, such as
490: .BR aes128-aes256-sha1-modp3072-modp2048,3des-sha1-md5-modp1024 .
491:
492: Defaults to
493: .BR aes128-sha256-modp3072 .
494: The daemon adds its extensive default proposal to this
495: default or the configured value. To restrict it to the configured proposal an
496: exclamation mark
497: .RB ( ! )
498: can be added at the end.
499:
500: .BR Note :
501: As a responder the daemon accepts the first supported proposal received from
502: the peer. In order to restrict a responder to only accept specific cipher
503: suites, the strict flag
504: .RB ( ! ,
505: exclamation mark) can be used, e.g:
506: .BR aes256-sha512-modp4096!
507: .TP
508: .BR ikedscp " = " 000000 " | <DSCP field>"
509: Differentiated Services Field Codepoint to set on outgoing IKE packets sent
510: from this connection. The value is a six digit binary encoded string defining
511: the Codepoint to set, as defined in RFC 2474.
512: .TP
513: .BR ikelifetime " = " 3h " | <time>"
514: how long the keying channel of a connection (ISAKMP or IKE SA)
515: should last before being renegotiated. Also see EXPIRY/REKEY below.
516: .TP
517: .BR installpolicy " = " yes " | no"
518: decides whether IPsec policies are installed in the kernel by the charon daemon
519: for a given connection. Allows peaceful cooperation e.g. with
520: the Mobile IPv6 daemon mip6d who wants to control the kernel policies.
521: Acceptable values are
522: .B yes
523: (the default) and
524: .BR no .
525: .TP
526: .BR keyexchange " = " ike " | ikev1 | ikev2"
527: which key exchange protocol should be used to initiate the connection.
528: Connections marked with
529: .B ike
530: use IKEv2 when initiating, but accept any protocol version when responding.
531: .TP
532: .BR keyingtries " = " 3 " | <number> | %forever"
533: how many attempts (a whole number or \fB%forever\fP) should be made to
534: negotiate a connection, or a replacement for one, before giving up
535: (default
536: .BR 3 ).
537: The value \fB%forever\fP
538: means 'never give up'.
539: Relevant only locally, other end need not agree on it.
540: .TP
541: .BR left " = <ip address> | <fqdn> | " %any " | <range> | <subnet> "
542: The IP address of the left participant's public-network interface
543: or one of several magic values.
544: The value
545: .B %any
546: (the default) for the local endpoint signifies an address to be filled in (by
547: automatic keying) during negotiation. If the local peer initiates the
548: connection setup the routing table will be queried to determine the correct
549: local IP address.
550: In case the local peer is responding to a connection setup then any IP address
551: that is assigned to a local interface will be accepted.
552:
553: The prefix
554: .B %
555: in front of a fully-qualified domain name or an IP address will implicitly set
556: .BR leftallowany =yes.
557:
558: If
559: .B %any
560: is used for the remote endpoint it literally means any IP address.
561:
562: If an
563: .B FQDN
564: is assigned it is resolved every time a configuration lookup is done. If DNS
565: resolution times out, the lookup is delayed for that time.
566:
567: To limit the connection to a specific range of hosts, a range (
568: .BR 10.1.0.0-10.2.255.255
569: ) or a subnet (
570: .BR 10.1.0.0/16
571: ) can be specified, and multiple addresses, ranges and subnets can be separated
572: by commas. While one can freely combine these items, to initiate the connection
573: at least one non-range/subnet is required.
574:
575: Please note that with the usage of wildcards multiple connection descriptions
576: might match a given incoming connection attempt. The most specific description
577: is used in that case.
578: .TP
579: .BR leftallowany " = yes | " no
580: a modifier for
581: .BR left ,
582: making it behave as
583: .B %any
584: although a concrete IP address or domain name has been assigned.
585: .TP
586: .BR leftauth " = <auth method>"
587: Authentication method to use locally (left) or require from the remote (right)
588: side.
589: Acceptable values are
590: .B pubkey
591: for public key authentication (RSA/ECDSA),
592: .B psk
593: for pre-shared key authentication,
594: .B eap
595: to (require the) use of the Extensible Authentication Protocol in IKEv2, and
596: .B xauth
597: for IKEv1 eXtended Authentication.
598:
599: To require a trustchain public key strength for the remote side, specify the
600: key type followed by the minimum strength in bits (for example
601: .BR ecdsa-384
602: or
603: .BR rsa-2048-ecdsa-256 ).
604: To limit the acceptable set of hashing algorithms for trustchain validation,
605: append hash algorithms to
606: .BR pubkey
607: or a key strength definition (for example
608: .BR pubkey-sha256-sha512 ,
609: .BR rsa-2048-sha256-sha384-sha512 ,
610: or
611: .BR rsa-2048-sha256-ecdsa-256-sha256-sha384 ).
612: Unless disabled in
613: .BR strongswan.conf (5),
614: or explicit IKEv2 signature constraints are configured (see below), such key
615: types and hash algorithms are also applied as constraints against IKEv2
616: signature authentication schemes used by the remote side.
617:
618: If both peers support RFC 7427 ("Signature Authentication in IKEv2") specific
619: hash algorithms to be used during IKEv2 authentication may be configured.
620: The syntax is the same as above, but with ike: prefix. For example, with
621: .B ike:pubkey-sha384-sha256
622: a public key signature scheme with either SHA-384 or SHA-256 would get used for
623: authentication, in that order and depending on the hash algorithms supported by
624: the peer. If no specific hash algorithms are configured, the default is to
625: prefer an algorithm that matches or exceeds the strength of the signature key.
626: If no constraints with ike: prefix are configured any signature scheme
627: constraint (without ike: prefix) will also apply to IKEv2 authentication, unless
628: this is disabled in
629: .BR strongswan.conf (5).
630:
631: To use or require RSASSA-PSS signatures use rsa/pss instead of rsa as in e.g.
632: .BR ike:rsa/pss-sha256 .
633: If \fBpubkey\fR or \fBrsa\fR constraints are configured RSASSA-PSS signatures
634: will only be used/accepted if enabled in
635: .BR strongswan.conf (5).
636:
637: For
638: .BR eap ,
639: an optional EAP method can be appended. Currently defined methods are
640: .BR eap-aka ,
641: .BR eap-gtc ,
642: .BR eap-md5 ,
643: .BR eap-mschapv2 ,
644: .BR eap-peap ,
645: .BR eap-sim ,
646: .BR eap-tls ,
647: .BR eap-ttls ,
648: .BR eap-dynamic ,
649: and
650: .BR eap-radius .
651: Alternatively, IANA assigned EAP method numbers are accepted. Vendor specific
652: EAP methods are defined in the form
653: .B eap-type-vendor
654: .RB "(e.g. " eap-7-12345 ).
655: To specify signature and trust chain constraints for EAP-(T)TLS, append a colon
656: to the EAP method, followed by the key type/size and hash algorithm as discussed
657: above. For
658: .B xauth,
659: an XAuth authentication backend can be specified, such as
660: .B xauth-generic
661: or
662: .BR xauth-eap .
663: If XAuth is used in
664: .BR leftauth ,
665: Hybrid authentication is used. For traditional XAuth authentication, define
666: XAuth in
667: .BR lefauth2 .
668: .TP
669: .BR leftauth2 " = <auth method>"
670: Same as
671: .BR leftauth ,
672: but defines an additional authentication exchange. In IKEv1, only XAuth can be
673: used in the second authentication round. IKEv2 supports multiple complete
674: authentication rounds using "Multiple Authentication Exchanges" defined
675: in RFC 4739. This allows, for example, separated authentication
676: of host and user.
677: .TP
678: .BR leftca " = <issuer dn> | %same"
679: the distinguished name of a certificate authority which is required to
680: lie in the trust path going from the left participant's certificate up
681: to the root certification authority.
682: .B %same
683: means that the value configured for the right participant should be reused.
684: .TP
685: .BR leftca2 " = <issuer dn> | %same"
686: Same as
687: .BR leftca ,
688: but for the second authentication round (IKEv2 only).
689: .TP
690: .BR leftcert " = <path>"
691: the path to the left participant's X.509 certificate. The file can be encoded
692: either in PEM or DER format. OpenPGP certificates are supported as well.
693: Both absolute paths or paths relative to \fI/etc/ipsec.d/certs\fP
694: are accepted. By default
695: .B leftcert
696: sets
697: .B leftid
698: to the distinguished name of the certificate's subject.
699: The left participant's ID can be overridden by specifying a
700: .B leftid
701: value which must be certified by the certificate, though.
702: .br
703: A value in the form
704: .B %smartcard[<slot nr>[@<module>]]:<keyid>
705: defines a specific certificate to load from a PKCS#11 backend for this
706: connection. See ipsec.secrets(5) for details about smartcard definitions.
707: .B leftcert
708: is required only if selecting the certificate with
709: .B leftid
710: is not sufficient, for example if multiple certificates use the same subject.
711: .br
712: Multiple certificate paths or PKCS#11 backends can be specified in a comma
713: separated list. The daemon chooses the certificate based on the received
714: certificate requests if possible before enforcing the first.
715: .TP
716: .BR leftcert2 " = <path>"
717: Same as
718: .B leftcert,
719: but for the second authentication round (IKEv2 only).
720: .TP
721: .BR leftcertpolicy " = <OIDs>"
722: Comma separated list of certificate policy OIDs the peer's certificate must
723: have.
724: OIDs are specified using the numerical dotted representation.
725: .TP
726: .BR leftdns " = <servers>"
727: Comma separated list of DNS server addresses to exchange as configuration
728: attributes. On the initiator, a server is a fixed IPv4/IPv6 address, or
729: .BR %config4 / %config6
730: to request attributes without an address. On the responder,
731: only fixed IPv4/IPv6 addresses are allowed and define DNS servers assigned
732: to the client.
733: .TP
734: .BR leftfirewall " = yes | " no
735: whether the left participant is doing forwarding-firewalling
736: (including masquerading) using iptables for traffic from \fIleftsubnet\fR,
737: which should be turned off (for traffic to the other subnet)
738: once the connection is established;
739: acceptable values are
740: .B yes
741: and
742: .B no
743: (the default).
744: May not be used in the same connection description with
745: .BR leftupdown .
746: Implemented as a parameter to the default \fBipsec _updown\fR script.
747: See notes below.
748: Relevant only locally, other end need not agree on it.
749:
750: If one or both security gateways are doing forwarding firewalling
751: (possibly including masquerading),
752: and this is specified using the firewall parameters,
753: tunnels established with IPsec are exempted from it
754: so that packets can flow unchanged through the tunnels.
755: (This means that all subnets connected in this manner must have
756: distinct, non-overlapping subnet address blocks.)
757: This is done by the default \fBipsec _updown\fR script.
758:
759: In situations calling for more control,
760: it may be preferable for the user to supply his own
761: .I updown
762: script,
763: which makes the appropriate adjustments for his system.
764: .TP
765: .BR leftgroups " = <group list>"
766: a comma separated list of group names. If the
767: .B leftgroups
768: parameter is present then the peer must be a member of at least one
769: of the groups defined by the parameter.
770: .TP
771: .BR leftgroups2 " = <group list>"
772: Same as
773: .B leftgroups,
774: but for the second authentication round defined with
775: .B leftauth2.
776: .TP
777: .BR lefthostaccess " = yes | " no
778: inserts a pair of INPUT and OUTPUT iptables rules using the default
779: \fBipsec _updown\fR script, thus allowing access to the host itself
780: in the case where the host's internal interface is part of the
781: negotiated client subnet.
782: Acceptable values are
783: .B yes
784: and
785: .B no
786: (the default).
787: .TP
788: .BR leftid " = <id>"
789: how the left participant should be identified for authentication;
790: defaults to
791: .B left
792: or the subject of the certificate configured with
793: .BR leftcert .
794: If
795: .B leftcert
796: is configured the identity has to be confirmed by the certificate.
797:
798: Can be an IP address, a fully-qualified domain name, an email address or a
799: Distinguished Name for which the ID type is determined automatically and the
800: string is converted to the appropriate encoding. The rules for this conversion
801: are described in IDENTITY PARSING below.
802:
803: In certain special situations the identity parsing above might be inadequate
804: or produce the wrong result. Examples are the need to encode a FQDN as KEY_ID or
805: the string parser being unable to produce the correct binary ASN.1 encoding of
806: a certificate's DN. For these situations it is possible to enforce a specific
807: identity type and to provide the binary encoding of the identity. To do this a
808: prefix may be used, followed by a colon (:). If the number sign (#) follows the
809: colon, the remaining data is interpreted as hex encoding, otherwise the string
810: is used as is as the identification data.
811: .BR Note :
812: The latter implies that no conversion is performed for non-string identities.
813: For example,
814: \fIipv4:10.0.0.1\fP does not create a valid ID_IPV4_ADDR IKE identity, as it
815: does not get converted to binary 0x0a000001. Instead, one could use
816: \fIipv4:#0a000001\fP to get a valid identity, but just using the implicit type
817: with automatic conversion is usually simpler. The same applies to the ASN.1
818: encoded types. The following prefixes are known:
819: .BR ipv4 ,
820: .BR ipv6 ,
821: .BR rfc822 ,
822: .BR email ,
823: .BR userfqdn ,
824: .BR fqdn ,
825: .BR dns ,
826: .BR asn1dn ,
827: .B asn1gn
828: and
829: .BR keyid .
830: Custom type prefixes may be specified by surrounding the numerical type value by
831: curly brackets.
832:
833: For IKEv2 and
834: .B rightid
835: the prefix
836: .B %
837: in front of the identity prevents the daemon from sending IDr in its IKE_AUTH
838: request and will allow it to verify the configured identity against the subject
839: and subjectAltNames contained in the responder's certificate (otherwise it is
840: only compared with the IDr returned by the responder). The IDr sent by the
841: initiator might otherwise prevent the responder from finding a config if it
842: has configured a different value for
843: .BR leftid .
844: .TP
845: .BR leftid2 " = <id>"
846: identity to use for a second authentication for the left participant
847: (IKEv2 only); defaults to
848: .BR leftid .
849: .TP
850: .BR leftikeport " = <port>"
851: UDP port the left participant uses for IKE communication.
852: If unspecified, port 500 is used with the port floating
853: to 4500 if a NAT is detected or MOBIKE is enabled. Specifying a local IKE port
854: different from the default additionally requires a socket implementation that
855: listens on this port.
856: .TP
857: .BR leftprotoport " = <protocol>/<port>"
858: restrict the traffic selector to a single protocol and/or port. This option
859: is now deprecated, protocol/port information can be defined for each subnet
860: directly in
861: .BR leftsubnet .
862: .TP
863: .BR leftsigkey " = <raw public key> | <path to public key>"
864: the left participant's public key for public key signature authentication,
865: in PKCS#1 format using hex (0x prefix) or base64 (0s prefix) encoding. With the
866: optional
867: .B dns:
868: or
869: .B ssh:
870: prefix in front of 0x or 0s, the public key is expected to be in either
871: the RFC 3110 (not the full RR, only RSA key part) or RFC 4253 public key format,
872: respectively.
873: Also accepted is the path to a file containing the public key in PEM, DER or SSH
874: encoding. Both absolute paths or paths relative to \fI/etc/ipsec.d/certs\fP
875: are accepted.
876: .TP
877: .BR leftsendcert " = never | no | " ifasked " | always | yes"
878: Accepted values are
879: .B never
880: or
881: .BR no ,
882: .B always
883: or
884: .BR yes ,
885: and
886: .BR ifasked " (the default),"
887: the latter meaning that the peer must send a certificate request payload in
888: order to get a certificate in return.
889: .TP
890: .BR leftsourceip " = %config4 | %config6 | <ip address>"
891: Comma separated list of internal source IPs to use in a tunnel, also known as
892: virtual IP. If the value is one of the synonyms
893: .BR %config ,
894: .BR %cfg ,
895: .BR %modeconfig ,
896: or
897: .BR %modecfg ,
898: an address (from the tunnel address family) is requested from the peer. With
899: .B %config4
900: and
901: .B %config6
902: an address of the given address family will be requested explicitly.
903: If an IP address is configured, it will be requested from the responder,
904: which is free to respond with a different address.
905: .TP
906: .BR rightsourceip " = %config | <network>/<netmask> | <from>-<to> | %poolname"
907: Comma separated list of internal source IPs to use in a tunnel for the remote
908: peer. If the value is
909: .B %config
910: on the responder side, the initiator must propose an address which is then
911: echoed back. Also supported are address pools expressed as
912: \fInetwork\fB/\fInetmask\fR
913: and
914: \fIfrom\fB-\fIto\fR
915: or the use of an external IP address pool using %\fIpoolname\fR,
916: where \fIpoolname\fR is the name of the IP address pool used for the lookup.
917: .TP
918: .BR leftsubnet " = <ip subnet>[[<proto/port>]][,...]"
919: private subnet behind the left participant, expressed as
920: \fInetwork\fB/\fInetmask\fR;
921: if omitted, essentially assumed to be \fIleft\fB/32\fR,
922: signifying that the left end of the connection goes to the left participant
923: only. Configured subnets of the peers may differ, the protocol narrows it to
924: the greatest common subnet. In IKEv1, this may lead to problems with other
925: implementations, make sure to configure identical subnets in such
926: configurations. IKEv2 supports multiple subnets separated by commas. IKEv1 only
927: interprets the first subnet of such a definition, unless the Cisco Unity
928: extension plugin is enabled. This is due to a limitation of the IKEv1 protocol,
929: which only allows a single pair of subnets per CHILD_SA. So to tunnel several
930: subnets a conn entry has to be defined and brought up for each pair of subnets.
931:
932: The optional part after each subnet enclosed in square brackets specifies a
933: protocol/port to restrict the selector for that subnet.
934:
935: Examples:
936: .BR leftsubnet=10.0.0.1[tcp/http],10.0.0.2[6/80] " or"
937: .BR leftsubnet=fec1::1[udp],10.0.0.0/16[/53] .
938: Instead of omitting either value
939: .B %any
940: can be used to the same effect, e.g.
941: .BR leftsubnet=fec1::1[udp/%any],10.0.0.0/16[%any/53] .
942:
943: If the protocol is
944: .B icmp
945: or
946: .B ipv6-icmp
947: the port is interpreted as ICMP message type if it is less than 256 or as type
948: and code if it is greater or equal to 256, with the type in the most significant
949: 8 bits and the code in the least significant 8 bits.
950:
951: The port value can alternatively take the value
952: .B %opaque
953: for RFC 4301 OPAQUE selectors, or a numerical range in the form
954: .BR 1024-65535 .
955: None of the kernel backends currently supports opaque or port ranges and uses
956: .B %any
957: for policy installation instead.
958:
959: Instead of specifying a subnet,
960: .B %dynamic
961: can be used to replace it with the IKE address, having the same effect
962: as omitting
963: .B leftsubnet
964: completely. Using
965: .B %dynamic
966: can be used to define multiple dynamic selectors, each having a potentially
967: different protocol/port definition.
968:
969: .TP
970: .BR leftupdown " = <path>"
971: what ``updown'' script to run to adjust routing and/or firewalling
972: when the status of the connection
973: changes (default
974: .BR "ipsec _updown" ).
975: May include positional parameters separated by white space
976: (although this requires enclosing the whole string in quotes);
977: including shell metacharacters is unwise.
978: Relevant only locally, other end need not agree on it. Charon uses the updown
979: script to insert firewall rules only, since routing has been implemented
980: directly into the daemon.
981: .TP
982: .BR lifebytes " = <number>"
983: the number of bytes transmitted over an IPsec SA before it expires.
984: .TP
985: .BR lifepackets " = <number>"
986: the number of packets transmitted over an IPsec SA before it expires.
987: .TP
988: .BR lifetime " = " 1h " | <time>"
989: how long a particular instance of a connection
990: (a set of encryption/authentication keys for user packets) should last,
991: from successful negotiation to expiry;
992: acceptable values are an integer optionally followed by
993: .BR s
994: (a time in seconds)
995: or a decimal number followed by
996: .BR m ,
997: .BR h ,
998: or
999: .B d
1000: (a time
1001: in minutes, hours, or days respectively)
1002: (default
1003: .BR 1h ,
1004: maximum
1005: .BR 24h ).
1006: Normally, the connection is renegotiated (via the keying channel)
1007: before it expires (see
1008: .BR margintime ).
1009: The two ends need not exactly agree on
1010: .BR lifetime ,
1011: although if they do not,
1012: there will be some clutter of superseded connections on the end
1013: which thinks the lifetime is longer. Also see EXPIRY/REKEY below.
1014: .TP
1015: .BR marginbytes " = <number>"
1016: how many bytes before IPsec SA expiry (see
1017: .BR lifebytes )
1018: should attempts to negotiate a replacement begin.
1019: .TP
1020: .BR marginpackets " = <number>"
1021: how many packets before IPsec SA expiry (see
1022: .BR lifepackets )
1023: should attempts to negotiate a replacement begin.
1024: .TP
1025: .BR margintime " = " 9m " | <time>"
1026: how long before connection expiry or keying-channel expiry
1027: should attempts to
1028: negotiate a replacement
1029: begin; acceptable values as for
1030: .B lifetime
1031: (default
1032: .BR 9m ).
1033: Relevant only locally, other end need not agree on it. Also see EXPIRY/REKEY
1034: below.
1035: .TP
1036: .BR mark " = <value>[/<mask>]"
1037: sets an XFRM mark on the inbound policy and outbound
1038: IPsec SA and policy. If the mask is missing then a default
1039: mask of
1040: .B 0xffffffff
1041: is assumed. The special value
1042: .B %unique
1043: assigns a unique value to each newly created IPsec SA. To additionally
1044: make the mark unique for each IPsec SA direction (in/out) the special value
1045: .B %unique-dir
1046: may be used.
1047: .TP
1048: .BR mark_in " = <value>[/<mask>]"
1049: sets an XFRM mark on the inbound policy (not on the SA). If the mask is missing
1050: then a default mask of
1051: .B 0xffffffff
1052: is assumed.
1053: .TP
1054: .BR mark_out " = <value>[/<mask>]"
1055: sets an XFRM mark on the outbound IPsec SA and
1056: policy. If the mask is missing then a default mask of
1057: .B 0xffffffff
1058: is assumed.
1059: .TP
1060: .BR mobike " = " yes " | no"
1061: enables the IKEv2 MOBIKE protocol defined by RFC 4555. Accepted values are
1062: .B yes
1063: (the default) and
1064: .BR no .
1065: If set to
1066: .BR no ,
1067: the charon daemon will not actively propose MOBIKE as initiator and
1068: ignore the MOBIKE_SUPPORTED notify as responder.
1069: .TP
1070: .BR modeconfig " = push | " pull
1071: defines which mode is used to assign a virtual IP.
1072: Accepted values are
1073: .B push
1074: and
1075: .B pull
1076: (the default).
1077: Push mode is currently not supported with IKEv2.
1078: The setting must be the same on both sides.
1079: .TP
1080: .BR reauth " = " yes " | no"
1081: whether rekeying of an IKE_SA should also reauthenticate the peer. In IKEv1,
1082: reauthentication is always done. In IKEv2, a value of
1083: .B no
1084: rekeys without uninstalling the IPsec SAs, a value of
1085: .B yes
1086: (the default) creates a new IKE_SA from scratch and tries to recreate
1087: all IPsec SAs.
1088: .TP
1089: .BR rekey " = " yes " | no"
1090: whether a connection should be renegotiated when it is about to expire;
1091: acceptable values are
1092: .B yes
1093: (the default)
1094: and
1095: .BR no .
1096: The two ends need not agree, but while a value of
1097: .B no
1098: prevents charon from requesting renegotiation,
1099: it does not prevent responding to renegotiation requested from the other end,
1100: so
1101: .B no
1102: will be largely ineffective unless both ends agree on it. Also see
1103: .BR reauth .
1104: .TP
1105: .BR rekeyfuzz " = " 100% " | <percentage>"
1106: maximum percentage by which
1107: .BR marginbytes ,
1108: .B marginpackets
1109: and
1110: .B margintime
1111: should be randomly increased to randomize rekeying intervals
1112: (important for hosts with many connections);
1113: acceptable values are an integer,
1114: which may exceed 100,
1115: followed by a `%'
1116: (defaults to
1117: .BR 100% ).
1118: The value of
1119: .BR marginTYPE ,
1120: after this random increase,
1121: must not exceed
1122: .B lifeTYPE
1123: (where TYPE is one of
1124: .IR bytes ,
1125: .I packets
1126: or
1127: .IR time ).
1128: The value
1129: .B 0%
1130: will suppress randomization.
1131: Relevant only locally, other end need not agree on it. Also see EXPIRY/REKEY
1132: below.
1133: .TP
1134: .BR replay_window " = " \-1 " | <number>"
1135: The IPsec replay window size for this connection. With the default of \-1
1136: the value configured with
1137: .I charon.replay_window
1138: in
1139: .BR strongswan.conf (5)
1140: is used. Larger values than 32 are supported using the Netlink backend only,
1141: a value of 0 disables IPsec replay protection.
1142: .TP
1143: .BR reqid " = <number>"
1144: sets the reqid for a given connection to a pre-configured fixed value.
1145: .TP
1146: .BR sha256_96 " = " no " | yes"
1147: HMAC-SHA-256 is used with 128-bit truncation with IPsec. For compatibility
1148: with implementations that incorrectly use 96-bit truncation this option may be
1149: enabled to configure the shorter truncation length in the kernel. This is not
1150: negotiated, so this only works with peers that use the incorrect truncation
1151: length (or have this option enabled).
1152: .TP
1153: .BR tfc " = <value>"
1154: number of bytes to pad ESP payload data to. Traffic Flow Confidentiality
1155: is currently supported in IKEv2 and applies to outgoing packets only. The
1156: special value
1157: .BR %mtu
1158: fills up ESP packets with padding to have the size of the MTU.
1159: .TP
1160: .BR type " = " tunnel " | transport | transport_proxy | passthrough | drop"
1161: the type of the connection; currently the accepted values
1162: are
1163: .B tunnel
1164: (the default)
1165: signifying a host-to-host, host-to-subnet, or subnet-to-subnet tunnel;
1166: .BR transport ,
1167: signifying host-to-host transport mode;
1168: .BR transport_proxy ,
1169: signifying the special Mobile IPv6 transport proxy mode;
1170: .BR passthrough ,
1171: signifying that no IPsec processing should be done at all;
1172: .BR drop ,
1173: signifying that packets should be discarded.
1174: .TP
1175: .BR xauth " = " client " | server"
1176: specifies the role in the XAuth protocol if activated by
1177: .B authby=xauthpsk
1178: or
1179: .B authby=xauthrsasig.
1180: Accepted values are
1181: .B server
1182: and
1183: .B client
1184: (the default).
1185: .TP
1186: .BR xauth_identity " = <id>"
1187: defines the identity/username the client uses to reply to an XAuth request.
1188: If not defined, the IKEv1 identity will be used as XAuth identity.
1189:
1190: .SS "CONN PARAMETERS: IKEv2 MEDIATION EXTENSION"
1191: The following parameters are relevant to IKEv2 Mediation Extension
1192: operation only.
1193: .TP
1194: .BR mediation " = yes | " no
1195: whether this connection is a mediation connection, ie. whether this
1196: connection is used to mediate other connections. Mediation connections
1197: create no child SA. Acceptable values are
1198: .B no
1199: (the default) and
1200: .BR yes .
1201: .TP
1202: .BR mediated_by " = <name>"
1203: the name of the connection to mediate this connection through. If given,
1204: the connection will be mediated through the named mediation connection.
1205: The mediation connection must set
1206: .BR mediation=yes .
1207: .TP
1208: .BR me_peerid " = <id>"
1209: ID as which the peer is known to the mediation server, ie. which the other
1210: end of this connection uses as its
1211: .B leftid
1212: on its connection to the mediation server. This is the ID we request the
1213: mediation server to mediate us with. If
1214: .B me_peerid
1215: is not given, the
1216: .B rightid
1217: of this connection will be used as peer ID.
1218:
1219: .SH "CA SECTIONS"
1220: These are optional sections that can be used to assign special
1221: parameters to a Certification Authority (CA). Because the daemons
1222: automatically import CA certificates from \fI/etc/ipsec.d/cacerts\fP,
1223: there is no need to explicitly add them with a CA section, unless you
1224: want to assign special parameters (like a CRL) to a CA.
1225: .TP
1226: .BR also " = <name>"
1227: includes ca section
1228: .BR <name> .
1229: .TP
1230: .BR auto " = " ignore " | add"
1231: currently can have either the value
1232: .B ignore
1233: (the default) or
1234: .BR add .
1235: .TP
1236: .BR cacert " = <path>"
1237: defines a path to the CA certificate either relative to
1238: \fI/etc/ipsec.d/cacerts\fP or as an absolute path.
1239: .br
1240: A value in the form
1241: .B %smartcard[<slot nr>[@<module>]]:<keyid>
1242: defines a specific CA certificate to load from a PKCS#11 backend for this CA.
1243: See ipsec.secrets(5) for details about smartcard definitions.
1244: .TP
1245: .BR crluri " = <uri>"
1246: defines a CRL distribution point (ldap, http, or file URI)
1247: .TP
1248: .B crluri1
1249: synonym for
1250: .B crluri.
1251: .TP
1252: .BR crluri2 " = <uri>"
1253: defines an alternative CRL distribution point (ldap, http, or file URI)
1254: .TP
1255: .TP
1256: .BR ocspuri " = <uri>"
1257: defines an OCSP URI.
1258: .TP
1259: .B ocspuri1
1260: synonym for
1261: .B ocspuri.
1262: .TP
1263: .BR ocspuri2 " = <uri>"
1264: defines an alternative OCSP URI.
1265: .TP
1266: .BR certuribase " = <uri>"
1267: defines the base URI for the Hash and URL feature supported by IKEv2.
1268: Instead of exchanging complete certificates, IKEv2 allows one to send an URI
1269: that resolves to the DER encoded certificate. The certificate URIs are built
1270: by appending the SHA1 hash of the DER encoded certificates to this base URI.
1271: .SH "CONFIG SECTIONS"
1272: At present, the only
1273: .B config
1274: section known to the IPsec software is the one named
1275: .BR setup ,
1276: which contains information used when the software is being started.
1277: The currently-accepted
1278: .I parameter
1279: names in a
1280: .B config
1281: .B setup
1282: section are:
1283: .TP
1284: .BR cachecrls " = yes | " no
1285: if enabled, certificate revocation lists (CRLs) fetched via HTTP or LDAP will
1286: be cached in
1287: .I /etc/ipsec.d/crls/
1288: under a unique file name derived from the certification authority's public key.
1289: .TP
1290: .BR charondebug " = <debug list>"
1291: how much charon debugging output should be logged.
1292: A comma separated list containing type/level-pairs may
1293: be specified, e.g:
1294: .B dmn 3, ike 1, net -1.
1295: Acceptable values for types are
1296: .B dmn, mgr, ike, chd, job, cfg, knl, net, asn, enc, lib, esp, tls,
1297: .B tnc, imc, imv, pts
1298: and the level is one of
1299: .B -1, 0, 1, 2, 3, 4
1300: (for silent, audit, control, controlmore, raw, private). By default, the level
1301: is set to
1302: .B 1
1303: for all types. For more flexibility see LOGGER CONFIGURATION in
1304: .IR strongswan.conf (5).
1305: .TP
1306: .BR strictcrlpolicy " = yes | ifuri | " no
1307: defines if a fresh CRL must be available in order for the peer authentication
1308: based on RSA signatures to succeed.
1309: IKEv2 additionally recognizes
1310: .B ifuri
1311: which reverts to
1312: .B yes
1313: if at least one CRL URI is defined and to
1314: .B no
1315: if no URI is known.
1316: .TP
1317: .BR uniqueids " = " yes " | no | never | replace | keep"
1318: whether a particular participant ID should be kept unique,
1319: with any new IKE_SA using an ID deemed to replace all old ones using that ID;
1320: acceptable values are
1321: .B yes
1322: (the default),
1323: .B no
1324: and
1325: .BR never .
1326: Participant IDs normally \fIare\fR unique, so a new IKE_SA using the same ID is
1327: almost invariably intended to replace an old one. The difference between
1328: .B no
1329: and
1330: .B never
1331: is that the daemon will replace old IKE_SAs when receiving an INITIAL_CONTACT
1332: notify if the option is
1333: .B no
1334: but will ignore these notifies if
1335: .B never
1336: is configured.
1337: The daemon also accepts the value
1338: .B replace
1339: which is identical to
1340: .B yes
1341: and the value
1342: .B keep
1343: to reject new IKE_SA setups and keep the duplicate established earlier.
1344:
1345: .SH IDENTITY PARSING
1346: The type and binary encoding of identity strings specified in \fIleftid\fR
1347: are detected as follows:
1348: .IP \[bu]
1349: If the string value contains an equal sign (=) it is assumed to be a
1350: Distinguished Name, with RDNs separated by commas (,) \fIor\fR slashes (/ - the string
1351: must start with a slash to use this syntax). An attempt is made to create a
1352: binary ASN.1 encoding from this string. If that fails the type is set to KEY_ID
1353: with the literal string value adopted as encoding.
1354: .IP \[bu]
1355: If the string value contains an @ the type depends on the position of that
1356: character:
1357: .RS
1358: .IP \[bu]
1359: If the string begins with @# the type is set to KEY_ID and the string following
1360: that prefix is assumed to be the hex-encoded binary value of the identity.
1361: .IP \[bu]
1362: If the string begins with @@ the type is set to USER_FQDN and the encoding is
1363: the literal string after that prefix.
1364: .IP \[bu]
1365: If the string begins with @ the type is set to FQDN and the encoding is the
1366: literal string after that prefix.
1367: .IP \[bu]
1368: All remaining strings containing an @ are assumed to be of type USER_FQDN/RFC822
1369: with the literal string value as encoding.
1370: .RE
1371: .IP \[bu]
1372: If the value does not contain any @ or = characters it is parsed as follows:
1373: .RS
1374: .IP \[bu]
1375: If the value is an empty string, or equals %any[6], 0.0.0.0, ::, or * the
1376: type is set to ID_ANY, which matches any other identity.
1377: .IP \[bu]
1378: If the value contains a colon (:) it is assumed to be an IPv6 address. But if
1379: parsing the address and converting it to its binary encoding fails the type is
1380: set to KEY_ID and the encoding is the literal value.
1381: .IP \[bu]
1382: For all other strings an attempt at parsing them as IPv4 addresses is made. If
1383: that fails the type is set to FQDN and the literal value is adopted as
1384: encoding (this is where domain names and simple names end up).
1385: .RE
1386:
1387: .SH SA EXPIRY/REKEY
1388: The IKE SAs and IPsec SAs negotiated by the daemon can be configured to expire
1389: after a specific amount of time. For IPsec SAs this can also happen after a
1390: specified number of transmitted packets or transmitted bytes. The following
1391: settings can be used to configure this:
1392: .TS
1393: l r l r,- - - -,lB s lB s,a r a r.
1394: Setting Default Setting Default
1395: IKE SA IPsec SA
1396: ikelifetime 3h lifebytes -
1397: lifepackets -
1398: lifetime 1h
1399: .TE
1400: .SS Rekeying
1401: IKE SAs as well as IPsec SAs can be rekeyed before they expire. This can be
1402: configured using the following settings:
1403: .TS
1404: l r l r,- - - -,lB s lB s,a r a r.
1405: Setting Default Setting Default
1406: IKE and IPsec SA IPsec SA
1407: margintime 9m marginbytes -
1408: marginpackets -
1409: .TE
1410: .SS Randomization
1411: To avoid collisions the specified margins are increased randomly before
1412: subtracting them from the expiration limits (see formula below). This is
1413: controlled by the
1414: .B rekeyfuzz
1415: setting:
1416: .TS
1417: l r,- -,lB s,a r.
1418: Setting Default
1419: IKE and IPsec SA
1420: rekeyfuzz 100%
1421: .TE
1422: .PP
1423: Randomization can be disabled by setting
1424: .BR rekeyfuzz " to " 0% .
1425: .SS Formula
1426: The following formula is used to calculate the rekey time of IPsec SAs:
1427: .PP
1428: .EX
1429: rekeytime = lifetime - (margintime + random(0, margintime * rekeyfuzz))
1430: .EE
1431: .PP
1432: It applies equally to IKE SAs and byte and packet limits for IPsec SAs.
1433: .SS Example
1434: Let's consider the default configuration:
1435: .PP
1436: .EX
1437: lifetime = 1h
1438: margintime = 9m
1439: rekeyfuzz = 100%
1440: .EE
1441: .PP
1442: From the formula above follows that the rekey time lies between:
1443: .PP
1444: .EX
1445: rekeytime_min = 1h - (9m + 9m) = 42m
1446: rekeytime_max = 1h - (9m + 0m) = 51m
1447: .EE
1448: .PP
1449: Thus, the daemon will attempt to rekey the IPsec SA at a random time
1450: between 42 and 51 minutes after establishing the SA. Or, in other words,
1451: between 9 and 18 minutes before the SA expires.
1452: .SS Notes
1453: .IP \[bu]
1454: Since the rekeying of an SA needs some time, the margin values must not be
1455: too low.
1456: .IP \[bu]
1457: The value
1458: .B margin... + margin... * rekeyfuzz
1459: must not exceed the original limit. For example, specifying
1460: .B margintime = 30m
1461: in the default configuration is a bad idea as there is a chance that the rekey
1462: time equals zero and, thus, rekeying gets disabled.
1463:
1464: .SH FILES
1465: .nf
1466: /etc/ipsec.conf
1467: /etc/ipsec.d/aacerts
1468: /etc/ipsec.d/acerts
1469: /etc/ipsec.d/cacerts
1470: /etc/ipsec.d/certs
1471: /etc/ipsec.d/crls
1472:
1473: .SH SEE ALSO
1474: strongswan.conf(5), ipsec.secrets(5), ipsec(8)
1475: .SH HISTORY
1476: Originally written for the FreeS/WAN project by Henry Spencer.
1477: Updated and extended for the strongSwan project <http://www.strongswan.org> by
1478: Tobias Brunner, Andreas Steffen and Martin Willi.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to ipsec.conf.5.in CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / strongswan / man