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