3 .\" Overview of the whole system
5 .\" (c) 2008 Straylight/Edgeware
8 .\"----- Licensing notice ---------------------------------------------------
10 .\" This file is part of Trivial IP Encryption (TrIPE).
12 .\" TrIPE is free software; you can redistribute it and/or modify
13 .\" it under the terms of the GNU General Public License as published by
14 .\" the Free Software Foundation; either version 2 of the License, or
15 .\" (at your option) any later version.
17 .\" TrIPE is distributed in the hope that it will be useful,
18 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
19 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 .\" GNU General Public License for more details.
22 .\" You should have received a copy of the GNU General Public License
23 .\" along with TrIPE; if not, write to the Free Software Foundation,
24 .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
26 .so common/defs.man \" @@@PRE@@@
28 .\"--------------------------------------------------------------------------
29 .TH tripe 7 "28 March 2008" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
31 .\"--------------------------------------------------------------------------
33 tripe \- overview of the TrIPE suite
35 .\"--------------------------------------------------------------------------
36 .SH "NOTES TO THE AUTHOR"
38 .SS "What do we actually need to cover?"
42 Setting up peer connections.
44 Choosing algorithm suites?
46 .\"--------------------------------------------------------------------------
49 TrIPE is a Virtual Private Network (VPN) implementation. It uses
50 cryptography to protect network packets from being read or tampered with
51 as they travel over hostile networks (e.g., the Internet). The effect
52 of this is that you can connect together geographically-separated
53 networks of machines and use network protocols which would be unsafe to
54 use over public networks.
56 The name `TrIPE' stands for `Trivial IP Encryption'. Unfortunately,
57 while the TrIPE network protocol is still fairly simple (and this is one
58 of TrIPE's conspicuous advantages over other VPN systems), the software
59 suite which implements it is not. Over time, the original single server
60 has acquired various strangely-shaped extensions and add-on-services in
61 order to solve various problems, and even given fairly detailed
62 descriptions of all of the individual pieces it can be difficult to see
63 how to fit them together in order to actually do anything useful.
65 This manual page provides an overview of the TrIPE software suite. The
66 individual components are described in their respective reference manual
67 pages. This page exists to provide a picture for how the various pieces
68 fit together and how to use them effectively. It presents a number of
69 worked examples, but it's not intended to be used as a `cookbook'; TrIPE
70 is a complicated system, and the author believes that you're less likely
71 to become confused by it if you understand how its various bits fit
72 together rather than following canned recipes which don't quite match
73 your particular circumstances.
75 The TrIPE software runs entirely in user mode. It does not require any
78 .SS "Who this documentation is for"
79 This document is intended for network administrators who are comfortable
80 with the fundamentals of IP networking and routing. It assumes
81 knowledge of how to configure network interfaces and routing. It
82 doesn't assume a strong background in cryptography, though a good
83 grounding won't hurt; the author recommends the
84 .I "Handbook of Applied Cryptography"
85 by Alfred Menezes, Paul van Oorschott and Scott Vanstone, which is
86 published by CRC Press, or available online.
88 .\"--------------------------------------------------------------------------
91 The TrIPE protocol is a simple packet-based protocol transmitted over
92 UDP (RFC768). TrIPE has been allocated port 4070 by the IANA, but you
93 can use other ports if you like.
95 .SS "Network structure and addressing"
96 In TrIPE's model, a virtual network consists of a number of physical
97 networks joined together. Each physical network needs a
99 (at least one, though more may be useful) which actually speaks the
100 TrIPE protocol. The representative establishes secure point-to-point
101 links with representatives of other physical networks over the Internet
102 (or at least over some larger physical network). These links are
103 strictly pairwise: they carry packets back and forth between precisely
104 two endpoints. The two endpoints of such a link are
106 the link is, as far as TrIPE is concerned, utterly symmetrical.
108 Most of the hosts in the physical networks only need `internal'
109 addresses, i.e., their addresses need only be unique
111 the virtual network \(en and, if NAT is in use, even that needn't hold,
112 though NAT is at best a necessary evil and not to be used lightly.
113 Obviously, in order to be useful, the representatives need
115 addresses, so that they can send each other IP packets over the wider
120 Alice is the administrator of
122 Internally, she has allocated IP addresses from the private address
123 range 10.0.1.0/24. She has an externally facing server
124 .BR anubis.alice.net ,
125 which has an internal address of 10.0.1.1 and an external address of
128 Bob is an administrator at
130 Internally, he's allocated IP addresses from the private address range
131 10.0.2.0/24. He has an externally facing server
133 which has an internal address of 10.0.2.1 and an external address of
136 (At this point, the author would like to apologize for the unrealistic
137 nature of the external IP addresses in this example. Unfortunately,
138 allocating the addresses from the private-use space, e.g., 10.0.0.0/8,
139 would be confusing, since these are normally
141 addresses only; the network 192.0.2.0/24 is allocated by IANA for use in
142 examples such as this, but is rather too small to divide into realistic
143 subnets, as I've tried to do here.)
145 It would be reasonable for Alice and Bob to choose
149 as their respective TrIPE representatives. If, say,
150 .B amaterasu.alice.net
151 was an internal host with address 10.0.1.42, it would not be a suitable
152 representative, since this is an internal address and (presumably) the
157 don't know how to send packets there.
159 We'll return to Alice and Bob in other examples later.
162 .SS "Tunnels and routing"
165 is a network interface, usually configured as a point-to-point link,
166 except that rather than sending network packets through some physical
167 interface, it makes them available to a user-mode process through a
168 character device; similarly, packets written to the character device
169 appear to the kernel to have originated in the tunnel interface.
171 A cheesy hack for implementing a `tunnel' interface like this is to
174 and configure the slave side of the pty to use the SLIP line discipline.
175 A user-mode process can now use the master side of the pty to read and
176 write SLIP-encoded network packets. Linux's TUN/TAP and BSD's
178 interfaces provide a more convenient and efficient means of achieving
179 the same goal. TrIPE prefers to use these more refined tunnel
180 interfaces, but is willing to use the cheesy SLIP hack if necessary.
182 For each peer with which it is exchanging secured packets, a TrIPE
183 representative creates a tunnel interface. Packets being sent through
184 the interface are encrypted, authenticated, and retransmitted to the
185 peer's UDP port; packets arriving from a peer are verified, decrypted,
186 and inserted into the tunnel.
188 For this to work, the representative needs to have at least two routes
191 a route to its peer's external address, so that it can send it encrypted
192 packets encapsulated in UDP;
194 a route to the peer's
196 address, directed over the tunnel interface; and possibly
198 if the peer is acting as a representative for a network of other hosts,
199 a route to that network also over the tunnel.
204 Continuing the earlier example,
206 needs to have one route to
208 external address 192.0.2.129. We'll assume that
210 has a direct connection to the Internet, and that therefore no special
211 action needs to be taken here. In order to tunnel traffic to
216 interface configured as follows.
218 .B "ifconfig tripe-bob 10.0.1.1 pointopoint 10.0.2.1 mtu 1435"
220 (Network configuration commands are system-specific. This manual page
221 assumes a Linux system because that's the author's primary operating
222 system; consult your system's manual to find out what the equivalent
223 commands are. Network interface names are also system-specific; Linux
224 lets us rename network interfaces to make their names meaningful, and
225 these examples reflect this. Finally, don't worry about the MTU
226 setting. Usually, TrIPE's ancillary services will work out the correct
229 Further, in order to communicate with the larger
233 has set up an additional route
235 .B "route add -net 10.0.2.0/24 gw 10.0.2.1 dev tripe-bob metric 2"
237 Other hosts in Alice's network might need to be told
239 .B "route add -net 10.0.2.0/24 gw 10.0.1.1 metric 3"
241 (spot the difference between this and
243 route), though in many cases it's useful to choose the TrIPE
244 representative as a router anyway.
247 .SS "Connection styles"
248 There are essentially two kinds of connections possible between TrIPE
252 Each of the two peers expects to find the other up and running all of
253 the time. This works well, and is easy to set up and maintain, if the
254 two peers have stable external IP addresses, have network connectivity,
255 and are almost always turned on. If one is frequently down, or the
256 network between them is not always available (e.g., it's a dial-up link)
257 then the servers will be wasting their time trying to contact each
258 other: maybe one of the other options will be better. Either or both of
259 the peers may be providing VPN services for a network of other machines.
261 .B "Dynamically established."
262 One of the peers explicitly establishes a connection with the other when
263 it wants to communicate. The
265 peer \(en the one making the connection \(en doesn't need a stable
266 static IP address. The
268 peer \(en the one connected to \(en does need a stable external IP
269 address, to have reasonable network connectivity, and to be up most of
270 the time. Dynamic connections are more complicated to configure and
271 support, but much more flexible.
273 (In principle, it might be possible for two hosts, both behind NAT
274 routers, to make use of, say, STUN to establish a connection; but this
275 doesn't seem sufficiently useful.)
294 .\"--------------------------------------------------------------------------
295 .SH "CRYPTOGRAPHY AND KEY MANAGEMENT"
297 .SS "A very quick introduction to modern cryptography"
298 This isn't really the place for a full survey of modern cryptography,
299 but I'll try to provide a little background.
301 Cryptography is the use of mathematics in order to achieve security
302 objectives. There are two main objectives of modern cryptography.
305 Preventing an adversary from learning anything about a message (except
306 its length), even though the adversary is responsible for delivering
307 it. The original message is called the
311 process converts the plaintext into a
315 the ciphertext in order to recover the original plaintext.
317 .IR Integrity " or " authenticity
318 Preventing an adversary from creating
320 i.e., messages which appear to have been sent by a particular person or
321 group of people. The sender
325 a message (tags are symmetric, signatures asymmetric, as explained
326 below); the recipient
328 the tag or signature.
330 In order to be able to do this, the recipient (in the case of secrecy)
331 or the sender (for integrity) need to know a
333 unknown to the adversary. We can now distinguish two important cases.
335 .IR "Symmetric" " or " "secret-key cryptography"
336 Both participants know the same key (or at least they can easily compute
337 each others' keys). Somehow, the two participants must agree on the
338 same key without letting it fall into the hands of the adversary.
339 Before 1976, all publicly-known cryptographic schemes were symmetric.
341 .IR "Asymmetric" " or " "public-key cryptography"
342 In the case of secrecy, the sender knows only a
344 which is sufficient to encrypt a message so that it can only be
345 decrypted by the holder of the corresponding
347 but insufficient to decrypt messages sent by others using the same
348 public key. In the case of integrity, the sender holds a secret key
349 with which he can make signatures; the public key allows others to
350 verify existing signatures but not to make new signatures. The holder
351 of the private key needs to convey an
353 copy of the corresponding public key to other participants, but the
354 public key doesn't need to be kept secret. Asymmetric cryptography was
355 first described to the public in 1976 by Whitfield Diffie and Martin
356 Hellman, though it had been known to governments (e.g., the British
357 CESG) for a number of years.
359 The advantage of symmetric cryptography is efficiency: symmetric
360 techniques for secrecy and integrity require smaller keys, less memory,
361 and much less time, than asymmetric techniques. The disadvantage is
362 that key distribution is much harder: symmetric keys must be known to
363 all participants, but kept secret from adversaries; public keys need not
364 be kept secret. It's therefore common to use asymmetric methods to
365 distribute short symmetric keys, and use the latter for ensuring the
366 secrecy and integrity of longer messages.
368 Asymmetric cryptography makes key distribution easier, but doesn't
369 eliminate the problem entirely. In particular, the problem of ensuring
370 that the participants have a correct copy of each others' keys remains.
371 There are a number of (partial) solutions to this problem, but they all
372 use the same basic idea: if (say) Alice knows Bob's public key, and Bob
373 knows Carol's public key, then Bob can send Alice a message saying
374 `Carol's public key is
376 now, if Alice is willing to take Bob's word for this, then she now knows
379 A signed message binding together a public key and some facts about the
380 corresponding private key is often called a
383 .I certificate authority
384 (or CA) is an organization which issues certificates. Internet
385 certificate authorities are organizations whose public keys are well
386 known (e.g., included with web browsers) and which are generally
387 believed to be careful to issue only correct certificates. However, the
388 economics of this arrangement are strange: CAs are usually paid by the
389 holders of private keys, so they get their money whether or not the
390 certificates are actually true.
394 program and its successors (e.g.,
396 use a more sophisticated approach called the
398 which allows Alice to collect certificates from a number of different
399 signers, compare them, and decide based on how much she trusts each of
400 them how likely their claims are. This can be complicated to manage.
402 .SS "Cryptography in TrIPE"
403 The long-term keys in TrIPE are all asymmetric. There are no
404 `pre-shared keys'. If two peers are to establish a link between them,
405 it is essential that each has a correct copy of the other's public key.
406 In principle, this ought to be easier than arranging for each to know a
407 common secret; pre-shared keys are easier to deal with only if they're
408 memorable, and memorable keys are not likely to be difficult to guess.
410 The TrIPE server, and its ancillary services, simply assume that you've
411 already acquired genuine copies of other peers' public keys and put them
412 in the right place; exactly how you go about this is up to you, and
413 tools such as CAs or PGP can help. However, the TrIPE distribution
414 contains a simple tool
416 for dealing with public key distribution. This is described in more
419 The TrIPE suite's primary author is a cryptographer, and he enjoys
420 having fine control over the cryptographic primitives involved.
421 Fortunately it's not that difficult to
430 .\"--------------------------------------------------------------------------
434 TrIPE runs entirely in user mode, unlike many IPsec implementations.
435 The main server, which is written in C, mostly runs as an unprivileged
436 user. However, a small part of the server runs with
438 privileges because it needs to be able to open new tunnel devices
439 dynamically. Even this can be avoided, for example by using SLIP
440 tunnels, allocated by a GNU
442 service. If the server is compromised, an attacker can use it to inject
443 arbitrary network packets, but little else.
445 The ancillary service
447 needs root privileges in order to configure new network interfaces. It
448 is written in Python, a safe interpreted language. In turn, this
449 invokes an external program, again as
451 to do the actual network interface configuration. This program is
452 user-selectable, but the default program is a simple shell script; it
453 does not process untrusted input.
455 .SS "Cryptographic security"
456 The TrIPE protocol is not standards-based. However, it has been
457 designed by an experienced cryptographer, and has a formal `security
458 proof' showing that an attack against the protocol can be transformed
459 into an attack against one of its primitive components. Other VPN
460 protocols are too complicated to admit such proofs. The guarantees
461 afforded by security proofs of this kind are
463 on the security of the primitive components rather than absolute, but
464 even such a contingent proof is much better than no proof at all.
466 The software allows users a wide selection of primitive components, some
467 standardized and some not; the author recommends the widely standardized
468 and well-respected Rijndael (AES) for encryption and SHA256 for hashing
471 .SS "Why TrIPE doesn't use X.509"
472 The TrIPE protocol does not use X.509 certificates, as deployed in TLS and
473 IPsec. X.509 certificates are hard to parse: software which processes
474 them has a history of vulnerabilities. The certification model used by
475 TLS, where the holder of a key pays a certification authority for his or
476 her certificate, is economically backwards: the direct beneficiaries of
477 the certificate are those who rely on it to establish the validity of
478 the public key. The author does not understand why an external
479 certificate authority is needed in order to construct a VPN anyway: if
480 Alice has no idea who Bob is, she's unlikely to want to allow him access
481 to her private network!
483 The main TrIPE software does not assume any particular certification
484 model: rather, it considers the issue of establish authenticity of
485 public keys to be out-of-scope. The supplied
487 program implements a very simple key-distribution system which avoids
488 the complexity inherent in X.509. Of course, because public key
489 distribution is separated from the main system, nothing prevents
490 swapping in a more sophisticated system where necessary.
492 .SS "Comparison with other systems"
493 This section compares TrIPE with other VPN protocols.
497 IPsec is an IETF standard. It defines two protocols for handling bulk
498 data. The Authentication Header (AH) simply adds cryptographic
499 authentication to an IP packet, including the header; this causes
500 trouble with NAT firewalls. The Encapsulating Security Payload (ESP)
501 provides both encryption and authenticity, and operates in one of two
504 mode simply processes the payload data, but not the header; the
506 mode encapsulates an entire IP packet. Of these, AH and ESP transport
507 mode need to be supported by all participating hosts. ESP tunnel mode
508 only needs to be supported by a single representative (`security
509 gateway') of each network, and provides header security which works
510 properly with NAT. TrIPE works very similarly to ESP tunnel mode.
511 The IPsec AH and ESP protocols work directly over IP, rather than using
512 UDP as TrIPE does. This reduces the per-packet overhead, but means that
513 implementations need to be highly privileged, either running as part of
514 the kernel or at least with
518 Key exchange in IPsec (IKE) is very complicated, with many options. The
519 protocol can use a number of different certificate formats, or none at
520 all. Partly this is due to the fact that IPsec has more ambitious goals
521 than TrIPE: IPsec aims to allow `opportunistic' security between
522 previously unrelated entities, whereas TrIPE assumes that all the
523 participants in its virtual network are administrated in a coordinated
524 fashion. This means that TrIPE's usefulness is comparatively limited;
525 of course, it also means that TrIPE is much simpler.
530 In many respects, OpenVPN is very similar to TrIPE: it runs in userland,
531 and operates over UDP. OpenVPN uses a variant of the TLS protocol for
532 its key-exchange. TLS is very complex, and uses X.509 certificates
533 which bring their own problems. (OpenVPN provides a
535 option to mitigate this, though it partially defeats the point of
536 public key cryptography.)
538 OpenVPN can use TAP interfaces in order to simulate an Ethernet rather
539 than a point-to-point link, which allows Ethernet bridging across the
540 VPN. TrIPE could do this relatively easily (it's just a matter of
541 configuring the tunnel interface differently) but it hasn't seemed
545 .B "SSH- and SSL-based VPNs"
547 OpenSSH can implement a simple VPN, by opening tunnel devices at each
548 end and forwarding packets over the SSH connection. This causes
549 problems: SSH is already running over TCP, and TCP provides congestion
550 control and reliability. TCP over this tunnel will therefore have two
551 layers of congestion control and reliability, and the two have a
552 tendency to interfere. When there is little or no packet loss,
553 everything will be fine; if the underlying connection becomes flaky, the
554 VPN will suffer greatly.
556 SSL-based VPNs (simply forwarding packets over an SSL or TLS connection)
557 have the same problem, and all of the problems associated with SSL's use
558 of X.509 certificates.
561 .SS "Firewall considerations"
562 You should be able to write firewall rules for packets travelling over
563 TrIPE's tunnel interfaces just as for any other interfaces.
564 Unfortunately, it is hard to predict the name of the tunnel interface
565 that TrIPE will allocate for any particular peer. There are two basic
566 solutions to this problem.
568 Some operating systems allow you to rename network interfaces. You can
569 use this feature to assign the interface a more useful name, which may
570 already be known to your firewall.
572 You can dynamically modify the firewall rules once you know which
573 interface has been assigned to the peer. This is probably more
592 .SS "Structure of the system"
593 The TrIPE system consists of a number of components.
597 daemon itself. The daemon runs continually in the background. At any
598 given moment, the daemon knows of a number of
600 other servers with which it is meant to interact. It accepts network
601 packets from the kernel, encrypts them, and sends them to appropriate
602 peers; it also receives encrypted packets from peers, decrypts them, and
603 hands them to the kernel. It also provides an administration interface
604 through which the daemon can be told about new peers, and old ones
607 A number of ancillary services which run alongside the daemon and
608 provide additional functionality. The
610 service accepts requests to attach new peers and makes the necessary
613 service notices peers being added and removed; it configures network
614 interfaces; when necessary it attempts to `wake up' remote peers to
615 inform them of its presence; and it can time out old peers which aren't
616 responding. This is useful in environments where peers appear and
617 disappear dynamically.
621 utility. The TrIPE system uses asymmetric (`public-key') cryptography.
622 Therefore it's necessary to ensure that the participants in the VPN have
623 authentic copies of each others' public keys. This is nontrivial, but
624 easier than the traditional key-distribution problem, which additionally
625 involves keeping all of the keys secret. The
627 program helps maintain a
628 .I "certificate authority"
629 (CA) which can distribute public keys in a secure way.
631 .SS "The basic model"
632 As far as the TrIPE protocol goes, there is no distinction between
633 clients and servers, or between initiators and responders. The protocol
634 treats all participants equally; we call them peers. Each peer knows
635 about a number of other peers. It establishes point-to-point
636 communications separately with each peer it knows about.
638 Each peer refers to the other peers with whom it communicates by name.
639 Theoretically, these names are only for the individual peer's (and its
640 administrator's) convenience, and a single peer may be assigned
641 completely different names by all of the other peers with which it
642 communicates. In practise, this would be very confusing, and all peers
643 use the same, or very similar, names for each other.
645 When a daemon is informed about a new peer \(en its name, and an IP
646 address and port number \(en it creates a new network interface for the
647 peer and attempts to initiate a key-exchange. If both ends have been
648 informed of each other's presence, and they have each other's correct
649 public keys, they will successfully negotiate symmetric keys and be able
650 to transmit and receive network packets.
652 By this point, the daemon has indeed created a network interface, but no
653 network traffic will actually be carried because the interface is not
656 daemon leaves the messy details of configuring interfaces to other
659 service is running, it will notice the new peer, look up its details in
660 a database, and invoke a script, usually
662 to configure the interface correctly.
664 .SS "Addressing concepts"
665 Virtual private networks make addressing complicated. This
666 documentation isn't going to make that complexity go away, but it might
667 shed some light on it. In particular, each peer involved needs at least
668 two distinct addresses.
678 The TrIPE VPN isn't magic. It runs over standard IP, so the machines
679 you want to participate in the VPN need to be able to send each other IP
686 In particular, each needs to have an address and port number
688 .I "external address"
689 (and port) \(en on which it can send and receive packets to/from the
692 Additionally, each needs to be able to send packets to the others
694 the VPN. The addresses which are routed over the VPN are
695 .IR "internal addresses" .
696 Clearly, the internal addresses need to be distinct from the external
697 addresses if the machines involved are to be able
700 .I "external addresses"
702 TrIPE has the port number 4070 allocated to it by IANA, so it shouldn't
703 interfere with anything else. But some firewalls may block TrIPE
704 traffic, or you may just not want to advertise your use of TrIPE, so you
705 can use any port you like.
710 .SS "Establishing connections"
717 The server itself maintains no persistent configuration other than a
718 simple database of public keys for its various peers.
720 .\"--------------------------------------------------------------------------
723 This section contains a number of worked examples for configuring and
726 We'll start with the case of Alice and Bob, who both administer
731 respectively, and want them to be able to communicate with each other
732 securely over the wild Internet. Later we'll deal with Carol, who has a
733 laptop and wants to be able to connect to the VPN from fleapit hotels
734 all around the world.
736 .SS "Alice sets herself up as a certificate authority"
737 Everyone participating in a TrIPE network needs to have a private key
740 copy of everyone else's public keys. If Bob's copy of Alice's public
741 key is wrong, then someone else, say Dave, might be able to pretend to
742 Bob that he's really Alice.
744 The easiest way to cope, at least in small networks, is for one person
745 to be designated as a
746 .IR "certificate authority" .
747 The certificate authority's job is to collect authentic copies of
748 everyone's public keys and make them available to the participants,
749 signed by the CA's master key. Now all people need to get them started
750 is a copy of the CA's public key.
752 A simple version of this model is supported by the
754 program. If you have a large network then the simple single-CA model
755 won't work for you: see the manual pages for
759 for the details on what you need to do.
761 Alice will be the certificate authority in our example. The CA's files
763 .BR thoth.alice.net ,
764 owned by a dedicated user
768 To set up the CA, she first creates a configuration file
773 base-url = http://www.alice.net/tripe-keys/
774 base-dir = /home/tripe-ca/dist/
775 upload-hook = rsync \-az ${base-dir} www.alice.com:/var/www/tripe-keys/
777 ## Cryptographic parameters.
778 kx-expire = now + 1 year
779 sig-fresh = 1 month ago
780 sig-expire now + 1 year
782 ## Master key integrity.
783 master-sequence = @MASTER-SEQUENCE@
784 hk-master = @HK-MASTER@
788 which runs for a fair while, printing lots of dots to keep her amused.
789 Eventually it asks her for a passphrase, so she types in a good, strong
790 passphrase that'll be hard for anyone to guess. It'll ask her to verify
791 the passphrase, so she types it in again:
793 .IC $ "tripe-keys setup"
794 + key \-krepos/param add \-adh-param \-LS \-b2048 \-B256 \-eforever
795 \h'8n'\-tparam tripe-dh-param cipher=blowfish-cbc hash=sha256
796 \h'8n'mac=sha256-hmac/128 mgf=sha256-mgf
797 Searching for p: ...........++ ok
798 Searching for g: + ok
799 + key -kmaster add \-adsa \-b2048 \-B256 \-enow + 1 year \-l
800 \h'8n'\-tmaster-0 tripe-keys-master sig=dsa hash=sha256
801 Searching for q: ..++++++++++++ ok
802 Searching for p: .................................++ ok
803 Searching for g: + ok
804 .IC "New passphrase e3f32b86:tripe-keys-master:master-0.private:" good-passphrase
805 .IC "Verify passphrase e3f32b86:tripe-keys-master:master-0.private:" good-passphrase
806 + key \-kmaster extract \-f\-secret repos/master.pub
808 (The lines beginning with
810 indicate commands that Alice could have run by hand. The
812 program does a lot of work figuring out sensible defaults to apply.)
818 and a master CA key in the file
820 (There are also a bunch of
822 files lying around for the sake of paranoia. You can ignore these, or
823 even delete them if you like.)
825 She publishes the empty repository on her webserver by running
826 .BR "tripe-keys upload" .
827 This will create a signed copy of her repository and install it on her
828 webserver. It will need to ask her for her passphrase again. (If she's
829 running the passphrase pixie
831 and she's fairly quick about this, then the pixie will remember the
832 passphrase and she won't need to type it again.)
834 .IC $ "tripe-keys upload"
835 + tar chozf /tmp/mdw/tripe-ca/dist/tripe-keys.tar.gz.new .
836 + catsign \-kmaster sign \-abdC \-kmaster-0
837 \h'8n'\-o/home/tripe-ca/dist/tripe-keys.sig-0.new
838 \h'8n'/home/tripe-ca/dist/tripe-keys.tar.gz.new
839 .IC "Passphrase e3f32b86:tripe-keys-master:master-0.private:" good-passphrase
840 + sh \-c rsync \-az /tmp/mdw/tripe-ca/dist/ www.alice.net:/var/www/tripe-keys/
842 Alice's CA is now ready!
844 .SS "Alice generates a server key"
845 She'll need a key for herself, obviously, so she generates one. This
846 also serves as a sanity check that she's set up the CA properly.
848 She's going to run her
850 server on a machine called
851 .BR anubis.alice.net .
854 configuration directory
856 if it doesn't already exist, and makes it current.
858 .IC $ "mkdir -p \*(/c"
861 The first thing she needs to do is to get a copy of
865 .IC $ "curl \-sS \-O http://www.alice.net/tripe-keys/tripe-keys.conf"
867 She must ensure that the copy is authentic. Since she can log into
871 she can use that to check. (She could just have fetched the file from
873 directly, but that wouldn't test that the webserver was set up properly.)
875 .IC $ "hashsum \-armd160 tripe-keys.conf"
877 0033d67c45027643c43577ff6bd188deb15fa65a tripe-keys.conf
878 .IC $ "ssh thoth cat /home/tripe-ca/dist/tripe-keys.conf | hashsum \-armd160"
879 0033d67c45027643c43577ff6bd188deb15fa65a
881 Good! Now she can fetch the copy of the empty repository.
883 .IC $ "tripe-keys update"
884 + curl \-s \-o tripe-keys.tar.gz http://www.alice.net/tripe-keys/tripe-keys.tar.gz
885 + curl \-s \-o tripe-keys.sig http://www.alice.net/tripe-keys/tripe-keys.sig-0
886 + tar xfz tripe-keys.tar.gz
887 + catsign \-krepos/master.pub verify \-avC \-kmaster-0 \-t1 month ago
888 \h'8n'tripe-keys.sig tripe-keys.tar.gz
889 INFO good-signature e3f32b86:tripe-keys-master:master-0
890 INFO date 2008-04-09 18:25:39 BST
891 OK verified successfully
893 Joy. Now Alice can actually generate her key.
895 .IC $ "tripe-keys generate alice"
896 + key \-kkeyring merge repos/param
897 + key \-kkeyring add \-adh \-pparam -enow + 1 year \-talice tripe-dh
898 + key \-kkeyring extract \-f\-secret peer-alice.pub alice
900 At this point, Alice must get her public key, conveniently placed in
902 back to her master repository on
904 The easiest way is to log back into
908 .IC $ "scp anubis:\*(/c/peer-alice.pub repos/"
910 Then all she needs to do is republish the change
911 .RB ( "tripe-keys upload"
914 and fetch the new version
915 .RB ( "tripe-keys update"
919 .SS "Bob generates his key"
920 If Alice's and Bob's networks are going to communicate then Bob needs to
921 generate a key too. The first thing he needs is an
924 .BR tripe-keys.conf .
929 won't cut it. (Well, maybe if he uses HTTPS and already knows that he
930 has an authentic copy of the webserver's public key certificate he can
933 Bob has several options.
935 If he knows Alice's voice he can phone her up and get her to
938 of the file to him. He can compare this to the hash he computed on the
942 If Alice is geographically close, he can just meet her and she can hand
943 him either a copy of the hash or the file itself (on some suitable
944 read-only medium like a CD-R).
946 Alternatively, they can use
948 Alice signs her copy of the file and sends it to Bob who verifies it.
949 Of course, this assumes that he's somehow managed to get an authentic
950 copy of Alice's OpenPGP key.
958 be his current directory, and puts his copy of
960 there. Once he's done that, he runs
961 .B "tripe-keys update"
962 to fetch the repository (now with Alice's public key in it), and then
964 .IC $ "tripe-keys generate bob"
965 + key \-kkeyring merge repos/param
966 + key \-kkeyring add \-adh \-pparam -enow + 1 year \-tbob tripe-dh
967 + key \-kkeyring extract \-f\-secret peer-bob.pub bob
969 He now needs to send the file
971 back to Alice, and again they need to ensure the authenticity of the
972 file that Alice receives. They can use the same methods as they did
973 before for the configuration file.
975 However they manage it, Alice puts her authentic copy of Bob's public
977 .B /home/tripe-ca/repos/
981 .B "tripe-keys upload"
984 Finally, both she and Bob need to run
985 .B "tripe-keys update"
990 respectively, to install the new collection of public keys. (Actually,
991 Bob probably needn't bother, but it means that he can check that his
992 public key is included.)
994 .SS "Alice and Bob set up their servers"
995 The crypto setup is now done: we move on to the network administration
996 part. The two networks in question are:
999 uses IP addresses 10.1.0.0/16. The main gateway to the outside world is
1000 .B apophis.alice.net
1001 (10.1.0.1 and 192.0.2.1).
1004 uses IP addresses 10.2.0.0/16. The main gateway to the outside world is
1006 (10.2.0.1 and 192.0.2.65).
1008 (The internal addresses can, but don't need, to be allocated from the
1009 RFC1918 space. The addresses of the gateway machines, on which
1011 is running, and which the example has drawn from 192.0.2.0/24, need to
1012 be publicly routable \(en or at least, routable with respect to whatever
1013 networks physically connect them.)
1018 .\"--------------------------------------------------------------------------
1021 In the following entries, terms which are themselves defined in the
1022 glossary are written in
1026 .B "External address"
1027 The IP address (and port number) used to contact a
1031 server. External addresses must usually be proper, publically routable
1032 IP address, i.e., not RFC1918 address. Compare with
1033 .BR "tunnel address" .
1036 The process by which two
1038 verify each other's identity and agree cryptographic keys for securing
1046 server running on a remote host. The local server maintains secure
1048 with each of the peers it knows about.
1053 server to prove its identity to its
1055 who know the corresponding
1061 server to verify the identity of its
1067 The secure virtual network link between two
1071 The (possibly private) IP address associated with a particular
1075 Tunnel addresses need not be publically routable, and might reasonably
1076 be allocated from the private-use space defined in RFC1918. Compare
1078 .BR "external address" .
1080 .\"--------------------------------------------------------------------------
1083 .SS "Documents provided in the distribution"
1086 The main TrIPE server.
1089 Client program for administering the server.
1092 Description of the server administration protocol.
1094 .BR tripe-keys "(8), " tripe-keys.conf (5)
1095 Tool for managing TrIPE public keys.
1098 Graphical monitor program for the TrIPE server.
1100 .SS "Other documents"
1102 .I "The Wrestlers Protocol: A simple, practical, secure, deniable protocol for key-exchange"
1103 Research paper on the protocol TrIPE uses for key exchange. Available
1105 .BR http://eprint.iacr.org/2006/386/ .
1107 .\"--------------------------------------------------------------------------
1109 Mark Wooding, <mdw@distorted.org.uk>
1111 .\"----- That's all, folks --------------------------------------------------
~mdw / tripe / blob