4. The PKCIPE tool

The pkcipe program, included in the CIPE package since version 1.5, eases configuration and running of CIPE links. With pkcipe it is not necessary to use long lived static keys. A public key based scheme (using Diffie-Hellman key exchange and RSA signatures) is used instead. pkcipe also automatically handles dynamic carrier addresses.

4.1 How it works		Short overview on PKCIPE.
4.2 Public Keys		What public keys are and how to use them.
4.3 Running the pkcipe program		Running the pkcipe program.

4.1 How it works

To start a CIPE link, two instances of the pkcipe program, one on each side of the link, are connected via TCP. They do a key exchange, yielding a new random key which is used as the key parameter for CIPE. They tell each other their identity and send a signature built with their private key.

Each side verifies the signature using the other side's public key. Additional parameters are exchanged as necessary. Currently these additional parameters are only the carrier IP addresses, which the pkcipe program obtains from the system at run time.

After all parameters are set up, pkcipe writes an options file containing the new key and other parameters and starts ciped with this options file. Then pkcipe exits and the TCP connection is closed.

4.2 Public Keys

With PKCIPE, each host has a public/private key pair. The private (secret) key is kept in the file `/etc/cipe/identity.priv' and never copied anywhere else. The `/etc/cipe/pk' directory contains the public keys of all peers. For all key files, the same restrictions on file and directory permissions apply as for options files. See section 3.1 Specifying options.

Each host has an identity (usually its host name, but really it is an arbitrary string) by which it is known to its peers. The public key files are named according to these identities. Each public key files also contains options (as in a CIPE options file) for this peer. The peer which has the right private key is allowed to connect.(5)

A public key pair may be generated with the rsa-keygen script. This generates two files, one with the public and one with the private key, the latter having the file name ending .priv. The Makefile automatically does this on installation time if necessary.

The secret key may be encrypted with a passphrase. In this case pkcipe asks for the passphrase every time it starts. This may be useful e.g. for mobile systems which connect manually to a central host. The `-p' argument to rsa-keygen allows to set a passphrase on the newly generated secret key. For existing secret keys, the passphrase can be changed with the command

openssl rsa -des3 -out newfile -in oldfile

and deleted with the command

openssl rsa -out newfile -in oldfile

where `oldfile' is the existing secret key file; the result will be stored in `newfile'.

4.3 Running the pkcipe program

The pkcipe program must be run as root. (Do not make it setuid.) pkcipe takes the following command line parameters:

`-c host:port'

Run in client mode, connect to the given address.

`-t timeout'

Set the timeout for each network read (default is 60 seconds).

`-r host'

Give the host where the actual CIPE UDP packets are routed to. This option is necessary when the TCP connection is done via a SOCKS or other proxy (e.g. SSH redirection).

`-k keyfile'

Specify the private key file. Default is `/etc/cipe/identity.priv'.

`-p proto'

Set the PKCIPE protocol level to use. Currently there exists only the protocol level 2.

`-D debug'

Debug logging flags.

`-E'

Log to standard error instead of syslog. For debugging purposes.

`identity'

(non-option parameter) Specify the identity to use. Default is the host name.

See section 5.3 Example 2, for how pkcipe is run in server mode.

The location of the ciped command to be run by PKCIPE, as well as the auxiliary files read from and written to, is currently hardcoded at compile time.