1.\" $OpenBSD: iked.conf.5,v 1.93 2022/04/13 11:06:15 tobhe 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 2022 $ 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 user Ar name password 220.Xr iked 8 221supports user-based authentication by tunneling the Extensible 222Authentication Protocol (EAP) over IKEv2. 223In its most basic form, the users will be authenticated against a 224local, integrated password database that is configured with the 225.Ic user 226lines in 227.Nm 228and the 229.Ar name 230and 231.Ar password 232arguments. 233The password has to be specified in plain text which is 234required to support different challenge-based EAP methods like 235EAP-MD5 or EAP-MSCHAPv2. 236.El 237.Sh AUTOMATIC KEYING POLICIES 238This section is used to configure policies that will be used by 239.Xr iked 8 240to set up flows and SAs automatically. 241Some examples of setting up automatic keying: 242.Bd -literal -offset 3n 243# Set up a VPN: 244# First between the gateway machines 192.168.3.1 and 192.168.3.2 245# Second between the networks 10.1.1.0/24 and 10.1.2.0/24 246ikev2 esp from 192.168.3.1 to 192.168.3.2 247ikev2 esp from 10.1.1.0/24 to 10.1.2.0/24 peer 192.168.3.2 248.Ed 249.Pp 250For incoming connections from remote peers, the policies are evaluated 251in sequential order, from first to last. 252The last matching policy decides what action is taken; if no policy matches 253the connection, the default action is to ignore the connection attempt or 254to use the 255.Ar default 256policy, if set. 257See the 258.Sx EXAMPLES 259section for a detailed example of the policy evaluation. 260.Pp 261The first time an IKEv2 connection matches a policy, an IKE SA is 262created; for subsequent packets the connection is identified by the 263IKEv2 parameters that are stored in the SA without evaluating any 264policies. 265After the connection is closed or times out, the IKE SA is 266automatically removed. 267.Pp 268The commands are as follows: 269.Bl -tag -width xxxx -compact 270.It Xo 271.Ic ikev2 272.Op Ar name 273.Xc 274The mandatory 275.Ic ikev2 276keyword will identify an IKEv2 automatic keying policy. 277.Ar name 278is an optional arbitrary string identifying the policy. 279The name should only occur once in 280.Nm 281or any included files. 282If omitted, 283a name will be generated automatically for the policy. 284.Pp 285.It Op Ar eval 286The 287.Ar eval 288option modifies the policy evaluation for this policy. 289It can be one of 290.Ar quick , 291.Ar skip 292or 293.Ar default . 294If a new incoming connection matches a policy with the 295.Ar quick 296option set, that policy is considered the last matching policy, 297and evaluation of subsequent policies is skipped. 298The 299.Ar skip 300option will disable evaluation of this policy for incoming connections. 301The 302.Ar default 303option sets the default policy and should only be specified once. 304.Pp 305.It Op Ar mode 306.Ar mode 307specifies the IKEv2 mode to use: 308one of 309.Ar passive 310or 311.Ar active . 312When 313.Ar passive 314is specified, 315.Xr iked 8 316will not immediately start negotiation of this tunnel, but wait for an incoming 317request from the remote peer. 318When 319.Ar active 320is specified, negotiation will be started at once. 321If omitted, 322.Ar passive 323mode will be used. 324.Pp 325.It Op Ar ipcomp 326The keyword 327.Ar ipcomp 328specifies that 329.Xr ipcomp 4 , 330the IP Payload Compression protocol, is negotiated in addition to encapsulation. 331The optional compression is applied before packets are encapsulated. 332IPcomp must be enabled in the kernel: 333.Pp 334.Dl # sysctl net.inet.ipcomp.enable=1 335.Pp 336.It Op Ar tmode 337.Ar tmode 338describes the encapsulation mode to be used. 339Possible modes are 340.Ar tunnel 341and 342.Ar transport ; 343the default is 344.Ar tunnel . 345.Pp 346.It Op Ar encap 347.Ar encap 348specifies the encapsulation protocol to be used. 349Possible protocols are 350.Ar esp 351and 352.Ar ah ; 353the default is 354.Ar esp . 355.Pp 356.It Op Ar af 357This policy only applies to endpoints of the specified address family 358which can be either 359.Ar inet 360or 361.Ar inet6 . 362This only matters for IKEv2 endpoints and does not 363restrict the traffic selectors to negotiate flows with different 364address families, e.g. IPv6 flows negotiated by IPv4 endpoints. 365.Pp 366.It Xo 367.Ic proto Ar protocol 368.Xc 369.It Xo 370.Ic proto 371.Ic { Ar protocol ... Ic } 372.Xc 373The optional 374.Ic proto 375parameter restricts the flow to a specific IP protocol. 376Common protocols are 377.Xr icmp 4 , 378.Xr tcp 4 , 379and 380.Xr udp 4 . 381For a list of all the protocol name to number mappings used by 382.Xr iked 8 , 383see the file 384.Pa /etc/protocols . 385.Pp 386Multiple 387.Ar protocol 388entries can be specified, separated by commas or whitespace, 389if enclosed in curly brackets: 390.Bd -literal -offset indent 391proto { tcp, udp } 392.Ed 393.Pp 394.It Ic rdomain Ar number 395Specify a different routing domain for unencrypted traffic. 396The resulting IPsec SAs will match outgoing packets in the specified 397.Ic rdomain Ar number 398and move the encrypted packets to the rdomain the 399.Xr iked 8 400instance is running in. 401Vice versa, incoming 402.Xr ipsec 4 403traffic is moved to 404.Ic rdomain Ar number 405after decryption. 406.Pp 407.It Xo 408.Ic from Ar src 409.Op Ic port Ar sport 410.Op Pq Ar srcnat 411.Ic to Ar dst 412.Op Ic port Ar dport 413.Xc 414Specify one or more traffic selectors for this policy which will be 415used to negotiate the IPsec flows between the IKEv2 peers. 416During the negotiation, the peers may decide to narrow a flow to a 417subset of the configured traffic selector networks to match the 418policies on each side. 419.Pp 420Each traffic selector will apply for packets with source address 421.Ar src 422and destination address 423.Ar dst . 424If the 425.Ar src 426argument specifies a fictional source ID, 427the 428.Ar srcnat 429parameter can be used to specify the actual source address. 430This can be used in outgoing NAT/BINAT scenarios as described below. 431The keyword 432.Ar any 433will match any address (i.e. 0.0.0.0/0 and ::/0). 434If the 435.Ic config address 436option is specified, the 437.Ar dynamic 438keyword can be used to create flows from or to the dynamically 439assigned address. 440.Pp 441The optional 442.Ic port 443modifiers restrict the traffic selectors to the specified ports. 444They are only valid in conjunction with the 445.Xr tcp 4 446and 447.Xr udp 4 448protocols. 449Ports can be specified by number or by name. 450For a list of all port name to number mappings used by 451.Xr ipsecctl 8 , 452see the file 453.Pa /etc/services . 454.Pp 455.It Ic local Ar localip Ic peer Ar remote 456The 457.Ic local 458parameter specifies the address or FQDN of the local endpoint. 459Unless the gateway is multi-homed or uses address aliases, 460this option is generally not needed. 461.Pp 462The 463.Ic peer 464parameter specifies the address or FQDN of the remote endpoint. 465For host-to-host connections where 466.Ar dst 467is identical to 468.Ar remote , 469this option is generally not needed as it will be set to 470.Ar dst 471automatically. 472If it is not specified or if the keyword 473.Ar any 474is given, the default peer is used. 475.Pp 476.It Xo 477.Ic ikesa 478.Ic auth Ar algorithm 479.Ic enc Ar algorithm 480.Ic prf Ar algorithm 481.Ic group Ar group 482.Xc 483These parameters define the mode and cryptographic transforms to be 484used for the IKE SA negotiation, also known as phase 1. 485The IKE SA will be used to authenticate the machines and to set up an 486encrypted channel for the IKEv2 protocol. 487.Pp 488Possible values for 489.Ic auth , 490.Ic enc , 491.Ic prf , 492.Ic group , 493and the default proposals are described below in 494.Sx CRYPTO TRANSFORMS . 495If omitted, 496.Xr iked 8 497will use the default proposals for the IKEv2 protocol. 498.Pp 499The keyword 500.Ic ikesa 501can be used multiple times as a delimiter between IKE SA proposals. 502The order of the proposals depend on the order in the configuration. 503The keywords 504.Ic auth , 505.Ic enc , 506.Ic prf 507and 508.Ic group 509can be used multiple times within a single proposal to configure 510multiple crypto transforms. 511.Pp 512.It Xo 513.Ic childsa 514.Ic auth Ar algorithm 515.Ic enc Ar algorithm 516.Ic group Ar group 517.Ic esn 518.Xc 519These parameters define the cryptographic transforms to be used for 520the Child SA negotiation, also known as phase 2. 521Each Child SA will be used to negotiate the actual IPsec SAs. 522The initial Child SA is always negotiated with the initial IKEv2 key 523exchange; additional Child SAs may be negotiated with additional 524Child SA key exchanges for an established IKE SA. 525.Pp 526Possible values for 527.Ic auth , 528.Ic enc , 529.Ic group , 530.Ic esn , 531and the default proposals are described below in 532.Sx CRYPTO TRANSFORMS . 533If omitted, 534.Xr iked 8 535will use the default proposals for the ESP or AH protocol. 536.Pp 537The 538.Ic group 539option will only be used to enable Perfect Forward Secrecy (PFS) 540for additional Child SAs exchanges that are not part of the initial 541key exchange. 542.Pp 543The keyword 544.Ic childsa 545can be used multiple times as a delimiter between Child SA proposals. 546The order of the proposals depend on the order in the configuration. 547The keywords 548.Ic auth , 549.Ic enc 550and 551.Ic group 552can be used multiple times within a single proposal to configure 553multiple crypto transforms. 554.Pp 555.It Ic srcid Ar string Ic dstid Ar string 556.Ic srcid 557defines an ID of type 558.Dq FQDN , 559.Dq ASN1_DN , 560.Dq IPV4 , 561.Dq IPV6 , 562or 563.Dq UFQDN 564that will be used by 565.Xr iked 8 566as the identity of the local peer. 567If the argument is an email address (reyk@example.com), 568.Xr iked 8 569will use UFQDN as the ID type. 570The ASN1_DN type will be used if the string starts with a slash 571.Sq / 572(/C=DE/../CN=10.0.0.1/emailAddress=reyk@example.com). 573If the argument is an IPv4 address or a compressed IPv6 address, 574the ID types IPV4 or IPV6 will be used. 575Anything else is considered to be an FQDN. 576.Pp 577If 578.Ic srcid 579is omitted, 580the default is to use the hostname of the local machine, 581see 582.Xr hostname 1 583to set or print the hostname. 584.Pp 585.Ic dstid 586is similar to 587.Ic srcid , 588but instead specifies the ID to be used 589by the remote peer. 590.Pp 591.It Ic ikelifetime Ar time 592The optional 593.Ic ikelifetime 594parameter defines the IKE SA expiration timeout by the 595.Ar time 596SA was created. 597A zero value disables active IKE SA rekeying. 598This is the default. 599.Pp 600The accepted format of the 601.Ar time 602specification is described below. 603.Pp 604.It Ic lifetime Ar time Op Ic bytes Ar bytes 605The optional 606.Ic lifetime 607parameter defines the Child SA expiration timeout by the 608.Ar time 609SA was in use and by the number of 610.Ar bytes 611that were processed using the SA. 612Default values are 3 hours and 4 gigabytes which means that SA will be 613rekeyed before reaching the time limit or 4 gigabytes of data 614will pass through. 615Zero values disable rekeying. 616.Pp 617Several unit specifiers are recognized (ignoring case): 618.Ql m 619and 620.Ql h 621for minutes and hours, and 622.Ql K , 623.Ql M 624and 625.Ql G 626for kilo-, mega- and gigabytes accordingly. 627.Pp 628Rekeying must happen at least several times a day as 629IPsec security heavily depends on frequent key renewals. 630.Pp 631.It Op Ar ikeauth 632Specify a method to be used to authenticate the remote peer. 633.Xr iked 8 634will automatically determine a method based on public keys or certificates 635configured for the peer. 636.Ar ikeauth 637can be used to override this behaviour. 638Non-psk modes will require setting up certificates and RSA or ECDSA public 639keys; see 640.Xr iked 8 641for more information. 642.Pp 643.Bl -tag -width $domain -compact -offset indent 644.It Ic eap Ar type 645Use EAP to authenticate the initiator. 646The only supported EAP 647.Ar type 648is currently 649.Ar MSCHAP-V2 . 650The responder will use RSA public key authentication. 651.It Ic ecdsa256 652Use ECDSA with a 256-bit elliptic curve key and SHA2-256 for authentication. 653.It Ic ecdsa384 654Use ECDSA with a 384-bit elliptic curve key and SHA2-384 for authentication. 655.It Ic ecdsa521 656Use ECDSA with a 521-bit elliptic curve key and SHA2-512 for authentication. 657.It Ic psk Ar string 658Use a pre-shared key 659.Ar string 660or hex value (starting with 0x) for authentication. 661.It Ic rfc7427 662Only use RFC 7427 signatures for authentication. 663RFC 7427 signatures currently only support SHA2-256 as the hash. 664.It Ic rsa 665Use RSA public key authentication with SHA1 as the hash. 666.El 667.Pp 668The default is to allow any signature authentication. 669.Pp 670.It Cm config Ar option address 671.It Cm request Ar option address 672Request or serve one or more optional configuration payloads (CP). 673The configuration 674.Ar option 675can be one of the following with the expected address format: 676.Pp 677.Bl -tag -width Ds -compact -offset indent 678.It Ic address Ar address 679Assign a static address on the internal network. 680.It Ic address Ar address/prefix 681Assign a dynamic address on the internal network. 682The address will be assigned from an address pool with the size specified by 683.Ar prefix . 684.It Ic netmask Ar netmask 685The IPv4 netmask of the internal network. 686.It Ic name-server Ar address 687The DNS server address within the internal network. 688.It Ic netbios-server Ar address 689The NetBIOS name server (WINS) within the internal network. 690This option is provided for compatibility with legacy clients. 691.It Ic dhcp-server Ar address 692The address of an internal DHCP server for further configuration. 693.It Ic protected-subnet Ar address/prefix 694The address of an additional IPv4 or IPv6 subnet reachable over the 695gateway. 696This option is used to notify the peer of a subnet behind the gateway (that 697might require a second SA). 698Networks specified in this SA's "from" or "to" options do not need to be 699included. 700.It Ic access-server Ar address 701The address of an internal remote access server. 702.El 703.Pp 704.It Ic iface Ar interface 705Enable automatic network configuration as initiator. 706Received addresses, routes and nameservers will be installed on the specified 707.Ar interface . 708.Pp 709.It Ic tag Ar string 710Add a 711.Xr pf 4 712tag to all packets of IPsec SAs created for this connection. 713This will allow matching packets for this connection by defining 714rules in 715.Xr pf.conf 5 716using the 717.Cm tagged 718keyword. 719.Pp 720The following variables can be used in tags to include information 721from the remote peer on runtime: 722.Pp 723.Bl -tag -width $domain -compact -offset indent 724.It Ar $id 725The 726.Ic dstid 727that was proposed by the remote peer to identify itself. 728It will be expanded to 729.Ar id-value , 730e.g.\& 731.Ar FQDN/foo.example.com . 732To limit the size of the derived tag, 733.Xr iked 8 734will extract the common name 735.Sq CN= 736from ASN1_DN IDs, for example 737.Ar ASN1_ID//C=DE/../CN=10.1.1.1/.. 738will be expanded to 739.Ar 10.1.1.1 . 740.It Ar $eapid 741For a connection using EAP, the identity (username) used by the remote peer. 742.It Ar $domain 743Extract the domain from IDs of type FQDN, UFQDN or ASN1_DN. 744.It Ar $name 745The name of the IKEv2 policy that was configured in 746.Nm 747or automatically generated by 748.Xr iked 8 . 749.El 750.Pp 751For example, if the ID is 752.Ar FQDN/foo.example.com 753or 754.Ar UFQDN/user@example.com , 755.Dq ipsec-$domain 756expands to 757.Dq ipsec-example.com . 758The variable expansion for the 759.Ar tag 760directive occurs only at runtime (not when the file is parsed) 761and must be quoted, or it will be interpreted as a macro. 762.Pp 763.It Ic tap Ar interface 764Send the decapsulated IPsec traffic to the specified 765.Xr enc 4 766.Ar interface 767instead of 768.Ar enc0 769for filtering and monitoring. 770The traffic will be blocked if the specified 771.Ar interface 772does not exist. 773.El 774.Sh PACKET FILTERING 775IPsec traffic appears unencrypted on the 776.Xr enc 4 777interface 778and can be filtered accordingly using the 779.Ox 780packet filter, 781.Xr pf 4 . 782The grammar for the packet filter is described in 783.Xr pf.conf 5 . 784.Pp 785The following components are relevant to filtering IPsec traffic: 786.Bl -ohang -offset indent 787.It external interface 788Interface for IKE traffic and encapsulated IPsec traffic. 789.It proto udp port 500 790IKE traffic on the external interface. 791.It proto udp port 4500 792IKE NAT-Traversal traffic on the external interface. 793.It proto ah | esp 794Encapsulated IPsec traffic 795on the external interface. 796.It enc0 797Default interface for outgoing traffic before it's been encapsulated, 798and incoming traffic after it's been decapsulated. 799State on this interface should be interface bound; 800see 801.Xr enc 4 802for further information. 803.It proto ipencap 804[tunnel mode only] 805IP-in-IP traffic flowing between gateways 806on the enc0 interface. 807.It tagged ipsec-example.org 808Match traffic of IPsec SAs using the 809.Ic tag 810keyword. 811.El 812.Pp 813If the filtering rules specify to block everything by default, 814the following rule 815would ensure that IPsec traffic never hits the packet filtering engine, 816and is therefore passed: 817.Bd -literal -offset indent 818set skip on enc0 819.Ed 820.Pp 821In the following example, all traffic is blocked by default. 822IPsec-related traffic from gateways {192.168.3.1, 192.168.3.2} and 823networks {10.0.1.0/24, 10.0.2.0/24} is permitted. 824.Bd -literal -offset indent 825block on ix0 826block on enc0 827 828pass in on ix0 proto udp from 192.168.3.2 to 192.168.3.1 \e 829 port {500, 4500} 830pass out on ix0 proto udp from 192.168.3.1 to 192.168.3.2 \e 831 port {500, 4500} 832 833pass in on ix0 proto esp from 192.168.3.2 to 192.168.3.1 834pass out on ix0 proto esp from 192.168.3.1 to 192.168.3.2 835 836pass in on enc0 proto ipencap from 192.168.3.2 to 192.168.3.1 \e 837 keep state (if-bound) 838pass out on enc0 proto ipencap from 192.168.3.1 to 192.168.3.2 \e 839 keep state (if-bound) 840pass in on enc0 from 10.0.2.0/24 to 10.0.1.0/24 \e 841 keep state (if-bound) 842pass out on enc0 from 10.0.1.0/24 to 10.0.2.0/24 \e 843 keep state (if-bound) 844.Ed 845.Pp 846.Xr pf 4 847has the ability to filter IPsec-related packets 848based on an arbitrary 849.Em tag 850specified within a ruleset. 851The tag is used as an internal marker 852which can be used to identify the packets later on. 853This could be helpful, 854for example, 855in scenarios where users are connecting in from differing IP addresses, 856or to support queue-based bandwidth control, 857since the enc0 interface does not support it. 858.Pp 859The following 860.Xr pf.conf 5 861fragment uses queues for all IPsec traffic with special 862handling for developers and employees: 863.Bd -literal -offset indent 864queue std on ix0 bandwidth 100M 865queue deflt parent std bandwidth 10M default 866queue developers parent std bandwidth 75M 867queue employees parent std bandwidth 5M 868queue ipsec parent std bandwidth 10M 869 870pass out on ix0 proto esp set queue ipsec 871 872pass out on ix0 tagged ipsec-developers.example.com \e 873 set queue developers 874pass out on ix0 tagged ipsec-employees.example.com \e 875 set queue employees 876.Ed 877.Pp 878The following example assigns the tags in the 879.Nm 880configuration and also sets an alternative 881.Xr enc 4 882device: 883.Bd -literal -offset indent 884ikev2 esp from 10.1.1.0/24 to 10.1.2.0/24 peer 192.168.3.2 \e 885 tag "ipsec-$domain" tap "enc1" 886.Ed 887.Sh OUTGOING NETWORK ADDRESS TRANSLATION 888In some network topologies it is desirable to perform NAT on traffic leaving 889through the VPN tunnel. 890In order to achieve that, 891the 892.Ar src 893argument is used to negotiate the desired network ID with the peer 894and the 895.Ar srcnat 896parameter defines the true local subnet, 897so that a correct SA can be installed on the local side. 898.Pp 899For example, 900if the local subnet is 192.168.1.0/24 and all the traffic 901for a specific VPN peer should appear as coming from 10.10.10.1, 902the following configuration is used: 903.Bd -literal -offset indent 904ikev2 esp from 10.10.10.1 (192.168.1.0/24) to 192.168.2.0/24 \e 905 peer 10.10.20.1 906.Ed 907.Pp 908Naturally, 909a relevant NAT rule is required in 910.Xr pf.conf 5 . 911For the example above, 912this would be: 913.Bd -literal -offset indent 914match out on enc0 from 192.168.1.0/24 to 192.168.2.0/24 \e 915 nat-to 10.10.10.1 916.Ed 917.Pp 918From the peer's point of view, 919the local end of the VPN tunnel is declared to be 10.10.10.1 920and all the traffic arrives with that source address. 921.Sh CRYPTO TRANSFORMS 922The following authentication types are permitted with the 923.Ic auth 924keyword: 925.Bl -column "Authentication" "Key Length" "Truncated Length" "Default" -offset indent 926.It Em "Authentication" Ta Em "Key Length" Ta Em "Truncated Length" Ta Em "Default" 927.It Li hmac-md5 Ta "128 bits" Ta "96 bits" Ta "" 928.It Li hmac-sha1 Ta "160 bits" Ta "96 bits" Ta "x" 929.It Li hmac-sha2-256 Ta "256 bits" Ta "128 bits" Ta "x" 930.It Li hmac-sha2-384 Ta "384 bits" Ta "192 bits" Ta "x" 931.It Li hmac-sha2-512 Ta "512 bits" Ta "256 bits" Ta "x" 932.El 933.Pp 934The following pseudo-random function types are permitted with the 935.Ic prf 936keyword: 937.Bl -column "hmac-sha2-512" "Key Length" "Default" "[IKE only]" -offset indent 938.It Em "PRF" Ta Em "Key Length" Ta Em "Default" Ta "" 939.It Li hmac-md5 Ta "128 bits" Ta "" Ta "[IKE only]" 940.It Li hmac-sha1 Ta "160 bits" Ta "x" Ta "[IKE only]" 941.It Li hmac-sha2-256 Ta "256 bits" Ta "x" Ta "[IKE only]" 942.It Li hmac-sha2-384 Ta "384 bits" Ta "x" Ta "[IKE only]" 943.It Li hmac-sha2-512 Ta "512 bits" Ta "x" Ta "[IKE only]" 944.El 945.Pp 946The following cipher types are permitted with the 947.Ic enc 948keyword: 949.Bl -column "chacha20-poly1305" "Key Length" "Default" "[ESP only]" -offset indent 950.It Em "Cipher" Ta Em "Key Length" Ta Em "Default" Ta "" 951.It Li 3des Ta "168 bits" Ta "x" Ta "" 952.It Li aes-128 Ta "128 bits" Ta "x" Ta "" 953.It Li aes-192 Ta "192 bits" Ta "x" Ta "" 954.It Li aes-256 Ta "256 bits" Ta "x" Ta "" 955.It Li aes-128-ctr Ta "160 bits" Ta "" Ta "[ESP only]" 956.It Li aes-192-ctr Ta "224 bits" Ta "" Ta "[ESP only]" 957.It Li aes-256-ctr Ta "288 bits" Ta "" Ta "[ESP only]" 958.It Li aes-128-gcm Ta "160 bits" Ta "x" Ta "" 959.It Li aes-192-gcm Ta "224 bits" Ta "" Ta "[ESP only]" 960.It Li aes-256-gcm Ta "288 bits" Ta "x" Ta "" 961.It Li aes-128-gcm-12 Ta "160 bits" Ta "" Ta "[IKE only]" 962.It Li aes-256-gcm-12 Ta "288 bits" Ta "" Ta "[IKE only]" 963.It Li blowfish Ta "160 bits" Ta "" Ta "[ESP only]" 964.It Li cast Ta "128 bits" Ta "" Ta "[ESP only]" 965.It Li chacha20-poly1305 Ta "288 bits" Ta "" Ta "[ESP only]" 966.El 967.Pp 968The following cipher types provide only authentication, 969not encryption: 970.Bl -column "chacha20-poly1305" "Key Length" "Default" "[ESP only]" -offset indent 971.It Li aes-128-gmac Ta "160 bits" Ta "" Ta "[ESP only]" 972.It Li aes-192-gmac Ta "224 bits" Ta "" Ta "[ESP only]" 973.It Li aes-256-gmac Ta "288 bits" Ta "" Ta "[ESP only]" 974.It Li null Ta "" Ta "" Ta "[ESP only]" 975.El 976.Pp 977The Extended Sequence Numbers option can be enabled or disabled with the 978.Ic esn 979or 980.Ic noesn 981keywords: 982.Bl -column "noesn" "Default" "[ESP only]" -offset indent 983.It Em ESN Ta Em "Default" Ta Em "" 984.It Li esn Ta "x" Ta "[ESP only]" 985.It Li noesn Ta "x" Ta "[ESP only]" 986.El 987.Pp 988Transforms followed by 989.Bq IKE only 990can only be used with the 991.Ic ikesa 992keyword, transforms with 993.Bq ESP only 994can only be used with the 995.Ic childsa 996keyword. 997.Pp 998Using AES-GMAC or NULL with ESP will only provide authentication. 999This is useful in setups where AH cannot be used, e.g. when NAT is involved. 1000.Pp 1001The following group types are permitted with the 1002.Ic group 1003keyword: 1004.Bl -column "sntrup761x25519" "Group" "1190 B" "Hybrid PQKE" "Default" -offset indent 1005.It Em Name Ta Em Group Ta Em Size Ta Em Type Ta Em Default 1006.It Li modp768 Ta grp1 Ta 768 Ta "MODP" Ta "" Ta "[insecure]" 1007.It Li modp1024 Ta grp2 Ta 1024 Ta "MODP" Ta "x" Ta "[weak]" 1008.It Li modp1536 Ta grp5 Ta 1536 Ta "MODP" Ta "x" Ta "[weak]" 1009.It Li modp2048 Ta grp14 Ta 2048 Ta "MODP" Ta "x" 1010.It Li modp3072 Ta grp15 Ta 3072 Ta "MODP" Ta "x" 1011.It Li modp4096 Ta grp16 Ta 4096 Ta "MODP" Ta "x" 1012.It Li modp6144 Ta grp17 Ta 6144 Ta "MODP" Ta "" 1013.It Li modp8192 Ta grp18 Ta 8192 Ta "MODP" Ta "" 1014.It Li ecp256 Ta grp19 Ta 256 Ta "ECP" Ta "x" 1015.It Li ecp384 Ta grp20 Ta 384 Ta "ECP" Ta "x" 1016.It Li ecp521 Ta grp21 Ta 521 Ta "ECP" Ta "x" 1017.It Li ecp192 Ta grp25 Ta 192 Ta "ECP" Ta "" 1018.It Li ecp224 Ta grp26 Ta 224 Ta "ECP" Ta "" 1019.It Li brainpool224 Ta grp27 Ta 224 Ta "ECP" Ta "" 1020.It Li brainpool256 Ta grp28 Ta 256 Ta "ECP" Ta "" 1021.It Li brainpool384 Ta grp29 Ta 384 Ta "ECP" Ta "" 1022.It Li brainpool512 Ta grp30 Ta 512 Ta "ECP" Ta "" 1023.It Li curve25519 Ta grp31 Ta 256 Ta "Curve25519" Ta "x" 1024.It Li sntrup761x25519 Ta "" Ta 1190 B Ta "Hybrid PQKE" Ta "" 1025.El 1026.Pp 1027The currently supported group types are either 1028MODP (exponentiation groups modulo a prime), 1029ECP (elliptic curve groups modulo a prime), 1030or Curve25519. 1031MODP groups of less than 2048 bits are considered 1032as weak or insecure (see RFC 8247 section 2.4) and only provided for 1033backwards compatibility. 1034.Sh FILES 1035.Bl -tag -width /etc/examples/iked.conf -compact 1036.It Pa /etc/iked.conf 1037.It Pa /etc/examples/iked.conf 1038.El 1039.Sh EXAMPLES 1040The first example is intended for a server with clients connecting to 1041.Xr iked 8 1042as an IPsec gateway, or IKEv2 responder, using mutual public key 1043authentication and additional challenge-based EAP-MSCHAPv2 password 1044authentication: 1045.Bd -literal -offset indent 1046user "test" "password123" 1047 1048ikev2 "win7" esp \e 1049 from dynamic to 172.16.2.0/24 \e 1050 peer 10.0.0.0/8 local 192.168.56.0/24 \e 1051 eap "mschap-v2" \e 1052 config address 172.16.2.1 \e 1053 tag "$name-$id" 1054.Ed 1055.Pp 1056The next example allows peers to authenticate using a pre-shared key 1057.Sq foobar : 1058.Bd -literal -offset indent 1059ikev2 "big test" \e 1060 esp proto tcp \e 1061 from 10.0.0.0/8 port 23 to 20.0.0.0/8 port 40 \e 1062 from 192.168.1.1 to 192.168.2.2 \e 1063 peer any local any \e 1064 ikesa \e 1065 enc aes-128-gcm \e 1066 group ecp256 group curve25519 \e 1067 ikesa \e 1068 enc aes-128 auth hmac-sha2-256 \e 1069 group ecp256 group curve25519 \e 1070 childsa enc aes-128-gcm \e 1071 childsa enc aes-128 auth hmac-sha2-256 \e 1072 srcid host.example.com \e 1073 dstid 192.168.0.254 \e 1074 psk "foobar" 1075.Ed 1076.Pp 1077The following example illustrates the last matching policy 1078evaluation for incoming connections on an IKEv2 gateway. 1079The peer 192.168.1.34 will always match the first policy because of the 1080.Ar quick 1081keyword; 1082connections from the peers 192.168.1.3 and 192.168.1.2 will be matched 1083by one of the last two policies; 1084any other connections from 192.168.1.0/24 will be matched by the 1085.Sq subnet 1086policy; 1087and any other connection will be matched by the 1088.Sq catch all 1089policy. 1090.Bd -literal -offset indent 1091ikev2 quick esp from 10.10.10.0/24 to 10.20.20.0/24 \e 1092 peer 192.168.1.34 1093ikev2 "catch all" esp from 10.0.1.0/24 to 10.0.2.0/24 \e 1094 peer any 1095ikev2 "subnet" esp from 10.0.3.0/24 to 10.0.4.0/24 \e 1096 peer 192.168.1.0/24 1097ikev2 esp from 10.0.5.0/30 to 10.0.5.4/30 peer 192.168.1.2 1098ikev2 esp from 10.0.5.8/30 to 10.0.5.12/30 peer 192.168.1.3 1099.Ed 1100.Pp 1101This example encrypts a 1102.Xr gre 4 1103tunnel from local machine A (2001:db8::aa:1) to peer D (2001:db8::dd:4) based on 1104FQDN-based public key authentication; 1105.Ar transport 1106mode avoids double encapsulation: 1107.Bd -literal -offset indent 1108ikev2 transport \e 1109 proto gre \e 1110 from 2001:db8::aa:1 to 2001:db8::dd:4 \e 1111 peer D.example.com 1112.Ed 1113.Sh SEE ALSO 1114.Xr enc 4 , 1115.Xr ipsec 4 , 1116.Xr ipsec.conf 5 , 1117.Xr pf.conf 5 , 1118.Xr ikectl 8 , 1119.Xr iked 8 1120.Sh HISTORY 1121The 1122.Nm 1123file format first appeared in 1124.Ox 4.8 . 1125.Sh AUTHORS 1126The 1127.Xr iked 8 1128program was written by 1129.An Reyk Floeter Aq Mt reyk@openbsd.org . 1130