--- /dev/null
+.\" -*-nroff-*-
+.\".
+.\" Overview of the whole system
+.\"
+.\" (c) 2008 Straylight/Edgeware
+.\"
+.
+.\"----- Licensing notice ---------------------------------------------------
+.\"
+.\" This file is part of Trivial IP Encryption (TrIPE).
+.\"
+.\" TrIPE 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.
+.\"
+.\" TrIPE 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 TrIPE; if not, write to the Free Software Foundation,
+.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+.
+.so common/defs.man \" @@@PRE@@@
+.
+.\"--------------------------------------------------------------------------
+.TH tripe 7 "28 March 2008" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
+.
+.\"--------------------------------------------------------------------------
+.SH "NAME"
+tripe \- overview of the TrIPE suite
+.
+.\"--------------------------------------------------------------------------
+.SH "NOTES TO THE AUTHOR"
+.
+.SS "What do we actually need to cover?"
+.hP \*o
+Key management.
+.hP \*o
+Setting up peer connections.
+.hP \*o
+Choosing algorithm suites?
+.
+.\"--------------------------------------------------------------------------
+.SH "DESCRIPTION"
+.
+TrIPE is a Virtual Private Network (VPN) implementation. It uses
+cryptography to protect network packets from being read or tampered with
+as they travel over hostile networks (e.g., the Internet). The effect
+of this is that you can connect together geographically-separated
+networks of machines and use network protocols which would be unsafe to
+use over public networks.
+.PP
+The name `TrIPE' stands for `Trivial IP Encryption'. Unfortunately,
+while the TrIPE network protocol is still fairly simple (and this is one
+of TrIPE's conspicuous advantages over other VPN systems), the software
+suite which implements it is not. Over time, the original single server
+has acquired various strangely-shaped extensions and add-on-services in
+order to solve various problems, and even given fairly detailed
+descriptions of all of the individual pieces it can be difficult to see
+how to fit them together in order to actually do anything useful.
+.PP
+This manual page provides an overview of the TrIPE software suite. The
+individual components are described in their respective reference manual
+pages. This page exists to provide a picture for how the various pieces
+fit together and how to use them effectively. It presents a number of
+worked examples, but it's not intended to be used as a `cookbook'; TrIPE
+is a complicated system, and the author believes that you're less likely
+to become confused by it if you understand how its various bits fit
+together rather than following canned recipes which don't quite match
+your particular circumstances.
+.PP
+The TrIPE software runs entirely in user mode. It does not require any
+kernel modifications.
+.
+.SS "Who this documentation is for"
+This document is intended for network administrators who are comfortable
+with the fundamentals of IP networking and routing. It assumes
+knowledge of how to configure network interfaces and routing. It
+doesn't assume a strong background in cryptography, though a good
+grounding won't hurt; the author recommends the
+.I "Handbook of Applied Cryptography"
+by Alfred Menezes, Paul van Oorschott and Scott Vanstone, which is
+published by CRC Press, or available online.
+.
+.\"--------------------------------------------------------------------------
+.SH "HOW TrIPE WORKS"
+.
+The TrIPE protocol is a simple packet-based protocol transmitted over
+UDP (RFC768). TrIPE has been allocated port 4070 by the IANA, but you
+can use other ports if you like.
+.
+.SS "Network structure and addressing"
+In TrIPE's model, a virtual network consists of a number of physical
+networks joined together. Each physical network needs a
+.I representative
+(at least one, though more may be useful) which actually speaks the
+TrIPE protocol. The representative establishes secure point-to-point
+links with representatives of other physical networks over the Internet
+(or at least over some larger physical network). These links are
+strictly pairwise: they carry packets back and forth between precisely
+two endpoints. The two endpoints of such a link are
+.IR peers :
+the link is, as far as TrIPE is concerned, utterly symmetrical.
+.PP
+Most of the hosts in the physical networks only need `internal'
+addresses, i.e., their addresses need only be unique
+.I within
+the virtual network \(en and, if NAT is in use, even that needn't hold,
+though NAT is at best a necessary evil and not to be used lightly.
+Obviously, in order to be useful, the representatives need
+.I external
+addresses, so that they can send each other IP packets over the wider
+Internet.
+.TP
+.B Example
+.RS
+Alice is the administrator of
+.BR alice.net .
+Internally, she has allocated IP addresses from the private address
+range 10.0.1.0/24. She has an externally facing server
+.BR anubis.alice.net ,
+which has an internal address of 10.0.1.1 and an external address of
+192.0.2.1.
+.PP
+Bob is an administrator at
+.BR bob.com .
+Internally, he's allocated IP addresses from the private address range
+10.0.2.0/24. He has an externally facing server
+.BR bast.bob.com ,
+which has an internal address of 10.0.2.1 and an external address of
+192.0.2.129.
+.PP
+(At this point, the author would like to apologize for the unrealistic
+nature of the external IP addresses in this example. Unfortunately,
+allocating the addresses from the private-use space, e.g., 10.0.0.0/8,
+would be confusing, since these are normally
+.I internal
+addresses only; the network 192.0.2.0/24 is allocated by IANA for use in
+examples such as this, but is rather too small to divide into realistic
+subnets, as I've tried to do here.)
+.PP
+It would be reasonable for Alice and Bob to choose
+.B anubis
+and
+.B bast
+as their respective TrIPE representatives. If, say,
+.B amaterasu.alice.net
+was an internal host with address 10.0.1.42, it would not be a suitable
+representative, since this is an internal address and (presumably) the
+routers between
+.B alice.net
+and
+.B bob.com
+don't know how to send packets there.
+.PP
+We'll return to Alice and Bob in other examples later.
+.RE
+.
+.SS "Tunnels and routing"
+A
+.I tunnel
+is a network interface, usually configured as a point-to-point link,
+except that rather than sending network packets through some physical
+interface, it makes them available to a user-mode process through a
+character device; similarly, packets written to the character device
+appear to the kernel to have originated in the tunnel interface.
+.PP
+A cheesy hack for implementing a `tunnel' interface like this is to
+open a
+.BR pty (7)
+and configure the slave side of the pty to use the SLIP line discipline.
+A user-mode process can now use the master side of the pty to read and
+write SLIP-encoded network packets. Linux's TUN/TAP and BSD's
+.BR tun (4)
+interfaces provide a more convenient and efficient means of achieving
+the same goal. TrIPE prefers to use these more refined tunnel
+interfaces, but is willing to use the cheesy SLIP hack if necessary.
+.PP
+For each peer with which it is exchanging secured packets, a TrIPE
+representative creates a tunnel interface. Packets being sent through
+the interface are encrypted, authenticated, and retransmitted to the
+peer's UDP port; packets arriving from a peer are verified, decrypted,
+and inserted into the tunnel.
+.PP
+For this to work, the representative needs to have at least two routes
+established:
+.hP \*o
+a route to its peer's external address, so that it can send it encrypted
+packets encapsulated in UDP;
+.hP \*o
+a route to the peer's
+.I internal
+address, directed over the tunnel interface; and possibly
+.hP \*o
+if the peer is acting as a representative for a network of other hosts,
+a route to that network also over the tunnel.
+.PP
+.TP
+.B Example
+.RS
+Continuing the earlier example,
+.B anubis.alice.net
+needs to have one route to
+.BR bast.bob.com 's
+external address 192.0.2.129. We'll assume that
+.B anubis
+has a direct connection to the Internet, and that therefore no special
+action needs to be taken here. In order to tunnel traffic to
+.BR bast.bob.com ,
+.B anubis
+has its
+.B tripe-bob
+interface configured as follows.
+.IP
+.B "ifconfig tripe-bob 10.0.1.1 pointopoint 10.0.2.1 mtu 1435"
+.PP
+(Network configuration commands are system-specific. This manual page
+assumes a Linux system because that's the author's primary operating
+system; consult your system's manual to find out what the equivalent
+commands are. Network interface names are also system-specific; Linux
+lets us rename network interfaces to make their names meaningful, and
+these examples reflect this. Finally, don't worry about the MTU
+setting. Usually, TrIPE's ancillary services will work out the correct
+MTU automatically.)
+.PP
+Further, in order to communicate with the larger
+.B bob.com
+internal network,
+.B anubis
+has set up an additional route
+.IP
+.B "route add -net 10.0.2.0/24 gw 10.0.2.1 dev tripe-bob metric 2"
+.PP
+Other hosts in Alice's network might need to be told
+.IP
+.B "route add -net 10.0.2.0/24 gw 10.0.1.1 metric 3"
+.PP
+(spot the difference between this and
+.BR anubis 's
+route), though in many cases it's useful to choose the TrIPE
+representative as a router anyway.
+.RE
+.
+.SS "Connection styles"
+There are essentially two kinds of connections possible between TrIPE
+peers.b
+.hP 1.
+.B "Always up."
+Each of the two peers expects to find the other up and running all of
+the time. This works well, and is easy to set up and maintain, if the
+two peers have stable external IP addresses, have network connectivity,
+and are almost always turned on. If one is frequently down, or the
+network between them is not always available (e.g., it's a dial-up link)
+then the servers will be wasting their time trying to contact each
+other: maybe one of the other options will be better. Either or both of
+the peers may be providing VPN services for a network of other machines.
+.hP 2.
+.B "Dynamically established."
+One of the peers explicitly establishes a connection with the other when
+it wants to communicate. The
+.I active
+peer \(en the one making the connection \(en doesn't need a stable
+static IP address. The
+.I passive
+peer \(en the one connected to \(en does need a stable external IP
+address, to have reasonable network connectivity, and to be up most of
+the time. Dynamic connections are more complicated to configure and
+support, but much more flexible.
+.PP
+(In principle, it might be possible for two hosts, both behind NAT
+routers, to make use of, say, STUN to establish a connection; but this
+doesn't seem sufficiently useful.)
+.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+.\"--------------------------------------------------------------------------
+.SH "CRYPTOGRAPHY AND KEY MANAGEMENT"
+.
+.SS "A very quick introduction to modern cryptography"
+This isn't really the place for a full survey of modern cryptography,
+but I'll try to provide a little background.
+.PP
+Cryptography is the use of mathematics in order to achieve security
+objectives. There are two main objectives of modern cryptography.
+.TP
+.I Secrecy
+Preventing an adversary from learning anything about a message (except
+its length), even though the adversary is responsible for delivering
+it. The original message is called the
+.IR plaintext ;
+an
+.I encryption
+process converts the plaintext into a
+.IR ciphertext ;
+a recipient
+.I decrypts
+the ciphertext in order to recover the original plaintext.
+.TP
+.IR Integrity " or " authenticity
+Preventing an adversary from creating
+.IR forgeries :
+i.e., messages which appear to have been sent by a particular person or
+group of people. The sender
+.I tags
+or
+.I signs
+a message (tags are symmetric, signatures asymmetric, as explained
+below); the recipient
+.I verifies
+the tag or signature.
+.PP
+In order to be able to do this, the recipient (in the case of secrecy)
+or the sender (for integrity) need to know a
+.I key
+unknown to the adversary. We can now distinguish two important cases.
+.TP
+.IR "Symmetric" " or " "secret-key cryptography"
+Both participants know the same key (or at least they can easily compute
+each others' keys). Somehow, the two participants must agree on the
+same key without letting it fall into the hands of the adversary.
+Before 1976, all publicly-known cryptographic schemes were symmetric.
+.TP
+.IR "Asymmetric" " or " "public-key cryptography"
+In the case of secrecy, the sender knows only a
+.I public key
+which is sufficient to encrypt a message so that it can only be
+decrypted by the holder of the corresponding
+.IR private key ,
+but insufficient to decrypt messages sent by others using the same
+public key. In the case of integrity, the sender holds a secret key
+with which he can make signatures; the public key allows others to
+verify existing signatures but not to make new signatures. The holder
+of the private key needs to convey an
+.I authentic
+copy of the corresponding public key to other participants, but the
+public key doesn't need to be kept secret. Asymmetric cryptography was
+first described to the public in 1976 by Whitfield Diffie and Martin
+Hellman, though it had been known to governments (e.g., the British
+CESG) for a number of years.
+.PP
+The advantage of symmetric cryptography is efficiency: symmetric
+techniques for secrecy and integrity require smaller keys, less memory,
+and much less time, than asymmetric techniques. The disadvantage is
+that key distribution is much harder: symmetric keys must be known to
+all participants, but kept secret from adversaries; public keys need not
+be kept secret. It's therefore common to use asymmetric methods to
+distribute short symmetric keys, and use the latter for ensuring the
+secrecy and integrity of longer messages.
+.PP
+Asymmetric cryptography makes key distribution easier, but doesn't
+eliminate the problem entirely. In particular, the problem of ensuring
+that the participants have a correct copy of each others' keys remains.
+There are a number of (partial) solutions to this problem, but they all
+use the same basic idea: if (say) Alice knows Bob's public key, and Bob
+knows Carol's public key, then Bob can send Alice a message saying
+`Carol's public key is
+.IR mumble ':
+now, if Alice is willing to take Bob's word for this, then she now knows
+Carol's key.
+.PP
+A signed message binding together a public key and some facts about the
+corresponding private key is often called a
+.IR certificate ,
+and a
+.I certificate authority
+(or CA) is an organization which issues certificates. Internet
+certificate authorities are organizations whose public keys are well
+known (e.g., included with web browsers) and which are generally
+believed to be careful to issue only correct certificates. However, the
+economics of this arrangement are strange: CAs are usually paid by the
+holders of private keys, so they get their money whether or not the
+certificates are actually true.
+.PP
+The famous
+.BR pgp (1)
+program and its successors (e.g.,
+.BR gpg (1))
+use a more sophisticated approach called the
+.IR "web of trust" ,
+which allows Alice to collect certificates from a number of different
+signers, compare them, and decide based on how much she trusts each of
+them how likely their claims are. This can be complicated to manage.
+.
+.SS "Cryptography in TrIPE"
+The long-term keys in TrIPE are all asymmetric. There are no
+`pre-shared keys'. If two peers are to establish a link between them,
+it is essential that each has a correct copy of the other's public key.
+In principle, this ought to be easier than arranging for each to know a
+common secret; pre-shared keys are easier to deal with only if they're
+memorable, and memorable keys are not likely to be difficult to guess.
+.PP
+The TrIPE server, and its ancillary services, simply assume that you've
+already acquired genuine copies of other peers' public keys and put them
+in the right place; exactly how you go about this is up to you, and
+tools such as CAs or PGP can help. However, the TrIPE distribution
+contains a simple tool
+.BR tripe-keys (8)
+for dealing with public key distribution. This is described in more
+detail below.
+.PP
+The TrIPE suite's primary author is a cryptographer, and he enjoys
+having fine control over the cryptographic primitives involved.
+Fortunately it's not that difficult to
+
+
+
+
+
+
+
+
+.\"--------------------------------------------------------------------------
+.SH "SECURITY"
+.
+.SS "Host security"
+TrIPE runs entirely in user mode, unlike many IPsec implementations.
+The main server, which is written in C, mostly runs as an unprivileged
+user. However, a small part of the server runs with
+.B root
+privileges because it needs to be able to open new tunnel devices
+dynamically. Even this can be avoided, for example by using SLIP
+tunnels, allocated by a GNU
+.BR userv (1)
+service. If the server is compromised, an attacker can use it to inject
+arbitrary network packets, but little else.
+.PP
+The ancillary service
+.BR watch (8)
+needs root privileges in order to configure new network interfaces. It
+is written in Python, a safe interpreted language. In turn, this
+invokes an external program, again as
+.BR root ,
+to do the actual network interface configuration. This program is
+user-selectable, but the default program is a simple shell script; it
+does not process untrusted input.
+.
+.SS "Cryptographic security"
+The TrIPE protocol is not standards-based. However, it has been
+designed by an experienced cryptographer, and has a formal `security
+proof' showing that an attack against the protocol can be transformed
+into an attack against one of its primitive components. Other VPN
+protocols are too complicated to admit such proofs. The guarantees
+afforded by security proofs of this kind are
+.I contingent
+on the security of the primitive components rather than absolute, but
+even such a contingent proof is much better than no proof at all.
+.PP
+The software allows users a wide selection of primitive components, some
+standardized and some not; the author recommends the widely standardized
+and well-respected Rijndael (AES) for encryption and SHA256 for hashing
+and authentication.
+.
+.SS "Why TrIPE doesn't use X.509"
+The TrIPE protocol does not use X.509 certificates, as deployed in TLS and
+IPsec. X.509 certificates are hard to parse: software which processes
+them has a history of vulnerabilities. The certification model used by
+TLS, where the holder of a key pays a certification authority for his or
+her certificate, is economically backwards: the direct beneficiaries of
+the certificate are those who rely on it to establish the validity of
+the public key. The author does not understand why an external
+certificate authority is needed in order to construct a VPN anyway: if
+Alice has no idea who Bob is, she's unlikely to want to allow him access
+to her private network!
+.PP
+The main TrIPE software does not assume any particular certification
+model: rather, it considers the issue of establish authenticity of
+public keys to be out-of-scope. The supplied
+.BR tripe-keys (8)
+program implements a very simple key-distribution system which avoids
+the complexity inherent in X.509. Of course, because public key
+distribution is separated from the main system, nothing prevents
+swapping in a more sophisticated system where necessary.
+.
+.SS "Comparison with other systems"
+This section compares TrIPE with other VPN protocols.
+.TP
+.B IPsec
+.RS
+IPsec is an IETF standard. It defines two protocols for handling bulk
+data. The Authentication Header (AH) simply adds cryptographic
+authentication to an IP packet, including the header; this causes
+trouble with NAT firewalls. The Encapsulating Security Payload (ESP)
+provides both encryption and authenticity, and operates in one of two
+modes:
+.I transport
+mode simply processes the payload data, but not the header; the
+.I tunnel
+mode encapsulates an entire IP packet. Of these, AH and ESP transport
+mode need to be supported by all participating hosts. ESP tunnel mode
+only needs to be supported by a single representative (`security
+gateway') of each network, and provides header security which works
+properly with NAT. TrIPE works very similarly to ESP tunnel mode.
+The IPsec AH and ESP protocols work directly over IP, rather than using
+UDP as TrIPE does. This reduces the per-packet overhead, but means that
+implementations need to be highly privileged, either running as part of
+the kernel or at least with
+.B root
+privileges.
+.PP
+Key exchange in IPsec (IKE) is very complicated, with many options. The
+protocol can use a number of different certificate formats, or none at
+all. Partly this is due to the fact that IPsec has more ambitious goals
+than TrIPE: IPsec aims to allow `opportunistic' security between
+previously unrelated entities, whereas TrIPE assumes that all the
+participants in its virtual network are administrated in a coordinated
+fashion. This means that TrIPE's usefulness is comparatively limited;
+of course, it also means that TrIPE is much simpler.
+.RE
+.TP
+.B OpenVPN
+.RS
+In many respects, OpenVPN is very similar to TrIPE: it runs in userland,
+and operates over UDP. OpenVPN uses a variant of the TLS protocol for
+its key-exchange. TLS is very complex, and uses X.509 certificates
+which bring their own problems. (OpenVPN provides a
+.B tls-auth
+option to mitigate this, though it partially defeats the point of
+public key cryptography.)
+.PP
+OpenVPN can use TAP interfaces in order to simulate an Ethernet rather
+than a point-to-point link, which allows Ethernet bridging across the
+VPN. TrIPE could do this relatively easily (it's just a matter of
+configuring the tunnel interface differently) but it hasn't seemed
+useful yet.
+.RE
+.TP
+.B "SSH- and SSL-based VPNs"
+.RS
+OpenSSH can implement a simple VPN, by opening tunnel devices at each
+end and forwarding packets over the SSH connection. This causes
+problems: SSH is already running over TCP, and TCP provides congestion
+control and reliability. TCP over this tunnel will therefore have two
+layers of congestion control and reliability, and the two have a
+tendency to interfere. When there is little or no packet loss,
+everything will be fine; if the underlying connection becomes flaky, the
+VPN will suffer greatly.
+.PP
+SSL-based VPNs (simply forwarding packets over an SSL or TLS connection)
+have the same problem, and all of the problems associated with SSL's use
+of X.509 certificates.
+.RE
+.
+.SS "Firewall considerations"
+You should be able to write firewall rules for packets travelling over
+TrIPE's tunnel interfaces just as for any other interfaces.
+Unfortunately, it is hard to predict the name of the tunnel interface
+that TrIPE will allocate for any particular peer. There are two basic
+solutions to this problem.
+.hP \*o
+Some operating systems allow you to rename network interfaces. You can
+use this feature to assign the interface a more useful name, which may
+already be known to your firewall.
+.hP \*o
+You can dynamically modify the firewall rules once you know which
+interface has been assigned to the peer. This is probably more
+complicated.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+.
+.SS "Structure of the system"
+The TrIPE system consists of a number of components.
+.hP \*o
+The
+.BR tripe (8)
+daemon itself. The daemon runs continually in the background. At any
+given moment, the daemon knows of a number of
+.IR peers :
+other servers with which it is meant to interact. It accepts network
+packets from the kernel, encrypts them, and sends them to appropriate
+peers; it also receives encrypted packets from peers, decrypts them, and
+hands them to the kernel. It also provides an administration interface
+through which the daemon can be told about new peers, and old ones
+removed.
+.hP \*o
+A number of ancillary services which run alongside the daemon and
+provide additional functionality. The
+.BR connect (8)
+service accepts requests to attach new peers and makes the necessary
+arrangements. The
+.BR watch (8)
+service notices peers being added and removed; it configures network
+interfaces; when necessary it attempts to `wake up' remote peers to
+inform them of its presence; and it can time out old peers which aren't
+responding. This is useful in environments where peers appear and
+disappear dynamically.
+.hP \*o
+The
+.BR tripe-keys (8)
+utility. The TrIPE system uses asymmetric (`public-key') cryptography.
+Therefore it's necessary to ensure that the participants in the VPN have
+authentic copies of each others' public keys. This is nontrivial, but
+easier than the traditional key-distribution problem, which additionally
+involves keeping all of the keys secret. The
+.BR tripe-keys (8)
+program helps maintain a
+.I "certificate authority"
+(CA) which can distribute public keys in a secure way.
+.
+.SS "The basic model"
+As far as the TrIPE protocol goes, there is no distinction between
+clients and servers, or between initiators and responders. The protocol
+treats all participants equally; we call them peers. Each peer knows
+about a number of other peers. It establishes point-to-point
+communications separately with each peer it knows about.
+.PP
+Each peer refers to the other peers with whom it communicates by name.
+Theoretically, these names are only for the individual peer's (and its
+administrator's) convenience, and a single peer may be assigned
+completely different names by all of the other peers with which it
+communicates. In practise, this would be very confusing, and all peers
+use the same, or very similar, names for each other.
+.PP
+When a daemon is informed about a new peer \(en its name, and an IP
+address and port number \(en it creates a new network interface for the
+peer and attempts to initiate a key-exchange. If both ends have been
+informed of each other's presence, and they have each other's correct
+public keys, they will successfully negotiate symmetric keys and be able
+to transmit and receive network packets.
+.PP
+By this point, the daemon has indeed created a network interface, but no
+network traffic will actually be carried because the interface is not
+configured. The
+.BR tripe (8)
+daemon leaves the messy details of configuring interfaces to other
+programs. If the
+.BR watch (8)
+service is running, it will notice the new peer, look up its details in
+a database, and invoke a script, usually
+.BR tripe-ifup (8),
+to configure the interface correctly.
+.
+.SS "Addressing concepts"
+Virtual private networks make addressing complicated. This
+documentation isn't going to make that complexity go away, but it might
+shed some light on it. In particular, each peer involved needs at least
+two distinct addresses.
+.PP
+
+
+
+
+
+
+
+.PP
+The TrIPE VPN isn't magic. It runs over standard IP, so the machines
+you want to participate in the VPN need to be able to send each other IP
+packets.
+
+
+
+
+
+ In particular, each needs to have an address and port number
+\(en its
+.I "external address"
+(and port) \(en on which it can send and receive packets to/from the
+others.
+.PP
+Additionally, each needs to be able to send packets to the others
+.I through
+the VPN. The addresses which are routed over the VPN are
+.IR "internal addresses" .
+Clearly, the internal addresses need to be distinct from the external
+addresses if the machines involved are to be able
+
+
+.I "external addresses"
+.P
+TrIPE has the port number 4070 allocated to it by IANA, so it shouldn't
+interfere with anything else. But some firewalls may block TrIPE
+traffic, or you may just not want to advertise your use of TrIPE, so you
+can use any port you like.
+
+
+
+.
+.SS "Establishing connections"
+
+
+
+
+.PP
+.PP
+The server itself maintains no persistent configuration other than a
+simple database of public keys for its various peers.
+
+.\"--------------------------------------------------------------------------
+.SH "EXAMPLES"
+.
+This section contains a number of worked examples for configuring and
+running TrIPE.
+.PP
+We'll start with the case of Alice and Bob, who both administer
+networks
+.B alice.net
+and
+.B bob.com
+respectively, and want them to be able to communicate with each other
+securely over the wild Internet. Later we'll deal with Carol, who has a
+laptop and wants to be able to connect to the VPN from fleapit hotels
+all around the world.
+.
+.SS "Alice sets herself up as a certificate authority"
+Everyone participating in a TrIPE network needs to have a private key
+and an
+.I authentic
+copy of everyone else's public keys. If Bob's copy of Alice's public
+key is wrong, then someone else, say Dave, might be able to pretend to
+Bob that he's really Alice.
+.PP
+The easiest way to cope, at least in small networks, is for one person
+to be designated as a
+.IR "certificate authority" .
+The certificate authority's job is to collect authentic copies of
+everyone's public keys and make them available to the participants,
+signed by the CA's master key. Now all people need to get them started
+is a copy of the CA's public key.
+.PP
+A simple version of this model is supported by the
+.BR tripe-keys (8)
+program. If you have a large network then the simple single-CA model
+won't work for you: see the manual pages for
+.BR tripe (8)
+and
+.BR key (1)
+for the details on what you need to do.
+.PP
+Alice will be the certificate authority in our example. The CA's files
+will be stored on
+.BR thoth.alice.net ,
+owned by a dedicated user
+.BR tripe-ca ,
+and stored in
+.BR /home/tripe-ca .
+To set up the CA, she first creates a configuration file
+.B tripe-keys.master
+with the contents
+.VS
+## File locations.
+base-url = http://www.alice.net/tripe-keys/
+base-dir = /home/tripe-ca/dist/
+upload-hook = rsync \-az ${base-dir} www.alice.com:/var/www/tripe-keys/
+
+## Cryptographic parameters.
+kx-expire = now + 1 year
+sig-fresh = 1 month ago
+sig-expire now + 1 year
+
+## Master key integrity.
+master-sequence = @MASTER-SEQUENCE@
+hk-master = @HK-MASTER@
+.VE
+She then runs
+.B tripe-keys setup
+which runs for a fair while, printing lots of dots to keep her amused.
+Eventually it asks her for a passphrase, so she types in a good, strong
+passphrase that'll be hard for anyone to guess. It'll ask her to verify
+the passphrase, so she types it in again:
+.IS
+.IC $ "tripe-keys setup"
++ key \-krepos/param add \-adh-param \-LS \-b2048 \-B256 \-eforever
+\h'8n'\-tparam tripe-dh-param cipher=blowfish-cbc hash=sha256
+\h'8n'mac=sha256-hmac/128 mgf=sha256-mgf
+Searching for p: ...........++ ok
+Searching for g: + ok
++ key -kmaster add \-adsa \-b2048 \-B256 \-enow + 1 year \-l
+\h'8n'\-tmaster-0 tripe-keys-master sig=dsa hash=sha256
+Searching for q: ..++++++++++++ ok
+Searching for p: .................................++ ok
+Searching for g: + ok
+.IC "New passphrase e3f32b86:tripe-keys-master:master-0.private:" good-passphrase
+.IC "Verify passphrase e3f32b86:tripe-keys-master:master-0.private:" good-passphrase
++ key \-kmaster extract \-f\-secret repos/master.pub
+.IE
+(The lines beginning with
+.RB ` + '
+indicate commands that Alice could have run by hand. The
+.B tripe-keys
+program does a lot of work figuring out sensible defaults to apply.)
+.PP
+She now has an empty
+.I key repository
+in the directory
+.BR repos ,
+and a master CA key in the file
+.BR master .
+(There are also a bunch of
+.B .old
+files lying around for the sake of paranoia. You can ignore these, or
+even delete them if you like.)
+.PP
+She publishes the empty repository on her webserver by running
+.BR "tripe-keys upload" .
+This will create a signed copy of her repository and install it on her
+webserver. It will need to ask her for her passphrase again. (If she's
+running the passphrase pixie
+.BR pixie (8)
+and she's fairly quick about this, then the pixie will remember the
+passphrase and she won't need to type it again.)
+.IS
+.IC $ "tripe-keys upload"
++ tar chozf /tmp/mdw/tripe-ca/dist/tripe-keys.tar.gz.new .
++ catsign \-kmaster sign \-abdC \-kmaster-0
+\h'8n'\-o/home/tripe-ca/dist/tripe-keys.sig-0.new
+\h'8n'/home/tripe-ca/dist/tripe-keys.tar.gz.new
+.IC "Passphrase e3f32b86:tripe-keys-master:master-0.private:" good-passphrase
++ sh \-c rsync \-az /tmp/mdw/tripe-ca/dist/ www.alice.net:/var/www/tripe-keys/
+.IE
+Alice's CA is now ready!
+.
+.SS "Alice generates a server key"
+She'll need a key for herself, obviously, so she generates one. This
+also serves as a sanity check that she's set up the CA properly.
+.PP
+She's going to run her
+.BR tripe (8)
+server on a machine called
+.BR anubis.alice.net .
+She creates
+.BR tripe 's
+configuration directory
+.B \*(c/
+if it doesn't already exist, and makes it current.
+.IS
+.IC $ "mkdir -p \*(/c"
+.IC $ "cd \*(/c"
+.IE
+The first thing she needs to do is to get a copy of
+.B tripe-keys.conf
+from her webserver:
+.IS
+.IC $ "curl \-sS \-O http://www.alice.net/tripe-keys/tripe-keys.conf"
+.IE
+She must ensure that the copy is authentic. Since she can log into
+.B thoth
+directly using
+.BR ssh (1)
+she can use that to check. (She could just have fetched the file from
+.B thoth
+directly, but that wouldn't test that the webserver was set up properly.)
+.IS
+.IC $ "hashsum \-armd160 tripe-keys.conf"
+#hash rmd160
+0033d67c45027643c43577ff6bd188deb15fa65a tripe-keys.conf
+.IC $ "ssh thoth cat /home/tripe-ca/dist/tripe-keys.conf | hashsum \-armd160"
+0033d67c45027643c43577ff6bd188deb15fa65a
+.IE
+Good! Now she can fetch the copy of the empty repository.
+.IS
+.IC $ "tripe-keys update"
++ curl \-s \-o tripe-keys.tar.gz http://www.alice.net/tripe-keys/tripe-keys.tar.gz
++ curl \-s \-o tripe-keys.sig http://www.alice.net/tripe-keys/tripe-keys.sig-0
++ tar xfz tripe-keys.tar.gz
++ catsign \-krepos/master.pub verify \-avC \-kmaster-0 \-t1 month ago
+\h'8n'tripe-keys.sig tripe-keys.tar.gz
+INFO good-signature e3f32b86:tripe-keys-master:master-0
+INFO date 2008-04-09 18:25:39 BST
+OK verified successfully
+.IE
+Joy. Now Alice can actually generate her key.
+.IS
+.IC $ "tripe-keys generate alice"
++ key \-kkeyring merge repos/param
++ key \-kkeyring add \-adh \-pparam -enow + 1 year \-talice tripe-dh
++ key \-kkeyring extract \-f\-secret peer-alice.pub alice
+.IE
+At this point, Alice must get her public key, conveniently placed in
+.BR peer-alice.pub ,
+back to her master repository on
+.BR thoth .
+The easiest way is to log back into
+.B thoth
+and run
+.IS
+.IC $ "scp anubis:\*(/c/peer-alice.pub repos/"
+.IE
+Then all she needs to do is republish the change
+.RB ( "tripe-keys upload"
+on
+.BR thoth )
+and fetch the new version
+.RB ( "tripe-keys update"
+on
+.BR anubis ).
+.
+.SS "Bob generates his key"
+If Alice's and Bob's networks are going to communicate then Bob needs to
+generate a key too. The first thing he needs is an
+.I authentic
+copy of Alice's
+.BR tripe-keys.conf .
+Fetching it from
+.B www.alice.net
+using
+.BR curl (1)
+won't cut it. (Well, maybe if he uses HTTPS and already knows that he
+has an authentic copy of the webserver's public key certificate he can
+use that.)
+.PP
+Bob has several options.
+.hP \*o
+If he knows Alice's voice he can phone her up and get her to
+read out the
+.BR hashsum (1)
+of the file to him. He can compare this to the hash he computed on the
+file he got with
+.BR curl (1).
+.hP \*o
+If Alice is geographically close, he can just meet her and she can hand
+him either a copy of the hash or the file itself (on some suitable
+read-only medium like a CD-R).
+.hP \*o
+Alternatively, they can use
+.BR gnupg (1):
+Alice signs her copy of the file and sends it to Bob who verifies it.
+Of course, this assumes that he's somehow managed to get an authentic
+copy of Alice's OpenPGP key.
+.PP
+Bob's going to run
+.BR tripe (8)
+on
+.BR bast.bob.com .
+He makes
+.B \*(/c
+be his current directory, and puts his copy of
+.B tripe-keys.conf
+there. Once he's done that, he runs
+.B "tripe-keys update"
+to fetch the repository (now with Alice's public key in it), and then
+generates his key.
+.IC $ "tripe-keys generate bob"
++ key \-kkeyring merge repos/param
++ key \-kkeyring add \-adh \-pparam -enow + 1 year \-tbob tripe-dh
++ key \-kkeyring extract \-f\-secret peer-bob.pub bob
+.IE
+He now needs to send the file
+.B peer-bob.pub
+back to Alice, and again they need to ensure the authenticity of the
+file that Alice receives. They can use the same methods as they did
+before for the configuration file.
+.PP
+However they manage it, Alice puts her authentic copy of Bob's public
+key in
+.B /home/tripe-ca/repos/
+on
+.B thoth
+and runs
+.B "tripe-keys upload"
+again.
+.PP
+Finally, both she and Bob need to run
+.B "tripe-keys update"
+on
+.B anubis
+and
+.B bast
+respectively, to install the new collection of public keys. (Actually,
+Bob probably needn't bother, but it means that he can check that his
+public key is included.)
+.
+.SS "Alice and Bob set up their servers"
+The crypto setup is now done: we move on to the network administration
+part. The two networks in question are:
+.TP
+.B alice.net
+uses IP addresses 10.1.0.0/16. The main gateway to the outside world is
+.B apophis.alice.net
+(10.1.0.1 and 192.0.2.1).
+.TP
+.B bob.com
+uses IP addresses 10.2.0.0/16. The main gateway to the outside world is
+.B bast.bob.com
+(10.2.0.1 and 192.0.2.65).
+.PP
+(The internal addresses can, but don't need, to be allocated from the
+RFC1918 space. The addresses of the gateway machines, on which
+.BR tripe (8)
+is running, and which the example has drawn from 192.0.2.0/24, need to
+be publicly routable \(en or at least, routable with respect to whatever
+networks physically connect them.)
+.PP
+
+
+.
+.\"--------------------------------------------------------------------------
+.SH "GLOSSARY"
+.
+In the following entries, terms which are themselves defined in the
+glossary are written in
+.BR "bold face" .
+.
+.TP
+.B "External address"
+The IP address (and port number) used to contact a
+.BR peer 's
+instance of the
+.BR tripe (8)
+server. External addresses must usually be proper, publically routable
+IP address, i.e., not RFC1918 address. Compare with
+.BR "tunnel address" .
+.TP
+.B "Key exchange"
+The process by which two
+.BR peer s
+verify each other's identity and agree cryptographic keys for securing
+the
+.B tunnel
+between them.
+.TP
+.B "Peer"
+An instance of the
+.BR tripe (8)
+server running on a remote host. The local server maintains secure
+.BR tunnel s
+with each of the peers it knows about.
+.TP
+.B "Private key"
+A secret, used by a
+.BR tripe (8)
+server to prove its identity to its
+.BR peer s,
+who know the corresponding
+.BR "public key" .
+.TP
+.B "Public key"
+A value used by the
+.BR tripe (8)
+server to verify the identity of its
+.BR peer s.
+See also
+.BR "private key" .
+.TP
+.B "Tunnel"
+The secure virtual network link between two
+.BR peer s.
+.TP
+.B "Tunnel address"
+The (possibly private) IP address associated with a particular
+.BR peer 's
+end of a
+.BR tunnel .
+Tunnel addresses need not be publically routable, and might reasonably
+be allocated from the private-use space defined in RFC1918. Compare
+with
+.BR "external address" .
+.
+.\"--------------------------------------------------------------------------
+.SH "SEE ALSO"
+.
+.SS "Documents provided in the distribution"
+.TP
+.BR tripe (8)
+The main TrIPE server.
+.TP
+.BR tripectl (1)
+Client program for administering the server.
+.TP
+.BR tripe-admin (5)
+Description of the server administration protocol.
+.TP
+.BR tripe-keys "(8), " tripe-keys.conf (5)
+Tool for managing TrIPE public keys.
+.TP
+.BR tripemon (1)
+Graphical monitor program for the TrIPE server.
+.
+.SS "Other documents"
+.TP
+.I "The Wrestlers Protocol: A simple, practical, secure, deniable protocol for key-exchange"
+Research paper on the protocol TrIPE uses for key exchange. Available
+electronically as
+.BR http://eprint.iacr.org/2006/386/ .
+.
+.\"--------------------------------------------------------------------------
+.SH "AUTHOR"
+Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
~mdw / tripe / blobdiff