1.\" $OpenBSD: ikectl.8,v 1.25 2015/11/02 10:27:44 jsg 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: November 2 2015 $ 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.El 92.Sh PKI AND CERTIFICATE AUTHORITY COMMANDS 93In order to use public key based authentication with IKEv2, 94a public key infrastructure (PKI) has to be set up to create and sign 95the peer certificates. 96.Nm 97includes commands to simplify maintenance of the PKI 98and to set up a simple certificate authority (CA) for 99.Xr iked 8 100and its peers. 101.Pp 102The following commands are available to control the CA: 103.Bl -tag -width Ds 104.It Xo 105.Cm ca Ar name Cm create 106.Op Cm password Ar password 107.Xc 108Create a new certificate authority with the specified 109.Ar name . 110The command will prompt for a CA password unless it is specified with 111the optional 112.Ar password 113argument. 114The password will be saved in a protected file 115.Pa ikeca.passwd 116in the CA directory and used for subsequent commands. 117.It Cm ca Ar name Cm delete 118Delete the certificate authority with the specified 119.Ar name . 120.It Xo 121.Cm ca Ar name Cm export 122.Op Cm peer Ar peer 123.Op Cm password Ar password 124.Xc 125Export the certificate authority with the specified 126.Ar name 127into the current directory for transport to other systems. 128This command will create a compressed tarball called 129.Pa ca.tgz 130in the local directory and optionally 131.Pa ca.zip 132if the 133.Sq zip 134tool is installed. 135The optional 136.Ar peer 137argument can be used to specify the address or FQDN of the local gateway 138which will be written into a text file 139.Pa peer.txt 140and included in the archives. 141.It Xo 142.Cm ca Ar name 143.Cm install Op Ar path 144.Xc 145Install the certificate and Certificate Revocation List (CRL) for CA 146.Ar name 147as the currently active CA or into the specified 148.Ar path . 149.It Xo 150.Cm ca Ar name Cm certificate Ar host 151.Cm create 152.Op Ic server | client | ocsp 153.Xc 154Create a private key and certificate for 155.Ar host 156and sign then with the key of certificate authority with the specified 157.Ar name . 158.Pp 159The certificate will be valid for client and server authentication by 160default by setting both flags as the extended key usage in the certificate; 161this can be restricted using the optional 162.Ic server 163or 164.Ic client 165argument. 166If the 167.Ic ocsp 168argument is specified the extended key usage will be set for OCSP signing. 169.It Xo 170.Cm ca Ar name Cm certificate Ar host 171.Cm delete 172.Xc 173Deletes the private key and certificates associated with 174.Ar host . 175.It Xo 176.Cm ca Ar name Cm certificate Ar host 177.Cm export 178.Op Cm peer Ar peer 179.Op Cm password Ar password 180.Xc 181Export key files for 182.Ar host 183of the certificate authority with the specified 184.Ar name 185into the current directory for transport to other systems. 186This command will create a compressed tarball 187.Pa host.tgz 188in the local directory and optionally 189.Pa host.zip 190if the 191.Sq zip 192tool is installed. 193The optional 194.Ar peer 195argument can be used to specify the address or FQDN of the local gateway 196which will be written into a text file 197.Pa peer.txt 198and included in the archives. 199.It Xo 200.Cm ca Ar name Cm certificate Ar host 201.Cm install Op Ar path 202.Xc 203Install the private and public key for 204.Ar host 205into the active configuration or specified 206.Ar path . 207.It Xo 208.Cm ca Ar name Cm certificate Ar host 209.Cm revoke 210.Xc 211Revoke the certificate specified by 212.Ar host 213and generate a new Certificate Revocation List (CRL). 214.It Xo 215.Cm show Cm ca Ar name Cm certificates 216.Op Ar host 217.Xc 218Display a listing of certificates associated with CA 219.Ar name 220or display certificate details if 221.Ar host 222is specified. 223.It Xo 224.Cm ca Ar name Cm key Ar host 225.Cm create 226.Xc 227Create a private key for 228.Ar host 229if one does not already exist. 230.It Xo 231.Cm ca Ar name Cm key Ar host 232.Cm install Op Ar path 233.Xc 234Install the private and public keys for 235.Ar host 236into the active configuration or specified 237.Ar path . 238.It Xo 239.Cm ca Ar name Cm key Ar host 240.Cm delete 241.Xc 242Delete the private key for 243.Ar host . 244.It Xo 245.Cm ca Ar name Cm key Ar host 246.Cm import 247.Ar file 248.Xc 249Source the private key for 250.Ar host 251from the named 252.Ar file . 253.El 254.Sh FILES 255.Bl -tag -width "/var/run/iked.sockXX" -compact 256.It Pa /etc/iked/ 257Active configuration. 258.It Pa /etc/ssl/ 259Directory to store the CA files. 260.It Pa /usr/share/iked/ 261If this optional directory exists, 262.Nm 263will include the contents with the 264.Cm ca export 265commands. 266.It Pa /var/run/iked.sock 267Default 268.Ux Ns -domain 269socket used for communication with 270.Xr iked 8 . 271.El 272.Sh EXAMPLES 273First create a new certificate authority: 274.Bd -literal -offset indent 275# ikectl ca vpn create 276.Ed 277.Pp 278Now create the certificates for the VPN peers. 279The specified hostname, either IP address or FQDN, will be saved in 280the signed certificate and has to match the IKEv2 identity, or 281.Ar srcid , 282of the peers: 283.Bd -literal -offset indent 284# ikectl ca vpn certificate 10.1.2.3 create 285# ikectl ca vpn certificate 10.2.3.4 create 286# ikectl ca vpn certificate 10.3.4.5 create 287.Ed 288.Pp 289It is possible that the host that was used to create the CA is also 290one of the VPN peers. 291In this case you can install the peer and CA certificates locally: 292.Bd -literal -offset indent 293# ikectl ca vpn install 294# ikectl ca vpn certificate 10.1.2.3 install 295.Ed 296.Pp 297Now export the individual host key, the certificate and the CA 298certificate to each other peer. 299First run the 300.Ic export 301command to create tarballs that include the required files: 302.Bd -literal -offset indent 303# ikectl ca vpn certificate 10.2.3.4 export 304# ikectl ca vpn certificate 10.3.4.5 export 305.Ed 306.Pp 307These commands will produce two tarballs 308.Em 10.2.3.4.tgz 309and 310.Em 10.3.4.5.tgz . 311Copy these tarballs over to the appropriate peers and extract them 312to the 313.Pa /etc/iked/ 314directory: 315.Bd -literal -offset indent 31610.2.3.4# tar -C /etc/iked -xzpf 10.2.3.4.tgz 31710.3.4.5# tar -C /etc/iked -xzpf 10.3.4.5.tgz 318.Ed 319.Pp 320.Nm 321will also create 322.Sq zip 323archives 10.2.3.4.zip and 10.3.4.5.zip 324in addition to the tarballs if the zip tool is found in 325.Pa /usr/local/bin/zip . 326These archives can be exported to peers running Windows and will 327include the certificates in a format that is supported by the OS. 328The zip tool can be installed from the 329.Ox 330packages or ports collection before running the 331.Ic export 332commands, see 333.Xr packages 7 334for more information. 335For example: 336.Bd -literal -offset indent 337# pkg_add zip 338.Ed 339.Sh SEE ALSO 340.Xr packages 7 , 341.Xr iked 8 , 342.Xr ssl 8 343.Sh HISTORY 344The 345.Nm 346program first appeared in 347.Ox 4.8 . 348.Sh AUTHORS 349The 350.Nm 351program was written by 352.An Reyk Floeter Aq Mt reyk@openbsd.org 353and 354.An Jonathan Gray Aq Mt jsg@openbsd.org . 355.Sh CAVEATS 356For ease of use, the 357.Ic ca 358commands maintain all peers' private keys on the CA machine. 359In contrast to a 360.Sq real 361CA, it does not support signing of public keys that have been imported 362from peers that do not want to expose their private keys to the CA. 363