1.\" $OpenBSD: iked.conf.5,v 1.96 2024/04/13 12:11:08 jmc Exp $ 2.\" 3.\" Copyright (c) 2010 - 2014 Reyk Floeter <reyk@openbsd.org> 4.\" Copyright (c) 2004 Mathieu Sauve-Frankel All rights reserved. 5.\" 6.\" Permission to use, copy, modify, and distribute this software for any 7.\" purpose with or without fee is hereby granted, provided that the above 8.\" copyright notice and this permission notice appear in all copies. 9.\" 10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17.\" 18.Dd $Mdocdate: April 13 2024 $ 19.Dt IKED.CONF 5 20.Os 21.Sh NAME 22.Nm iked.conf 23.Nd IKEv2 configuration file 24.Sh DESCRIPTION 25.Nm 26is the configuration file for 27.Xr iked 8 , 28the Internet Key Exchange version 2 (IKEv2) daemon for IPsec. 29IPsec itself is a pair of protocols: 30Encapsulating Security Payload (ESP), 31which provides integrity and confidentiality; 32and Authentication Header (AH), 33which provides integrity. 34The IPsec protocol itself is described in 35.Xr ipsec 4 . 36.Pp 37In its most basic form, a flow is established between hosts and/or 38networks, and then Security Associations (SA) are established, 39which detail how the desired protection will be achieved. 40IPsec uses flows to determine whether to apply security services to an 41IP packet or not. 42.Xr iked 8 43is used to set up flows and establish SAs automatically, 44by specifying 45.Sq ikev2 46policies in 47.Nm 48(see 49.Sx AUTOMATIC KEYING POLICIES , 50below). 51.Pp 52Alternative methods of setting up flows and SAs are also possible 53using manual keying or automatic keying using the older ISAKMP/Oakley 54a.k.a. IKEv1 protocol. 55Manual keying is not recommended, but can be convenient for quick 56setups and testing. 57See 58.Xr ipsec.conf 5 59and 60.Xr isakmpd 8 61for more information about manual keying and ISAKMP support. 62.Sh IKED.CONF FILE FORMAT 63.Nm 64is divided into three main sections: 65.Bl -tag -width xxxx 66.It Sy Macros 67User-defined macros may be defined and used later, simplifying the 68configuration file. 69.It Sy Global Configuration 70Global settings for 71.Xr iked 8 . 72.It Sy Automatic Keying Policies 73Policies to set up IPsec flows and SAs automatically. 74.El 75.Pp 76Lines beginning with 77.Sq # 78and empty lines are regarded as comments, 79and ignored. 80Lines may be split using the 81.Sq \e 82character. 83.Pp 84Argument names not beginning with a letter, digit, or underscore 85must be quoted. 86.Pp 87Addresses can be specified in CIDR notation (matching netblocks), 88as symbolic host names, interface names, or interface group names. 89.Pp 90Additional configuration files can be included with the 91.Ic include 92keyword, for example: 93.Bd -literal -offset indent 94include "/etc/macros.conf" 95.Ed 96.Pp 97Certain parameters can be expressed as lists, in which case 98.Xr iked 8 99generates all the necessary flow combinations. 100For example: 101.Bd -literal -offset indent 102ikev2 esp proto { tcp, udp } \e 103 from 192.168.1.1 to 10.0.0.18 \e 104 peer 192.168.10.1 105.Ed 106.Sh MACROS 107Macros can be defined that will later be expanded in context. 108Macro names must start with a letter, digit, or underscore, 109and may contain any of those characters. 110Macro names may not be reserved words (for example 111.Ic flow , 112.Ic from , 113.Ic esp ) . 114Macros are not expanded inside quotes. 115.Pp 116For example: 117.Bd -literal -offset indent 118remote_gw = "192.168.3.12" 119ikev2 esp from 192.168.7.0/24 to 192.168.8.0/24 peer $remote_gw 120.Ed 121.Sh GLOBAL CONFIGURATION 122Here are the settings that can be set globally: 123.Bl -tag -width xxxx 124.It Ic set active 125Set 126.Xr iked 8 127to global active mode. 128In active mode the per-policy 129.Ar mode 130setting is respected. 131.Xr iked 8 132will initiate policies set to 133.Ar active 134and wait for incoming requests for policies set to 135.Ar passive . 136This is the default. 137.It Ic set passive 138Set 139.Xr iked 8 140to global passive mode. 141In passive mode no packets are sent to peers and no connections are 142initiated by 143.Xr iked 8 , 144even for 145.Ar active 146policies. 147This option is used for setups using 148.Xr sasyncd 8 149and 150.Xr carp 4 151to provide redundancy. 152.Xr iked 8 153will run in passive mode until sasyncd has determined that the host 154is the master and can switch to active mode. 155.It Ic set couple 156Load the negotiated security associations (SAs) and flows into the kernel. 157This is the default. 158.It Ic set decouple 159Don't load the negotiated SAs and flows from the kernel. 160This mode is only useful for testing and debugging. 161.It Ic set dpd_check_interval Ar time 162Specify the liveness check interval, in seconds. 163Setting 164.Ar time 165to 0 disables DPD. 166The default value is 60 seconds. 167.It Ic set enforcesingleikesa 168Allow only a single active IKE SA for each 169.Ic dstid . 170When a new SA with the same 171.Ic dstid 172is established, it replaces the old SA. 173.It Ic set noenforcesingleikesa 174Don't limit the number of IKE SAs per 175.Ic dstid . 176This is the default. 177.It Ic set fragmentation 178Enable IKEv2 Message Fragmentation (RFC 7383) support. 179This allows IKEv2 to operate in environments that might block IP fragments. 180.It Ic set nofragmentation 181Disables IKEv2 Message Fragmentation support. 182This is the default. 183.It Ic set mobike 184Enable MOBIKE (RFC 4555) support. 185This is the default. 186MOBIKE allows the peer IP address to be changed for IKE and IPsec SAs. 187Currently 188.Xr iked 8 189only supports MOBIKE when acting as a responder. 190.It Ic set nomobike 191Disables MOBIKE support. 192.It Ic set cert_partial_chain 193Allow partial certificate chain if at least one certificate is a trusted CA from 194.Pa /etc/iked/ca/ . 195.It Ic set ocsp Ar URL Op Ic tolerate Ar time Op Ic maxage Ar time 196Enable OCSP and set the fallback URL of the OCSP responder. 197This fallback will be used if the trusted CA from 198.Pa /etc/iked/ca/ 199does not have an OCSP-URL extension. 200The matching responder certificates have to be placed in 201.Pa /etc/iked/ocsp/responder.crt . 202.Pp 203The optional 204.Ic tolerate 205parameter specifies how much the OCSP response attribute 206.Sq thisUpdate 207may be in the future and how much 208.Sq nextUpdate 209may be in the past, with respect to the local time. 210The optional 211.Ic maxage 212parameter specifies how much 213.Sq thisUpdate 214may be in the past. 215If 216.Ic tolerate 217is set to 0 then the times are not verified at all. 218This is the default setting. 219.It Ic set vendorid 220Send OpenIKED Vendor ID payload. 221This is the default. 222.It Ic set novendorid 223Don't send a Vendor ID payload. 224.It Ic user Ar name password 225.Xr iked 8 226supports user-based authentication by tunneling the Extensible 227Authentication Protocol (EAP) over IKEv2. 228In its most basic form, the users will be authenticated against a 229local, integrated password database that is configured with the 230.Ic user 231lines in 232.Nm 233and the 234.Ar name 235and 236.Ar password 237arguments. 238The password has to be specified in plain text which is 239required to support different challenge-based EAP methods like 240EAP-MD5 or EAP-MSCHAPv2. 241.El 242.Sh AUTOMATIC KEYING POLICIES 243This section is used to configure policies that will be used by 244.Xr iked 8 245to set up flows and SAs automatically. 246Some examples of setting up automatic keying: 247.Bd -literal -offset 3n 248# Set up a VPN: 249# First between the gateway machines 192.168.3.1 and 192.168.3.2 250# Second between the networks 10.1.1.0/24 and 10.1.2.0/24 251ikev2 esp from 192.168.3.1 to 192.168.3.2 252ikev2 esp from 10.1.1.0/24 to 10.1.2.0/24 peer 192.168.3.2 253.Ed 254.Pp 255For incoming connections from remote peers, the policies are evaluated 256in sequential order, from first to last. 257The last matching policy decides what action is taken; if no policy matches 258the connection, the default action is to ignore the connection attempt or 259to use the 260.Ar default 261policy, if set. 262See the 263.Sx EXAMPLES 264section for a detailed example of the policy evaluation. 265.Pp 266The first time an IKEv2 connection matches a policy, an IKE SA is 267created; for subsequent packets the connection is identified by the 268IKEv2 parameters that are stored in the SA without evaluating any 269policies. 270After the connection is closed or times out, the IKE SA is 271automatically removed. 272.Pp 273The commands are as follows: 274.Bl -tag -width xxxx -compact 275.It Xo 276.Ic ikev2 277.Op Ar name 278.Xc 279The mandatory 280.Ic ikev2 281keyword will identify an IKEv2 automatic keying policy. 282.Ar name 283is an optional arbitrary string identifying the policy. 284The name should only occur once in 285.Nm 286or any included files. 287If omitted, 288a name will be generated automatically for the policy. 289.Pp 290.It Op Ar eval 291The 292.Ar eval 293option modifies the policy evaluation for this policy. 294It can be one of 295.Ar quick , 296.Ar skip 297or 298.Ar default . 299If a new incoming connection matches a policy with the 300.Ar quick 301option set, that policy is considered the last matching policy, 302and evaluation of subsequent policies is skipped. 303The 304.Ar skip 305option will disable evaluation of this policy for incoming connections. 306The 307.Ar default 308option sets the default policy and should only be specified once. 309.Pp 310.It Op Ar mode 311.Ar mode 312specifies the IKEv2 mode to use: 313one of 314.Ar passive 315or 316.Ar active . 317When 318.Ar passive 319is specified, 320.Xr iked 8 321will not immediately start negotiation of this tunnel, but wait for an incoming 322request from the remote peer. 323When 324.Ar active 325is specified, negotiation will be started at once. 326If omitted, 327.Ar passive 328mode will be used. 329.Pp 330.It Op Ar ipcomp 331The keyword 332.Ar ipcomp 333specifies that 334.Xr ipcomp 4 , 335the IP Payload Compression protocol, is negotiated in addition to encapsulation. 336The optional compression is applied before packets are encapsulated. 337IPcomp must be enabled in the kernel: 338.Pp 339.Dl # sysctl net.inet.ipcomp.enable=1 340.Pp 341.It Op Ar tmode 342.Ar tmode 343describes the encapsulation mode to be used. 344Possible modes are 345.Ar tunnel 346and 347.Ar transport ; 348the default is 349.Ar tunnel . 350.Pp 351.It Op Ar encap 352.Ar encap 353specifies the encapsulation protocol to be used. 354Possible protocols are 355.Ar esp 356and 357.Ar ah ; 358the default is 359.Ar esp . 360.Pp 361.It Op Ar af 362This policy only applies to endpoints of the specified address family 363which can be either 364.Ar inet 365or 366.Ar inet6 . 367This only matters for IKEv2 endpoints and does not 368restrict the traffic selectors to negotiate flows with different 369address families, e.g. IPv6 flows negotiated by IPv4 endpoints. 370.Pp 371.It Xo 372.Ic proto Ar protocol 373.Xc 374.It Xo 375.Ic proto 376.Ic { Ar protocol ... Ic } 377.Xc 378The optional 379.Ic proto 380parameter restricts the flow to a specific IP protocol. 381Common protocols are 382.Xr icmp 4 , 383.Xr tcp 4 , 384and 385.Xr udp 4 . 386For a list of all the protocol name to number mappings used by 387.Xr iked 8 , 388see the file 389.Pa /etc/protocols . 390.Pp 391Multiple 392.Ar protocol 393entries can be specified, separated by commas or whitespace, 394if enclosed in curly brackets: 395.Bd -literal -offset indent 396proto { tcp, udp } 397.Ed 398.Pp 399.It Ic rdomain Ar number 400Specify a different routing domain for unencrypted traffic. 401The resulting IPsec SAs will match outgoing packets in the specified 402.Ic rdomain Ar number 403and move the encrypted packets to the rdomain the 404.Xr iked 8 405instance is running in. 406Vice versa, incoming 407.Xr ipsec 4 408traffic is moved to 409.Ic rdomain Ar number 410after decryption. 411.Pp 412.It Xo 413.Ic from Ar src 414.Op Ic port Ar sport 415.Op Pq Ar srcnat 416.Ic to Ar dst 417.Op Ic port Ar dport 418.Xc 419Specify one or more traffic selectors for this policy which will be 420used to negotiate the IPsec flows between the IKEv2 peers. 421During the negotiation, the peers may decide to narrow a flow to a 422subset of the configured traffic selector networks to match the 423policies on each side. 424.Pp 425Each traffic selector will apply for packets with source address 426.Ar src 427and destination address 428.Ar dst . 429If the 430.Ar src 431argument specifies a fictional source ID, 432the 433.Ar srcnat 434parameter can be used to specify the actual source address. 435This can be used in outgoing NAT/BINAT scenarios as described below. 436The keyword 437.Ar any 438will match any address (i.e. 0.0.0.0/0 and ::/0). 439If the 440.Ic config address 441option is specified, the 442.Ar dynamic 443keyword can be used to create flows from or to the dynamically 444assigned address. 445.Pp 446The optional 447.Ic port 448modifiers restrict the traffic selectors to the specified ports. 449They are only valid in conjunction with the 450.Xr tcp 4 451and 452.Xr udp 4 453protocols. 454Ports can be specified by number or by name. 455For a list of all port name to number mappings used by 456.Xr ipsecctl 8 , 457see the file 458.Pa /etc/services . 459.Pp 460.It Ic local Ar localip Ic peer Ar remote 461The 462.Ic local 463parameter specifies the address or FQDN of the local endpoint. 464Unless the gateway is multi-homed or uses address aliases, 465this option is generally not needed. 466.Pp 467The 468.Ic peer 469parameter specifies the address or FQDN of the remote endpoint. 470For host-to-host connections where 471.Ar dst 472is identical to 473.Ar remote , 474this option is generally not needed as it will be set to 475.Ar dst 476automatically. 477If it is not specified or if the keyword 478.Ar any 479is given, the default peer is used. 480.Pp 481.It Xo 482.Ic ikesa 483.Ic auth Ar algorithm 484.Ic enc Ar algorithm 485.Ic prf Ar algorithm 486.Ic group Ar group 487.Xc 488These parameters define the mode and cryptographic transforms to be 489used for the IKE SA negotiation, also known as phase 1. 490The IKE SA will be used to authenticate the machines and to set up an 491encrypted channel for the IKEv2 protocol. 492.Pp 493Possible values for 494.Ic auth , 495.Ic enc , 496.Ic prf , 497.Ic group , 498and the default proposals are described below in 499.Sx CRYPTO TRANSFORMS . 500If omitted, 501.Xr iked 8 502will use the default proposals for the IKEv2 protocol. 503.Pp 504The keyword 505.Ic ikesa 506can be used multiple times as a delimiter between IKE SA proposals. 507The order of the proposals depend on the order in the configuration. 508The keywords 509.Ic auth , 510.Ic enc , 511.Ic prf 512and 513.Ic group 514can be used multiple times within a single proposal to configure 515multiple crypto transforms. 516.Pp 517.It Xo 518.Ic childsa 519.Ic auth Ar algorithm 520.Ic enc Ar algorithm 521.Ic group Ar group 522.Ic esn 523.Xc 524These parameters define the cryptographic transforms to be used for 525the Child SA negotiation, also known as phase 2. 526Each Child SA will be used to negotiate the actual IPsec SAs. 527The initial Child SA is always negotiated with the initial IKEv2 key 528exchange; additional Child SAs may be negotiated with additional 529Child SA key exchanges for an established IKE SA. 530.Pp 531Possible values for 532.Ic auth , 533.Ic enc , 534.Ic group , 535.Ic esn , 536and the default proposals are described below in 537.Sx CRYPTO TRANSFORMS . 538If omitted, 539.Xr iked 8 540will use the default proposals for the ESP or AH protocol. 541.Pp 542The 543.Ic group 544option will only be used to enable Perfect Forward Secrecy (PFS) 545for additional Child SAs exchanges that are not part of the initial 546key exchange. 547.Pp 548The keyword 549.Ic childsa 550can be used multiple times as a delimiter between Child SA proposals. 551The order of the proposals depend on the order in the configuration. 552The keywords 553.Ic auth , 554.Ic enc 555and 556.Ic group 557can be used multiple times within a single proposal to configure 558multiple crypto transforms. 559.Pp 560.It Ic srcid Ar string Ic dstid Ar string 561.Ic srcid 562defines an ID of type 563.Dq FQDN , 564.Dq ASN1_DN , 565.Dq IPV4 , 566.Dq IPV6 , 567or 568.Dq UFQDN 569that will be used by 570.Xr iked 8 571as the identity of the local peer. 572If the argument is an email address (reyk@example.com), 573.Xr iked 8 574will use UFQDN as the ID type. 575The ASN1_DN type will be used if the string starts with a slash 576.Sq / 577(/C=DE/../CN=10.0.0.1/emailAddress=reyk@example.com). 578If the argument is an IPv4 address or a compressed IPv6 address, 579the ID types IPV4 or IPV6 will be used. 580Anything else is considered to be an FQDN. 581.Pp 582If 583.Ic srcid 584is omitted, 585the default is to use the hostname of the local machine, 586see 587.Xr hostname 1 588to set or print the hostname. 589.Pp 590.Ic dstid 591is similar to 592.Ic srcid , 593but instead specifies the ID to be used 594by the remote peer. 595.Pp 596.It Ic ikelifetime Ar time 597The optional 598.Ic ikelifetime 599parameter defines the IKE SA expiration timeout by the 600.Ar time 601SA was created. 602A zero value disables active IKE SA rekeying. 603This is the default. 604.Pp 605The accepted format of the 606.Ar time 607specification is described below. 608.Pp 609.It Ic lifetime Ar time Op Ic bytes Ar bytes 610The optional 611.Ic lifetime 612parameter defines the Child SA expiration timeout by the 613.Ar time 614SA was in use and by the number of 615.Ar bytes 616that were processed using the SA. 617Default values are 3 hours and 4 gigabytes which means that SA will be 618rekeyed before reaching the time limit or 4 gigabytes of data 619will pass through. 620Zero values disable rekeying. 621.Pp 622Several unit specifiers are recognized (ignoring case): 623.Ql m 624and 625.Ql h 626for minutes and hours, and 627.Ql K , 628.Ql M 629and 630.Ql G 631for kilo-, mega- and gigabytes accordingly. 632.Pp 633Rekeying must happen at least several times a day as 634IPsec security heavily depends on frequent key renewals. 635.Pp 636.It Op Ar ikeauth 637Specify a method to be used to authenticate the remote peer. 638.Xr iked 8 639will automatically determine a method based on public keys or certificates 640configured for the peer. 641.Ar ikeauth 642can be used to override this behaviour. 643Non-psk modes will require setting up certificates and RSA or ECDSA public 644keys; see 645.Xr iked 8 646for more information. 647.Pp 648.Bl -tag -width $domain -compact -offset indent 649.It Ic eap Ar type 650Use EAP to authenticate the initiator. 651The only supported EAP 652.Ar type 653is currently 654.Ar MSCHAP-V2 . 655The responder will use RSA public key authentication. 656.It Ic ecdsa256 657Use ECDSA with a 256-bit elliptic curve key and SHA2-256 for authentication. 658.It Ic ecdsa384 659Use ECDSA with a 384-bit elliptic curve key and SHA2-384 for authentication. 660.It Ic ecdsa521 661Use ECDSA with a 521-bit elliptic curve key and SHA2-512 for authentication. 662.It Ic psk Ar string 663Use a pre-shared key 664.Ar string 665or hex value (starting with 0x) for authentication. 666.It Ic psk file Ar path 667Use a pre-shared hex key (without leading 0x) read from 668.Ar path 669for authentication. 670.It Ic rfc7427 671Only use RFC 7427 signatures for authentication. 672RFC 7427 signatures currently only support SHA2-256 as the hash. 673.It Ic rsa 674Use RSA public key authentication with SHA1 as the hash. 675.El 676.Pp 677The default is to allow any signature authentication. 678.Pp 679.It Cm config Ar option address 680.It Cm request Ar option address 681Request or serve one or more optional configuration payloads (CP). 682The configuration 683.Ar option 684can be one of the following with the expected address format: 685.Pp 686.Bl -tag -width Ds -compact -offset indent 687.It Ic address Ar address 688Assign a static address on the internal network. 689.It Ic address Ar address/prefix 690Assign a dynamic address on the internal network. 691The address will be assigned from an address pool with the size specified by 692.Ar prefix . 693.It Ic netmask Ar netmask 694The IPv4 netmask of the internal network. 695.It Ic name-server Ar address 696The DNS server address within the internal network. 697.It Ic netbios-server Ar address 698The NetBIOS name server (WINS) within the internal network. 699This option is provided for compatibility with legacy clients. 700.It Ic dhcp-server Ar address 701The address of an internal DHCP server for further configuration. 702.It Ic protected-subnet Ar address/prefix 703The address of an additional IPv4 or IPv6 subnet reachable over the 704gateway. 705This option is used to notify the peer of a subnet behind the gateway (that 706might require a second SA). 707Networks specified in this SA's "from" or "to" options do not need to be 708included. 709.It Ic access-server Ar address 710The address of an internal remote access server. 711.El 712.Pp 713.It Ic iface Ar interface 714Enable automatic network configuration as initiator. 715Received addresses, routes and nameservers will be installed on the specified 716.Ar interface . 717.Pp 718.It Ic tag Ar string 719Add a 720.Xr pf 4 721tag to all packets of IPsec SAs created for this connection. 722This will allow matching packets for this connection by defining 723rules in 724.Xr pf.conf 5 725using the 726.Cm tagged 727keyword. 728.Pp 729The following variables can be used in tags to include information 730from the remote peer on runtime: 731.Pp 732.Bl -tag -width $domain -compact -offset indent 733.It Ar $id 734The 735.Ic dstid 736that was proposed by the remote peer to identify itself. 737It will be expanded to 738.Ar id-value , 739e.g.\& 740.Ar FQDN/foo.example.com . 741To limit the size of the derived tag, 742.Xr iked 8 743will extract the common name 744.Sq CN= 745from ASN1_DN IDs, for example 746.Ar ASN1_ID//C=DE/../CN=10.1.1.1/.. 747will be expanded to 748.Ar 10.1.1.1 . 749.It Ar $eapid 750For a connection using EAP, the identity (username) used by the remote peer. 751.It Ar $domain 752Extract the domain from IDs of type FQDN, UFQDN or ASN1_DN. 753.It Ar $name 754The name of the IKEv2 policy that was configured in 755.Nm 756or automatically generated by 757.Xr iked 8 . 758.El 759.Pp 760For example, if the ID is 761.Ar FQDN/foo.example.com 762or 763.Ar UFQDN/user@example.com , 764.Dq ipsec-$domain 765expands to 766.Dq ipsec-example.com . 767The variable expansion for the 768.Ar tag 769directive occurs only at runtime (not when the file is parsed) 770and must be quoted, or it will be interpreted as a macro. 771.Pp 772.It Ic tap Ar interface 773Send the decapsulated IPsec traffic to the specified 774.Xr enc 4 775.Ar interface 776instead of 777.Ar enc0 778for filtering and monitoring. 779The traffic will be blocked if the specified 780.Ar interface 781does not exist. 782.El 783.Sh PACKET FILTERING 784IPsec traffic appears unencrypted on the 785.Xr enc 4 786interface 787and can be filtered accordingly using the 788.Ox 789packet filter, 790.Xr pf 4 . 791The grammar for the packet filter is described in 792.Xr pf.conf 5 . 793.Pp 794The following components are relevant to filtering IPsec traffic: 795.Bl -ohang -offset indent 796.It external interface 797Interface for IKE traffic and encapsulated IPsec traffic. 798.It proto udp port 500 799IKE traffic on the external interface. 800.It proto udp port 4500 801IKE NAT-Traversal traffic on the external interface. 802.It proto ah | esp 803Encapsulated IPsec traffic 804on the external interface. 805.It enc0 806Default interface for outgoing traffic before it's been encapsulated, 807and incoming traffic after it's been decapsulated. 808State on this interface should be interface bound; 809see 810.Xr enc 4 811for further information. 812.It proto ipencap 813[tunnel mode only] 814IP-in-IP traffic flowing between gateways 815on the enc0 interface. 816.It tagged ipsec-example.org 817Match traffic of IPsec SAs using the 818.Ic tag 819keyword. 820.El 821.Pp 822If the filtering rules specify to block everything by default, 823the following rule 824would ensure that IPsec traffic never hits the packet filtering engine, 825and is therefore passed: 826.Bd -literal -offset indent 827set skip on enc0 828.Ed 829.Pp 830In the following example, all traffic is blocked by default. 831IPsec-related traffic from gateways {192.168.3.1, 192.168.3.2} and 832networks {10.0.1.0/24, 10.0.2.0/24} is permitted. 833.Bd -literal -offset indent 834block on ix0 835block on enc0 836 837pass in on ix0 proto udp from 192.168.3.2 to 192.168.3.1 \e 838 port {500, 4500} 839pass out on ix0 proto udp from 192.168.3.1 to 192.168.3.2 \e 840 port {500, 4500} 841 842pass in on ix0 proto esp from 192.168.3.2 to 192.168.3.1 843pass out on ix0 proto esp from 192.168.3.1 to 192.168.3.2 844 845pass in on enc0 proto ipencap from 192.168.3.2 to 192.168.3.1 \e 846 keep state (if-bound) 847pass out on enc0 proto ipencap from 192.168.3.1 to 192.168.3.2 \e 848 keep state (if-bound) 849pass in on enc0 from 10.0.2.0/24 to 10.0.1.0/24 \e 850 keep state (if-bound) 851pass out on enc0 from 10.0.1.0/24 to 10.0.2.0/24 \e 852 keep state (if-bound) 853.Ed 854.Pp 855.Xr pf 4 856has the ability to filter IPsec-related packets 857based on an arbitrary 858.Em tag 859specified within a ruleset. 860The tag is used as an internal marker 861which can be used to identify the packets later on. 862This could be helpful, 863for example, 864in scenarios where users are connecting in from differing IP addresses, 865or to support queue-based bandwidth control, 866since the enc0 interface does not support it. 867.Pp 868The following 869.Xr pf.conf 5 870fragment uses queues for all IPsec traffic with special 871handling for developers and employees: 872.Bd -literal -offset indent 873queue std on ix0 bandwidth 100M 874queue deflt parent std bandwidth 10M default 875queue developers parent std bandwidth 75M 876queue employees parent std bandwidth 5M 877queue ipsec parent std bandwidth 10M 878 879pass out on ix0 proto esp set queue ipsec 880 881pass out on ix0 tagged ipsec-developers.example.com \e 882 set queue developers 883pass out on ix0 tagged ipsec-employees.example.com \e 884 set queue employees 885.Ed 886.Pp 887The following example assigns the tags in the 888.Nm 889configuration and also sets an alternative 890.Xr enc 4 891device: 892.Bd -literal -offset indent 893ikev2 esp from 10.1.1.0/24 to 10.1.2.0/24 peer 192.168.3.2 \e 894 tag "ipsec-$domain" tap "enc1" 895.Ed 896.Sh OUTGOING NETWORK ADDRESS TRANSLATION 897In some network topologies it is desirable to perform NAT on traffic leaving 898through the VPN tunnel. 899In order to achieve that, 900the 901.Ar src 902argument is used to negotiate the desired network ID with the peer 903and the 904.Ar srcnat 905parameter defines the true local subnet, 906so that a correct SA can be installed on the local side. 907.Pp 908For example, 909if the local subnet is 192.168.1.0/24 and all the traffic 910for a specific VPN peer should appear as coming from 10.10.10.1, 911the following configuration is used: 912.Bd -literal -offset indent 913ikev2 esp from 10.10.10.1 (192.168.1.0/24) to 192.168.2.0/24 \e 914 peer 10.10.20.1 915.Ed 916.Pp 917Naturally, 918a relevant NAT rule is required in 919.Xr pf.conf 5 . 920For the example above, 921this would be: 922.Bd -literal -offset indent 923match out on enc0 from 192.168.1.0/24 to 192.168.2.0/24 \e 924 nat-to 10.10.10.1 925.Ed 926.Pp 927From the peer's point of view, 928the local end of the VPN tunnel is declared to be 10.10.10.1 929and all the traffic arrives with that source address. 930.Sh CRYPTO TRANSFORMS 931The following authentication types are permitted with the 932.Ic auth 933keyword: 934.Bl -column "Authentication" "Key Length" "Truncated Length" "Default" -offset indent 935.It Em "Authentication" Ta Em "Key Length" Ta Em "Truncated Length" Ta Em "Default" 936.It Li hmac-md5 Ta "128 bits" Ta "96 bits" Ta "" 937.It Li hmac-sha1 Ta "160 bits" Ta "96 bits" Ta "x" 938.It Li hmac-sha2-256 Ta "256 bits" Ta "128 bits" Ta "x" 939.It Li hmac-sha2-384 Ta "384 bits" Ta "192 bits" Ta "x" 940.It Li hmac-sha2-512 Ta "512 bits" Ta "256 bits" Ta "x" 941.El 942.Pp 943The following pseudo-random function types are permitted with the 944.Ic prf 945keyword: 946.Bl -column "hmac-sha2-512" "Key Length" "Default" "[IKE only]" -offset indent 947.It Em "PRF" Ta Em "Key Length" Ta Em "Default" Ta "" 948.It Li hmac-md5 Ta "128 bits" Ta "" Ta "[IKE only]" 949.It Li hmac-sha1 Ta "160 bits" Ta "x" Ta "[IKE only]" 950.It Li hmac-sha2-256 Ta "256 bits" Ta "x" Ta "[IKE only]" 951.It Li hmac-sha2-384 Ta "384 bits" Ta "x" Ta "[IKE only]" 952.It Li hmac-sha2-512 Ta "512 bits" Ta "x" Ta "[IKE only]" 953.El 954.Pp 955The following cipher types are permitted with the 956.Ic enc 957keyword: 958.Bl -column "chacha20-poly1305" "Key Length" "Default" "[ESP only]" -offset indent 959.It Em "Cipher" Ta Em "Key Length" Ta Em "Default" Ta "" 960.It Li 3des Ta "168 bits" Ta "x" Ta "" 961.It Li aes-128 Ta "128 bits" Ta "x" Ta "" 962.It Li aes-192 Ta "192 bits" Ta "x" Ta "" 963.It Li aes-256 Ta "256 bits" Ta "x" Ta "" 964.It Li aes-128-ctr Ta "160 bits" Ta "" Ta "[ESP only]" 965.It Li aes-192-ctr Ta "224 bits" Ta "" Ta "[ESP only]" 966.It Li aes-256-ctr Ta "288 bits" Ta "" Ta "[ESP only]" 967.It Li aes-128-gcm Ta "160 bits" Ta "x" Ta "" 968.It Li aes-192-gcm Ta "224 bits" Ta "" Ta "[ESP only]" 969.It Li aes-256-gcm Ta "288 bits" Ta "x" Ta "" 970.It Li aes-128-gcm-12 Ta "160 bits" Ta "" Ta "[IKE only]" 971.It Li aes-256-gcm-12 Ta "288 bits" Ta "" Ta "[IKE only]" 972.It Li blowfish Ta "160 bits" Ta "" Ta "[ESP only]" 973.It Li cast Ta "128 bits" Ta "" Ta "[ESP only]" 974.It Li chacha20-poly1305 Ta "288 bits" Ta "" Ta "[ESP only]" 975.El 976.Pp 977The following cipher types provide only authentication, 978not encryption: 979.Bl -column "chacha20-poly1305" "Key Length" "Default" "[ESP only]" -offset indent 980.It Li aes-128-gmac Ta "160 bits" Ta "" Ta "[ESP only]" 981.It Li aes-192-gmac Ta "224 bits" Ta "" Ta "[ESP only]" 982.It Li aes-256-gmac Ta "288 bits" Ta "" Ta "[ESP only]" 983.It Li null Ta "" Ta "" Ta "[ESP only]" 984.El 985.Pp 986The Extended Sequence Numbers option can be enabled or disabled with the 987.Ic esn 988or 989.Ic noesn 990keywords: 991.Bl -column "noesn" "Default" "[ESP only]" -offset indent 992.It Em ESN Ta Em "Default" Ta Em "" 993.It Li esn Ta "x" Ta "[ESP only]" 994.It Li noesn Ta "x" Ta "[ESP only]" 995.El 996.Pp 997Transforms followed by 998.Bq IKE only 999can only be used with the 1000.Ic ikesa 1001keyword, transforms with 1002.Bq ESP only 1003can only be used with the 1004.Ic childsa 1005keyword. 1006.Pp 1007Using AES-GMAC or NULL with ESP will only provide authentication. 1008This is useful in setups where AH cannot be used, e.g. when NAT is involved. 1009.Pp 1010The following group types are permitted with the 1011.Ic group 1012keyword: 1013.Bl -column "sntrup761x25519" "Group" "1190 B" "Hybrid PQKE" "Default" -offset indent 1014.It Em Name Ta Em Group Ta Em Size Ta Em Type Ta Em Default 1015.It Li modp768 Ta grp1 Ta 768 Ta "MODP" Ta "" Ta "[insecure]" 1016.It Li modp1024 Ta grp2 Ta 1024 Ta "MODP" Ta "x" Ta "[weak]" 1017.It Li modp1536 Ta grp5 Ta 1536 Ta "MODP" Ta "x" Ta "[weak]" 1018.It Li modp2048 Ta grp14 Ta 2048 Ta "MODP" Ta "x" 1019.It Li modp3072 Ta grp15 Ta 3072 Ta "MODP" Ta "x" 1020.It Li modp4096 Ta grp16 Ta 4096 Ta "MODP" Ta "x" 1021.It Li modp6144 Ta grp17 Ta 6144 Ta "MODP" Ta "" 1022.It Li modp8192 Ta grp18 Ta 8192 Ta "MODP" Ta "" 1023.It Li ecp256 Ta grp19 Ta 256 Ta "ECP" Ta "x" 1024.It Li ecp384 Ta grp20 Ta 384 Ta "ECP" Ta "x" 1025.It Li ecp521 Ta grp21 Ta 521 Ta "ECP" Ta "x" 1026.It Li ecp192 Ta grp25 Ta 192 Ta "ECP" Ta "" 1027.It Li ecp224 Ta grp26 Ta 224 Ta "ECP" Ta "" 1028.It Li brainpool224 Ta grp27 Ta 224 Ta "ECP" Ta "" 1029.It Li brainpool256 Ta grp28 Ta 256 Ta "ECP" Ta "" 1030.It Li brainpool384 Ta grp29 Ta 384 Ta "ECP" Ta "" 1031.It Li brainpool512 Ta grp30 Ta 512 Ta "ECP" Ta "" 1032.It Li curve25519 Ta grp31 Ta 256 Ta "Curve25519" Ta "x" 1033.It Li sntrup761x25519 Ta "" Ta 1190 B Ta "Hybrid PQKE" Ta "" 1034.El 1035.Pp 1036The currently supported group types are either 1037MODP (exponentiation groups modulo a prime), 1038ECP (elliptic curve groups modulo a prime), 1039or Curve25519. 1040MODP groups of less than 2048 bits are considered 1041as weak or insecure (see RFC 8247 section 2.4) and only provided for 1042backwards compatibility. 1043.Sh FILES 1044.Bl -tag -width /etc/examples/iked.conf -compact 1045.It Pa /etc/iked.conf 1046.It Pa /etc/examples/iked.conf 1047.El 1048.Sh EXAMPLES 1049The first example is intended for a server with clients connecting to 1050.Xr iked 8 1051as an IPsec gateway, or IKEv2 responder, using mutual public key 1052authentication and additional challenge-based EAP-MSCHAPv2 password 1053authentication: 1054.Bd -literal -offset indent 1055user "test" "password123" 1056 1057ikev2 "win7" esp \e 1058 from dynamic to 172.16.2.0/24 \e 1059 peer 10.0.0.0/8 local 192.168.56.0/24 \e 1060 eap "mschap-v2" \e 1061 config address 172.16.2.1 \e 1062 tag "$name-$id" 1063.Ed 1064.Pp 1065The next example allows peers to authenticate using a pre-shared key 1066.Sq foobar : 1067.Bd -literal -offset indent 1068ikev2 "big test" \e 1069 esp proto tcp \e 1070 from 10.0.0.0/8 port 23 to 20.0.0.0/8 port 40 \e 1071 from 192.168.1.1 to 192.168.2.2 \e 1072 peer any local any \e 1073 ikesa \e 1074 enc aes-128-gcm \e 1075 group ecp256 group curve25519 \e 1076 ikesa \e 1077 enc aes-128 auth hmac-sha2-256 \e 1078 group ecp256 group curve25519 \e 1079 childsa enc aes-128-gcm \e 1080 childsa enc aes-128 auth hmac-sha2-256 \e 1081 srcid host.example.com \e 1082 dstid 192.168.0.254 \e 1083 psk "foobar" 1084.Ed 1085.Pp 1086The following example illustrates the last matching policy 1087evaluation for incoming connections on an IKEv2 gateway. 1088The peer 192.168.1.34 will always match the first policy because of the 1089.Ar quick 1090keyword; 1091connections from the peers 192.168.1.3 and 192.168.1.2 will be matched 1092by one of the last two policies; 1093any other connections from 192.168.1.0/24 will be matched by the 1094.Sq subnet 1095policy; 1096and any other connection will be matched by the 1097.Sq catch all 1098policy. 1099.Bd -literal -offset indent 1100ikev2 quick esp from 10.10.10.0/24 to 10.20.20.0/24 \e 1101 peer 192.168.1.34 1102ikev2 "catch all" esp from 10.0.1.0/24 to 10.0.2.0/24 \e 1103 peer any 1104ikev2 "subnet" esp from 10.0.3.0/24 to 10.0.4.0/24 \e 1105 peer 192.168.1.0/24 1106ikev2 esp from 10.0.5.0/30 to 10.0.5.4/30 peer 192.168.1.2 1107ikev2 esp from 10.0.5.8/30 to 10.0.5.12/30 peer 192.168.1.3 1108.Ed 1109.Pp 1110This example encrypts a 1111.Xr gre 4 1112tunnel from local machine A (2001:db8::aa:1) to peer D (2001:db8::dd:4) based on 1113FQDN-based public key authentication; 1114.Ar transport 1115mode avoids double encapsulation: 1116.Bd -literal -offset indent 1117ikev2 transport \e 1118 proto gre \e 1119 from 2001:db8::aa:1 to 2001:db8::dd:4 \e 1120 peer D.example.com 1121.Ed 1122.Sh SEE ALSO 1123.Xr enc 4 , 1124.Xr ipsec 4 , 1125.Xr ipsec.conf 5 , 1126.Xr pf.conf 5 , 1127.Xr ikectl 8 , 1128.Xr iked 8 1129.Sh HISTORY 1130The 1131.Nm 1132file format first appeared in 1133.Ox 4.8 . 1134.Sh AUTHORS 1135The 1136.Xr iked 8 1137program was written by 1138.An Reyk Floeter Aq Mt reyk@openbsd.org . 1139