| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The CIPE software package is available via the WWW from
http://sites.inka.de/~bigred/devel/cipe.html. It is distributed in
a tar.gz file, currently about 138k in size. After unpacking the
distribution, run the configure script, possibly specifying
options there. Then run make.
2.1 Prerequisites What you need before installing. 2.2 Protocols and ciphers Important compile-time options to select. 2.3 Advanced compiling Configuring the compile for different targets. 2.4 Installation Compiling and installing the software. 2.5 Compilation errors If something goes wrong. 2.6 Running CIPE Running the software.
CIPE runs under Linux 2.0.* since 2.0.12, 2.1.* since about 2.1.103, 2.2.*, 2.3.* since 2.3.48, 2.4.*, and 2.6.*. It was developed for the i386 architecture; other architectures should work.
Make sure you have the complete source tree of the running kernel installed (usually in `/usr/src/linux'). The version and configuration of the kernel sources must match the kernel on which it will run exactly, or else you risk building a module which crashes. You also have to use the same compiler version than the one with which the kernel was compiled. After reconfiguring and rebuilding the kernel, don't forget to rebuild the CIPE module too. (This applies to all externally compiled modules.) Enabling "versioned symbols" on the kernel is strongly recommended, because it protects against version skew between kernel and modules.
The kernel needs "IP Forwarding/Gatewaying" enabled in the configuration for 2.0 kernels. Make sure to enable IP forwarding with
echo 1 > /proc/sys/net/ipv4/ip_forward |
urandom
device must be available.
For kernels that have it (i.e. 2.4.22 upwards or 2.6), the option "CRC32 functions" under "Library routines" should be enabled.
A suited version of the module utilities (modprobe and friends)
needs to be installed. When in doubt, consult the documentation in the
kernel source.
The PKCIPE tool needs the OpenSSL package, version 0.9.6 or later. If this is not available, the rest of the CIPE package can still be compiled and installed as usual.
Since version 1.3, CIPE uses an autoconf-generated configure script to configure its Makefiles. This script takes the following parameters on the command line. All of the parameters have defaults which should suffice for a simple installation.
--with-linux.
ciped and pkcipe
(default and usually right is LOG_DAEMON).
The script then looks for certain parameters (like whether compiling for
an SMP system) in the kernel headers, and it creates a new directory
named like 2.2.6-i386-cb in which compilation of the module and
daemon will take place. (This would be for Linux 2.2.6 on i386, protocol
3 [the "c"], Blowfish [the "b"].)
The PKCIPE tool and some library components are built in their source
directories, they do not depend on configuration (in theory;
unfortunately pkcipe is still tied to the particular
ciped in use, but this is going to be fixed).
CIPE supports different versions of the encryption protocol, which in
turn can be used with different ciphers (encryption algorithms). Which
one is used is chosen at compile time with arguments to the
configure script.
As of CIPE 1.5, the following options are possible:
Protocol version 3: This is the default protocol and recommended for most use. It is described in detail in this document. See section 6.1 The CIPE protocol. The device works as an IP-only point-to-point device much like with SLIP or PPP.
Protocol version 4: This protocol uses the same data format as protocol version 3, except that the packets transmitted contain an Ethernet-compatible link-level header. With this it is possible to run payload protocols other than IP, and particularly it is possible to make the CIPE device part of an Ethernet bridge. The disadvantage is that the packets get larger than with protocol 3. It may be necessary to set the MAC address using the `hwaddr' option to make it unique across the VPN. With this protocol, the device has a subnet mask and broadcast address which can be set with appropriate options.
Blowfish: This is the default encryption algorithm, used with a 128 bit key.
IDEA: An alternate encryption algorithm with a 128 bit key. This algorithm is patented and may need a licence for commercial use. It is no longer included in the CIPE package, but can (in theory) be used via the cryptographic API.
Since CIPE 1.4, the built-in Blowfish is available in generic C and i386 assembler implementations. The assembler versions are used where possible.
With CIPE 1.6 it is possible to use the cryptographic API in Linux
2.4.22 or later and 2.6 and use the modularized ciphers. In this case,
the module and daemon are named like cipc and ciped-c
(note the lack of the last letter indicating the builtin cipher).
The cipher actually used can be specified as a configuration parameter,
defaulting to blowfish-internal which gives the old builtin
Blowfish algorithm. Note that this version is not compatible with the
kernel Blowfish module, because blowfish-internal is originally
coded little-endian (real Blowfish is big-endian) and remains so for
compatibility with older versions.
Ciphers with a block or IV size other than 64 bits are not supported.
The use of a separate object directory means it is possible to compile
CIPE for separate targets in the same directory. An example would be a
machine running different kernels for testing, etc. In that case you
would have kernel directories like `/usr/src/linux-2.0.36',
`/usr/src/linux-2.2.6', and so on. Running configure
--with-linux=/usr/src/linux-2.0.36 and after that configure
--with-linux=/usr/src/linux-2.2.6 leaves two directories
2.0.36-i386-cb and 2.2.6-i386-cb. You can run make
in each of the object directories separately.
Another common case is a setup where one central box compiles kernels for different machines. You can rename CIPE's compilation directories with the --enable-name option, perhaps name them after the target machine:
./configure --with-linux=/usr/src/linux-2.2.6-bigbox \
--enable-name=bigbox
make -C 2.2.6-i386-cb-bigbox
./configure --with-linux=/usr/src/linux-2.2.6-satellite \
--enable-name=satellite
make -C 2.2.6-i386-cb-satellite
./configure --with-linux=/mounts/srv1/linux-2.2.5-small \
--enable-name=laptop
make -C 2.2.5-i386-cb-laptop
|
In the same way distribution maintainers could prepare a set of differently configured CIPE modules (IDEA vs. Blowfish) for one target. The names of the module and driver are chosen so that different configurations can coexist on one target. See section 2.6.1 Program Names.
Note that real cross-compilation is not possible for now, because the configure script always assumes the CPU architecture of the system where it runs.
A simple make command compiles everything. Compiler warnings
should not occur. Do make install as
root to install the software components in their final location.
These are a kernel module, named according to the protocol version and
encryption algorithm selected, and the driver program, which is (since
CIPE 1.3) also named after the protocol version and encryption
algorithm. See section 2.6.1 Program Names. The Makefiles accept the semi-standard
options BINDIR, MODDIR, INFODIR to specify where the stuff gets
installed.
If PKCIPE was compiled, make install also installs the
pkcipe program and a helper rsa-keygen, sets up the
necessary directories and generates a host key if none is already there.
See section 4. The PKCIPE tool.
You need to create a directory `/etc/cipe' which contains at least two files, `options' and `ip-up'. You can copy the files from the `samples' directory in the distribution here, and edit them to suit your needs. See section 3. Configuration of the CIPE software.
There is a known problem in that the various 2.0.30 and 2.0.31
pre-releases disagree on whether they have a certain feature
(SO_BINDTODEVICE), and detecting this version dependency via the
version number is not foolproof. Apparently, since 2.0.32, this problem
is resolved. If output.c doesn't compile under 2.0.*, change the
line
#ifdef SO_BINDTODEVICE |
#if 1 or #if 0 as needed.
A similar problem exists in the 2.3.99 pre-releases, where the
name part of the net_device structure has changed. If an
error occurs during compilation of `device.c' under 2.3.99pre-n,
change the conditional definition of HAVE_DEVNAME_ARRAY in
`cipe.h' to #if 1 or #if 0 as needed.
Since the 2.4.0 test releases this problem is resolved.
Once installed, the CIPE software is run by loading the module and
running the ciped daemon.
2.6.1 Program Names How the components of CIPE are named. 2.6.2 Loading the module Loading the kernel module. 2.6.3 Running the cipeddaemonRunning the daemon.
The module name is cip followed by the protocol version as a
letter and the first letter of the encryption algorithm. E.g.
cipcb for version 3 (i.e. "c"), Blowfish (the default). The
device names which this module manages are the module name followed by a
number, e.g. cipcb0.
Since CIPE 1.3, the daemon program is named ciped- followed by
the protocol and encryption letters, likewise. E.g. ciped-cb.
Where this manual refers to ciped, assume the real name as given
here.
The configuration parameters of kernel module and daemon must match (the module checks this), but the daemon does not depend (at least not in theory) on the kernel version. The naming scheme is chosen so that all possible modules and daemons on one machine can coexist.
The pkcipe program is designed to be independent from the
configuration. However, currently it can only handle one version of
ciped (i.e. one protocol and cipher version). This will be fixed
in future versions.
The kernel module is loaded into the kernel via the command
modprobe modulename parameter=value... |
The CIPE module accepts the following additional parameters:
cipe_debug=(number)
cipe_maxdev=(number)
cipe_maxdev=4 the devices cipcb0
through cipcb3 are available. Maximum is 9999 Since CIPE 1.2, there
is no need to set this, since channels are allocated dynamically.
The module can be autoloaded via kerneld/kmod. Advanced
users will recognize the following options in `/etc/conf.modules'
necessary to make it work correctly:
alias cipcb0 cipcb options cipcb cipe_debug=0 |
cipcb0 is pointless and autoloading only works when the
requesting application is ciped (not ifconfig etc.)
This is a limitation inherent in dynamic device allocation.
ciped daemon
The ciped daemon must be run as root. (Do not make
it setuid.) It takes as command line arguments an optional `-o
file' parameter specifying an options file followed by any number of
individual option arguments. See section 3.1 Specifying options.
Except in debugging mode, the daemon puts itself in the background and
uses syslog(3) for logging messages. Normal operation causes no
log messages except for errors and a notice when the daemon terminates.
Shutting down (with ifconfig(8)) a CIPE device terminates its
ciped process, and vice-versa terminating a ciped closes
the device. When a device is closed, its configuration parameters
including all keys and statistics are erased. (This is different from
earlier CIPE versions!) ciped does not keep any keys in memory.
When the device comes up, ciped spawns `/etc/cipe/ip-up'
with the parameters described in the sample version. It waits for
completion of this script before data can be sent over the device and
before it goes into the background. The script is called with standard
input, output and error to `/dev/null'. It typically sets routes
and does some logging. Since CIPE 1.4, the script is called with all
options (except key) in environment variables named after the option.
Likewise, when a CIPE device goes down, `/etc/cipe/ip-down' is
invoked. ciped itself logs the interface statistics when closing.
ciped will terminate when an error occurs. This includes a
"connection refused" message from the peer, to be able to detect
non-working peers. This default error handling implies that no data may
be sent over a link unless both ends are up and running, or the
first one to come up will go down again immediately. In particular, the
"ping" command in the sample `ip-up' should not be activated on
both ends of a link. This behaviour can be customized. See section 3.6 Error handling in ciped, for more details.
| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |