Documentation restructuring: provide a useful overview.

[tripe] / tripe.7.in

.\" -*-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 --------------------------------------------------