Annotation of embedaddon/strongswan/src/swanctl/swanctl.conf.5.main, revision 1.1
1.1 ! misho 1: .TP
! 2: .B connections
! 3: .br
! 4: Section defining IKE connection configurations.
! 5:
! 6: The connections section defines IKE connection configurations, each in its own
! 7: subsections. In the keyword description below, the connection is named
! 8: .RI "" "<conn>" ","
! 9: but an arbitrary yet unique connection name can be chosen for each connection
! 10: subsection.
! 11:
! 12: .TP
! 13: .B connections.<conn>
! 14: .br
! 15: Section for an IKE connection named <conn>.
! 16:
! 17: .TP
! 18: .BR connections.<conn>.version " [0]"
! 19: IKE major version to use for connection.
! 20: .RI "" "1" ""
! 21: uses IKEv1 aka ISAKMP,
! 22: .RI "" "2" ""
! 23: uses
! 24: IKEv2. A connection using the default of
! 25: .RI "" "0" ""
! 26: accepts both IKEv1 and IKEv2 as
! 27: responder, and initiates the connection actively with IKEv2.
! 28:
! 29: .TP
! 30: .BR connections.<conn>.local_addrs " [%any]"
! 31: Local address(es) to use for IKE communication, comma separated. Takes single
! 32: IPv4/IPv6 addresses, DNS names, CIDR subnets or IP address ranges.
! 33:
! 34: As initiator, the first non\-range/non\-subnet is used to initiate the connection
! 35: from. As responder, the local destination address must match at least to one of
! 36: the specified addresses, subnets or ranges.
! 37:
! 38: If FQDNs are assigned they are resolved every time a configuration lookup is
! 39: done. If DNS resolution times out, the lookup is delayed for that time.
! 40:
! 41: .TP
! 42: .BR connections.<conn>.remote_addrs " [%any]"
! 43: Remote address(es) to use for IKE communication, comma separated. Takes single
! 44: IPv4/IPv6 addresses, DNS names, CIDR subnets or IP address ranges.
! 45:
! 46: As initiator, the first non\-range/non\-subnet is used to initiate the connection
! 47: to. As responder, the initiator source address must match at least to one of the
! 48: specified addresses, subnets or ranges.
! 49:
! 50: If FQDNs are assigned they are resolved every time a configuration lookup is
! 51: done. If DNS resolution times out, the lookup is delayed for that time.
! 52:
! 53: To initiate a connection, at least one specific address or DNS name must be
! 54: specified.
! 55:
! 56: .TP
! 57: .BR connections.<conn>.local_port " [500]"
! 58: Local UDP port for IKE communication. By default the port of the socket backend
! 59: is used, which is usually
! 60: .RI "" "500" "."
! 61: If port
! 62: .RI "" "500" ""
! 63: is used, automatic IKE port
! 64: floating to port 4500 is used to work around NAT issues.
! 65:
! 66: Using a non\-default local IKE port requires support from the socket backend in
! 67: use (socket\-dynamic).
! 68:
! 69: .TP
! 70: .BR connections.<conn>.remote_port " [500]"
! 71: Remote UDP port for IKE communication. If the default of port
! 72: .RI "" "500" ""
! 73: is used,
! 74: automatic IKE port floating to port 4500 is used to work around NAT issues.
! 75:
! 76: .TP
! 77: .BR connections.<conn>.proposals " [default]"
! 78: A proposal is a set of algorithms. For non\-AEAD algorithms, this includes for
! 79: IKE an encryption algorithm, an integrity algorithm, a pseudo random function
! 80: and a Diffie\-Hellman group. For AEAD algorithms, instead of encryption and
! 81: integrity algorithms, a combined algorithm is used.
! 82:
! 83: In IKEv2, multiple algorithms of the same kind can be specified in a single
! 84: proposal, from which one gets selected. In IKEv1, only one algorithm per kind is
! 85: allowed per proposal, more algorithms get implicitly stripped. Use multiple
! 86: proposals to offer different algorithms combinations in IKEv1.
! 87:
! 88: Algorithm keywords get separated using dashes. Multiple proposals may be
! 89: separated by commas. The special value
! 90: .RI "" "default" ""
! 91: forms a default proposal of
! 92: supported algorithms considered safe, and is usually a good choice for
! 93: interoperability.
! 94:
! 95: .TP
! 96: .BR connections.<conn>.vips " []"
! 97: Comma separated list of virtual IPs to request in IKEv2 configuration payloads
! 98: or IKEv1 Mode Config. The wildcard addresses
! 99: .RI "" "0.0.0.0" ""
! 100: and
! 101: .RI "" "::" ""
! 102: request an
! 103: arbitrary address, specific addresses may be defined. The responder may return a
! 104: different address, though, or none at all.
! 105:
! 106: .TP
! 107: .BR connections.<conn>.aggressive " [no]"
! 108: Enables Aggressive Mode instead of Main Mode with Identity Protection.
! 109: Aggressive Mode is considered less secure, because the ID and HASH payloads are
! 110: exchanged unprotected. This allows a passive attacker to snoop peer identities,
! 111: and even worse, start dictionary attacks on the Preshared Key.
! 112:
! 113: .TP
! 114: .BR connections.<conn>.pull " [yes]"
! 115: If the default of
! 116: .RI "" "yes" ""
! 117: is used, Mode Config works in pull mode, where the
! 118: initiator actively requests a virtual IP. With
! 119: .RI "" "no" ","
! 120: push mode is used, where
! 121: the responder pushes down a virtual IP to the initiating peer.
! 122:
! 123: Push mode is currently supported for IKEv1, but not in IKEv2. It is used by a
! 124: few implementations only, pull mode is recommended.
! 125:
! 126: .TP
! 127: .BR connections.<conn>.dscp " [000000]"
! 128: Differentiated Services Field Codepoint to set on outgoing IKE packets for this
! 129: connection. The value is a six digit binary encoded string specifying the
! 130: Codepoint to set, as defined in RFC 2474.
! 131:
! 132: .TP
! 133: .BR connections.<conn>.encap " [no]"
! 134: To enforce UDP encapsulation of ESP packets, the IKE daemon can fake the NAT
! 135: detection payloads. This makes the peer believe that NAT takes place on the
! 136: path, forcing it to encapsulate ESP packets in UDP.
! 137:
! 138: Usually this is not required, but it can help to work around connectivity issues
! 139: with too restrictive intermediary firewalls.
! 140:
! 141: .TP
! 142: .BR connections.<conn>.mobike " [yes]"
! 143: Enables MOBIKE on IKEv2 connections. MOBIKE is enabled by default on IKEv2
! 144: connections, and allows mobility of clients and multi\-homing on servers by
! 145: migrating active IPsec tunnels.
! 146:
! 147: Usually keeping MOBIKE enabled is unproblematic, as it is not used if the peer
! 148: does not indicate support for it. However, due to the design of MOBIKE, IKEv2
! 149: always floats to port 4500 starting from the second exchange. Some
! 150: implementations don't like this behavior, hence it can be disabled.
! 151:
! 152: .TP
! 153: .BR connections.<conn>.dpd_delay " [0s]"
! 154: Interval to check the liveness of a peer actively using IKEv2 INFORMATIONAL
! 155: exchanges or IKEv1 R_U_THERE messages. Active DPD checking is only enforced if
! 156: no IKE or ESP/AH packet has been received for the configured DPD delay.
! 157:
! 158: .TP
! 159: .BR connections.<conn>.dpd_timeout " [0s]"
! 160: Charon by default uses the normal retransmission mechanism and timeouts to check
! 161: the liveness of a peer, as all messages are used for liveness checking. For
! 162: compatibility reasons, with IKEv1 a custom interval may be specified; this
! 163: option has no effect on connections using IKE2.
! 164:
! 165: .TP
! 166: .BR connections.<conn>.fragmentation " [yes]"
! 167: Use IKE fragmentation (proprietary IKEv1 extension or RFC 7383 IKEv2
! 168: fragmentation). Acceptable values are
! 169: .RI "" "yes" ""
! 170: (the default),
! 171: .RI "" "accept" ","
! 172: .RI "" "force" ""
! 173: and
! 174: .RI "" "no" "."
! 175: If set to
! 176: .RI "" "yes" ","
! 177: and the peer supports it, oversized IKE
! 178: messages will be sent in fragments. If set to
! 179: .RI "" "accept" ","
! 180: support for
! 181: fragmentation is announced to the peer but the daemon does not send its own
! 182: messages in fragments. If set to
! 183: .RI "" "force" ""
! 184: (only supported for IKEv1) the initial
! 185: IKE message will already be fragmented if required. Finally, setting the option
! 186: to
! 187: .RI "" "no" ""
! 188: will disable announcing support for this feature.
! 189:
! 190: Note that fragmented IKE messages sent by a peer are always accepted
! 191: irrespective of the value of this option (even when set to
! 192: .RI "" "no" ")."
! 193:
! 194:
! 195: .TP
! 196: .BR connections.<conn>.childless " [allow]"
! 197: Use childless IKE_SA initiation (RFC 6023) for IKEv2. Acceptable values are
! 198: .RI "" "allow" ""
! 199: (the default),
! 200: .RI "" "force" ""
! 201: and
! 202: .RI "" "never" "."
! 203: If set to
! 204: .RI "" "allow" ","
! 205: responders will
! 206: accept childless IKE_SAs (as indicated via notify in the IKE_SA_INIT response)
! 207: while initiators continue to create regular IKE_SAs with the first CHILD_SA
! 208: created during IKE_AUTH, unless the IKE_SA is initiated explicitly without any
! 209: children (which will fail if the responder does not support or has disabled this
! 210: extension). If set to
! 211: .RI "" "force" ","
! 212: only childless initiation is accepted and the
! 213: first CHILD_SA is created with a separate CREATE_CHILD_SA exchange (e.g. to use
! 214: an independent DH exchange for all CHILD_SAs). Finally, setting the option to
! 215: .RI "" "never" ""
! 216: disables support for childless IKE_SAs as responder.
! 217:
! 218: .TP
! 219: .BR connections.<conn>.send_certreq " [yes]"
! 220: Send certificate request payloads to offer trusted root CA certificates to the
! 221: peer. Certificate requests help the peer to choose an appropriate
! 222: certificate/private key for authentication and are enabled by default.
! 223:
! 224: Disabling certificate requests can be useful if too many trusted root CA
! 225: certificates are installed, as each certificate request increases the size of
! 226: the initial IKE packets.
! 227:
! 228: .TP
! 229: .BR connections.<conn>.send_cert " [ifasked]"
! 230: Send certificate payloads when using certificate authentication. With the
! 231: default of
! 232: .RI "" "ifasked" ""
! 233: the daemon sends certificate payloads only if certificate
! 234: requests have been received.
! 235: .RI "" "never" ""
! 236: disables sending of certificate payloads
! 237: altogether,
! 238: .RI "" "always" ""
! 239: causes certificate payloads to be sent unconditionally
! 240: whenever certificate authentication is used.
! 241:
! 242: .TP
! 243: .BR connections.<conn>.ppk_id " []"
! 244: String identifying the Postquantum Preshared Key (PPK) to be used.
! 245:
! 246: .TP
! 247: .BR connections.<conn>.ppk_required " [no]"
! 248: Whether a Postquantum Preshared Key (PPK) is required for this connection.
! 249:
! 250: .TP
! 251: .BR connections.<conn>.keyingtries " [1]"
! 252: Number of retransmission sequences to perform during initial connect. Instead of
! 253: giving up initiation after the first retransmission sequence with the default
! 254: value of
! 255: .RI "" "1" ","
! 256: additional sequences may be started according to the configured
! 257: value. A value of
! 258: .RI "" "0" ""
! 259: initiates a new sequence until the connection establishes
! 260: or fails with a permanent error.
! 261:
! 262: .TP
! 263: .BR connections.<conn>.unique " [no]"
! 264: Connection uniqueness policy to enforce. To avoid multiple connections from the
! 265: same user, a uniqueness policy can be enforced. The value
! 266: .RI "" "never" ""
! 267: does never
! 268: enforce such a policy, even if a peer included INITIAL_CONTACT notification
! 269: messages, whereas
! 270: .RI "" "no" ""
! 271: replaces existing connections for the same identity if a
! 272: new one has the INITIAL_CONTACT notify.
! 273: .RI "" "keep" ""
! 274: rejects new connection attempts
! 275: if the same user already has an active connection,
! 276: .RI "" "replace" ""
! 277: deletes any
! 278: existing connection if a new one for the same user gets established.
! 279:
! 280: To compare connections for uniqueness, the remote IKE identity is used. If EAP
! 281: or XAuth authentication is involved, the EAP\-Identity or XAuth username is used
! 282: to enforce the uniqueness policy instead.
! 283:
! 284: On initiators this setting specifies whether an INITIAL_CONTACT notify is sent
! 285: during IKE_AUTH if no existing connection is found with the remote peer
! 286: (determined by the identities of the first authentication round). Unless set to
! 287: .RI "" "never" ""
! 288: the client will send a notify.
! 289:
! 290: .TP
! 291: .BR connections.<conn>.reauth_time " [0s]"
! 292: Time to schedule IKE reauthentication. IKE reauthentication recreates the
! 293: IKE/ISAKMP SA from scratch and re\-evaluates the credentials. In asymmetric
! 294: configurations (with EAP or configuration payloads) it might not be possible to
! 295: actively reauthenticate as responder. The IKEv2 reauthentication lifetime
! 296: negotiation can instruct the client to perform reauthentication.
! 297:
! 298: Reauthentication is disabled by default. Enabling it usually may lead to small
! 299: connection interruptions, as strongSwan uses a break\-before\-make policy with
! 300: IKEv2 to avoid any conflicts with associated tunnel resources.
! 301:
! 302: .TP
! 303: .BR connections.<conn>.rekey_time " [4h]"
! 304: IKE rekeying refreshes key material using a Diffie\-Hellman exchange, but does
! 305: not re\-check associated credentials. It is supported in IKEv2 only, IKEv1
! 306: performs a reauthentication procedure instead.
! 307:
! 308: With the default value IKE rekeying is scheduled every 4 hours, minus the
! 309: configured
! 310: .RB "" "rand_time" "."
! 311: If a
! 312: .RB "" "reauth_time" ""
! 313: is configured,
! 314: .RB "" "rekey_time" ""
! 315: defaults to zero disabling rekeying; explicitly set both to enforce rekeying and
! 316: reauthentication.
! 317:
! 318: .TP
! 319: .BR connections.<conn>.over_time " [10% of rekey_time/reauth_time]"
! 320: Hard IKE_SA lifetime if rekey/reauth does not complete, as time. To avoid having
! 321: an IKE/ISAKMP kept alive if IKE reauthentication or rekeying fails perpetually,
! 322: a maximum hard lifetime may be specified. If the IKE_SA fails to rekey or
! 323: reauthenticate within the specified time, the IKE_SA gets closed.
! 324:
! 325: In contrast to CHILD_SA rekeying,
! 326: .RB "" "over_time" ""
! 327: is relative in time to the
! 328: .RB "" "rekey_time" ""
! 329: .RI "" "and" ""
! 330: .RB "" "reauth_time" ""
! 331: values, as it applies to both.
! 332:
! 333: The default is 10% of the longer of
! 334: .RB "" "rekey_time" ""
! 335: and
! 336: .RB "" "reauth_time" "."
! 337:
! 338:
! 339: .TP
! 340: .BR connections.<conn>.rand_time " [over_time]"
! 341: Time range from which to choose a random value to subtract from rekey/reauth
! 342: times. To avoid having both peers initiating the rekey/reauth procedure
! 343: simultaneously, a random time gets subtracted from the rekey/reauth times.
! 344:
! 345: The default is equal to the configured
! 346: .RB "" "over_time" "."
! 347:
! 348:
! 349: .TP
! 350: .BR connections.<conn>.pools " []"
! 351: Comma separated list of named IP pools to allocate virtual IP addresses and
! 352: other configuration attributes from. Each name references a pool by name from
! 353: either the
! 354: .RB "" "pools" ""
! 355: section or an external pool.
! 356:
! 357: .TP
! 358: .BR connections.<conn>.if_id_in " [0]"
! 359: XFRM interface ID set on inbound policies/SA, can be overridden by child config,
! 360: see there for details.
! 361:
! 362: .TP
! 363: .BR connections.<conn>.if_id_out " [0]"
! 364: XFRM interface ID set on outbound policies/SA, can be overridden by child
! 365: config, see there for details.
! 366:
! 367: .TP
! 368: .BR connections.<conn>.mediation " [no]"
! 369: Whether this connection is a mediation connection, that is, whether this
! 370: connection is used to mediate other connections using the IKEv2 Mediation
! 371: Extension. Mediation connections create no CHILD_SA.
! 372:
! 373: .TP
! 374: .BR connections.<conn>.mediated_by " []"
! 375: The name of the connection to mediate this connection through. If given, the
! 376: connection will be mediated through the named mediation connection. The
! 377: mediation connection must have
! 378: .RB "" "mediation" ""
! 379: enabled.
! 380:
! 381: .TP
! 382: .BR connections.<conn>.mediation_peer " []"
! 383: Identity under which the peer is registered at the mediation server, that is,
! 384: the IKE identity the other end of this connection uses as its local identity on
! 385: its connection to the mediation server. This is the identity we request the
! 386: mediation server to mediate us with. Only relevant on connections that set
! 387: .RB "" "mediated_by" "."
! 388: If it is not given, the remote IKE identity of the first
! 389: authentication round of this connection will be used.
! 390:
! 391: .TP
! 392: .B connections.<conn>.local<suffix>
! 393: .br
! 394: Section for a local authentication round. A local authentication round defines
! 395: the rules how authentication is performed for the local peer. Multiple rounds
! 396: may be defined to use IKEv2 RFC 4739 Multiple Authentication or IKEv1 XAuth.
! 397:
! 398: Each round is defined in a section having
! 399: .RI "" "local" ""
! 400: as prefix, and an optional
! 401: unique suffix. To define a single authentication round, the suffix may be
! 402: omitted.
! 403:
! 404: .TP
! 405: .BR connections.<conn>.local<suffix>.round " [0]"
! 406: Optional numeric identifier by which authentication rounds are sorted. If not
! 407: specified rounds are ordered by their position in the config file/VICI message.
! 408:
! 409: .TP
! 410: .BR connections.<conn>.local<suffix>.certs " []"
! 411: Comma separated list of certificate candidates to use for authentication. The
! 412: certificates may use a relative path from the
! 413: .RB "" "swanctl" ""
! 414: .RI "" "x509" ""
! 415: directory or an
! 416: absolute path.
! 417:
! 418: The certificate used for authentication is selected based on the received
! 419: certificate request payloads. If no appropriate CA can be located, the first
! 420: certificate is used.
! 421:
! 422: .TP
! 423: .BR connections.<conn>.local<suffix>.cert<suffix> " []"
! 424: Section for a certificate candidate to use for authentication. Certificates in
! 425: .RI "" "certs" ""
! 426: are transmitted as binary blobs, these sections offer more flexibility.
! 427:
! 428: .TP
! 429: .BR connections.<conn>.local<suffix>.cert<suffix>.file " []"
! 430: Absolute path to the certificate to load. Passed as\-is to the daemon, so it must
! 431: be readable by it.
! 432:
! 433: Configure either this or
! 434: .RI "" "handle" ","
! 435: but not both, in one section.
! 436:
! 437: .TP
! 438: .BR connections.<conn>.local<suffix>.cert<suffix>.handle " []"
! 439: Hex\-encoded CKA_ID of the certificate on a token.
! 440:
! 441: Configure either this or
! 442: .RI "" "file" ","
! 443: but not both, in one section.
! 444:
! 445: .TP
! 446: .BR connections.<conn>.local<suffix>.cert<suffix>.slot " []"
! 447: Optional slot number of the token that stores the certificate.
! 448:
! 449: .TP
! 450: .BR connections.<conn>.local<suffix>.cert<suffix>.module " []"
! 451: Optional PKCS#11 module name.
! 452:
! 453: .TP
! 454: .BR connections.<conn>.local<suffix>.pubkeys " []"
! 455: Comma separated list of raw public key candidates to use for authentication. The
! 456: public keys may use a relative path from the
! 457: .RB "" "swanctl" ""
! 458: .RI "" "pubkey" ""
! 459: directory or
! 460: an absolute path.
! 461:
! 462: Even though multiple local public keys could be defined in principle, only the
! 463: first public key in the list is used for authentication.
! 464:
! 465: .TP
! 466: .BR connections.<conn>.local<suffix>.auth " [pubkey]"
! 467: Authentication to perform locally.
! 468: .RI "" "pubkey" ""
! 469: uses public key authentication using
! 470: a private key associated to a usable certificate.
! 471: .RI "" "psk" ""
! 472: uses pre\-shared key
! 473: authentication. The IKEv1 specific
! 474: .RI "" "xauth" ""
! 475: is used for XAuth or Hybrid
! 476: authentication, while the IKEv2 specific
! 477: .RI "" "eap" ""
! 478: keyword defines EAP
! 479: authentication.
! 480:
! 481: For
! 482: .RI "" "xauth" ","
! 483: a specific backend name may be appended, separated by a dash. The
! 484: appropriate
! 485: .RI "" "xauth" ""
! 486: backend is selected to perform the XAuth exchange. For
! 487: traditional XAuth, the
! 488: .RI "" "xauth" ""
! 489: method is usually defined in the second
! 490: authentication round following an initial
! 491: .RI "" "pubkey" ""
! 492: (or
! 493: .RI "" "psk" ")"
! 494: round. Using
! 495: .RI "" "xauth" ""
! 496: in the first round performs Hybrid Mode client authentication.
! 497:
! 498: For
! 499: .RI "" "eap" ","
! 500: a specific EAP method name may be appended, separated by a dash. An
! 501: EAP module implementing the appropriate method is selected to perform the EAP
! 502: conversation.
! 503:
! 504: If both peers support RFC 7427 ("Signature Authentication in IKEv2") specific
! 505: hash algorithms to be used during IKEv2 authentication may be configured. To do
! 506: so use
! 507: .RI "" "ike:" ""
! 508: followed by a trust chain signature scheme constraint (see
! 509: description of the
! 510: .RB "" "remote" ""
! 511: section's
! 512: .RB "" "auth" ""
! 513: keyword). For example, with
! 514: .RI "" "ike:pubkey\-sha384\-sha256" ""
! 515: a public key signature scheme with either SHA\-384 or
! 516: SHA\-256 would get used for authentication, in that order and depending on the
! 517: hash algorithms supported by the peer. If no specific hash algorithms are
! 518: configured, the default is to prefer an algorithm that matches or exceeds the
! 519: strength of the signature key. If no constraints with
! 520: .RI "" "ike:" ""
! 521: prefix are
! 522: configured any signature scheme constraint (without
! 523: .RI "" "ike:" ""
! 524: prefix) will also
! 525: apply to IKEv2 authentication, unless this is disabled in
! 526: .RB "" "strongswan.conf" "(5)."
! 527: To use RSASSA\-PSS signatures use
! 528: .RI "" "rsa/pss" ""
! 529: instead of
! 530: .RI "" "pubkey" ""
! 531: or
! 532: .RI "" "rsa" ""
! 533: as in e.g.
! 534: .RI "" "ike:rsa/pss\-sha256" "."
! 535: If
! 536: .RI "" "pubkey" ""
! 537: or
! 538: .RI "" "rsa" ""
! 539: constraints are configured RSASSA\-PSS signatures will only be used if enabled in
! 540: .RB "" "strongswan.conf" "(5)."
! 541:
! 542:
! 543: .TP
! 544: .BR connections.<conn>.local<suffix>.id " []"
! 545: IKE identity to use for authentication round. When using certificate
! 546: authentication, the IKE identity must be contained in the certificate, either as
! 547: subject or as subjectAltName.
! 548:
! 549: The identity can be an IP address, a fully\-qualified domain name, an email
! 550: address or a Distinguished Name for which the ID type is determined
! 551: automatically and the string is converted to the appropriate encoding. To
! 552: enforce a specific identity type, a prefix may be used, followed by a colon (:).
! 553: If the number sign (#) follows the colon, the remaining data is interpreted as
! 554: hex encoding, otherwise the string is used as\-is as the identification data.
! 555: Note that this implies that no conversion is performed for non\-string
! 556: identities. For example,
! 557: .RI "" "ipv4:10.0.0.1" ""
! 558: does not create a valid ID_IPV4_ADDR
! 559: IKE identity, as it does not get converted to binary 0x0a000001. Instead, one
! 560: could use
! 561: .RI "" "ipv4:#0a000001" ""
! 562: to get a valid identity, but just using the implicit
! 563: type with automatic conversion is usually simpler. The same applies to the ASN1
! 564: encoded types. The following prefixes are known:
! 565: .RI "" "ipv4" ","
! 566: .RI "" "ipv6" ","
! 567: .RI "" "rfc822" ","
! 568: .RI "" "email" ","
! 569: .RI "" "userfqdn" ","
! 570: .RI "" "fqdn" ","
! 571: .RI "" "dns" ","
! 572: .RI "" "asn1dn" ","
! 573: .RI "" "asn1gn" ""
! 574: and
! 575: .RI "" "keyid" "."
! 576: Custom type
! 577: prefixes may be specified by surrounding the numerical type value by curly
! 578: brackets.
! 579:
! 580: .TP
! 581: .BR connections.<conn>.local<suffix>.eap_id " [id]"
! 582: Client EAP\-Identity to use in EAP\-Identity exchange and the EAP method.
! 583:
! 584: .TP
! 585: .BR connections.<conn>.local<suffix>.aaa_id " [remote-id]"
! 586: Server side EAP\-Identity to expect in the EAP method. Some EAP methods, such as
! 587: EAP\-TLS, use an identity for the server to perform mutual authentication. This
! 588: identity may differ from the IKE identity, especially when EAP authentication is
! 589: delegated from the IKE responder to an AAA backend.
! 590:
! 591: For EAP\-(T)TLS, this defines the identity for which the server must provide a
! 592: certificate in the TLS exchange.
! 593:
! 594: .TP
! 595: .BR connections.<conn>.local<suffix>.xauth_id " [id]"
! 596: Client XAuth username used in the XAuth exchange.
! 597:
! 598: .TP
! 599: .B connections.<conn>.remote<suffix>
! 600: .br
! 601: Section for a remote authentication round. A remote authentication round defines
! 602: the constraints how the peers must authenticate to use this connection. Multiple
! 603: rounds may be defined to use IKEv2 RFC 4739 Multiple Authentication or IKEv1
! 604: XAuth.
! 605:
! 606: Each round is defined in a section having
! 607: .RI "" "remote" ""
! 608: as prefix, and an optional
! 609: unique suffix. To define a single authentication round, the suffix may be
! 610: omitted.
! 611:
! 612: .TP
! 613: .BR connections.<conn>.remote<suffix>.round " [0]"
! 614: Optional numeric identifier by which authentication rounds are sorted. If not
! 615: specified rounds are ordered by their position in the config file/VICI message.
! 616:
! 617: .TP
! 618: .BR connections.<conn>.remote<suffix>.id " [%any]"
! 619: IKE identity to expect for authentication round. Refer to the
! 620: .RB "" "local" ""
! 621: section's
! 622: .RB "" "id" ""
! 623: keyword for details.
! 624:
! 625: It's possible to use wildcards to match remote identities (e.g.
! 626: .RI "" "*@strongswan.org" ","
! 627: .RI "" "*.strongswan.org" ","
! 628: or
! 629: .RI "" "C=CH,O=strongSwan,CN=*" ")."
! 630: Connections with exact matches are preferred. When using distinguished names
! 631: with wildcards, the
! 632: .RI "" "charon.rdn_matching" ""
! 633: option in
! 634: .RB "" "strongswan.conf" "(5)"
! 635: specifies how RDNs are matched.
! 636:
! 637: .TP
! 638: .BR connections.<conn>.remote<suffix>.eap_id " [id]"
! 639: Identity to use as peer identity during EAP authentication. If set to
! 640: .RI "" "%any" ""
! 641: the
! 642: EAP\-Identity method will be used to ask the client for an identity.
! 643:
! 644: .TP
! 645: .BR connections.<conn>.remote<suffix>.groups " []"
! 646: Comma separated authorization group memberships to require. The peer must prove
! 647: membership to at least one of the specified groups. Group membership can be
! 648: certified by different means, for example by appropriate Attribute Certificates
! 649: or by an AAA backend involved in the authentication.
! 650:
! 651: .TP
! 652: .BR connections.<conn>.remote<suffix>.cert_policy " []"
! 653: Comma separated list of certificate policy OIDs the peer's certificate must
! 654: have. OIDs are specified using the numerical dotted representation.
! 655:
! 656: .TP
! 657: .BR connections.<conn>.remote<suffix>.certs " []"
! 658: Comma separated list of certificates to accept for authentication. The
! 659: certificates may use a relative path from the
! 660: .RB "" "swanctl" ""
! 661: .RI "" "x509" ""
! 662: directory or an
! 663: absolute path.
! 664:
! 665: .TP
! 666: .BR connections.<conn>.remote<suffix>.cert<suffix> " []"
! 667: Section for a certificate to accept for authentication. Certificates in
! 668: .RI "" "certs" ""
! 669: are transmitted as binary blobs, these sections offer more flexibility.
! 670:
! 671: .TP
! 672: .BR connections.<conn>.remote<suffix>.cert<suffix>.file " []"
! 673: Absolute path to the certificate to load. Passed as\-is to the daemon, so it must
! 674: be readable by it.
! 675:
! 676: Configure either this or
! 677: .RI "" "handle" ","
! 678: but not both, in one section.
! 679:
! 680: .TP
! 681: .BR connections.<conn>.remote<suffix>.cert<suffix>.handle " []"
! 682: Hex\-encoded CKA_ID of the certificate on a token.
! 683:
! 684: Configure either this or
! 685: .RI "" "file" ","
! 686: but not both, in one section.
! 687:
! 688: .TP
! 689: .BR connections.<conn>.remote<suffix>.cert<suffix>.slot " []"
! 690: Optional slot number of the token that stores the certificate.
! 691:
! 692: .TP
! 693: .BR connections.<conn>.remote<suffix>.cert<suffix>.module " []"
! 694: Optional PKCS#11 module name.
! 695:
! 696: .TP
! 697: .BR connections.<conn>.remote<suffix>.cacerts " []"
! 698: Comma separated list of CA certificates to accept for authentication. The
! 699: certificates may use a relative path from the
! 700: .RB "" "swanctl" ""
! 701: .RI "" "x509ca" ""
! 702: directory or
! 703: an absolute path.
! 704:
! 705: .TP
! 706: .BR connections.<conn>.remote<suffix>.cacert<suffix> " []"
! 707: Section for a CA certificate to accept for authentication. Certificates in
! 708: .RI "" "cacerts" ""
! 709: are transmitted as binary blobs, these sections offer more
! 710: flexibility.
! 711:
! 712: .TP
! 713: .BR connections.<conn>.remote<suffix>.cacert<suffix>.file " []"
! 714: Absolute path to the certificate to load. Passed as\-is to the daemon, so it must
! 715: be readable by it.
! 716:
! 717: Configure either this or
! 718: .RI "" "handle" ","
! 719: but not both, in one section.
! 720:
! 721: .TP
! 722: .BR connections.<conn>.remote<suffix>.cacert<suffix>.handle " []"
! 723: Hex\-encoded CKA_ID of the CA certificate on a token.
! 724:
! 725: Configure either this or
! 726: .RI "" "file" ","
! 727: but not both, in one section.
! 728:
! 729: .TP
! 730: .BR connections.<conn>.remote<suffix>.cacert<suffix>.slot " []"
! 731: Optional slot number of the token that stores the CA certificate.
! 732:
! 733: .TP
! 734: .BR connections.<conn>.remote<suffix>.cacert<suffix>.module " []"
! 735: Optional PKCS#11 module name.
! 736:
! 737: .TP
! 738: .BR connections.<conn>.remote<suffix>.ca_id " []"
! 739: The specified identity must be contained in one (intermediate) CA of the remote
! 740: peer trustchain, either as subject or as subjectAltName. This has the same
! 741: effect as specifying
! 742: .RI "" "cacerts" ""
! 743: to force clients under a CA to specific
! 744: connections; it does not require the CA certificate to be available locally, and
! 745: can be received from the peer during the IKE exchange.
! 746:
! 747: .TP
! 748: .BR connections.<conn>.remote<suffix>.pubkeys " []"
! 749: Comma separated list of raw public keys to accept for authentication. The public
! 750: keys may use a relative path from the
! 751: .RB "" "swanctl" ""
! 752: .RI "" "pubkey" ""
! 753: directory or an
! 754: absolute path.
! 755:
! 756: .TP
! 757: .BR connections.<conn>.remote<suffix>.revocation " [relaxed]"
! 758: Certificate revocation policy for CRL or OCSP revocation.
! 759:
! 760: A
! 761: .RI "" "strict" ""
! 762: revocation policy fails if no revocation information is available,
! 763: i.e. the certificate is not known to be unrevoked.
! 764:
! 765: .RI "" "ifuri" ""
! 766: fails only if a CRL/OCSP URI is available, but certificate revocation
! 767: checking fails, i.e. there should be revocation information available, but it
! 768: could not be obtained.
! 769:
! 770: The default revocation policy
! 771: .RI "" "relaxed" ""
! 772: fails only if a certificate is revoked,
! 773: i.e. it is explicitly known that it is bad.
! 774:
! 775: .TP
! 776: .BR connections.<conn>.remote<suffix>.auth " [pubkey]"
! 777: Authentication to expect from remote. See the
! 778: .RB "" "local" ""
! 779: section's
! 780: .RB "" "auth" ""
! 781: keyword description about the details of supported mechanisms.
! 782:
! 783: To require a trustchain public key strength for the remote side, specify the key
! 784: type followed by the minimum strength in bits (for example
! 785: .RI "" "ecdsa\-384" ""
! 786: or
! 787: .RI "" "rsa\-2048\-ecdsa\-256" ")."
! 788: To limit the acceptable set of hashing algorithms for
! 789: trustchain validation, append hash algorithms to
! 790: .RI "" "pubkey" ""
! 791: or a key strength
! 792: definition (for example
! 793: .RI "" "pubkey\-sha256\-sha512" ","
! 794: .RI "" "rsa\-2048\-sha256\-sha384\-sha512" ""
! 795: or
! 796: .RI "" "rsa\-2048\-sha256\-ecdsa\-256\-sha256\-sha384" ")."
! 797: Unless disabled in
! 798: .RB "" "strongswan.conf" "(5),"
! 799: or explicit IKEv2 signature constraints are configured
! 800: (refer to the description of the
! 801: .RB "" "local" ""
! 802: section's
! 803: .RB "" "auth" ""
! 804: keyword for
! 805: details), such key types and hash algorithms are also applied as constraints
! 806: against IKEv2 signature authentication schemes used by the remote side. To
! 807: require RSASSA\-PSS signatures use
! 808: .RI "" "rsa/pss" ""
! 809: instead of
! 810: .RI "" "pubkey" ""
! 811: or
! 812: .RI "" "rsa" ""
! 813: as in
! 814: e.g.
! 815: .RI "" "rsa/pss\-sha256" "."
! 816: If
! 817: .RI "" "pubkey" ""
! 818: or
! 819: .RI "" "rsa" ""
! 820: constraints are configured
! 821: RSASSA\-PSS signatures will only be accepted if enabled in
! 822: .RB "" "strongswan.conf" "(5)."
! 823:
! 824:
! 825: To specify trust chain constraints for EAP\-(T)TLS, append a colon to the EAP
! 826: method, followed by the key type/size and hash algorithm as discussed above
! 827: (e.g.
! 828: .RI "" "eap\-tls:ecdsa\-384\-sha384" ")."
! 829:
! 830:
! 831: .TP
! 832: .B connections.<conn>.children.<child>
! 833: .br
! 834: CHILD_SA configuration sub\-section. Each connection definition may have one or
! 835: more sections in its
! 836: .RI "" "children" ""
! 837: subsection. The section name defines the name of
! 838: the CHILD_SA configuration, which must be unique within the connection.
! 839:
! 840: .TP
! 841: .BR connections.<conn>.children.<child>.ah_proposals " []"
! 842: AH proposals to offer for the CHILD_SA. A proposal is a set of algorithms. For
! 843: AH, this includes an integrity algorithm and an optional Diffie\-Hellman group.
! 844: If a DH group is specified, CHILD_SA/Quick Mode rekeying and initial negotiation
! 845: uses a separate Diffie\-Hellman exchange using the specified group (refer to
! 846: .RI "" "esp_proposals" ""
! 847: for details).
! 848:
! 849: In IKEv2, multiple algorithms of the same kind can be specified in a single
! 850: proposal, from which one gets selected. In IKEv1, only one algorithm per kind is
! 851: allowed per proposal, more algorithms get implicitly stripped. Use multiple
! 852: proposals to offer different algorithms combinations in IKEv1.
! 853:
! 854: Algorithm keywords get separated using dashes. Multiple proposals may be
! 855: separated by commas. The special value
! 856: .RI "" "default" ""
! 857: forms a default proposal of
! 858: supported algorithms considered safe, and is usually a good choice for
! 859: interoperability. By default no AH proposals are included, instead ESP is
! 860: proposed.
! 861:
! 862: .TP
! 863: .BR connections.<conn>.children.<child>.esp_proposals " [default]"
! 864: ESP proposals to offer for the CHILD_SA. A proposal is a set of algorithms. For
! 865: ESP non\-AEAD proposals, this includes an integrity algorithm, an encryption
! 866: algorithm, an optional Diffie\-Hellman group and an optional Extended Sequence
! 867: Number Mode indicator. For AEAD proposals, a combined mode algorithm is used
! 868: instead of the separate encryption/integrity algorithms.
! 869:
! 870: If a DH group is specified, CHILD_SA/Quick Mode rekeying and initial negotiation
! 871: use a separate Diffie\-Hellman exchange using the specified group. However, for
! 872: IKEv2, the keys of the CHILD_SA created implicitly with the IKE_SA will always
! 873: be derived from the IKE_SA's key material. So any DH group specified here will
! 874: only apply when the CHILD_SA is later rekeyed or is created with a separate
! 875: CREATE_CHILD_SA exchange. A proposal mismatch might, therefore, not immediately
! 876: be noticed when the SA is established, but may later cause rekeying to fail.
! 877:
! 878: Extended Sequence Number support may be indicated with the
! 879: .RI "" "esn" ""
! 880: and
! 881: .RI "" "noesn" ""
! 882: values, both may be included to indicate support for both modes. If omitted,
! 883: .RI "" "noesn" ""
! 884: is assumed.
! 885:
! 886: In IKEv2, multiple algorithms of the same kind can be specified in a single
! 887: proposal, from which one gets selected. In IKEv1, only one algorithm per kind is
! 888: allowed per proposal, more algorithms get implicitly stripped. Use multiple
! 889: proposals to offer different algorithms combinations in IKEv1.
! 890:
! 891: Algorithm keywords get separated using dashes. Multiple proposals may be
! 892: separated by commas. The special value
! 893: .RI "" "default" ""
! 894: forms a default proposal of
! 895: supported algorithms considered safe, and is usually a good choice for
! 896: interoperability. If no algorithms are specified for AH nor ESP, the
! 897: .RI "" "default" ""
! 898: set of algorithms for ESP is included.
! 899:
! 900: .TP
! 901: .BR connections.<conn>.children.<child>.sha256_96 " [no]"
! 902: HMAC\-SHA\-256 is used with 128\-bit truncation with IPsec. For compatibility with
! 903: implementations that incorrectly use 96\-bit truncation this option may be
! 904: enabled to configure the shorter truncation length in the kernel. This is not
! 905: negotiated, so this only works with peers that use the incorrect truncation
! 906: length (or have this option enabled).
! 907:
! 908: .TP
! 909: .BR connections.<conn>.children.<child>.local_ts " [dynamic]"
! 910: Comma separated list of local traffic selectors to include in CHILD_SA. Each
! 911: selector is a CIDR subnet definition, followed by an optional proto/port
! 912: selector. The special value
! 913: .RI "" "dynamic" ""
! 914: may be used instead of a subnet
! 915: definition, which gets replaced by the tunnel outer address or the virtual IP,
! 916: if negotiated. This is the default.
! 917:
! 918: A protocol/port selector is surrounded by opening and closing square brackets.
! 919: Between these brackets, a numeric or
! 920: .RB "" "getservent" "(3)"
! 921: protocol name may be
! 922: specified. After the optional protocol restriction, an optional port restriction
! 923: may be specified, separated by a slash. The port restriction may be numeric, a
! 924: .RB "" "getservent" "(3)"
! 925: service name, or the special value
! 926: .RI "" "opaque" ""
! 927: for RFC 4301
! 928: OPAQUE selectors. Port ranges may be specified as well, none of the kernel
! 929: backends currently support port ranges, though.
! 930:
! 931: When IKEv1 is used only the first selector is interpreted, except if the Cisco
! 932: Unity extension plugin is used. This is due to a limitation of the IKEv1
! 933: protocol, which only allows a single pair of selectors per CHILD_SA. So to
! 934: tunnel traffic matched by several pairs of selectors when using IKEv1 several
! 935: children (CHILD_SAs) have to be defined that cover the selectors.
! 936:
! 937: The IKE daemon uses traffic selector narrowing for IKEv1, the same way it is
! 938: standardized and implemented for IKEv2. However, this may lead to problems with
! 939: other implementations. To avoid that, configure identical selectors in such
! 940: scenarios.
! 941:
! 942: .TP
! 943: .BR connections.<conn>.children.<child>.remote_ts " [dynamic]"
! 944: Comma separated list of remote selectors to include in CHILD_SA. See
! 945: .RB "" "local_ts" ""
! 946: for a description of the selector syntax.
! 947:
! 948: .TP
! 949: .BR connections.<conn>.children.<child>.rekey_time " [1h]"
! 950: Time to schedule CHILD_SA rekeying. CHILD_SA rekeying refreshes key material,
! 951: optionally using a Diffie\-Hellman exchange if a group is specified in the
! 952: proposal.
! 953:
! 954: To avoid rekey collisions initiated by both ends simultaneously, a value in the
! 955: range of
! 956: .RB "" "rand_time" ""
! 957: gets subtracted to form the effective soft lifetime.
! 958:
! 959: By default CHILD_SA rekeying is scheduled every hour, minus
! 960: .RB "" "rand_time" "."
! 961:
! 962:
! 963: .TP
! 964: .BR connections.<conn>.children.<child>.life_time " [rekey_time + 10%]"
! 965: Maximum lifetime before CHILD_SA gets closed. Usually this hard lifetime is
! 966: never reached, because the CHILD_SA gets rekeyed before. If that fails for
! 967: whatever reason, this limit closes the CHILD_SA.
! 968:
! 969: The default is 10% more than the
! 970: .RB "" "rekey_time" "."
! 971:
! 972:
! 973: .TP
! 974: .BR connections.<conn>.children.<child>.rand_time " [life_time - rekey_time]"
! 975: Time range from which to choose a random value to subtract from
! 976: .RB "" "rekey_time" "."
! 977: The default is the difference between
! 978: .RB "" "life_time" ""
! 979: and
! 980: .RB "" "rekey_time" "."
! 981:
! 982:
! 983: .TP
! 984: .BR connections.<conn>.children.<child>.rekey_bytes " [0]"
! 985: Number of bytes processed before initiating CHILD_SA rekeying. CHILD_SA rekeying
! 986: refreshes key material, optionally using a Diffie\-Hellman exchange if a group is
! 987: specified in the proposal.
! 988:
! 989: To avoid rekey collisions initiated by both ends simultaneously, a value in the
! 990: range of
! 991: .RB "" "rand_bytes" ""
! 992: gets subtracted to form the effective soft volume limit.
! 993:
! 994: Volume based CHILD_SA rekeying is disabled by default.
! 995:
! 996: .TP
! 997: .BR connections.<conn>.children.<child>.life_bytes " [rekey_bytes + 10%]"
! 998: Maximum bytes processed before CHILD_SA gets closed. Usually this hard volume
! 999: limit is never reached, because the CHILD_SA gets rekeyed before. If that fails
! 1000: for whatever reason, this limit closes the CHILD_SA.
! 1001:
! 1002: The default is 10% more than
! 1003: .RB "" "rekey_bytes" "."
! 1004:
! 1005:
! 1006: .TP
! 1007: .BR connections.<conn>.children.<child>.rand_bytes " [life_bytes - rekey_bytes]"
! 1008: Byte range from which to choose a random value to subtract from
! 1009: .RB "" "rekey_bytes" "."
! 1010: The default is the difference between
! 1011: .RB "" "life_bytes" ""
! 1012: and
! 1013: .RB "" "rekey_bytes" "."
! 1014:
! 1015:
! 1016: .TP
! 1017: .BR connections.<conn>.children.<child>.rekey_packets " [0]"
! 1018: Number of packets processed before initiating CHILD_SA rekeying. CHILD_SA
! 1019: rekeying refreshes key material, optionally using a Diffie\-Hellman exchange if a
! 1020: group is specified in the proposal.
! 1021:
! 1022: To avoid rekey collisions initiated by both ends simultaneously, a value in the
! 1023: range of
! 1024: .RB "" "rand_packets" ""
! 1025: gets subtracted to form the effective soft packet
! 1026: count limit.
! 1027:
! 1028: Packet count based CHILD_SA rekeying is disabled by default.
! 1029:
! 1030: .TP
! 1031: .BR connections.<conn>.children.<child>.life_packets " [rekey_packets + 10%]"
! 1032: Maximum number of packets processed before CHILD_SA gets closed. Usually this
! 1033: hard packets limit is never reached, because the CHILD_SA gets rekeyed before.
! 1034: If that fails for whatever reason, this limit closes the CHILD_SA.
! 1035:
! 1036: The default is 10% more than
! 1037: .RB "" "rekey_bytes" "."
! 1038:
! 1039:
! 1040: .TP
! 1041: .BR connections.<conn>.children.<child>.rand_packets " [life_packets - rekey_packets]"
! 1042: Packet range from which to choose a random value to subtract from
! 1043: .RB "" "rekey_packets" "."
! 1044: The default is the difference between
! 1045: .RB "" "life_packets" ""
! 1046: and
! 1047: .RB "" "rekey_packets" "."
! 1048:
! 1049:
! 1050: .TP
! 1051: .BR connections.<conn>.children.<child>.updown " []"
! 1052: Updown script to invoke on CHILD_SA up and down events.
! 1053:
! 1054: .TP
! 1055: .BR connections.<conn>.children.<child>.hostaccess " [no]"
! 1056: Hostaccess variable to pass to
! 1057: .RB "" "updown" ""
! 1058: script.
! 1059:
! 1060: .TP
! 1061: .BR connections.<conn>.children.<child>.mode " [tunnel]"
! 1062: IPsec Mode to establish CHILD_SA with.
! 1063: .RI "" "tunnel" ""
! 1064: negotiates the CHILD_SA in IPsec
! 1065: Tunnel Mode, whereas
! 1066: .RI "" "transport" ""
! 1067: uses IPsec Transport Mode.
! 1068: .RI "" "transport_proxy" ""
! 1069: signifying the special Mobile IPv6 Transport Proxy Mode.
! 1070: .RI "" "beet" ""
! 1071: is the Bound End
! 1072: to End Tunnel mixture mode, working with fixed inner addresses without the need
! 1073: to include them in each packet.
! 1074:
! 1075: Both
! 1076: .RI "" "transport" ""
! 1077: and
! 1078: .RI "" "beet" ""
! 1079: modes are subject to mode negotiation;
! 1080: .RI "" "tunnel" ""
! 1081: mode
! 1082: is negotiated if the preferred mode is not available.
! 1083:
! 1084: .RI "" "pass" ""
! 1085: and
! 1086: .RI "" "drop" ""
! 1087: are used to install shunt policies which explicitly bypass the
! 1088: defined traffic from IPsec processing or drop it, respectively.
! 1089:
! 1090: .TP
! 1091: .BR connections.<conn>.children.<child>.policies " [yes]"
! 1092: Whether to install IPsec policies or not. Disabling this can be useful in some
! 1093: scenarios e.g. MIPv6, where policies are not managed by the IKE daemon.
! 1094:
! 1095: .TP
! 1096: .BR connections.<conn>.children.<child>.policies_fwd_out " [no]"
! 1097: Whether to install outbound FWD IPsec policies or not. Enabling this is required
! 1098: in case there is a drop policy that would match and block forwarded traffic for
! 1099: this CHILD_SA.
! 1100:
! 1101: .TP
! 1102: .BR connections.<conn>.children.<child>.dpd_action " [clear]"
! 1103: Action to perform for this CHILD_SA on DPD timeout. The default
! 1104: .RI "" "clear" ""
! 1105: closes
! 1106: the CHILD_SA and does not take further action.
! 1107: .RI "" "trap" ""
! 1108: installs a trap policy,
! 1109: which will catch matching traffic and tries to re\-negotiate the tunnel
! 1110: on\-demand.
! 1111: .RI "" "restart" ""
! 1112: immediately tries to re\-negotiate the CHILD_SA under a
! 1113: fresh IKE_SA.
! 1114:
! 1115: .TP
! 1116: .BR connections.<conn>.children.<child>.ipcomp " [no]"
! 1117: Enable IPComp compression before encryption. If enabled, IKE tries to negotiate
! 1118: IPComp compression to compress ESP payload data prior to encryption.
! 1119:
! 1120: .TP
! 1121: .BR connections.<conn>.children.<child>.inactivity " [0s]"
! 1122: Timeout before closing CHILD_SA after inactivity. If no traffic has been
! 1123: processed in either direction for the configured timeout, the CHILD_SA gets
! 1124: closed due to inactivity. The default value of
! 1125: .RI "" "0" ""
! 1126: disables inactivity checks.
! 1127:
! 1128: .TP
! 1129: .BR connections.<conn>.children.<child>.reqid " [0]"
! 1130: Fixed reqid to use for this CHILD_SA. This might be helpful in some scenarios,
! 1131: but works only if each CHILD_SA configuration is instantiated not more than
! 1132: once. The default of
! 1133: .RI "" "0" ""
! 1134: uses dynamic reqids, allocated incrementally.
! 1135:
! 1136: .TP
! 1137: .BR connections.<conn>.children.<child>.priority " [0]"
! 1138: Optional fixed priority for IPsec policies. This could be useful to install
! 1139: high\-priority drop policies. The default of
! 1140: .RI "" "0" ""
! 1141: uses dynamically calculated
! 1142: priorities based on the size of the traffic selectors.
! 1143:
! 1144: .TP
! 1145: .BR connections.<conn>.children.<child>.interface " []"
! 1146: Optional interface name to restrict IPsec policies.
! 1147:
! 1148: .TP
! 1149: .BR connections.<conn>.children.<child>.mark_in " [0/0x00000000]"
! 1150: Netfilter mark and mask for input traffic. On Linux, Netfilter may require marks
! 1151: on each packet to match an SA/policy having that option set. This allows
! 1152: installing duplicate policies and enables Netfilter rules to select specific
! 1153: SAs/policies for incoming traffic. Note that inbound marks are only set on
! 1154: policies, by default, unless *mark_in_sa* is enabled. The special value
! 1155: .RI "" "%unique" ""
! 1156: sets a unique mark on each CHILD_SA instance, beyond that the value
! 1157: .RI "" "%unique\-dir" ""
! 1158: assigns a different unique mark for each CHILD_SA direction
! 1159: (in/out).
! 1160:
! 1161: An additional mask may be appended to the mark, separated by
! 1162: .RI "" "/" "."
! 1163: The default
! 1164: mask if omitted is 0xffffffff.
! 1165:
! 1166: .TP
! 1167: .BR connections.<conn>.children.<child>.mark_in_sa " [no]"
! 1168: Whether to set *mark_in* on the inbound SA. By default, the inbound mark is only
! 1169: set on the inbound policy. The tuple destination address, protocol and SPI is
! 1170: unique and the mark is not required to find the correct SA, allowing to mark
! 1171: traffic after decryption instead (where more specific selectors may be used) to
! 1172: match different policies. Marking packets before decryption is still possible,
! 1173: even if no mark is set on the SA.
! 1174:
! 1175: .TP
! 1176: .BR connections.<conn>.children.<child>.mark_out " [0/0x00000000]"
! 1177: Netfilter mark and mask for output traffic. On Linux, Netfilter may require
! 1178: marks on each packet to match a policy/SA having that option set. This allows
! 1179: installing duplicate policies and enables Netfilter rules to select specific
! 1180: policies/SAs for outgoing traffic. The special value
! 1181: .RI "" "%unique" ""
! 1182: sets a unique
! 1183: mark on each CHILD_SA instance, beyond that the value
! 1184: .RI "" "%unique\-dir" ""
! 1185: assigns a
! 1186: different unique mark for each CHILD_SA direction (in/out).
! 1187:
! 1188: An additional mask may be appended to the mark, separated by
! 1189: .RI "" "/" "."
! 1190: The default
! 1191: mask if omitted is 0xffffffff.
! 1192:
! 1193: .TP
! 1194: .BR connections.<conn>.children.<child>.set_mark_in " [0/0x00000000]"
! 1195: Netfilter mark applied to packets after the inbound IPsec SA processed them.
! 1196: This way it's not necessary to mark packets via Netfilter before decryption or
! 1197: right afterwards to match policies or process them differently (e.g. via policy
! 1198: routing).
! 1199:
! 1200: An additional mask may be appended to the mark, separated by
! 1201: .RI "" "/" "."
! 1202: The default
! 1203: mask if omitted is 0xffffffff. The special value
! 1204: .RI "" "%same" ""
! 1205: uses the value (but not
! 1206: the mask) from
! 1207: .RB "" "mark_in" ""
! 1208: as mark value, which can be fixed,
! 1209: .RI "" "%unique" ""
! 1210: or
! 1211: .RI "" "%unique\-dir" "."
! 1212:
! 1213:
! 1214: Setting marks in XFRM input requires Linux 4.19 or higher.
! 1215:
! 1216: .TP
! 1217: .BR connections.<conn>.children.<child>.set_mark_out " [0/0x00000000]"
! 1218: Netfilter mark applied to packets after the outbound IPsec SA processed them.
! 1219: This allows processing ESP packets differently than the original traffic (e.g.
! 1220: via policy routing).
! 1221:
! 1222: An additional mask may be appended to the mark, separated by
! 1223: .RI "" "/" "."
! 1224: The default
! 1225: mask if omitted is 0xffffffff. The special value
! 1226: .RI "" "%same" ""
! 1227: uses the value (but not
! 1228: the mask) from
! 1229: .RB "" "mark_out" ""
! 1230: as mark value, which can be fixed,
! 1231: .RI "" "%unique" ""
! 1232: or
! 1233: .RI "" "%unique\-dir" "."
! 1234:
! 1235:
! 1236: Setting marks in XFRM output is supported since Linux 4.14. Setting a mask
! 1237: requires at least Linux 4.19.
! 1238:
! 1239: .TP
! 1240: .BR connections.<conn>.children.<child>.if_id_in " [0]"
! 1241: XFRM interface ID set on inbound policies/SA. This allows installing duplicate
! 1242: policies/SAs and associates them with an interface with the same ID. The special
! 1243: value
! 1244: .RI "" "%unique" ""
! 1245: sets a unique interface ID on each CHILD_SA instance, beyond
! 1246: that the value
! 1247: .RI "" "%unique\-dir" ""
! 1248: assigns a different unique interface ID for each
! 1249: CHILD_SA direction (in/out).
! 1250:
! 1251: .TP
! 1252: .BR connections.<conn>.children.<child>.if_id_out " [0]"
! 1253: XFRM interface ID set on outbound policies/SA. This allows installing duplicate
! 1254: policies/SAs and associates them with an interface with the same ID. The special
! 1255: value
! 1256: .RI "" "%unique" ""
! 1257: sets a unique interface ID on each CHILD_SA instance, beyond
! 1258: that the value
! 1259: .RI "" "%unique\-dir" ""
! 1260: assigns a different unique interface ID for each
! 1261: CHILD_SA direction (in/out).
! 1262:
! 1263: The daemon will not install routes for CHILD_SAs that have this option set.
! 1264:
! 1265: .TP
! 1266: .BR connections.<conn>.children.<child>.tfc_padding " [0]"
! 1267: Pads ESP packets with additional data to have a consistent ESP packet size for
! 1268: improved Traffic Flow Confidentiality. The padding defines the minimum size of
! 1269: all ESP packets sent.
! 1270:
! 1271: The default value of 0 disables TFC padding, the special value
! 1272: .RI "" "mtu" ""
! 1273: adds TFC
! 1274: padding to create a packet size equal to the Path Maximum Transfer Unit.
! 1275:
! 1276: .TP
! 1277: .BR connections.<conn>.children.<child>.replay_window " [32]"
! 1278: IPsec replay window to configure for this CHILD_SA. Larger values than the
! 1279: default of 32 are supported using the Netlink backend only, a value of 0
! 1280: disables IPsec replay protection.
! 1281:
! 1282: .TP
! 1283: .BR connections.<conn>.children.<child>.hw_offload " [no]"
! 1284: Enable hardware offload for this CHILD_SA, if supported by the IPsec
! 1285: implementation. The value
! 1286: .RI "" "yes" ""
! 1287: enforces offloading and the installation will
! 1288: fail if it's not supported by either kernel or device. The value
! 1289: .RI "" "auto" ""
! 1290: enables offloading, if it's supported, but the installation does not fail
! 1291: otherwise.
! 1292:
! 1293: .TP
! 1294: .BR connections.<conn>.children.<child>.copy_df " [yes]"
! 1295: Whether to copy the DF bit to the outer IPv4 header in tunnel mode. This
! 1296: effectively disables Path MTU discovery (PMTUD). Controlling this behavior is
! 1297: not supported by all kernel interfaces.
! 1298:
! 1299: .TP
! 1300: .BR connections.<conn>.children.<child>.copy_ecn " [yes]"
! 1301: Whether to copy the ECN (Explicit Congestion Notification) header field to/from
! 1302: the outer IP header in tunnel mode. Controlling this behavior is not supported
! 1303: by all kernel interfaces.
! 1304:
! 1305: .TP
! 1306: .BR connections.<conn>.children.<child>.copy_dscp " [out]"
! 1307: Whether to copy the DSCP (Differentiated Services Field Codepoint) header field
! 1308: to/from the outer IP header in tunnel mode. The value
! 1309: .RI "" "out" ""
! 1310: only copies the
! 1311: field from the inner to the outer header, the value
! 1312: .RI "" "in" ""
! 1313: does the opposite and
! 1314: only copies the field from the outer to the inner header when decapsulating, the
! 1315: value
! 1316: .RI "" "yes" ""
! 1317: copies the field in both directions, and the value
! 1318: .RI "" "no" ""
! 1319: disables
! 1320: copying the field altogether. Setting this to
! 1321: .RI "" "yes" ""
! 1322: or
! 1323: .RI "" "in" ""
! 1324: could allow an
! 1325: attacker to adversely affect other traffic at the receiver, which is why the
! 1326: default is
! 1327: .RI "" "out" "."
! 1328: Controlling this behavior is not supported by all kernel
! 1329: interfaces.
! 1330:
! 1331: .TP
! 1332: .BR connections.<conn>.children.<child>.start_action " [none]"
! 1333: Action to perform after loading the configuration. The default of
! 1334: .RI "" "none" ""
! 1335: loads
! 1336: the connection only, which then can be manually initiated or used as a responder
! 1337: configuration.
! 1338:
! 1339: The value
! 1340: .RI "" "trap" ""
! 1341: installs a trap policy, which triggers the tunnel as soon as
! 1342: matching traffic has been detected. The value
! 1343: .RI "" "start" ""
! 1344: initiates the connection
! 1345: actively.
! 1346:
! 1347: When unloading or replacing a CHILD_SA configuration having a
! 1348: .RB "" "start_action" ""
! 1349: different from
! 1350: .RI "" "none" ","
! 1351: the inverse action is performed. Configurations with
! 1352: .RI "" "start" ""
! 1353: get closed, while such with
! 1354: .RI "" "trap" ""
! 1355: get uninstalled.
! 1356:
! 1357: .TP
! 1358: .BR connections.<conn>.children.<child>.close_action " [none]"
! 1359: Action to perform after a CHILD_SA gets closed by the peer. The default of
! 1360: .RI "" "none" ""
! 1361: does not take any action,
! 1362: .RI "" "trap" ""
! 1363: installs a trap policy for the CHILD_SA.
! 1364: .RI "" "start" ""
! 1365: tries to re\-create the CHILD_SA.
! 1366:
! 1367: .RB "" "close_action" ""
! 1368: does not provide any guarantee that the CHILD_SA is kept alive.
! 1369: It acts on explicit close messages only, but not on negotiation failures. Use
! 1370: trap policies to reliably re\-create failed CHILD_SAs.
! 1371:
! 1372: .TP
! 1373: .B secrets
! 1374: .br
! 1375: Section defining secrets for IKE/EAP/XAuth authentication and private key
! 1376: decryption. The
! 1377: .RB "" "secrets" ""
! 1378: section takes sub\-sections having a specific prefix
! 1379: which defines the secret type.
! 1380:
! 1381: It is not recommended to define any private key decryption passphrases, as then
! 1382: there is no real security benefit in having encrypted keys. Either store the key
! 1383: unencrypted or enter the keys manually when loading credentials.
! 1384:
! 1385: .TP
! 1386: .B secrets.eap<suffix>
! 1387: .br
! 1388: EAP secret section for a specific secret. Each EAP secret is defined in a unique
! 1389: section having the
! 1390: .RI "" "eap" ""
! 1391: prefix. EAP secrets are used for XAuth authentication
! 1392: as well.
! 1393:
! 1394: .TP
! 1395: .BR secrets.eap<suffix>.secret " []"
! 1396: Value of the EAP/XAuth secret. It may either be an ASCII string, a hex encoded
! 1397: string if it has a
! 1398: .RI "" "0x" ""
! 1399: prefix or a Base64 encoded string if it has a
! 1400: .RI "" "0s" ""
! 1401: prefix in its value.
! 1402:
! 1403: .TP
! 1404: .BR secrets.eap<suffix>.id<suffix> " []"
! 1405: Identity the EAP/XAuth secret belongs to. Multiple unique identities may be
! 1406: specified, each having an
! 1407: .RI "" "id" ""
! 1408: prefix, if a secret is shared between multiple
! 1409: users.
! 1410:
! 1411: .TP
! 1412: .B secrets.xauth<suffix>
! 1413: .br
! 1414: XAuth secret section for a specific secret.
! 1415: .RB "" "xauth" ""
! 1416: is just an alias for
! 1417: .RB "" "eap" ","
! 1418: secrets under both section prefixes are used for both EAP and XAuth
! 1419: authentication.
! 1420:
! 1421: .TP
! 1422: .B secrets.ntlm<suffix>
! 1423: .br
! 1424: NTLM secret section for a specific secret. Each NTLM secret is defined in a
! 1425: unique section having the
! 1426: .RI "" "ntlm" ""
! 1427: prefix. NTLM secrets may only be used for
! 1428: EAP\-MSCHAPv2 authentication.
! 1429:
! 1430: .TP
! 1431: .BR secrets.ntlm<suffix>.secret " []"
! 1432: Value of the NTLM secret, which is the NT Hash of the actual secret, that is,
! 1433: MD4(UTF\-16LE(secret)). The resulting 16\-byte value may either be given as a hex
! 1434: encoded string with a
! 1435: .RI "" "0x" ""
! 1436: prefix or as a Base64 encoded string with a
! 1437: .RI "" "0s" ""
! 1438: prefix.
! 1439:
! 1440: .TP
! 1441: .BR secrets.ntlm<suffix>.id<suffix> " []"
! 1442: Identity the NTLM secret belongs to. Multiple unique identities may be
! 1443: specified, each having an
! 1444: .RI "" "id" ""
! 1445: prefix, if a secret is shared between multiple
! 1446: users.
! 1447:
! 1448: .TP
! 1449: .B secrets.ike<suffix>
! 1450: .br
! 1451: IKE preshared secret section for a specific secret. Each IKE PSK is defined in a
! 1452: unique section having the
! 1453: .RI "" "ike" ""
! 1454: prefix.
! 1455:
! 1456: .TP
! 1457: .BR secrets.ike<suffix>.secret " []"
! 1458: Value of the IKE preshared secret. It may either be an ASCII string, a hex
! 1459: encoded string if it has a
! 1460: .RI "" "0x" ""
! 1461: prefix or a Base64 encoded string if it has a
! 1462: .RI "" "0s" ""
! 1463: prefix in its value.
! 1464:
! 1465: .TP
! 1466: .BR secrets.ike<suffix>.id<suffix> " []"
! 1467: IKE identity the IKE preshared secret belongs to. Multiple unique identities may
! 1468: be specified, each having an
! 1469: .RI "" "id" ""
! 1470: prefix, if a secret is shared between multiple
! 1471: peers.
! 1472:
! 1473: .TP
! 1474: .B secrets.ppk<suffix>
! 1475: .br
! 1476: Postquantum Preshared Key (PPK) section for a specific secret. Each PPK is
! 1477: defined in a unique section having the
! 1478: .RI "" "ppk" ""
! 1479: prefix.
! 1480:
! 1481: .TP
! 1482: .BR secrets.ppk<suffix>.secret " []"
! 1483: Value of the PPK. It may either be an ASCII string, a hex encoded string if
! 1484: it has a
! 1485: .RI "" "0x" ""
! 1486: prefix or a Base64 encoded string if it has a
! 1487: .RI "" "0s" ""
! 1488: prefix in its
! 1489: value. Should have at least 256 bits of entropy for 128\-bit security.
! 1490:
! 1491: .TP
! 1492: .BR secrets.ppk<suffix>.id<suffix> " []"
! 1493: PPK identity the PPK belongs to. Multiple unique identities may be specified,
! 1494: each having an
! 1495: .RI "" "id" ""
! 1496: prefix, if a secret is shared between multiple peers.
! 1497:
! 1498: .TP
! 1499: .B secrets.private<suffix>
! 1500: .br
! 1501: Private key decryption passphrase for a key in the
! 1502: .RI "" "private" ""
! 1503: folder.
! 1504:
! 1505: .TP
! 1506: .BR secrets.private<suffix>.file " []"
! 1507: File name in the
! 1508: .RI "" "private" ""
! 1509: folder for which this passphrase should be used.
! 1510:
! 1511: .TP
! 1512: .BR secrets.private<suffix>.secret " []"
! 1513: Value of decryption passphrase for private key.
! 1514:
! 1515: .TP
! 1516: .B secrets.rsa<suffix>
! 1517: .br
! 1518: Private key decryption passphrase for a key in the
! 1519: .RI "" "rsa" ""
! 1520: folder.
! 1521:
! 1522: .TP
! 1523: .BR secrets.rsa<suffix>.file " []"
! 1524: File name in the
! 1525: .RI "" "rsa" ""
! 1526: folder for which this passphrase should be used.
! 1527:
! 1528: .TP
! 1529: .BR secrets.rsa<suffix>.secret " []"
! 1530: Value of decryption passphrase for RSA key.
! 1531:
! 1532: .TP
! 1533: .B secrets.ecdsa<suffix>
! 1534: .br
! 1535: Private key decryption passphrase for a key in the
! 1536: .RI "" "ecdsa" ""
! 1537: folder.
! 1538:
! 1539: .TP
! 1540: .BR secrets.ecdsa<suffix>.file " []"
! 1541: File name in the
! 1542: .RI "" "ecdsa" ""
! 1543: folder for which this passphrase should be used.
! 1544:
! 1545: .TP
! 1546: .BR secrets.ecdsa<suffix>.secret " []"
! 1547: Value of decryption passphrase for ECDSA key.
! 1548:
! 1549: .TP
! 1550: .B secrets.pkcs8<suffix>
! 1551: .br
! 1552: Private key decryption passphrase for a key in the
! 1553: .RI "" "pkcs8" ""
! 1554: folder.
! 1555:
! 1556: .TP
! 1557: .BR secrets.pkcs8<suffix>.file " []"
! 1558: File name in the
! 1559: .RI "" "pkcs8" ""
! 1560: folder for which this passphrase should be used.
! 1561:
! 1562: .TP
! 1563: .BR secrets.pkcs8<suffix>.secret " []"
! 1564: Value of decryption passphrase for PKCS#8 key.
! 1565:
! 1566: .TP
! 1567: .B secrets.pkcs12<suffix>
! 1568: .br
! 1569: PKCS#12 decryption passphrase for a container in the
! 1570: .RI "" "pkcs12" ""
! 1571: folder.
! 1572:
! 1573: .TP
! 1574: .BR secrets.pkcs12<suffix>.file " []"
! 1575: File name in the
! 1576: .RI "" "pkcs12" ""
! 1577: folder for which this passphrase should be used.
! 1578:
! 1579: .TP
! 1580: .BR secrets.pkcs12<suffix>.secret " []"
! 1581: Value of decryption passphrase for PKCS#12 container.
! 1582:
! 1583: .TP
! 1584: .B secrets.token<suffix>
! 1585: .br
! 1586: Definition for a private key that's stored on a token/smartcard.
! 1587:
! 1588: .TP
! 1589: .BR secrets.token<suffix>.handle " []"
! 1590: Hex\-encoded CKA_ID of the private key on the token.
! 1591:
! 1592: .TP
! 1593: .BR secrets.token<suffix>.slot " []"
! 1594: Optional slot number to access the token.
! 1595:
! 1596: .TP
! 1597: .BR secrets.token<suffix>.module " []"
! 1598: Optional PKCS#11 module name to access the token.
! 1599:
! 1600: .TP
! 1601: .BR secrets.token<suffix>.pin " []"
! 1602: Optional PIN required to access the key on the token. If none is provided the
! 1603: user is prompted during an interactive \-\-load\-creds call.
! 1604:
! 1605: .TP
! 1606: .B pools
! 1607: .br
! 1608: Section defining named pools. Named pools may be referenced by connections with
! 1609: the
! 1610: .RB "" "pools" ""
! 1611: option to assign virtual IPs and other configuration attributes.
! 1612:
! 1613: .TP
! 1614: .B pools.<name>
! 1615: .br
! 1616: Section defining a single pool with a unique name.
! 1617:
! 1618: .TP
! 1619: .BR pools.<name>.addrs " []"
! 1620: Subnet or range defining addresses allocated in pool. Accepts a single CIDR
! 1621: subnet defining the pool to allocate addresses from or an address range
! 1622: (<from>\-<to>). Pools must be unique and non\-overlapping.
! 1623:
! 1624: .TP
! 1625: .BR pools.<name>.<attr> " []"
! 1626: Comma separated list of additional attributes of type
! 1627: .RB "" "<attr>" "."
! 1628: The attribute
! 1629: type may be one of
! 1630: .RI "" "dns" ","
! 1631: .RI "" "nbns" ","
! 1632: .RI "" "dhcp" ","
! 1633: .RI "" "netmask" ","
! 1634: .RI "" "server" ","
! 1635: .RI "" "subnet" ","
! 1636: .RI "" "split_include" ""
! 1637: and
! 1638: .RI "" "split_exclude" ""
! 1639: to define addresses or CIDR subnets for the
! 1640: corresponding attribute types. Alternatively,
! 1641: .RB "" "<attr>" ""
! 1642: can be a numerical
! 1643: identifier, for which string attribute values are accepted as well.
! 1644:
! 1645: .TP
! 1646: .B authorities
! 1647: .br
! 1648: Section defining attributes of certification authorities.
! 1649:
! 1650: .TP
! 1651: .B authorities.<name>
! 1652: .br
! 1653: Section defining a certification authority with a unique name.
! 1654:
! 1655: .TP
! 1656: .BR authorities.<name>.cacert " []"
! 1657: CA certificate belonging to the certification authority. The certificates may
! 1658: use a relative path from the
! 1659: .RB "" "swanctl" ""
! 1660: .RI "" "x509ca" ""
! 1661: directory or an absolute path.
! 1662:
! 1663: Configure one of
! 1664: .RI "" "cacert" ","
! 1665: .RI "" "file" ","
! 1666: or
! 1667: .RI "" "handle" ""
! 1668: per section.
! 1669:
! 1670: .TP
! 1671: .BR authorities.<name>.file " []"
! 1672: Absolute path to the certificate to load. Passed as\-is to the daemon, so it must
! 1673: be readable by it.
! 1674:
! 1675: Configure one of
! 1676: .RI "" "cacert" ","
! 1677: .RI "" "file" ","
! 1678: or
! 1679: .RI "" "handle" ""
! 1680: per section.
! 1681:
! 1682: .TP
! 1683: .BR authorities.<name>.handle " []"
! 1684: Hex\-encoded CKA_ID of the CA certificate on a token.
! 1685:
! 1686: Configure one of
! 1687: .RI "" "cacert" ","
! 1688: .RI "" "file" ","
! 1689: or
! 1690: .RI "" "handle" ""
! 1691: per section.
! 1692:
! 1693: .TP
! 1694: .BR authorities.<name>.slot " []"
! 1695: Optional slot number of the token that stores the CA certificate.
! 1696:
! 1697: .TP
! 1698: .BR authorities.<name>.module " []"
! 1699: Optional PKCS#11 module name.
! 1700:
! 1701: .TP
! 1702: .BR authorities.<name>.crl_uris " []"
! 1703: Comma\-separated list of CRL distribution points (ldap, http, or file URI).
! 1704:
! 1705: .TP
! 1706: .BR authorities.<name>.ocsp_uris " []"
! 1707: Comma\-separated list of OCSP URIs.
! 1708:
! 1709: .TP
! 1710: .BR authorities.<name>.cert_uri_base " []"
! 1711: Defines the base URI for the Hash and URL feature supported by IKEv2. Instead of
! 1712: exchanging complete certificates, IKEv2 allows one to send an URI that resolves
! 1713: to the DER encoded certificate. The certificate URIs are built by appending the
! 1714: SHA1 hash of the DER encoded certificates to this base URI.
! 1715:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>