.\" -*-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, . .\"----- That's all, folks --------------------------------------------------