readme

cipe 编程

   PKCIPE - public key based configuration tool for CIPE

Olaf Titz, November 2000

This is alpha stuff, much of it does not work as intended - basic
functionality only. More to come. Expect bugs and hopefully not too
incompatible changes.

This package allows to manage CIPE links without the need for
statically configuring secret keys. It also eases the use of CIPE with
dynamic carrier addresses.

Installation instructions:
1. Make sure you have the necessary prerequisites (i.e. OpenSSL).
2. Install CIPE as usual.
3. Look at the ip-up and ip-down samples in this package.
   Install the snippets in your global ip-up and ip-down.
   They manage the PID files and act on the ARG parameter, without this
   pkcipe won't work correctly.
4. Set up options files for your peers in /etc/cipe/pk/NAME and
   copy their public keys there. See below.

It works like this: each machine in the VPN has an identity (may be
its host name) and a public/private RSA key pair. Its private key is
stored in /etc/cipe/identity.priv. For every allowed CIPE connection,
the public key of the other part is stored, along with configuration
parameters, in /etc/cipe/pk/NAME (where NAME is the identity of the other
part). Thus storing a public key gives permission to connect, similar
to the SSH package (it is important to know how this works to not open
holes).

The pkcipe program uses these keys to authenticate against other
instances. For this a signed Diffie-Hellman key exchange (which also
produces the formerly-known-as-"static key" for ciped) is performed.
The identities are checked and configuration options are negotiated.
When everything is right, pkcipe spawns ciped.

The pkcipe program can act as a server or client but this is only for
TCP connection establishment, the protocol is symmetric. In
particular, each host is authenticated against each other.
It is invoked as follows, NAME gives the own identity and defaults
to the host name:
pkcipe -i NAME
  to be invoked from inetd
pkcipe -c HOST:PORT NAME
  to connect to HOST:PORT
Other arguments to pkcipe are:
  -k keyfile	gives location of private key file
  -r ipaddr	routing IP address. Only for unusual cases, s.b.
  -D flags	Debugging flags.
  -E		Use stderr instead of syslog. (Debugging only,
		incompatible with -i.)
  -p proto	Fall back to given protocol level.
  -t secs	Set timeout.
After successful authentication and parameter exchange, pkcipe
generates an options file under /var/run/cipe and invokes ciped with
this options file. /etc/cipe/options is only used for defaults, it
should not contain stuff specific to any link (e.g. it may contain
"ipaddr" but not "ptpaddr").

To generate keys, use the "rsa-keygen" script:
rsa-keygen NAME 
writes the private key into the file NAME.priv and the corresponding
public key into NAME. It should be invoked on each host, the private
key should be moved to /etc/cipe/identity.priv and the public key
should be copied to the other machine(s). The public key files are
text files, it is possible (and necessary) to append options in the
usual format to these files _after_ the key.
"make install" generates a key and stores it in the /etc/cipe directory.

Note: option negotiation does not really work in this version. The
only options currently handled by pkcipe are: key, me, peer, arg. (arg
_must_ contain the peer's identity; the ip-up script needs to act on
this.) All other options (currently) have to be set in the public key
files. These are the options _we_ want to use when talking to that
peer, not the peer's options (e.g. "ipaddr" is our own address).

This is already enough to manage dynamic carriers: the dynamic end
calls pkcipe -c HOST:PORT with the static end as HOST, it will pick up
its own IP address and report this to the static end which tells it to
its ciped. (For two dynamic ends use a dynamic-DNS service on one end
and pretend that's the static one. Again, there is no distinction
between server and client; each one tells the other its current IP
address.) On the static end pkcipe will need to run from inetd.

The "routing IP address" argument is used to find out the right device
and IP address for connecting to the peer. This is usually the peer IP
address itself but when connecting through a tunnel or proxy, it may
be necessary to explicitly tell pkcipe the real address.

This needs the OpenSSL package (http://www.openssl.org), version 0.9.6
or later. The configure script tries to find the right path for
includes and libraries.

Do not use the --enable-bug-compatible configuration for CIPE.
PCKIPE can not check this.

TO DO: implement real parameter negotiation. Protocol hooks are there,
PPP-style.

TO DO: Currently the use of "ciped-cb" is hardcoded. This is one of
the next deficiencies to be fixed; it will be possible to select an
available device type.

TO DO: clean up the code. Too many globals, no module separation, etc.

TO DO: write better docs.

$Id: README,v 1.6 2001/11/18 18:27:04 olaf Exp $