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