3 * $Id: tripe.h,v 1.4 2001/02/05 19:56:37 mdw Exp $
5 * Main header file for TrIPE
7 * (c) 2001 Straylight/Edgeware
10 /*----- Licensing notice --------------------------------------------------*
12 * This file is part of Trivial IP Encryption (TrIPE).
14 * TrIPE is free software; you can redistribute it and/or modify
15 * it under the terms of the GNU General Public License as published by
16 * the Free Software Foundation; either version 2 of the License, or
17 * (at your option) any later version.
19 * TrIPE is distributed in the hope that it will be useful,
20 * but WITHOUT ANY WARRANTY; without even the implied warranty of
21 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22 * GNU General Public License for more details.
24 * You should have received a copy of the GNU General Public License
25 * along with TrIPE; if not, write to the Free Software Foundation,
26 * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
29 /*----- Revision history --------------------------------------------------*
32 * Revision 1.4 2001/02/05 19:56:37 mdw
33 * Sequence number protection, and BSD tunnels.
35 * Revision 1.3 2001/02/04 01:17:55 mdw
36 * Create a configuration header file to tidy up command lines.
38 * Revision 1.2 2001/02/03 22:40:29 mdw
39 * Put timer information into the entropy pool when packets are received
40 * and on similar events. Reseed the generator on the interval timer.
42 * Revision 1.1 2001/02/03 20:26:37 mdw
54 /*----- Header files ------------------------------------------------------*/
69 #include <sys/types.h>
75 #include <sys/socket.h>
77 #include <netinet/in.h>
78 #include <arpa/inet.h>
84 #include <mLib/alloc.h>
85 #include <mLib/arena.h>
86 #include <mLib/bres.h>
87 #include <mLib/dstr.h>
89 #include <mLib/fdflags.h>
90 #include <mLib/fwatch.h>
91 #include <mLib/mdwopt.h>
92 #include <mLib/quis.h>
93 #include <mLib/report.h>
95 #include <mLib/selbuf.h>
99 #include <mLib/trace.h>
101 #include <catacomb/gcipher.h>
102 #include <catacomb/gmac.h>
103 #include <catacomb/grand.h>
104 #include <catacomb/key.h>
105 #include <catacomb/paranoia.h>
107 #include <catacomb/blowfish.h>
108 #include <catacomb/blowfish-cbc.h>
109 #include <catacomb/noise.h>
110 #include <catacomb/rand.h>
111 #include <catacomb/rmd160.h>
112 #include <catacomb/rmd160-hmac.h>
114 #include <catacomb/mp.h>
115 #include <catacomb/mpmont.h>
116 #include <catacomb/mprand.h>
117 #include <catacomb/dh.h>
123 /*----- Magic numbers -----------------------------------------------------*/
125 /* --- Tunnel types --- */
131 /* --- Trace flags --- */
139 #define T_KEYEXCH 64u
140 #define T_KEYMGMT 128u
146 #define SEC(n) (n##u)
147 #define MIN(n) (n##u * 60u)
148 #define MEG(n) (n##ul * 1024ul * 1024ul)
150 /* --- Other things --- */
152 #define PKBUFSZ 65536
154 /*----- TrIPE protocol ----------------------------------------------------*/
156 /* --- TrIPE packet format --- *
158 * A packet begins with a single-byte packet type. The remaining data
159 * depends on the packet type.
162 #define MSG_PACKET 0u
163 /* Followed by a 64-bit MAC and an encrypted packet. The MAC is used as an
164 * IV for a 64-bit block cipher in CBC-stealing mode.
167 #define MSG_PRECHALLENGE 1u
168 /* Followed by the challenge only. Useful for bootstrapping the system.
171 #define MSG_CHALLENGE 2u
172 /* Followed by a response hash and a large-integer challenge.
175 #define MSG_RESPONSE 3u
176 /* Followed by a large-integer response.
179 /*----- Data structures ---------------------------------------------------*/
183 * Buffers provide a simple stream-like interface for building and parsing
188 octet *base, *p, *limit; /* Pointers to the buffer */
189 unsigned f; /* Various flags */
192 #define BF_BROKEN 1u /* Buffer is broken */
194 /* --- Socket addresses --- *
196 * A magic union of supported socket addresses.
201 struct sockaddr_in sin;
204 /* --- A symmetric keyset --- *
206 * A keyset contains a set of symmetric keys for encrypting and decrypting
207 * packets. Keysets are stored in a list, sorted in reverse order of
208 * creation, so that the most recent keyset (the one most likely to be used)
211 * Each keyset has a time limit and a data limit. The keyset is destroyed
212 * when either it has existed for too long, or it has been used to encrypt
213 * too much data. New key exchanges are triggered when keys are close to
217 typedef struct keyset {
218 struct keyset *next; /* Next active keyset in the list */
219 time_t t_exp; /* Expiry time for this keyset */
220 unsigned long sz_exp; /* Data limit for the keyset */
222 unsigned seq; /* Sequence number for tracing */
224 gcipher *c; /* Keyset cipher for encryption */
225 gmac *m; /* Keyset MAC for integrity */
226 uint32 oseq; /* Outbound sequence number */
227 uint32 iseq, iwin; /* Inbound sequence number */
230 #define KS_SEQWINSZ 32 /* Bits in sequence number window */
232 /* --- Key exchange --- *
234 * TrIPE uses the Wrestlers Protocol for its key exchange. The Wrestlers
235 * Protocol has a number of desirable features (e.g., perfect forward
236 * secrecy, and zero-knowledge authentication) which make it attractive for
237 * use in TrIPE. The Wrestlers Protocol was designed by Mark Wooding and
241 typedef struct keyexch {
242 keyset **ks; /* Peer's list of keysets */
243 struct peer *p; /* Pointer back to the peer */
244 unsigned f; /* Various useful flags */
245 sel_timer t; /* Timer for next exchange */
246 dh_pub kpub; /* Peer's public key */
247 mp *my_x, *my_gx, *my_gxy; /* My half of the exchange */
248 octet my_h[RMD160_HASHSZ]; /* My challenge hash */
249 mp *your_gx, *your_gxy; /* Your half of the exchange */
250 octet your_h[RMD160_HASHSZ]; /* Your challenge hash */
251 time_t t_valid; /* When this exchange goes bad */
252 time_t t_qchal, t_qresp; /* Quiet timers for packet types */
253 time_t t_newchal; /* When to accept a new challenge */
256 #define KXF_TIMER 1u /* Waiting for a timer to go off */
257 #define KXF_INIT 2u /* Big numbers are initialized */
258 #define KXF_MYH 4u /* My hash has been computed */
259 #define KXF_YOURH 8u /* Your hash has been received */
260 #define KXF_REPLY 16u /* Received your response OK */
261 #define KXF_DONE 32u /* Key exchange completed */
263 /* --- Tunnel structure --- *
265 * Used to maintain system-specific information about the tunnel interface.
268 typedef struct tunnel {
269 #if TUN_TYPE == TUN_UNET
270 sel_file f; /* Selector for Usernet device */
271 struct peer *p; /* Pointer to my peer */
272 #elif TUN_TYPE == TUN_BSD
273 sel_file f; /* Selector for tunnel device */
274 struct peer *p; /* Pointer to my peer */
275 unsigned n; /* Number of my tunnel device */
277 # error "No support for this tunnel type"
281 /* --- Peer structure --- *
283 * The main structure which glues everything else together.
286 typedef struct peer {
287 struct peer *next, *prev; /* Links to next and previous */
288 char *name; /* Name of this peer */
289 tunnel t; /* Tunnel for local packets */
290 keyset *ks; /* List head for keysets */
291 keyexch kx; /* Key exchange protocol block */
292 buf b; /* Buffer for sending packets */
293 addr peer; /* Peer socket address */
294 size_t sasz; /* Socket address size */
297 /* --- Admin structure --- */
299 typedef struct admin {
300 struct admin *next, *prev; /* Links to next and previous */
301 selbuf b; /* Line buffer for commands */
302 int fd; /* File descriptor for output */
304 unsigned seq; /* Sequence number for tracing */
306 char *pname; /* Peer name to create */
307 char *paddr; /* Address string to resolve */
308 bres_client r; /* Background resolver task */
309 sel_timer t; /* Timer for resolver */
310 addr peer; /* Address to set */
311 size_t sasz; /* Size of the address */
314 /*----- Global variables --------------------------------------------------*/
316 extern sel_state sel; /* Global I/O event state */
317 extern dh_priv kpriv; /* Our private key */
318 extern mpmont mg; /* Montgomery context for DH group */
319 extern octet buf_i[PKBUFSZ], buf_o[PKBUFSZ]; /* Big packet buffers */
322 extern const trace_opt tr_opts[]; /* Trace options array */
323 extern unsigned tr_flags; /* Trace options flags */
326 /*----- Other macros ------------------------------------------------------*/
328 #define TIMER noise_timer(RAND_GLOBAL)
330 /*----- Key management ----------------------------------------------------*/
332 /* --- @km_interval@ --- *
336 * Returns: Zero if OK, nonzero to force reloading of keys.
338 * Use: Called on the interval timer to perform various useful jobs.
341 extern int km_interval(void);
343 /* --- @km_init@ --- *
345 * Arguments: @const char *kr_priv@ = private keyring file
346 * @const char *kr_pub@ = public keyring file
347 * @const char *tag@ = tag to load
351 * Use: Initializes, and loads the private key.
354 extern void km_init(const char */*kr_priv*/, const char */*kr_pub*/,
355 const char */*tag*/);
357 /* --- @km_getpubkey@ --- *
359 * Arguments: @const char *tag@ = public key tag to load
360 * @dh_pub *kpub@ = where to put the public key
362 * Returns: Zero if OK, nonzero if it failed.
364 * Use: Fetches a public key from the keyring.
367 extern int km_getpubkey(const char */*tag*/, dh_pub */*kpub*/);
369 /*----- Key exchange ------------------------------------------------------*/
371 /* --- @kx_start@ --- *
373 * Arguments: @keyexch *kx@ = pointer to key exchange context
377 * Use: Stimulates a key exchange. If a key exchage is in progress,
378 * a new challenge is sent (unless the quiet timer forbids
379 * this); if no exchange is in progress, one is commenced.
382 extern void kx_start(keyexch */*kx*/);
384 /* --- @kx_prechallenge@ --- *
386 * Arguments: @keyexch *kx@ = pointer to key exhange context
387 * @buf *b@ = pointer to buffer containing the packet
391 * Use: Reads a prechallenge packet from the buffer and handles it.
394 extern void kx_prechallenge(keyexch */*kx*/, buf */*b*/);
396 /* --- @kx_challenge@ --- *
398 * Arguments: @keyexch *kx@ = pointer to key exchange context
399 * @buf *b@ = a buffer containing the packet to read
403 * Use: Reads a challenge from the buffer and handles it.
406 extern void kx_challenge(keyexch */*kx*/, buf */*b*/);
408 /* --- @kx_response@ --- *
410 * Arguments: @keyexch *kx@ = pointer to key exchange context
411 * @buf *b@ = a buffer containing the packet to read
415 * Use: Reads a response from the buffer and handles it.
418 extern void kx_response(keyexch */*kx*/, buf */*b*/);
420 /* --- @kx_free@ --- *
422 * Arguments: @keyexch *kx@ = pointer to key exchange context
426 * Use: Frees everything in a key exchange context.
429 extern void kx_free(keyexch */*kx*/);
431 /* --- @kx_newkeys@ --- *
433 * Arguments: @keyexch *kx@ = pointer to key exchange context
437 * Use: Informs the key exchange module that its keys may have
438 * changed. If fetching the new keys fails, the peer will be
439 * destroyed, we log messages and struggle along with the old
443 extern void kx_newkeys(keyexch */*kx*/);
445 /* --- @kx_init@ --- *
447 * Arguments: @keyexch *kx@ = pointer to key exchange context
448 * @peer *p@ = pointer to peer context
449 * @keyset **ks@ = pointer to keyset list
451 * Returns: Zero if OK, nonzero if it failed.
453 * Use: Initializes a key exchange module. The module currently
454 * contains no keys, and will attempt to initiate a key
458 extern int kx_init(keyexch */*kx*/, peer */*p*/, keyset **/*ks*/);
460 /*----- Keysets and symmetric cryptography --------------------------------*/
462 /* --- @ks_free@ --- *
464 * Arguments: @keyset **ksroot@ = pointer to keyset list head
468 * Use: Frees all of the keys in a keyset.
471 extern void ks_free(keyset **/*ksroot*/);
473 /* --- @ks_prune@ --- *
475 * Arguments: @keyset **ksroot@ = pointer to keyset list head
479 * Use: Prunes the keyset list by removing keys which mustn't be used
483 extern void ks_prune(keyset **/*ksroot*/);
485 /* --- @ks_gen@ --- *
487 * Arguments: @keyset **ksroot@ = pointer to keyset list head
488 * @const void *k@ = pointer to key material
489 * @size_t sz@ = size of the key material
491 * Returns: The regeneration time for the new key.
493 * Use: Derives a keyset from the given key material and adds it to
497 extern time_t ks_gen(keyset **/*ksroot*/, const void */*k*/, size_t /*sz*/);
499 /* --- @ks_encrypt@ --- *
501 * Arguments: @keyset **ksroot@ = pointer to keyset list head
502 * @buf *b@ = pointer to input buffer
503 * @buf *bb@ = pointer to output buffer
505 * Returns: Nonzero if a new key is needed.
507 * Use: Encrypts a packet.
510 extern int ks_encrypt(keyset **/*ksroot*/, buf */*b*/, buf */*bb*/);
512 /* --- @ks_decrypt@ --- *
514 * Arguments: @keyset **ksroot@ = pointer to keyset list head
515 * @buf *b@ = pointer to input buffer
516 * @buf *bb@ = pointer to output buffer
518 * Returns: Nonzero if the packet couldn't be decrypted.
520 * Use: Decrypts a packet.
523 extern int ks_decrypt(keyset **/*ksroot*/, buf */*b*/, buf */*bb*/);
525 /*----- Administration interface ------------------------------------------*/
527 /* --- @a_warn@ --- *
529 * Arguments: @const char *fmt@ = pointer to format string
530 * @...@ = other arguments
534 * Use: Informs all admin connections of a warning.
537 extern void a_warn(const char */*fmt*/, ...);
539 /* --- @a_create@ --- *
541 * Arguments: @int fd_in, fd_out@ = file descriptors to use
545 * Use: Creates a new admin connection.
548 extern void a_create(int /*fd_in*/, int /*fd_out*/);
550 /* --- @a_quit@ --- *
556 * Use: Shuts things down nicely.
559 extern void a_quit(void);
561 /* --- @a_daemon@ --- *
567 * Use: Informs the admin module that it's a daemon.
570 extern void a_daemon(void);
572 /* --- @a_init@ --- *
574 * Arguments: @const char *sock@ = socket name to create
578 * Use: Creates the admin listening socket.
581 extern void a_init(const char */*sock*/);
583 /*----- Peer management ---------------------------------------------------*/
585 /* --- @p_txstart@ --- *
587 * Arguments: @peer *p@ = pointer to peer block
588 * @unsigned msg@ = message type code
590 * Returns: A pointer to a buffer to write to.
592 * Use: Starts sending to a peer. Only one send can happen at a
596 extern buf *p_txstart(peer */*p*/, unsigned /*msg*/);
598 /* --- @p_txend@ --- *
600 * Arguments: @peer *p@ = pointer to peer block
604 * Use: Sends a packet to the peer.
607 extern void p_txend(peer */*p*/);
611 * Arguments: @peer *p@ = pointer to peer block
612 * @buf *b@ = buffer containing incoming packet
616 * Use: Handles a packet which needs to be sent to a peer.
619 extern void p_tun(peer */*p*/, buf */*b*/);
621 /* --- @p_interval@ --- *
627 * Use: Called periodically to do tidying.
630 extern void p_interval(void);
632 /* --- @p_ifname@ --- *
634 * Arguments: @peer *p@ = pointer to a peer block
636 * Returns: A pointer to the peer's interface name.
639 extern const char *p_ifname(peer */*p*/);
641 /* --- @p_addr@ --- *
643 * Arguments: @peer *p@ = pointer to a peer block
645 * Returns: A pointer to the peer's address.
648 extern const addr *p_addr(peer */*p*/);
650 /* --- @p_init@ --- *
652 * Arguments: @unsigned port@ = port number to listen to
656 * Use: Initializes the peer system; creates the socket.
659 extern void p_init(unsigned /*port*/);
661 /* --- @p_port@ --- *
665 * Returns: Port number used for socket.
668 unsigned p_port(void);
670 /* --- @p_create@ --- *
672 * Arguments: @const char *name@ = name for this peer
673 * @struct sockaddr *sa@ = socket address of peer
674 * @size_t sz@ = size of socket address
676 * Returns: Pointer to the peer block, or null if it failed.
678 * Use: Creates a new named peer block. No peer is actually attached
682 extern peer *p_create(const char */*name*/,
683 struct sockaddr */*sa*/, size_t /*sz*/);
685 /* --- @p_name@ --- *
687 * Arguments: @peer *p@ = pointer to a peer block
689 * Returns: A pointer to the peer's name.
692 extern const char *p_name(peer */*p*/);
694 /* --- @p_find@ --- *
696 * Arguments: @const char *name@ = name to look up
698 * Returns: Pointer to the peer block, or null if not found.
700 * Use: Finds a peer by name.
703 extern peer *p_find(const char */*name*/);
705 /* --- @p_destroy@ --- *
707 * Arguments: @peer *p@ = pointer to a peer
711 * Use: Destroys a peer.
714 extern void p_destroy(peer */*p*/);
716 /* --- @p_first@, @p_next@ --- *
718 * Arguments: @peer *p@ = a peer block
720 * Returns: @peer_first@ returns the first peer in some ordering;
721 * @peer_next@ returns the peer following a given one in the
722 * same ordering. Null is returned for the end of the list.
725 extern peer *p_first(void);
726 extern peer *p_next(peer */*p*/);
728 /*----- Tunnel interface --------------------------------------------------*/
730 /* --- @tun_init@ --- *
736 * Use: Initializes the tunneling system. Maybe this will require
737 * opening file descriptors or something.
740 extern void tun_init(void);
742 /* --- @tun_create@ --- *
744 * Arguments: @tunnel *t@ = pointer to tunnel block
745 * @peer *p@ = pointer to peer block
747 * Returns: Zero if it worked, nonzero on failure.
749 * Use: Initializes a new tunnel.
752 extern int tun_create(tunnel */*t*/, peer */*p*/);
754 /* --- @tun_ifname@ --- *
756 * Arguments: @tunnel *t@ = pointer to tunnel block
758 * Returns: A pointer to the tunnel's interface name.
761 extern const char *tun_ifname(tunnel */*t*/);
763 /* --- @tun_inject@ --- *
765 * Arguments: @tunnel *t@ = pointer to tunnel block
766 * @buf *b@ = buffer to send
770 * Use: Injects a packet into the local network stack.
773 extern void tun_inject(tunnel */*t*/, buf */*b*/);
775 /* --- @tun_destroy@ --- *
777 * Arguments: @tunnel *t@ = pointer to tunnel block
781 * Use: Destroys a tunnel.
784 extern void tun_destroy(tunnel */*t*/);
786 /*----- Buffer handling ---------------------------------------------------*/
788 /* --- Useful macros --- */
790 #define BBASE(b) ((b)->base)
791 #define BLIM(b) ((b)->limit)
792 #define BCUR(b) ((b)->p)
793 #define BSZ(b) ((b)->limit - (b)->base)
794 #define BLEN(b) ((b)->p - (b)->base)
795 #define BLEFT(b) ((b)->limit - (b)->p)
796 #define BSTEP(b, sz) ((b)->p += (sz))
797 #define BBAD(b) ((b)->f & BF_BROKEN)
798 #define BOK(b) (!BBAD(b))
800 #define BENSURE(b, sz) \
801 (BBAD(b) ? -1 : (sz) > BLEFT(b) ? (b)->f |= BF_BROKEN, -1 : 0)
803 /* --- @buf_init@ --- *
805 * Arguments: @buf *b@ = pointer to a buffer block
806 * @void *p@ = pointer to a buffer
807 * @size_t sz@ = size of the buffer
811 * Use: Initializes the buffer block appropriately.
814 extern void buf_init(buf */*b*/, void */*p*/, size_t /*sz*/);
816 /* --- @buf_break@ --- *
818 * Arguments: @buf *b@ = pointer to a buffer block
820 * Returns: Some negative value.
822 * Use: Marks a buffer as broken.
825 extern int buf_break(buf */*b*/);
827 /* --- @buf_ensure@ --- *
829 * Arguments: @buf *b@ = pointer to a buffer block
830 * @size_t sz@ = size of data wanted
832 * Returns: Zero if it worked, nonzero if there wasn't enough space.
834 * Use: Ensures that there are @sz@ bytes still in the buffer.
837 extern int buf_ensure(buf */*b*/, size_t /*sz*/);
839 /* --- @buf_get@ --- *
841 * Arguments: @buf *b@ = pointer to a buffer block
842 * @void *p@ = pointer to a buffer
843 * @size_t sz@ = size of the buffer
845 * Returns: Zero if it worked, nonzero if there wasn't enough data.
847 * Use: Fetches data from the buffer into some other place.
850 extern int buf_get(buf */*b*/, void */*p*/, size_t /*sz*/);
852 /* --- @buf_put@ --- *
854 * Arguments: @buf *b@ = pointer to a buffer block
855 * @const void *p@ = pointer to a buffer
856 * @size_t sz@ = size of the buffer
858 * Returns: Zero if it worked, nonzero if there wasn't enough space.
860 * Use: Fetches data from some place and puts it in the buffer
863 extern int buf_put(buf */*b*/, const void */*p*/, size_t /*sz*/);
865 /* --- @buf_getbyte@ --- *
867 * Arguments: @buf *b@ = pointer to a buffer block
869 * Returns: A byte, or less than zero if there wasn't a byte there.
871 * Use: Gets a single byte from a buffer.
874 extern int buf_getbyte(buf */*b*/);
876 /* --- @buf_putbyte@ --- *
878 * Arguments: @buf *b@ = pointer to a buffer block
879 * @int ch@ = byte to write
881 * Returns: Zero if OK, nonzero if there wasn't enough space.
883 * Use: Puts a single byte in a buffer.
886 extern int buf_putbyte(buf */*b*/, int /*ch*/);
888 /* --- @buf_getword@ --- *
890 * Arguments: @buf *b@ = pointer to a buffer block
891 * @uint32 *w@ = where to put the word
893 * Returns: Zero if OK, or nonzero if there wasn't a word there.
895 * Use: Gets a 32-bit word from a buffer.
898 extern int buf_getword(buf */*b*/, uint32 */*w*/);
900 /* --- @buf_putword@ --- *
902 * Arguments: @buf *b@ = pointer to a buffer block
903 * @uint32 w@ = word to write
905 * Returns: Zero if OK, nonzero if there wasn't enough space.
907 * Use: Puts a 32-but word in a buffer.
910 extern int buf_putword(buf */*b*/, uint32 /*w*/);
912 /* --- @buf_getmp@ --- *
914 * Arguments: @buf *b@ = pointer to a buffer block
916 * Returns: A multiprecision integer, or null if there wasn't one there.
918 * Use: Gets a multiprecision integer from a buffer.
921 extern mp *buf_getmp(buf */*b*/, mp */*d*/);
923 /* --- @buf_putmp@ --- *
925 * Arguments: @buf *b@ = pointer to a buffer block
926 * @mp *m@ = a multiprecision integer
928 * Returns: Zero if it worked, nonzero if there wasn't enough space.
930 * Use: Puts a multiprecision integer to a buffer.
933 extern int buf_putmp(buf */*b*/, mp */*m*/);
935 /*----- Other handy utilities ---------------------------------------------*/
939 * Arguments: @mp *m@ = a multiprecision integer
941 * Returns: A pointer to the integer's textual representation.
943 * Use: Converts a multiprecision integer to a string. Corrupts
947 extern const char *mpstr(mp */*m*/);
949 /*----- That's all, folks -------------------------------------------------*/