xref: /openbsd-src/usr.sbin/ikectl/ikectl.8 (revision 41ce3b17e73f6b7d2d9e1a3d961e4bab2d895cb5)
1*41ce3b17Snaddy.\" $OpenBSD: ikectl.8,v 1.28 2022/03/31 17:27:30 naddy Exp $
2901ee4f0Sreyk.\"
3fcebd35dSreyk.\" Copyright (c) 2007-2013 Reyk Floeter <reyk@openbsd.org>
4901ee4f0Sreyk.\"
5901ee4f0Sreyk.\" Permission to use, copy, modify, and distribute this software for any
6901ee4f0Sreyk.\" purpose with or without fee is hereby granted, provided that the above
7901ee4f0Sreyk.\" copyright notice and this permission notice appear in all copies.
8901ee4f0Sreyk.\"
9901ee4f0Sreyk.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10901ee4f0Sreyk.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11901ee4f0Sreyk.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12901ee4f0Sreyk.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13901ee4f0Sreyk.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14901ee4f0Sreyk.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15901ee4f0Sreyk.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16901ee4f0Sreyk.\"
17*41ce3b17Snaddy.Dd $Mdocdate: March 31 2022 $
18901ee4f0Sreyk.Dt IKECTL 8
19901ee4f0Sreyk.Os
20901ee4f0Sreyk.Sh NAME
21901ee4f0Sreyk.Nm ikectl
22901ee4f0Sreyk.Nd control the IKEv2 daemon
23901ee4f0Sreyk.Sh SYNOPSIS
24901ee4f0Sreyk.Nm
25cfd26ebdSreyk.Op Fl q
26901ee4f0Sreyk.Op Fl s Ar socket
27901ee4f0Sreyk.Ar command
28901ee4f0Sreyk.Op Ar arg ...
29901ee4f0Sreyk.Sh DESCRIPTION
30901ee4f0SreykThe
31901ee4f0Sreyk.Nm
32901ee4f0Sreykprogram controls the
33901ee4f0Sreyk.Xr iked 8
34901ee4f0Sreykdaemon and provides commands to maintain a simple X.509 certificate
35901ee4f0Sreykauthority (CA) for IKEv2 peers.
36901ee4f0Sreyk.Pp
37901ee4f0SreykThe options are as follows:
38901ee4f0Sreyk.Bl -tag -width Ds
39cfd26ebdSreyk.It Fl q
40cfd26ebdSreykDon't ask for confirmation of any default options.
41901ee4f0Sreyk.It Fl s Ar socket
42901ee4f0SreykUse
43901ee4f0Sreyk.Ar socket
44901ee4f0Sreykinstead of the default
45901ee4f0Sreyk.Pa /var/run/iked.sock
46901ee4f0Sreykto communicate with
47901ee4f0Sreyk.Xr iked 8 .
48901ee4f0Sreyk.El
49901ee4f0Sreyk.Sh IKED CONTROL COMMANDS
50901ee4f0SreykThe following commands are available to control
51901ee4f0Sreyk.Xr iked 8 :
52901ee4f0Sreyk.Bl -tag -width Ds
53fc20f985Sreyk.It Cm active
54fc20f985SreykSet
55fc20f985Sreyk.Xr iked 8
56fc20f985Sreykto active mode.
57fc20f985Sreyk.It Cm passive
58fc20f985SreykSet
59fc20f985Sreyk.Xr iked 8
60fc20f985Sreykto passive mode.
61fc20f985SreykIn passive mode no packets are sent to peers and no connections
62fc20f985Sreykare initiated by
63fc20f985Sreyk.Xr iked 8 .
64fc20f985Sreyk.It Cm couple
65fc20f985SreykLoad the negotiated security associations (SAs) and flows into the kernel.
66fc20f985Sreyk.It Cm decouple
67fc20f985SreykUnload the negotiated SAs and flows from the kernel.
68fc20f985SreykThis mode is only useful for testing and debugging.
69901ee4f0Sreyk.It Cm load Ar filename
70901ee4f0SreykReload the configuration from the specified file.
71901ee4f0Sreyk.It Cm log brief
72901ee4f0SreykDisable verbose logging.
73901ee4f0Sreyk.It Cm log verbose
74901ee4f0SreykEnable verbose logging.
75901ee4f0Sreyk.It Cm monitor
76901ee4f0SreykMonitor internal messages of the
77901ee4f0Sreyk.Xr iked 8
78901ee4f0Sreyksubsystems.
79901ee4f0Sreyk.It Cm reload
80901ee4f0SreykReload the configuration from the default configuration file.
81901ee4f0Sreyk.It Cm reset all
82a30aef17SjmcReset the running state.
83901ee4f0Sreyk.It Cm reset ca
84901ee4f0SreykReset the X.509 CA and certificate state.
85901ee4f0Sreyk.It Cm reset policy
86901ee4f0SreykFlush the configured policies.
87901ee4f0Sreyk.It Cm reset sa
88901ee4f0SreykFlush the running SAs.
89901ee4f0Sreyk.It Cm reset user
90901ee4f0SreykFlush the local user database.
918c502e93Stobhe.It Cm reset id Ar ikeid
928c502e93StobheDelete all IKE SAs with matching ID.
931f32a21fStobhe.It Cm show sa
941f32a21fStobheShow internal state of active IKE SAs, Child SAs and IPsec flows.
95901ee4f0Sreyk.El
96901ee4f0Sreyk.Sh PKI AND CERTIFICATE AUTHORITY COMMANDS
97901ee4f0SreykIn order to use public key based authentication with IKEv2,
98901ee4f0Sreyka public key infrastructure (PKI) has to be set up to create and sign
99901ee4f0Sreykthe peer certificates.
100901ee4f0Sreyk.Nm
101901ee4f0Sreykincludes commands to simplify maintenance of the PKI
102901ee4f0Sreykand to set up a simple certificate authority (CA) for
103901ee4f0Sreyk.Xr iked 8
104901ee4f0Sreykand its peers.
105901ee4f0Sreyk.Pp
106901ee4f0SreykThe following commands are available to control the CA:
107901ee4f0Sreyk.Bl -tag -width Ds
108fc2a6bf0Sreyk.It Xo
109fc2a6bf0Sreyk.Cm ca Ar name Cm create
110cfe372e4Sreyk.Op Cm password Ar password
111fc2a6bf0Sreyk.Xc
112901ee4f0SreykCreate a new certificate authority with the specified
113901ee4f0Sreyk.Ar name .
114cfd26ebdSreykThe command will prompt for a CA password unless it is specified with
115cfd26ebdSreykthe optional
116cfd26ebdSreyk.Ar password
117cfd26ebdSreykargument.
118cfd26ebdSreykThe password will be saved in a protected file
119cfd26ebdSreyk.Pa ikeca.passwd
120cfd26ebdSreykin the CA directory and used for subsequent commands.
121901ee4f0Sreyk.It Cm ca Ar name Cm delete
122901ee4f0SreykDelete the certificate authority with the specified
123901ee4f0Sreyk.Ar name .
124fc2a6bf0Sreyk.It Xo
125fc2a6bf0Sreyk.Cm ca Ar name Cm export
126cfe372e4Sreyk.Op Cm peer Ar peer
127cfe372e4Sreyk.Op Cm password Ar password
128fc2a6bf0Sreyk.Xc
1290dd4c7c3SjsgExport the certificate authority with the specified
1300dd4c7c3Sjsg.Ar name
1310dd4c7c3Sjsginto the current directory for transport to other systems.
1323659b08dSreykThis command will create a compressed tarball called
1333659b08dSreyk.Pa ca.tgz
1343659b08dSreykin the local directory and optionally
1353659b08dSreyk.Pa ca.zip
1363659b08dSreykif the
1373659b08dSreyk.Sq zip
1383659b08dSreyktool is installed.
1390dd4c7c3SjsgThe optional
1400dd4c7c3Sjsg.Ar peer
1410dd4c7c3Sjsgargument can be used to specify the address or FQDN of the local gateway
1420dd4c7c3Sjsgwhich will be written into a text file
1433659b08dSreyk.Pa peer.txt
1443659b08dSreykand included in the archives.
145ad377ae2Sjsg.It Xo
146ad377ae2Sjsg.Cm ca Ar name
147ad377ae2Sjsg.Cm install Op Ar path
148ad377ae2Sjsg.Xc
149c3cc2c5eSjsgInstall the certificate and Certificate Revocation List (CRL) for CA
150901ee4f0Sreyk.Ar name
1517638a50cSjsgas the currently active CA or into the specified
1527638a50cSjsg.Ar path .
153fc2a6bf0Sreyk.It Xo
154fc2a6bf0Sreyk.Cm ca Ar name Cm certificate Ar host
155fc2a6bf0Sreyk.Cm create
156ab7171b1Sjsg.Op Ic server | client | ocsp
157fc2a6bf0Sreyk.Xc
158901ee4f0SreykCreate a private key and certificate for
159901ee4f0Sreyk.Ar host
1603659b08dSreykand sign then with the key of certificate authority with the specified
161901ee4f0Sreyk.Ar name .
162cfd26ebdSreyk.Pp
163cfd26ebdSreykThe certificate will be valid for client and server authentication by
164cfd26ebdSreykdefault by setting both flags as the extended key usage in the certificate;
165cfd26ebdSreykthis can be restricted using the optional
166cfd26ebdSreyk.Ic server
167cfd26ebdSreykor
168cfd26ebdSreyk.Ic client
169cfd26ebdSreykargument.
170ab7171b1SjsgIf the
171ab7171b1Sjsg.Ic ocsp
172*41ce3b17Snaddyargument is specified, the extended key usage will be set for OCSP signing.
173fc2a6bf0Sreyk.It Xo
174fc2a6bf0Sreyk.Cm ca Ar name Cm certificate Ar host
175fc2a6bf0Sreyk.Cm delete
176fc2a6bf0Sreyk.Xc
177a30aef17SjmcDeletes the private key and certificates associated with
178901ee4f0Sreyk.Ar host .
179fc2a6bf0Sreyk.It Xo
180fc2a6bf0Sreyk.Cm ca Ar name Cm certificate Ar host
181fc2a6bf0Sreyk.Cm export
182cfe372e4Sreyk.Op Cm peer Ar peer
183cfe372e4Sreyk.Op Cm password Ar password
184fc2a6bf0Sreyk.Xc
185901ee4f0SreykExport key files for
186901ee4f0Sreyk.Ar host
187901ee4f0Sreykof the certificate authority with the specified
188901ee4f0Sreyk.Ar name
189901ee4f0Sreykinto the current directory for transport to other systems.
1903659b08dSreykThis command will create a compressed tarball
1913659b08dSreyk.Pa host.tgz
1923659b08dSreykin the local directory and optionally
1933659b08dSreyk.Pa host.zip
1943659b08dSreykif the
1953659b08dSreyk.Sq zip
1963659b08dSreyktool is installed.
1970dd4c7c3SjsgThe optional
1980dd4c7c3Sjsg.Ar peer
1990dd4c7c3Sjsgargument can be used to specify the address or FQDN of the local gateway
2000dd4c7c3Sjsgwhich will be written into a text file
2013659b08dSreyk.Pa peer.txt
2023659b08dSreykand included in the archives.
203fc2a6bf0Sreyk.It Xo
204fc2a6bf0Sreyk.Cm ca Ar name Cm certificate Ar host
2057638a50cSjsg.Cm install Op Ar path
206fc2a6bf0Sreyk.Xc
207901ee4f0SreykInstall the private and public key for
208901ee4f0Sreyk.Ar host
2097638a50cSjsginto the active configuration or specified
2107638a50cSjsg.Ar path .
211fc2a6bf0Sreyk.It Xo
212fc2a6bf0Sreyk.Cm ca Ar name Cm certificate Ar host
213fc2a6bf0Sreyk.Cm revoke
214fc2a6bf0Sreyk.Xc
215c3cc2c5eSjsgRevoke the certificate specified by
216c3cc2c5eSjsg.Ar host
217c3cc2c5eSjsgand generate a new Certificate Revocation List (CRL).
21869ffd282Sreyk.It Xo
21969ffd282Sreyk.Cm show Cm ca Ar name Cm certificates
22069ffd282Sreyk.Op Ar host
22169ffd282Sreyk.Xc
222901ee4f0SreykDisplay a listing of certificates associated with CA
22369ffd282Sreyk.Ar name
22469ffd282Sreykor display certificate details if
22569ffd282Sreyk.Ar host
22669ffd282Sreykis specified.
227fc2a6bf0Sreyk.It Xo
228fc2a6bf0Sreyk.Cm ca Ar name Cm key Ar host
229fc2a6bf0Sreyk.Cm create
230fc2a6bf0Sreyk.Xc
2311dbb1d4aSjsgCreate a private key for
2321dbb1d4aSjsg.Ar host
2331dbb1d4aSjsgif one does not already exist.
234fc2a6bf0Sreyk.It Xo
235fc2a6bf0Sreyk.Cm ca Ar name Cm key Ar host
2367638a50cSjsg.Cm install Op Ar path
237fc2a6bf0Sreyk.Xc
2381dbb1d4aSjsgInstall the private and public keys for
2391dbb1d4aSjsg.Ar host
2407638a50cSjsginto the active configuration or specified
2417638a50cSjsg.Ar path .
242fc2a6bf0Sreyk.It Xo
243fc2a6bf0Sreyk.Cm ca Ar name Cm key Ar host
244fc2a6bf0Sreyk.Cm delete
245fc2a6bf0Sreyk.Xc
2461dbb1d4aSjsgDelete the private key for
2471dbb1d4aSjsg.Ar host .
248fc2a6bf0Sreyk.It Xo
249fc2a6bf0Sreyk.Cm ca Ar name Cm key Ar host
250fc2a6bf0Sreyk.Cm import
251fc2a6bf0Sreyk.Ar file
252fc2a6bf0Sreyk.Xc
2531dbb1d4aSjsgSource the private key for
2541dbb1d4aSjsg.Ar host
2551dbb1d4aSjsgfrom the named
2561dbb1d4aSjsg.Ar file .
257901ee4f0Sreyk.El
258d6abf66aSjmc.Sh FILES
259d6abf66aSjmc.Bl -tag -width "/var/run/iked.sockXX" -compact
260b9170857Ssobrado.It Pa /etc/iked/
261d6abf66aSjmcActive configuration.
262b9170857Ssobrado.It Pa /etc/ssl/
263d6abf66aSjmcDirectory to store the CA files.
264d0de1b12Ssobrado.It Pa /usr/share/iked/
265d6abf66aSjmcIf this optional directory exists,
266d6abf66aSjmc.Nm
267d6abf66aSjmcwill include the contents with the
268d6abf66aSjmc.Cm ca export
269d6abf66aSjmccommands.
270b9170857Ssobrado.It Pa /var/run/iked.sock
271d0de1b12SsobradoDefault
272d6abf66aSjmc.Ux Ns -domain
273d6abf66aSjmcsocket used for communication with
274d0de1b12Ssobrado.Xr iked 8 .
275d6abf66aSjmc.El
2763659b08dSreyk.Sh EXAMPLES
2773659b08dSreykFirst create a new certificate authority:
2783659b08dSreyk.Bd -literal -offset indent
2793659b08dSreyk# ikectl ca vpn create
2803659b08dSreyk.Ed
2813659b08dSreyk.Pp
2823659b08dSreykNow create the certificates for the VPN peers.
2833659b08dSreykThe specified hostname, either IP address or FQDN, will be saved in
2843659b08dSreykthe signed certificate and has to match the IKEv2 identity, or
2853659b08dSreyk.Ar srcid ,
2863659b08dSreykof the peers:
2873659b08dSreyk.Bd -literal -offset indent
2883659b08dSreyk# ikectl ca vpn certificate 10.1.2.3 create
2893659b08dSreyk# ikectl ca vpn certificate 10.2.3.4 create
2903659b08dSreyk# ikectl ca vpn certificate 10.3.4.5 create
2913659b08dSreyk.Ed
2923659b08dSreyk.Pp
2933659b08dSreykIt is possible that the host that was used to create the CA is also
2943659b08dSreykone of the VPN peers.
2953659b08dSreykIn this case you can install the peer and CA certificates locally:
2963659b08dSreyk.Bd -literal -offset indent
2973659b08dSreyk# ikectl ca vpn install
2983659b08dSreyk# ikectl ca vpn certificate 10.1.2.3 install
2993659b08dSreyk.Ed
3003659b08dSreyk.Pp
3013659b08dSreykNow export the individual host key, the certificate and the CA
3023659b08dSreykcertificate to each other peer.
3033659b08dSreykFirst run the
3043659b08dSreyk.Ic export
3053659b08dSreykcommand to create tarballs that include the required files:
3063659b08dSreyk.Bd -literal -offset indent
3073659b08dSreyk# ikectl ca vpn certificate 10.2.3.4 export
3083659b08dSreyk# ikectl ca vpn certificate 10.3.4.5 export
3093659b08dSreyk.Ed
3103659b08dSreyk.Pp
3113659b08dSreykThese commands will produce two tarballs
3128ff129dbSsthen.Em 10.2.3.4.tgz
3133659b08dSreykand
314402e1911Ssthen.Em 10.3.4.5.tgz .
3153659b08dSreykCopy these tarballs over to the appropriate peers and extract them
3163659b08dSreykto the
3173659b08dSreyk.Pa /etc/iked/
3183659b08dSreykdirectory:
3193659b08dSreyk.Bd -literal -offset indent
3203659b08dSreyk10.2.3.4# tar -C /etc/iked -xzpf 10.2.3.4.tgz
3213659b08dSreyk10.3.4.5# tar -C /etc/iked -xzpf 10.3.4.5.tgz
3223659b08dSreyk.Ed
3233659b08dSreyk.Pp
3243659b08dSreyk.Nm
3253659b08dSreykwill also create
3263659b08dSreyk.Sq zip
3273659b08dSreykarchives 10.2.3.4.zip and 10.3.4.5.zip
3283659b08dSreykin addition to the tarballs if the zip tool is found in
3293659b08dSreyk.Pa /usr/local/bin/zip .
3303659b08dSreykThese archives can be exported to peers running Windows and will
3313659b08dSreykinclude the certificates in a format that is supported by the OS.
332d6abf66aSjmcThe zip tool can be installed from the
333d6abf66aSjmc.Ox
334d6abf66aSjmcpackages or ports collection before running the
3353659b08dSreyk.Ic export
3363659b08dSreykcommands, see
3373659b08dSreyk.Xr packages 7
3383659b08dSreykfor more information.
3393659b08dSreykFor example:
3403659b08dSreyk.Bd -literal -offset indent
3413659b08dSreyk# pkg_add zip
3423659b08dSreyk.Ed
343901ee4f0Sreyk.Sh SEE ALSO
3443659b08dSreyk.Xr packages 7 ,
345d6abf66aSjmc.Xr iked 8 ,
346d6abf66aSjmc.Xr ssl 8
347901ee4f0Sreyk.Sh HISTORY
348901ee4f0SreykThe
349901ee4f0Sreyk.Nm
350901ee4f0Sreykprogram first appeared in
351901ee4f0Sreyk.Ox 4.8 .
352901ee4f0Sreyk.Sh AUTHORS
353901ee4f0SreykThe
354901ee4f0Sreyk.Nm
355901ee4f0Sreykprogram was written by
35644e68d47Sschwarze.An Reyk Floeter Aq Mt reyk@openbsd.org
357e0eba464Sreykand
35844e68d47Sschwarze.An Jonathan Gray Aq Mt jsg@openbsd.org .
3593659b08dSreyk.Sh CAVEATS
360d6abf66aSjmcFor ease of use, the
3613659b08dSreyk.Ic ca
362d6abf66aSjmccommands maintain all peers' private keys on the CA machine.
3633659b08dSreykIn contrast to a
3643659b08dSreyk.Sq real
3653659b08dSreykCA, it does not support signing of public keys that have been imported
3663659b08dSreykfrom peers that do not want to expose their private keys to the CA.
367