Annotation of embedaddon/strongswan/man/ipsec.conf.5.in, revision 1.1
1.1 ! misho 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