chiark / gitweb /
Initial versions of documentation.
[tripe] / doc / tripe.8
74eb47db 1.\" -*-nroff-*-
2.\". hP
5\h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
6.. VS
8.sp 1
11.ft B
12.. VE
14.ft R
17.sp 1
18.. t \{\
20. ds o \(bu
21. ds ss \s8\u
22. ds se \d\s0
23. if \n(.g \{\
24. fam P
25. \}
27.el \{\
28. ds o o
29. ds ss ^
30. ds se _
32.TH tripe 8 "10 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
33.SH "NAME"
34tripe \- a simple VPN daemon
36.B tripe
37.RB [ \-D ]
38.RB [ \-p
39.IR port ]
40.RB [ \-T
41.IR trace-opts ]
42.RB [ \-d
43.IR dir ]
44.RB [ \-a
45.IR socket ]
48.RB [ \-k
49.IR priv-keyring ]
50.RB [ \-K
51.IR pub-keyring ]
52.RB [ \-t
53.IR key-tag ]
56.B tripe
57program is a server which can provide strong IP-level encryption and
58authentication between two co-operating hosts. The program and its
59protocol are deliberately very simple, to make analysing them easy and
60to help build trust rapidly in the system.
61.SS "Overview"
63.B tripe
64server manages a number of secure connections to other `peer' hosts.
65Each daemon is given a private key of its own, and a file of public keys
66for the peers with which it is meant to communicate. It is responsible
67for negotiating sets of symmetric keys with its peers, and for
68encrypting, encapsulating and sending IP packets to its peers, and
69decrypting, checking and de-encapsulating packets it receives from
72When the server starts, it creates a Unix-domain socket on which it
73listens for administration commands. It also logs warnings and
74diagnostic information to the programs connected to its admin socket.
75Clients connected to the socket can add new peers, and remove or find
76out about existing peers. The textual protocol used to give the
77.B tripe
78server admin commands is described in
79.BR tripe\-admin (5).
80A client program
81.BR tripectl (1)
82is provided to allow commands to be sent to the server either
83interactively or by simple scripts.
84.SS "Command-line arguments"
85If not given any command-line arguments,
86.B tripe
87will initialize by following these steps:
88.hP \*o
89It changes directory to
90.BR /var/lib/tripe .
91.hP \*o
92It acquires a UDP socket with an arbitrary kernel-selected port number.
93It will use this socket to send and receive all communications with its
94peer servers. The port chosen may be discovered by means of the
96admin command (see
97.BR tripe\-admin (5)).
98.hP \*o
99It loads the private key with the tag or type name
100.B tripe\-dh
101from the Catacomb-format file
102.BR keyring ,
103and loads the file
105ready for extracting the public keys of peers as they're introduced.
106(The format of these files is described in
107.BR keyring (5).
108They are maintained using the program
109.BR key (1)
110provided with the Catacomb distribution.)
111.hP \*o
112It creates and listens to the Unix-domain socket
113.BR tripesock .
115Following this, the server enters its main loop, accepting admin
116connections and obeying any administrative commands, and communicating
117with peers. It also treats its standard input and standard output
118streams as an admin connection, reading commands from standard input and
119writing responses and diagnostics messages to standard output.
121Much of this behaviour may be altered by giving
122.B tripe
123suitable command-line options:
125.B "\-h, \-\-help"
126Writes a brief description of the command-line options available to
127standard output and exits with status 0.
129.B "\-v, \-\-version"
131.BR tripe 's
132version number to standard output and exits with status 0.
134.B "\-u, \-\-usage"
135Writes a brief usage summary to standard output and exits with status 0.
137.B "\-D, \-\-daemon"
138Dissociates from its terminal and starts running in the background after
139completing the initialization procedure described above. If running as
140a daemon,
141.B tripe
142will not read commands from standard input or write diagnostics to
143standard output. A better way to start
144.B tripe
145in the background is with
146.BR tripectl (1).
148.BI "\-d, \-\-directory=" dir
150.I dir
151the current directory, instead of
152.BR /var/lib/tripe .
153Give a current directory of
154.B .
155if you don't want it to change directory at all.
157.BI "\-p, \-\-port=" port
158Use the specified UDP port for all communications with peers, rather
159than an arbitarary kernel-assigned port.
161.BI "\-k, \-\-priv\-keyring=" file
162Reads the private key from
163.I file
164rather than the default
165.BR keyring .
167.BI "\-K, \-\-pub\-keyring=" file
168Reads public keys from
169.I file
170rather than the default
171.BR .
172This can be the same as the private keyring, but that's not recommended.
174.BI "\-t, \-\-tag=" tag
175Uses the private key whose tag or type is
176.I tag
177rather than the default
178.BR tripe\-dh .
180.BI "\-a, \-\-admin\-socket=" socket
181Accept admin connections to a Unix-domain socket named
182.I socket
183rather than the default
184.BR tripesock .
186.BI "\-T, \-\-trace=" trace-opts
187Allows the enabling or disabling of various internal diagnostics. See
188below for the list of options.
189.SS "Key management"
190The TrIPE protocol requires all cooperating hosts to be using keys
191with the same group parameters. A suitable group may be created with the
194key add \-adh\-param \-LS \-b2048 \-B256 \e
195 \-eforever \-tparam tripe\-dh\-param
197This creates a `parameters' key labelled
198.B param
199in your keyring file: it doesn't contain any secrets. You may vary the
200security parameters
201.B \-b
203.B \-B
204to taste: the ones given provide good security, at the expense of
205performance. Even so, from a cryptographic point of view, these keys
206will be the weak point in the security of the system. Generation of the
207group parameters can take a few minutes.
209You should extract the parameters from your keyring and distribute them
210(securely) to the other administrators. The parameters may be extracted
211from your keyring with the command:
213key extract param param
215This may be merged into a keyring with:
217key merge param
219Once your keyring contains the parameters, a suitable key can be created
220with the command:
222key add \-adh \-pparam \-e"now + 1 year" tripe\-dh
224This creates a Diffie-Hellman key using the parameters from key
225.B param
226which expires in one year. The new key has type
227.BR tripe\-dh .
229.SS "About the name"
230The program's name is
231.BR tripe ,
232all in lower-case. The name of the protocol it uses is `TrIPE', with
233four capital letters and one lower-case. The name stands for `Trivial
234IP Encryption'.
235.SH "BUGS"
236It's too easy to deny service during key exchange. If both ends are
237honest, they'll notice any interference and resend their packets, but
238it's possible to delay successful negotation for as long as desired by
239sending bogus key exchange messages.
241The code hasn't been audited. It may contain security bugs. If you
242find one, please inform the author
243.IR immediately .
245.BR key (1),
246.BR tripectl (1),
247.BR tripe\-admin (5).
249.IR "The Trivial IP Encryption Protocol" ,
250.IR "The Wrestlers Protocol" .
252Mark Wooding, <>