cipe.texinfo

cipe 编程

(This section is only relevant to readers who want to understand the
source, not to the regular user.)

The module consists of an output driver, an input driver, the
encapsulation routines and some stuff to keep it all together. The
output driver is largely an adapted version of @code{new_tunnel} from
@cindex tunnel driver
the Linux distribution. @footnote{From Linux 2.2 on, this has been merged
into the @code{ipip} module, but the functionality is the same.}
In Linux 2.0 its actual packet sending is done via the
@cindex Kernel IP forwarding option
kernel IP forwarding engine. This implies that (a) forwarding must be
enabled in the kernel and (b) the encrypted packets, being UDP packets
with the source/dest addresses given as "me" and "peer", are checked
@cindex firewall rules
against the forwarding (as well as the output) firewall. (If it
doesn't work for you, first make sure that your firewall rules let the
packets pass!)

The input driver is an adaptation from the kernel UDP receiver. To
activate it, ciped has to set a socket into a special mode with an
@code{ioctl} call. This has to be a connected UDP socket. The
@code{ioctl_attach(2cipe)} call replaces the socket's @code{sendto(2)} and
@code{recvfrom(2)} operations with special versions that do decryption
of traffic internally and only pass key exchange blocks to the user
layer. The whole work of decrypting and rerouting incoming traffic is
done inside a blocking @code{recvfrom(2)}. This means that unlike
normal IP forwarding, it is called from user mode and the needed CPU
time is charged to the ciped process, although the data never passes
into user mode. @code{sendto(2)} encodes the block as a key exchange
block and sends it to the peer. The socket should not use
@code{read(2)}, @code{write(2)}, @code{select(2)} or nonblocking mode
(yet).

Before attaching the socket, the operational parameters of the device
have to be set using a @code{ioctl_setpar(2cipe)} call. The key exchange
process supplies keys to the kernel via @code{ioctl_setkey(2cipe)}.

The netdevice can only be opened (configured "UP") if it has a
controlling socket. When the controlling socket is closed, the netdevice
gets closed. Conversely, closing the netdevice (with @code{ifconfig(8)})
closes the socket too. Closing deletes all information that is set by
ciped on the device.

Devices can be dynamically allocated and deallocated using a
@code{ioctl_alloc(2cipe)} call. The first device always remains
allocated as a hook for the @code{ioctl} calls.

@c --------------------------------------------------------------------------

@node Installation, Configuration, Introduction, Top
@chapter        Installing the CIPE software package

@cindex Obtaining the CIPE package
The CIPE software package is available via the WWW from @*
@url{http://sites.inka.de/~bigred/devel/cipe.html}. It is distributed in
a @code{tar.gz} file, currently about 138k in size. After unpacking the
distribution, run the @command{configure} script, possibly specifying
options there. Then run @command{make}.

@menu
* Prerequisites::       What you need before installing.
* Protocols and ciphers::  Important compile-time options to select.
* Advanced compiling::  Configuring the compile for different targets.
* Install::             Compiling and installing the software.
* Compilation errors::  If something goes wrong.
* Run::                 Running the software.
@end menu

@node Prerequisites, Protocols and ciphers, Installation, Installation
@section        Prerequisites

@cindex Kernel versions
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
@emph{should} work.

@cindex Compiling modules
Make sure you have the complete source tree of the running kernel
installed (usually
in @file{/usr/src/linux}). The version @emph{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.

@cindex Kernel IP forwarding option
The kernel needs "IP Forwarding/Gatewaying" enabled in the configuration
for 2.0 kernels. Make sure to enable IP forwarding with
@example
echo 1 > /proc/sys/net/ipv4/ip_forward
@end example
on system boot with 2.2 or later and recent 2.0 kernels. The @code{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 (@command{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.
@cindex OpenSSL

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.
@table @samp
@item --with-linux=dir
Path to the Linux source tree (e.g., @samp{/usr/src/linux}).
Using an include tree without complete source is no longer supported, as
newer Linux versions need the kernel's build infrastructure.
@file{Makefile} parameters are also used.
@item --with-obj=dir
Path to the Linux compile tree. When the Linux kernel has been
compiled in a separate object directory (possible since Linux 2.6),
this parameter has to be given in addition to @code{--with-linux}.
@item --with-ssl-includes=dir
Path to the OpenSSL includes, if the script can not find it.
@item --with-ssl-libs=dir
Path to the OpenSSL libraries, if the script can not find it.
@item --enable-protocol=n
Use encapsulation protocol @samp{n}. The supported values in CIPE 1.5
are 3 and 4. @xref{Protocols and ciphers}, for how to choose the right one.
The default is 3.
@item --enable-cryptoapi
Use the new cryptographic API of Linux 2.4.22 or later or 2.6.
@item --disable-debug
Disable debugging code in kernel module. Not really useful.
@item --disable-dyndev
Disable dynamic device allocation. Not really useful.
@item --enable-logfacility=x
Set syslog facility for @command{ciped} and @command{pkcipe}
(default and usually right is LOG_DAEMON).
@item --disable-asm
Disable use of assembler code. Not really useful.
@item --enable-name=n
Set a name suffix for the compilation directory.
@item --enable-bug-compatible
Use old, broken interpretation of keys. @xref{Keys in older CIPE}.
@item --disable-send-config
Do not send configuration information to the peer. This is normally
sent on startup to help diagnose mismatches, but it is sent unencrypted,
which may be unwanted.
@item --disable-pkcipe
Do not compile and install the PKCIPE tool.
@end table

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 @code{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 @command{pkcipe} is still tied to the particular
@command{ciped} in use, but this is going to be fixed).

@node Protocols and ciphers, Advanced compiling, Prerequisites, Installation
@section        Protocols and ciphers

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
@command{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. @xref{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.
@cindex Ethernet
@cindex Bridging
The disadvantage is that the packets get larger than with protocol 3. It
may be necessary to set the MAC address using the @option{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 @code{cipc} and @code{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 @code{blowfish-internal} which gives the old builtin
Blowfish algorithm. Note that this version is not compatible with the
kernel Blowfish module, because @code{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.

@node  Advanced compiling, Install, Protocols and ciphers, Installation
@section        Advanced compiling

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 @file{/usr/src/linux-2.0.36},
@file{/usr/src/linux-2.2.6}, and so on. Running @code{configure
--with-linux=/usr/src/linux-2.0.36} and after that @code{configure
--with-linux=/usr/src/linux-2.2.6} leaves two directories
@code{2.0.36-i386-cb} and @code{2.2.6-i386-cb}. You can run @command{make}
@emph{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:
@example
./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
@end example

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. @xref{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.

@node Install, Compilation errors, Advanced compiling, Installation
@section        Installation

A simple @command{make} command compiles everything. Compiler warnings
should not occur. Do @command{make install} as
@emph{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. @xref{Program Names}. The Makefiles accept the semi-standard
options @code{BINDIR, MODDIR, INFODIR} to specify where the stuff gets
installed.

If PKCIPE was compiled, @command{make install} also installs the
@command{pkcipe} program and a helper @command{rsa-keygen}, sets up the
necessary directories and generates a host key if none is already there.
@xref{PKCIPE}.

@cindex @file{/etc/cipe} directory
You need to create a directory @file{/etc/cipe} which contains at
least two files, @file{options} and @file{ip-up}. You can copy the
files from the @file{samples} directory in the distribution here, and
edit them to suit your needs. @xref{Configuration}.

@node  Compilation errors, Run, Install, Installation
@section Compilation errors

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
@cindex SO_BINDTODEVICE
(@code{SO_BINDTODEVICE}), and detecting this version dependency via the
version number is not foolproof. Apparently, since 2.0.32, this problem
is resolved. If @code{output.c} doesn't compile under 2.0.*, change the
line
@example
#ifdef SO_BINDTODEVICE
@end example
to @code{#if 1} or @code{#if 0} as needed.

A similar problem exists in the 2.3.99 pre-releases, where the
@code{name} part of the @code{net_device} structure has changed. If an
error occurs during compilation of @file{device.c} under 2.3.99pre-n,
change the conditional definition of @code{HAVE_DEVNAME_ARRAY} in
@file{cipe.h} to @code{#if 1} or @code{#if 0} as needed.
@cindex net_device structure
Since the 2.4.0 test releases this problem is resolved.

@node Run,  , Compilation errors, Installation
@section        Running CIPE