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