Add some examples about using the CA commands to create and install the

CA and peers certificates.

With input from mikeb@

1 files changed, 99 insertions, 6 deletions

diff --git a/usr.sbin/ikectl/ikectl.8 b/usr.sbin/ikectl/ikectl.8
index 2b2e77a5f45..4a5ce83b935 100644
--- a/usr.sbin/ikectl/ikectl.8
+++ b/usr.sbin/ikectl/ikectl.8
@@ -1,4 +1,4 @@
-.\" $OpenBSD: ikectl.8,v 1.6 2010/06/23 16:01:01 jsg Exp $
+.\" $OpenBSD: ikectl.8,v 1.7 2010/09/30 10:03:52 reyk Exp $
 .\" $vantronix: ikectl.8,v 1.11 2010/06/03 15:55:51 reyk Exp $
 .\"
 .\" Copyright (c) 2007, 2008, 2009, 2010 Reyk Floeter <reyk@vantronix.net>
@@ -15,7 +15,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: June 23 2010 $
+.Dd $Mdocdate: September 30 2010 $
 .Dt IKECTL 8
 .Os
 .Sh NAME
@@ -109,11 +109,19 @@ Delete the certificate authority with the specified
 Export the certificate authority with the specified
 .Ar name
 into the current directory for transport to other systems.
+This command will create a compressed tarball called
+.Pa ca.tgz
+in the local directory and optionally
+.Pa ca.zip
+if the
+.Sq zip
+tool is installed.
 The optional
 .Ar peer
 argument can be used to specify the address or FQDN of the local gateway
 which will be written into a text file
-.Pa peer.txt .
+.Pa peer.txt
+and included in the archives.
 .It Cm ca Ar name Cm install
 Install the certificate and Certificate Revocation List (CRL) for CA
 .Ar name
@@ -121,7 +129,7 @@ as the currently active CA.
 .It Cm ca Ar name Cm certificate Ar host Cm create
 Create a private key and certificate for
 .Ar host
-and sign then with the key of certificate authority with the speicified
+and sign then with the key of certificate authority with the specified
 .Ar name .
 .It Cm ca Ar name Cm certificate Ar host Cm delete
 Deletes the private key and and certificates associated with
@@ -132,11 +140,19 @@ Export key files for
 of the certificate authority with the specified
 .Ar name
 into the current directory for transport to other systems.
+This command will create a compressed tarball
+.Pa host.tgz
+in the local directory and optionally
+.Pa host.zip
+if the
+.Sq zip
+tool is installed.
 The optional
 .Ar peer
 argument can be used to specify the address or FQDN of the local gateway
 which will be written into a text file
-.Pa peer.txt .
+.Pa peer.txt
+and included in the archives.
 .It Cm ca Ar name Cm certificate Ar host Cm install
 Install the private and public key for
 .Ar host
@@ -165,8 +181,76 @@ Source the private key for
 from the named
 .Ar file .
 .El
+.Sh EXAMPLES
+First create a new certificate authority:
+.Bd -literal -offset indent
+# ikectl ca vpn create
+.Ed
+.Pp
+Now create the certificates for the VPN peers.
+The specified hostname, either IP address or FQDN, will be saved in
+the signed certificate and has to match the IKEv2 identity, or
+.Ar srcid ,
+of the peers:
+.Bd -literal -offset indent
+# ikectl ca vpn certificate 10.1.2.3 create
+# ikectl ca vpn certificate 10.2.3.4 create
+# ikectl ca vpn certificate 10.3.4.5 create
+.Ed
+.Pp
+It is possible that the host that was used to create the CA is also
+one of the VPN peers.
+In this case you can install the peer and CA certificates locally:
+.Bd -literal -offset indent
+# ikectl ca vpn install
+# ikectl ca vpn certificate 10.1.2.3 install
+.Ed
+.Pp
+Now export the individual host key, the certificate and the CA
+certificate to each other peer.
+First run the
+.Ic export
+command to create tarballs that include the required files:
+.Bd -literal -offset indent
+# ikectl ca vpn certificate 10.2.3.4 export
+# ikectl ca vpn certificate 10.3.4.5 export
+.Ed
+.Pp
+These commands will produce two tarballs
+.Em 10.1.2.3.tgz
+and
+.Em 10.4.5.6.tgz .
+Copy these tarballs over to the appropriate peers and extract them
+to the
+.Pa /etc/iked/
+directory:
+.Bd -literal -offset indent
+10.2.3.4# tar -C /etc/iked -xzpf 10.2.3.4.tgz
+10.3.4.5# tar -C /etc/iked -xzpf 10.3.4.5.tgz
+.Ed
+.Pp
+.Nm
+will also create
+.Sq zip
+archives 10.2.3.4.zip and 10.3.4.5.zip
+in addition to the tarballs if the zip tool is found in
+.Pa /usr/local/bin/zip .
+These archives can be exported to peers running Windows and will
+include the certificates in a format that is supported by the OS.
+The zip tool can be installed from the OpenBSD packages or ports
+collection before running the
+.Ic export
+commands, see
+.Xr packages 7
+for more information.
+For example:
+.Bd -literal -offset indent
+# pkg_add zip
+.Ed
 .Sh FILES
 .Bl -tag -width "/var/run/iked.sockXX" -compact
+.It /etc/iked/
+Active configuration.
 .It /etc/ssl/
 Directory to store the CA files.
 .It /usr/share/iked
@@ -183,7 +267,8 @@ socket used for communication with
 .El
 .Sh SEE ALSO
 .Xr iked 8 ,
-.Xr ssl 8
+.Xr packages 7 ,
+.Xr ssl 8 ,
 .Sh HISTORY
 The
 .Nm
@@ -194,3 +279,11 @@ The
 .Nm
 program was written by
 .An Reyk Floeter Aq reyk@vantronix.net .
+.Sh CAVEATS
+For the ease of use, the
+.Ic ca
+commands will maintain all private keys of the peers on the CA machine.
+In contrast to a
+.Sq real
+CA, it does not support signing of public keys that have been imported
+from peers that do not want to expose their private keys to the CA.