\input texinfo   @c -*-texinfo-*-@c %**start of header@setfilename cipe.info@settitle CIPE Manual@direntry* cipe: (cipe). Crypto IP Encapsulation@end direntry@footnotestyle end@paragraphindent asis@iftex@parindent 0pt@end iftex@c %**end of header@c@c If the file options.t is missing, do the following:@c cd cipe; perl genoptions.pl options.in@c --------------------------------------------------------------------------@titlepage@title CIPE@subtitle An IP encryption package@subtitle Version 1.6@subtitle August 2004@author Olaf Titz@page@vskip 0pt plus 1filll    Copyright @copyright{} 1996--2004 Olaf Titz. All rights reserved.    This program including its documentation is free software; you can    redistribute it and/or modify it under the terms of the GNU General    Public License as published by the Free Software Foundation; either    version 2 of the License, or (at your option) any later version.    This program is distributed in the hope that it will be useful, but    WITHOUT ANY WARRANTY; without even the implied warranty of    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU    General Public License for more details.    You should have received a copy of the GNU General Public License    along with this program; if not, write to the Free Software    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.    The author can be contacted through the electronic mail address    @email{Olaf.Titz@@inka.de}.@c we can't macroize this copyright notice, which appears verbatim a few@c lines down again, because texinfo's macro expansion does not work inside@c @titlepage. Grrr.@end titlepage@ifnottex@node    Top, Introduction, (dir), (dir)@top CIPECIPE (the name is shortened from @emph{Crypto IP Encapsulation}) is apackage for an encrypting IP tunnel device. This can be used to buildencrypting routers for VPN (Virtual Private Networks) and similarapplications.@format    Copyright @copyright{} 1996--2004 Olaf Titz. All rights reserved.    This program including its documentation is free software; you can    redistribute it and/or modify it under the terms of the GNU General    Public License as published by the Free Software Foundation; either    version 2 of the License, or (at your option) any later version.    This program is distributed in the hope that it will be useful, but    WITHOUT ANY WARRANTY; without even the implied warranty of    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU    General Public License for more details.    You should have received a copy of the GNU General Public License    along with this program; if not, write to the Free Software    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.    The author can be contacted through the electronic mail address    @email{Olaf.Titz@@inka.de}.@end format@menu* Introduction::        About routing, VPNs and encryption.* Installation::        Installing the CIPE software package.* Configuration::       Configuration.* PKCIPE::              The PKCIPE public key tool.* Examples::            Examples of CIPE configurations.* Protocol descriptions::  How the protocols work internally.* Misc::                Odds and ends.* Concept Index::       Index. --- The Detailed Node Listing ---Introduction* Network layers::      Where encryption takes place.* Routing::             About IP routing and VPNs.* How CIPE works::      The encapsulation method employed here.* Components::          Which pieces of software CIPE consists of.* Internals::           A look under the hood of CIPE.Installing the CIPE software package* 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.Running CIPE* Program Names::       How the components of CIPE are named.* insmod::              Loading the kernel module.* ciped::               Running the daemon.Configuration of the CIPE software* Specifying options::  How CIPE gets its parameters.* Parameter list::      All valid and needed parameters.* Keys in older CIPE::  An incompatibility between Version 1.4 and earlier.* SOCKS::               Routing with CIPE over a SOCKS5 relayer.* Dynamic carrier::     How to deal with dynamic IP address assignment.* Error handling::      How ciped deals with errors.The PKCIPE tool* How it works::        Short overview on PKCIPE.* Public Keys::         What public keys are and how to use them.* pkcipe invocation::   Running the pkcipe program.Usage examples* Tips::                General useful tips on CIPE configuration.* Example 1::           The classic VPN setups.* Example 2::           A PKCIPE setup.* Connection modes::    Overview on different carrier network situations.Protocol descriptions* The CIPE Protocol::   Encrypted IP encapsulation used by CIPE.* The PKCIPE Protocol::  Public-key based setup and key exchange.@end menu@code{$Id: cipe.texinfo,v 1.37 2004/08/03 08:21:04 olaf81825 Exp $}@end ifnottex@c --------------------------------------------------------------------------@node Introduction, Installation, Top, Top@chapter        Introduction@menu* Network layers::      Where encryption takes place.* Routing::             About IP routing and VPNs.* How CIPE works::      The encapsulation method employed here.* Components::          Which pieces of software CIPE consists of.* Internals::           A look under the hood of CIPE.@end menu@node Network layers, Routing, Introduction, Introduction@section        Network layers and encryption@cindex Network layersThere are several different places where encryption can be built intoan existing network infrastructure, corresponding to the differentprotocol layers:@enumerate@itemOn the @dfn{network level}: Packets travelling between hosts on thenetwork are encrypted. The encryption engine is placed near the driverwhich sends and receives packets. An implementation is found in CIPE.@itemOn the @dfn{socket level}: A logical connection between programsrunning on different hosts (TCP connection; transport or session layerin OSI) is encrypted. The encryption engine intercepts or proxiesconnections. SSH and SSL work this way.@cindex SSH@cindex SSL@itemOn the @dfn{application level}: Applications contain their ownencryption engine and encrypt data themselves. The best known exampleis PGP for encrypting mail.@cindex PGP@end enumerateLow-level encryption as implemented with CIPE has the advantage thatit can be made to work transparently, without any change toapplication software. In the case of encrypting IP packets, it can bebuilt into IP routers which usually act as "black boxes" that onlyroute traffic between hosts, the hosts themselves don't see at all howthe routing works. So an @dfn{encrypting router} looks exactly like anon-encrypting one, without any difference seen by other hosts andapplications. It can thus be used in places where software changes athigher levels are not feasible.Low-level encryption has the disadvantage that it does not guard againstintruders on a higher level, e.g.@: Trojaned applications, bug exploitsin system software or rogue administrators "sniffing" on terminaldevices.@node Routing, How CIPE works, Network layers, Introduction@section        IP routing and Virtual Private Networks@cindex VPNA @dfn{virtual private network} (VPN for short) is a network@footnote{As CIPE is an IP routing application, this manual talks onlyabout IP-based networks. Even more precisely, this all is only aboutIPv4.} belonging to one organization, using its own address range, butoverlayed on existing network infrastructure.@cindex IP-in-IP tunneling@cindex carrier network@dfn{IP-in-IP tunneling} makes it possible to build IP-based VPNs ontop of other IP-based @dfn{carrier networks}, such as the Internet.@cindex Encrypted tunneling@dfn{Encrypted tunneling} guards against passive (sniffing) and active(faked message injection) attacks on the carrier network. The carriernetwork sees only encrypted data.@cindex traffic analysisDepending on the choice of protocol, all information the originalpackets carry can be encrypted. This includes not only the actual(payload) data but also the TCP/IP headers, leaving no trace as towhich addresses and services are actually used. @dfn{Traffic analysis}attacks, which attempt to gain useful information out of sniffing by"who contacts whom", are thus made unfeasible. An even moresophisticated technique to thwart traffic analysis employs theinjection of dummy packets into the network which carry no usefulinformation at all but are (at the carrier level) indistinguishablefrom real data packets.IP routing in a VPN situation consists of the routing of the carriernetwork, which in most situations is just a standard Internet setup,and routing of the overlayed VPN. This is easiest when the addressranges of carrier and VPN do not overlap in any way. It is common forVPNs to use the 10.0.0.0/8 and 192.168.0.0/16 address ranges, whichare not part of the Internet and thus do never conflict with actualInternet routing: any address in this range must be local to theorganization using it. @xref{Example 1}, for a typical example.@cindex IPSECThe IPSEC standards define a set of protocols which can be used (amongother things) to build encrypted VPNs. However, IPSEC is a ratherheavyweight and complicated protocol set with a lot of options,implementations of the full protocol set are still rarely used andsome issues (such as key management) are still not fully resolved.CIPE uses a simpler approach, in which many things which can beparameterized (such as the choice of the actual encryption algorithmused) are an install-time fixed choice. This limits flexibility butallows for a simple (and therefore efficient, easy to debug...)implementation.@node How CIPE works, Components, Routing, Introduction@section        How CIPE worksCIPE encapsulates encrypted IP datagrams in UDP datagrams and sendsthem via the normal UDP mechanism.@cindex UDPThis is different from standard IPIP encapsulation. UDP was chosen@cindex IPIPbecause this way many different endpoints can easily be distinguishedby port numbers; because an IP protocol number would warrant a formalregistration; and because handling of UDP datagrams is easier thanusing a separate IP protocol number, especially in firewalled setups.Specifically, UDP can be handled by user-level applications such as aSOCKS5 relayer. @xref{SOCKS}.A CIPE @dfn{link} always connects exactly two endpoints. In many ways,@cindex CIPE linkthe link works like a PPP dial-up link. At present, each link has itsown secret 128-bit key which has to be known by both ends (and nobody@cindex link keyelse). This @dfn{link key} (called @dfn{static key} in the protocoldescription) is used to negotiate a frequently changed @dfn{dynamickey}, which encrypts the actual data.Since CIPE 1.5 it is also possible to negotiate the keysvia a @dfn{public key} mechanism, similar to the SSH package. Thisremoves the need for shared secret keys. @xref{PKCIPE}.@node Components, Internals, How CIPE works, Introduction@section        CIPEs software componentsThe CIPE package consists of a kernel module and a driver program.The kernel module does the IP packet handling: sending and receivingpackets, encapsulation including encryption. It implements a@cindex network device@dfn{network device} which is mostly handled like any other networkdevice. Configuration and the whole key exchange process is done bythe user level program @command{ciped}. @xref{Program Names}.@cindex @command{ciped}@cindex @command{pppd}@command{ciped} looks and behaves rather similar to @command{pppd}. Inparticular, opening and closing a CIPE device is tied to starting andending a @command{ciped} process (one per device), the specification ofoptions to the daemon mimics @command{pppd}'s setup and @command{ciped}invokes scripts on opening and closing a device.@cindex @command{pkcipe}, programThe @command{pkcipe} program is a separate add-on to the @command{ciped}driver which manages keys and other parameters.@page@node Internals,  , Components, Introduction@section        Notes on internals