1.\" $OpenBSD: ikectl.8,v 1.28 2022/03/31 17:27:30 naddy Exp $ 2.\" 3.\" Copyright (c) 2007-2013 Reyk Floeter <reyk@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: March 31 2022 $ 18.Dt IKECTL 8 19.Os 20.Sh NAME 21.Nm ikectl 22.Nd control the IKEv2 daemon 23.Sh SYNOPSIS 24.Nm 25.Op Fl q 26.Op Fl s Ar socket 27.Ar command 28.Op Ar arg ... 29.Sh DESCRIPTION 30The 31.Nm 32program controls the 33.Xr iked 8 34daemon and provides commands to maintain a simple X.509 certificate 35authority (CA) for IKEv2 peers. 36.Pp 37The options are as follows: 38.Bl -tag -width Ds 39.It Fl q 40Don't ask for confirmation of any default options. 41.It Fl s Ar socket 42Use 43.Ar socket 44instead of the default 45.Pa /var/run/iked.sock 46to communicate with 47.Xr iked 8 . 48.El 49.Sh IKED CONTROL COMMANDS 50The following commands are available to control 51.Xr iked 8 : 52.Bl -tag -width Ds 53.It Cm active 54Set 55.Xr iked 8 56to active mode. 57.It Cm passive 58Set 59.Xr iked 8 60to passive mode. 61In passive mode no packets are sent to peers and no connections 62are initiated by 63.Xr iked 8 . 64.It Cm couple 65Load the negotiated security associations (SAs) and flows into the kernel. 66.It Cm decouple 67Unload the negotiated SAs and flows from the kernel. 68This mode is only useful for testing and debugging. 69.It Cm load Ar filename 70Reload the configuration from the specified file. 71.It Cm log brief 72Disable verbose logging. 73.It Cm log verbose 74Enable verbose logging. 75.It Cm monitor 76Monitor internal messages of the 77.Xr iked 8 78subsystems. 79.It Cm reload 80Reload the configuration from the default configuration file. 81.It Cm reset all 82Reset the running state. 83.It Cm reset ca 84Reset the X.509 CA and certificate state. 85.It Cm reset policy 86Flush the configured policies. 87.It Cm reset sa 88Flush the running SAs. 89.It Cm reset user 90Flush the local user database. 91.It Cm reset id Ar ikeid 92Delete all IKE SAs with matching ID. 93.It Cm show sa 94Show internal state of active IKE SAs, Child SAs and IPsec flows. 95.El 96.Sh PKI AND CERTIFICATE AUTHORITY COMMANDS 97In order to use public key based authentication with IKEv2, 98a public key infrastructure (PKI) has to be set up to create and sign 99the peer certificates. 100.Nm 101includes commands to simplify maintenance of the PKI 102and to set up a simple certificate authority (CA) for 103.Xr iked 8 104and its peers. 105.Pp 106The following commands are available to control the CA: 107.Bl -tag -width Ds 108.It Xo 109.Cm ca Ar name Cm create 110.Op Cm password Ar password 111.Xc 112Create a new certificate authority with the specified 113.Ar name . 114The command will prompt for a CA password unless it is specified with 115the optional 116.Ar password 117argument. 118The password will be saved in a protected file 119.Pa ikeca.passwd 120in the CA directory and used for subsequent commands. 121.It Cm ca Ar name Cm delete 122Delete the certificate authority with the specified 123.Ar name . 124.It Xo 125.Cm ca Ar name Cm export 126.Op Cm peer Ar peer 127.Op Cm password Ar password 128.Xc 129Export the certificate authority with the specified 130.Ar name 131into the current directory for transport to other systems. 132This command will create a compressed tarball called 133.Pa ca.tgz 134in the local directory and optionally 135.Pa ca.zip 136if the 137.Sq zip 138tool is installed. 139The optional 140.Ar peer 141argument can be used to specify the address or FQDN of the local gateway 142which will be written into a text file 143.Pa peer.txt 144and included in the archives. 145.It Xo 146.Cm ca Ar name 147.Cm install Op Ar path 148.Xc 149Install the certificate and Certificate Revocation List (CRL) for CA 150.Ar name 151as the currently active CA or into the specified 152.Ar path . 153.It Xo 154.Cm ca Ar name Cm certificate Ar host 155.Cm create 156.Op Ic server | client | ocsp 157.Xc 158Create a private key and certificate for 159.Ar host 160and sign then with the key of certificate authority with the specified 161.Ar name . 162.Pp 163The certificate will be valid for client and server authentication by 164default by setting both flags as the extended key usage in the certificate; 165this can be restricted using the optional 166.Ic server 167or 168.Ic client 169argument. 170If the 171.Ic ocsp 172argument is specified, the extended key usage will be set for OCSP signing. 173.It Xo 174.Cm ca Ar name Cm certificate Ar host 175.Cm delete 176.Xc 177Deletes the private key and certificates associated with 178.Ar host . 179.It Xo 180.Cm ca Ar name Cm certificate Ar host 181.Cm export 182.Op Cm peer Ar peer 183.Op Cm password Ar password 184.Xc 185Export key files for 186.Ar host 187of the certificate authority with the specified 188.Ar name 189into the current directory for transport to other systems. 190This command will create a compressed tarball 191.Pa host.tgz 192in the local directory and optionally 193.Pa host.zip 194if the 195.Sq zip 196tool is installed. 197The optional 198.Ar peer 199argument can be used to specify the address or FQDN of the local gateway 200which will be written into a text file 201.Pa peer.txt 202and included in the archives. 203.It Xo 204.Cm ca Ar name Cm certificate Ar host 205.Cm install Op Ar path 206.Xc 207Install the private and public key for 208.Ar host 209into the active configuration or specified 210.Ar path . 211.It Xo 212.Cm ca Ar name Cm certificate Ar host 213.Cm revoke 214.Xc 215Revoke the certificate specified by 216.Ar host 217and generate a new Certificate Revocation List (CRL). 218.It Xo 219.Cm show Cm ca Ar name Cm certificates 220.Op Ar host 221.Xc 222Display a listing of certificates associated with CA 223.Ar name 224or display certificate details if 225.Ar host 226is specified. 227.It Xo 228.Cm ca Ar name Cm key Ar host 229.Cm create 230.Xc 231Create a private key for 232.Ar host 233if one does not already exist. 234.It Xo 235.Cm ca Ar name Cm key Ar host 236.Cm install Op Ar path 237.Xc 238Install the private and public keys for 239.Ar host 240into the active configuration or specified 241.Ar path . 242.It Xo 243.Cm ca Ar name Cm key Ar host 244.Cm delete 245.Xc 246Delete the private key for 247.Ar host . 248.It Xo 249.Cm ca Ar name Cm key Ar host 250.Cm import 251.Ar file 252.Xc 253Source the private key for 254.Ar host 255from the named 256.Ar file . 257.El 258.Sh FILES 259.Bl -tag -width "/var/run/iked.sockXX" -compact 260.It Pa /etc/iked/ 261Active configuration. 262.It Pa /etc/ssl/ 263Directory to store the CA files. 264.It Pa /usr/share/iked/ 265If this optional directory exists, 266.Nm 267will include the contents with the 268.Cm ca export 269commands. 270.It Pa /var/run/iked.sock 271Default 272.Ux Ns -domain 273socket used for communication with 274.Xr iked 8 . 275.El 276.Sh EXAMPLES 277First create a new certificate authority: 278.Bd -literal -offset indent 279# ikectl ca vpn create 280.Ed 281.Pp 282Now create the certificates for the VPN peers. 283The specified hostname, either IP address or FQDN, will be saved in 284the signed certificate and has to match the IKEv2 identity, or 285.Ar srcid , 286of the peers: 287.Bd -literal -offset indent 288# ikectl ca vpn certificate 10.1.2.3 create 289# ikectl ca vpn certificate 10.2.3.4 create 290# ikectl ca vpn certificate 10.3.4.5 create 291.Ed 292.Pp 293It is possible that the host that was used to create the CA is also 294one of the VPN peers. 295In this case you can install the peer and CA certificates locally: 296.Bd -literal -offset indent 297# ikectl ca vpn install 298# ikectl ca vpn certificate 10.1.2.3 install 299.Ed 300.Pp 301Now export the individual host key, the certificate and the CA 302certificate to each other peer. 303First run the 304.Ic export 305command to create tarballs that include the required files: 306.Bd -literal -offset indent 307# ikectl ca vpn certificate 10.2.3.4 export 308# ikectl ca vpn certificate 10.3.4.5 export 309.Ed 310.Pp 311These commands will produce two tarballs 312.Em 10.2.3.4.tgz 313and 314.Em 10.3.4.5.tgz . 315Copy these tarballs over to the appropriate peers and extract them 316to the 317.Pa /etc/iked/ 318directory: 319.Bd -literal -offset indent 32010.2.3.4# tar -C /etc/iked -xzpf 10.2.3.4.tgz 32110.3.4.5# tar -C /etc/iked -xzpf 10.3.4.5.tgz 322.Ed 323.Pp 324.Nm 325will also create 326.Sq zip 327archives 10.2.3.4.zip and 10.3.4.5.zip 328in addition to the tarballs if the zip tool is found in 329.Pa /usr/local/bin/zip . 330These archives can be exported to peers running Windows and will 331include the certificates in a format that is supported by the OS. 332The zip tool can be installed from the 333.Ox 334packages or ports collection before running the 335.Ic export 336commands, see 337.Xr packages 7 338for more information. 339For example: 340.Bd -literal -offset indent 341# pkg_add zip 342.Ed 343.Sh SEE ALSO 344.Xr packages 7 , 345.Xr iked 8 , 346.Xr ssl 8 347.Sh HISTORY 348The 349.Nm 350program first appeared in 351.Ox 4.8 . 352.Sh AUTHORS 353The 354.Nm 355program was written by 356.An Reyk Floeter Aq Mt reyk@openbsd.org 357and 358.An Jonathan Gray Aq Mt jsg@openbsd.org . 359.Sh CAVEATS 360For ease of use, the 361.Ic ca 362commands maintain all peers' private keys on the CA machine. 363In contrast to a 364.Sq real 365CA, it does not support signing of public keys that have been imported 366from peers that do not want to expose their private keys to the CA. 367