SOCKS5 protocol.@c --------------------------------------------------------------------------@page@node PKCIPE, Examples, Configuration, Top@chapter        The PKCIPE toolThe @command{pkcipe} program, included in the CIPE package since version1.5, eases configuration and running of CIPE links. With@command{pkcipe} it is not necessary to use long lived static keys. Apublic key based scheme (using Diffie-Hellman key exchange and RSAsignatures) is used instead. @command{pkcipe} also automatically handlesdynamic carrier addresses.@menu* How it works::        Short overview on PKCIPE.* Public Keys::         What public keys are and how to use them.* pkcipe invocation::   Running the pkcipe program.@end menu@node  How it works, Public Keys, PKCIPE, PKCIPE@section        How it worksTo start a CIPE link, two instances of the @command{pkcipe} program, oneon each side of the link, are connected via TCP. They do a key exchange,yielding a new random key which is used as the @code{key} parameter forCIPE. They tell each other their @emph{identity} and send a@emph{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 theseadditional parameters are only the carrier IP addresses, which the@command{pkcipe} program obtains from the system at run time.After all parameters are set up, @command{pkcipe} writes an options filecontaining the new key and other parameters and starts @command{ciped}with this options file. Then @command{pkcipe} exits and the TCPconnection is closed.@node  Public Keys, pkcipe invocation, How it works, PKCIPE@section        Public KeysWith PKCIPE, each host has a public/private key pair. The private(secret) key is kept in the file @file{/etc/cipe/identity.priv} andnever copied anywhere else. The @file{/etc/cipe/pk} directory containsthe public keys of all peers. For all key files, the same restrictionson file and directory permissions apply as for options files.@xref{Specifying options}.Each host has an @dfn{identity} (usually its host name, but really it isan arbitrary string) by which it is known to its peers. The public keyfiles are named according to these identities. Each public key filesalso contains options (as in a CIPE options file) for this peer. Thepeer which has the right private key is allowed toconnect.@footnote{Note the similarity to the @command{ssh} program.}@cindex identityA public key pair may be generated with the @command{rsa-keygen} script.This generates two files, one with the public and one with the privatekey, the latter having the file name ending @code{.priv}. The Makefileautomatically does this on installation time if necessary.The secret key may be encrypted with a passphrase. In this case@command{pkcipe} asks for the passphrase every time it starts. This maybe useful e.g. for mobile systems which connect manually to a centralhost.The @option{-p} argument to @command{rsa-keygen} allows to set apassphrase on the newly generated secret key. For existing secret keys,the passphrase can be changed with the command@exampleopenssl rsa -des3 -out newfile -in oldfile@end exampleand deleted with the command@exampleopenssl rsa -out newfile -in oldfile@end examplewhere @file{oldfile} is the existing secret key file; the result will bestored in @file{newfile}.@node  pkcipe invocation,  , Public Keys, PKCIPE@section        Running the @command{pkcipe} programThe @command{pkcipe} program must be run as @emph{root}. (@strong{Do not}make it setuid.) @command{pkcipe} takes the following command lineparameters:@table @option@item -c @var{host}:@var{port}Run in client mode, connect to the given address.@item -t @var{timeout}Set the timeout for each network read (default is 60 seconds).@item -r @var{host}Give the host where the actual CIPE UDP packets are routed to. Thisoption is necessary when the TCP connection is done via a SOCKS or otherproxy (e.g. SSH redirection).@item -k @var{keyfile}Specify the private key file. Default is @file{/etc/cipe/identity.priv}.@item -p @var{proto}Set the PKCIPE protocol level to use. Currently there exists only theprotocol level 2.@item -D @var{debug}Debug logging flags.@item -ELog to standard error instead of syslog. For debugging purposes.@item @var{identity}(non-option parameter)Specify the identity to use. Default is the host name.@end table@xref{Example 2}, for how @code{pkcipe} is run in server mode.The location of the @code{ciped} command to be run by PKCIPE, as well asthe auxiliary files read from and written to, is currently hardcoded atcompile time.@c --------------------------------------------------------------------------@node Examples, Protocol descriptions, PKCIPE, Top@chapter        Usage examplesHere are some tips, examples and additional information on how to designa network structure with CIPE and configure the devices accordingly.@menu* 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.@end menu@node Tips, Example 1, Examples, Examples@section        General tips@itemize @bullet@itemThe IP address of a CIPE device and it's UDP carrier @emph{must} bedifferent. Chose a @dfn{transit network} (e.g.@: 192.168 address) forthe CIPE devices if these don't fit into existing structures.@cindex transit network@itemThe route to the UDP carrier ("peer" address) @emph{can not} go throughthe CIPE device. If both are on the same route (e.g.@: both are on thesame network, IP-address-wise), add a host route to the "peer" addressthrough the right device or gateway.@itemIn Linux 2.0, the @code{route add -host $5 dev $1} in @file{ip-up} is required.Without it the link won't work. This also means the @file{ip-up} script itselfis mandatory.@item@cindex Setting routesRoutes through a CIPE device should be set only in the @file{ip-up}script. Use case selections on @code{$1} or @code{$5} if you haveseveral CIPE links. Use @code{route add ... gw $5}, not @code{route add... dev $1}. Remember that Linux deletes any routes through a devicewhen this device goes down.@item@cindex reject routeIf you have a default route, the addresses reachable via the CIPE linkare routed via the default when the link is down. This can defeat thepurpose of an encrypted link. To guard against this, set a reject routeto the affected addresses with higher metric in the system startup script.@item@cindex Proxy-ARPSometimes it is necessary or advisable to announce the address of thepeer via proxy-ARP to avoid more complicated routing setups. The example@file{ip-up} shows how this can be done. In Linux 2.4 a sysctl can beused to use proxy-ARP for the whole network "behind" the peer.@item@cindex gatedOn a system running @command{gated}, gated is the only thing responsiblefor setting any routes and the routes through the CIPE device routesbelong in @file{gated.conf} as static routes, or are to be set via a routingprotocol. To gated, a CIPE link looks and behaves exactly like a dial-uplink. It is strongly recommended to put @command{gdc interface} in@file{ip-up} as well as @file{ip-down} to tell gated about statuschanges.@itemThe configuration of both ends of a link is symmetric. One side's@code{ipaddr} is the other's @code{ptpaddr}, and one side's @code{me}is the other's @code{peer}. Since CIPE 0.5, @code{peer} is picked updynamically and the real peer may be different from that set in theconfig file (but this config item must still be present, it shouldspecify the other end's reverse as a reasonable default).@item@cindex Designing network structureWhen designing a network structure, draw the CIPE links as if theywere SLIP/PPP links. Build the routing with these links enabled. Thenlook at the picture as if the CIPE links weren't there, so you can seethe routing needed for the UDP adresses.@item@cindex firewall rulesFirewall rules which contain a device are independent of the device'sexistence. This means that they can be established before the module isloaded and @command{ciped} run, and that an explicit @code{device} optionshould be used if the device name is used in firewall rules.@itemWith PKCIPE, the location and content of the PID files from the@code{ip-up} sample scripts is mandatory as they are used as lock files.Omitting these can cause confusion when several instances of@code{pkcipe} run at the same time.@end itemize@page@node Example 1, Example 2, Tips, Examples@section        Example 1@cindex Classic VPN setup@cindex Unofficial subnets@cindex Branch office --- head office@cindex Mobile hostThis basic example shows how to connect hosts and networks withunofficial network numbers through the Internet. Uses for this areclassic VPN setups:@enumerate@itemConnecting two unofficial subnets through an Internet link@itemConnecting a branch office to the head office through a one-address dialup@itemConnecting a mobile host with varying access points@end enumerate@format@group@t{               Internet               Internet                  ^                      ^                  |                      |                           hostz                  |ppp0                  |eth1                  200.0.24.3                  |200.0.24.65           |200.0.24.1                     |     +---------routera                routerb         eth0 200.0.24.1    |     |    eth0        \_ _ _ _ _ _ _ _/      \---------------+-------+---+     |  10.0.1.1   cipcb0         cipcb0      eth0           |       |   hosta           10.0.1.1      10.0.2.1     10.0.2.1       |       | 10.0.1.88                                                hostx   hosty                                                       10.0.2.5  10.0.2.6}@end group@end formatAs can be seen from the picture, a CIPE device and another networkdevice can have the same IP address if there are no overlapping routesbetween them.The CIPE devices are configured like this:@multitable @columnfractions .25 .35 .4@item                   @tab routera            @tab routerb@item			@tab cipcb0             @tab cipcb0@item ipaddr            @tab 10.0.1.1           @tab 10.0.2.1@item ptpaddr		@tab 10.0.2.1		@tab 10.0.1.1@item me		@tab 200.0.24.65:9999	@tab 200.0.24.1:9999@item peer		@tab 200.0.24.1:9999	@tab 200.0.24.65:9999@item static routes	@tab 10.0.1.0/24 dev eth0  @tab 10.0.2.0/24 dev eth0@item			@tab default dev ppp0      @tab 200.0.24.0/26 dev eth0@item			@tab                       @tab default dev eth1@item routes in ip-up   @tab 10.0.2.0/24 gw 10.0.2.1                                                @tab 10.0.1.0/24 gw 10.0.1.1@end multitableFor case 3, assume @code{routera} to be the mobile host, think of@code{eth0} missing and @code{ppp0} having a dynamic address. The@code{routerb} config remains unchanged. For @code{routera} simply omitthe @code{eth0} stuff, add the @code{dynip} flag for ciped. @code{routerb}picks up its peer dynamically. This even works when @code{routerb} isplugged behind a firewall and has to rely on a SOCKS5 server for outsideaccess. (Yes, this can be used to punch holes into firewalls. No, it'snot my intention to do anything about it. Local policy issues have to bedealt with locally.)@cindex Hole in firewall@page@node Example 2, Connection modes, Example 1, Examples@section        Example 2This example shows how to set up PKCIPE. The overall setup is symmetric,there are no designated servers and clients. However, one end has toaccept incoming TCP connections on a chosen port (@dfn{server mode}) andthe other one has to connect to it (@dfn{client mode}).@cindex PKCIPE, modes@cindex @command{pkcipe}, programThe basic configuration of a link is like this: assuming @code{routera}has the address (of the CIPE device) @code{10.0.1.1} and @code{routerb}has the address @code{10.0.2.1} like in Example 1. Each@file{/etc/cipe/pk/@var{host}} file contains the public key of that hosttogether with options applying to that host:On @code{routera}, @file{/etc/cipe/pk/routerb} looks like this:@example-----BEGIN PUBLIC KEY-----(here is the public key of routerb)-----END PUBLIC KEY-----ipaddr  10.0.1.1ptpaddr 10.0.2.1@end exampleand on @code{routerb}, @file{/etc/cipe/pk/routera} looks like this:@example-----BEGIN PUBLIC KEY-----(here is the public key of routera)-----END PUBLIC KEY-----ipaddr  10.0.2.1ptpaddr 10.0.1.1