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