chiark / gitweb /
Rearrange so as not to include Linux headers unless we need to.
[tripe] / tripe.h
1 /* -*-c-*-
2  *
3  * $Id: tripe.h,v 1.14 2003/04/06 10:36:33 mdw Exp $
4  *
5  * Main header file for TrIPE
6  *
7  * (c) 2001 Straylight/Edgeware
8  */
9
10 /*----- Licensing notice --------------------------------------------------* 
11  *
12  * This file is part of Trivial IP Encryption (TrIPE).
13  *
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.
18  * 
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.
23  * 
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.
27  */
28
29 /*----- Revision history --------------------------------------------------* 
30  *
31  * $Log: tripe.h,v $
32  * Revision 1.14  2003/04/06 10:36:33  mdw
33  * Rearrange so as not to include Linux headers unless we need to.
34  *
35  * Revision 1.13  2003/04/06 10:26:35  mdw
36  * Report peer name on decrypt errors.
37  *
38  * Revision 1.12  2003/04/06 10:25:17  mdw
39  * Support Linux TUN/TAP device.  Fix some bugs.
40  *
41  * Revision 1.11  2002/01/13 14:57:42  mdw
42  * Fix crap typo.
43  *
44  * Revision 1.10  2002/01/13 14:54:58  mdw
45  * Provide MGF macros.
46  *
47  * Revision 1.9  2001/06/22 19:40:36  mdw
48  * Support expiry of other peers' public keys.
49  *
50  * Revision 1.8  2001/06/19 22:10:57  mdw
51  * Some more constants for the algorithms.  Document the packet format
52  * change for non-malleability.  Moved @buf@ definitions to separate header
53  * file.
54  *
55  * Revision 1.7  2001/03/03 12:07:08  mdw
56  * Rename word get and put functions now that there's 16-bit support.
57  *
58  * Revision 1.6  2001/02/19 19:11:09  mdw
59  * Output buffering on admin connections.
60  *
61  * Revision 1.5  2001/02/16 21:41:43  mdw
62  * Major changes.  See source files for details.
63  *
64  * Revision 1.4  2001/02/05 19:56:37  mdw
65  * Sequence number protection, and BSD tunnels.
66  *
67  * Revision 1.3  2001/02/04 01:17:55  mdw
68  * Create a configuration header file to tidy up command lines.
69  *
70  * Revision 1.2  2001/02/03 22:40:29  mdw
71  * Put timer information into the entropy pool when packets are received
72  * and on similar events.  Reseed the generator on the interval timer.
73  *
74  * Revision 1.1  2001/02/03 20:26:37  mdw
75  * Initial checkin.
76  *
77  */
78
79 #ifndef TRIPE_H
80 #define TRIPE_H
81
82 #ifdef __cplusplus
83   extern "C" {
84 #endif
85
86 /*----- Header files ------------------------------------------------------*/
87
88 #include "config.h"
89
90 #include <assert.h>
91 #include <ctype.h>
92 #include <errno.h>
93 #include <signal.h>
94 #include <stdarg.h>
95 #include <stddef.h>
96 #include <stdio.h>
97 #include <stdlib.h>
98 #include <string.h>
99 #include <time.h>
100
101 #include <sys/types.h>
102 #include <sys/time.h>
103 #include <unistd.h>
104 #include <fcntl.h>
105 #include <sys/stat.h>
106
107 #include <sys/socket.h>
108 #include <sys/un.h>
109 #include <netinet/in.h>
110 #include <arpa/inet.h>
111 #include <netdb.h>
112
113 #include <pwd.h>
114 #include <grp.h>
115
116 #include <mLib/alloc.h>
117 #include <mLib/arena.h>
118 #include <mLib/bres.h>
119 #include <mLib/dstr.h>
120 #include <mLib/env.h>
121 #include <mLib/fdflags.h>
122 #include <mLib/fwatch.h>
123 #include <mLib/mdwopt.h>
124 #include <mLib/quis.h>
125 #include <mLib/report.h>
126 #include <mLib/sel.h>
127 #include <mLib/selbuf.h>
128 #include <mLib/sig.h>
129 #include <mLib/str.h>
130 #include <mLib/sub.h>
131 #include <mLib/trace.h>
132
133 #include <catacomb/gcipher.h>
134 #include <catacomb/gmac.h>
135 #include <catacomb/grand.h>
136 #include <catacomb/key.h>
137 #include <catacomb/paranoia.h>
138
139 #include <catacomb/noise.h>
140 #include <catacomb/rand.h>
141
142 #include <catacomb/mp.h>
143 #include <catacomb/mpmont.h>
144 #include <catacomb/mprand.h>
145 #include <catacomb/dh.h>
146
147 #include "buf.h"
148 #include "util.h"
149
150 #undef sun
151
152 /*----- Magic numbers -----------------------------------------------------*/
153
154 /* --- Tunnel types --- */
155
156 #define TUN_NOTDEF 0
157 #define TUN_UNET 1
158 #define TUN_BSD 2
159 #define TUN_LINUX 3
160
161 /* --- Trace flags --- */
162
163 #define T_TUNNEL 1u
164 #define T_PEER 2u
165 #define T_PACKET 4u
166 #define T_ADMIN 8u
167 #define T_CRYPTO 16u
168 #define T_KEYSET 32u
169 #define T_KEYEXCH 64u
170 #define T_KEYMGMT 128u
171
172 #define T_ALL 255u
173
174 /* --- Units --- */
175
176 #define SEC(n) (n##u)
177 #define MIN(n) (n##u * 60u)
178 #define MEG(n) (n##ul * 1024ul * 1024ul)
179
180 /* --- Other things --- */
181
182 #define PKBUFSZ 65536
183
184 /*----- TrIPE protocol ----------------------------------------------------*/
185
186 /* --- TrIPE message format --- *
187  *
188  * A packet begins with a single-byte message type.  The top four bits are a
189  * category code used to send the message to the right general place in the
190  * code; the bottom bits identify the actual message type.
191  */
192
193 #define MSG_CATMASK 0xf0
194 #define MSG_TYPEMASK 0x0f
195
196 /* --- Encrypted message packets --- *
197  *
198  * Messages of category @MSG_PACKET@ contain encrypted network packets.  The
199  * message content is a symmetric-encrypted block (see below).  Reception of
200  * a packet encrypted under a new key implicitly permits that key to be used
201  * to send further packets.
202  *
203  * The only packet type accepted is zero.
204  *
205  * Packets may be encrypted under any live keyset, but should use the most
206  * recent one.
207  */
208
209 #define MSG_PACKET 0x00
210
211 /* --- Key exchange packets --- */
212
213 #define MSG_KEYEXCH 0x10
214
215 #define KX_PRECHAL 0u
216 #define KX_COOKIE 1u
217 #define KX_CHAL 2u
218 #define KX_REPLY 3u
219 #define KX_SWITCH 4u
220 #define KX_SWITCHOK 5u
221 #define KX_NMSG 6u
222
223 /* --- Symmetric encryption and keysets --- *
224  *
225  * Packets consist of an 80-bit MAC, a 32-bit sequence number, and the
226  * encrypted payload.
227  *
228  * The plaintext is encrypted using Blowfish in CBC mode with ciphertext
229  * stealing (as described in [Schneier].  The initialization vector is
230  * selected randomly, and prepended to the actual ciphertext.
231  *
232  * The MAC is computed using the HMAC construction with RIPEMD160 over the
233  * sequence number and the ciphertext (with IV); the first 80 bits of the
234  * output are used.  (This is the minimum allowed by the draft FIPS for HMAC,
235  * and the recommended truncation.)
236  *
237  * A keyset consists of
238  *
239  *   * an integrity (MAC) key;
240  *   * a confidentiality (encryption) key; and
241  *   * a sequence numbering space
242  *
243  * in each direction.  The packets sent by a host encrypted under a
244  * particular keyset are assigned consecutive sequence numbers starting from
245  * zero.  The receiving host must ensure that it only accepts each packet at
246  * most once.  It should maintain a window of sequence numbers: packets with
247  * numbers beyond the end of the window are accepted and cause the window to
248  * be advanced; packets with numbers before the start of the window are
249  * rejected; packets with numbers which appear within the window are accepted
250  * only if the number has not been seen before.
251  *
252  * When a host sends a @KX_SWITCH@ or @KX_SWITCHOK@ message, it installs the
253  * newly-negotiated keyset in a `listen-only' state: it may not send a packet
254  * encrypted under the keyset until either it has received a @KX_SWITCH@ or
255  * @KX_SWITCHOK@ message, or a @MSG_PACKET@ encrypted under the keyset, from
256  * its peer.
257  */
258
259 /*----- Cipher selections -------------------------------------------------*/
260
261 #include <catacomb/blowfish.h>
262 #include <catacomb/blowfish-cbc.h>
263 #include <catacomb/blowfish-counter.h>
264 #include <catacomb/rmd160.h>
265 #include <catacomb/rmd160-hmac.h>
266
267 #define CIPHER (&blowfish_cbc)
268 #define MAC (&rmd160_hmac)
269
270 #define HASH_CTX rmd160_ctx
271 #define HASH_INIT rmd160_init
272 #define HASH rmd160_hash
273 #define HASH_STRING(c, s) HASH((c), s, sizeof(s))
274 #define HASH_DONE rmd160_done
275 #define HASHSZ RMD160_HASHSZ
276
277 #define MGF_CTX blowfish_counterctx
278 #define MGF_INIT blowfish_counterinit
279 #define MGF_CRYPT blowfish_counterencrypt
280
281 #define SEQSZ 4
282 #define IVSZ BLOWFISH_BLKSZ
283 #define MACSZ 10
284
285 /*----- Data structures ---------------------------------------------------*/
286
287 /* --- Socket addresses --- *
288  *
289  * A magic union of supported socket addresses.
290  */
291
292 typedef union addr {
293   struct sockaddr sa;
294   struct sockaddr_in sin;
295 } addr;
296
297 /* --- A symmetric keyset --- *
298  *
299  * A keyset contains a set of symmetric keys for encrypting and decrypting
300  * packets.  Keysets are stored in a list, sorted in reverse order of
301  * creation, so that the most recent keyset (the one most likely to be used)
302  * is first.
303  *
304  * Each keyset has a time limit and a data limit.  The keyset is destroyed
305  * when either it has existed for too long, or it has been used to encrypt
306  * too much data.  New key exchanges are triggered when keys are close to
307  * expiry.
308  */
309
310 typedef struct keyset {
311   struct keyset *next;                  /* Next active keyset in the list */
312   unsigned ref;                         /* Reference count for keyset */
313   struct peer *p;                       /* Pointer to peer structure */
314   time_t t_exp;                         /* Expiry time for this keyset */
315   unsigned long sz_exp;                 /* Data limit for the keyset */
316   T( unsigned seq; )                    /* Sequence number for tracing */
317   unsigned f;                           /* Various useful flags */
318   gcipher *cin, *cout;                  /* Keyset ciphers for encryption */
319   gmac *min, *mout;                     /* Keyset MACs for integrity */
320   uint32 oseq;                          /* Outbound sequence number */
321   uint32 iseq, iwin;                    /* Inbound sequence number */
322 } keyset;
323
324 #define KS_SEQWINSZ 32                  /* Bits in sequence number window */
325
326 #define KSF_LISTEN 1u                   /* Don't encrypt packets yet */
327 #define KSF_LINK 2u                     /* Key is in a linked list */
328
329 /* --- Key exchange --- *
330  *
331  * TrIPE uses the Wrestlers Protocol for its key exchange.  The Wrestlers
332  * Protocol has a number of desirable features (e.g., perfect forward
333  * secrecy, and zero-knowledge authentication) which make it attractive for
334  * use in TrIPE.  The Wrestlers Protocol was designed by Mark Wooding and
335  * Clive Jones.
336  */
337
338 #define KX_NCHAL 16u
339 #define KX_THRESH 4u
340
341 typedef struct kxchal {
342   struct keyexch *kx;                   /* Pointer back to key exchange */
343   mp *c;                                /* Responder's challenge */
344   mp *r;                                /* My reply to the challenge */
345   keyset *ks;                           /* Pointer to temporary keyset */
346   unsigned f;                           /* Various useful flags */
347   sel_timer t;                          /* Response timer for challenge */
348   octet hc[HASHSZ];                     /* Hash of his challenge */
349   mp *ck;                               /* The check value */
350   octet hswrq_in[HASHSZ];               /* Inbound switch request message */
351   octet hswok_in[HASHSZ];               /* Inbound switch confirmation */
352   octet hswrq_out[HASHSZ];              /* Outbound switch request message */
353   octet hswok_out[HASHSZ];              /* Outbound switch confirmation */
354 } kxchal;
355
356 typedef struct keyexch {
357   struct peer *p;                       /* Pointer back to the peer */
358   keyset **ks;                          /* Peer's list of keysets */
359   unsigned f;                           /* Various useful flags */
360   unsigned s;                           /* Current state in exchange */
361   sel_timer t;                          /* Timer for next exchange */
362   dh_pub kpub;                          /* Peer's public key */
363   time_t texp_kpub;                     /* Expiry time for public key */
364   mp *alpha;                            /* My temporary secret */
365   mp *c;                                /* My challenge */
366   mp *rx;                               /* The expected response */
367   unsigned nr;                          /* Number of extant responses */
368   time_t t_valid;                       /* When this exchange goes bad */
369   octet hc[HASHSZ];                     /* Hash of my challenge */
370   kxchal *r[KX_NCHAL];                  /* Array of challenges */
371 } keyexch;
372
373 #define KXF_TIMER 1u                    /* Waiting for a timer to go off */
374 #define KXF_DEAD 2u                     /* The key-exchanger isn't up */
375 #define KXF_PUBKEY 4u                   /* Key exchanger has a public key */
376
377 enum {
378   KXS_DEAD,                             /* Uninitialized state (magical) */
379   KXS_CHAL,                             /* Main answer-challenges state */
380   KXS_COMMIT,                           /* Committed: send switch request */
381   KXS_SWITCH                            /* Switched: send confirmation */
382 };
383
384 /* --- Tunnel structure --- *
385  *
386  * Used to maintain system-specific information about the tunnel interface.
387  */
388
389 #if TUN_TYPE == TUN_LINUX
390 #  include <linux/if.h>
391 #  include <linux/if_tun.h>
392 #endif
393
394 typedef struct tunnel {
395 #if TUN_TYPE == TUN_UNET 
396   sel_file f;                           /* Selector for Usernet device */
397   struct peer *p;                       /* Pointer to my peer */
398 #elif TUN_TYPE == TUN_LINUX
399   sel_file f;                           /* Selector for TUN/TAP device */
400   struct peer *p;                       /* Pointer to my peer */
401   char ifn[IFNAMSIZ];                   /* Interface name buffer */
402 #elif TUN_TYPE == TUN_BSD
403   sel_file f;                           /* Selector for tunnel device */
404   struct peer *p;                       /* Pointer to my peer */
405   unsigned n;                           /* Number of my tunnel device */
406 #else
407 #  error "No support for this tunnel type"
408 #endif
409 } tunnel;
410
411 /* --- Peer statistics --- *
412  *
413  * Contains various interesting and not-so-interesting statistics about a
414  * peer.  This is updated by various parts of the code.  The format of the
415  * structure isn't considered private, and @p_stats@ returns a pointer to the
416  * statistics block for a given peer.
417  */
418
419 typedef struct stats {
420   unsigned long sz_in, sz_out;          /* Size of all data in and out */
421   unsigned long sz_kxin, sz_kxout;      /* Size of key exchange messages */
422   unsigned long sz_ipin, sz_ipout;      /* Size of encapsulated IP packets */
423   time_t t_start, t_last;               /* Time peer created, last recv */
424   unsigned long n_reject;               /* Number of rejected packets */
425   unsigned long n_in, n_out;            /* Number of packets in and out */
426   unsigned long n_kxin, n_kxout;        /* Number of key exchange packets */
427   unsigned long n_ipin, n_ipout;        /* Number of encrypted packets */
428 } stats;
429
430 /* --- Peer structure --- *
431  *
432  * The main structure which glues everything else together.
433  */
434
435 typedef struct peer {
436   struct peer *next, *prev;             /* Links to next and previous */
437   char *name;                           /* Name of this peer */
438   tunnel t;                             /* Tunnel for local packets */
439   keyset *ks;                           /* List head for keysets */
440   buf b;                                /* Buffer for sending packets */
441   addr peer;                            /* Peer socket address */
442   size_t sasz;                          /* Socket address size */
443   stats st;                             /* Statistics */
444   keyexch kx;                           /* Key exchange protocol block */
445 } peer;
446
447 /* --- Admin structure --- */
448
449 #define OBUFSZ 16384u
450
451 typedef struct obuf {
452   struct obuf *next;                    /* Next buffer in list */
453   char *p_in, *p_out;                   /* Pointers into the buffer */
454   char buf[OBUFSZ];                     /* The actual buffer */
455 } obuf;
456
457 typedef struct admin {
458   struct admin *next, *prev;            /* Links to next and previous */
459   unsigned f;                           /* Various useful flags */
460 #ifndef NTRACE
461   unsigned seq;                         /* Sequence number for tracing */
462 #endif
463   char *pname;                          /* Peer name to create */
464   char *paddr;                          /* Address string to resolve */
465   obuf *o_head, *o_tail;                /* Output buffer list */
466   selbuf b;                             /* Line buffer for commands */
467   sel_file w;                           /* Selector for write buffering */
468   bres_client r;                        /* Background resolver task */
469   sel_timer t;                          /* Timer for resolver */
470   addr peer;                            /* Address to set */
471   size_t sasz;                          /* Size of the address */
472 } admin;
473
474 #define AF_DEAD 1u                      /* Destroy this admin block */
475 #define AF_LOCK 2u                      /* Don't destroy it yet */
476
477 /*----- Global variables --------------------------------------------------*/
478
479 extern sel_state sel;                   /* Global I/O event state */
480 extern dh_priv kpriv;                   /* Our private key */
481 extern mpmont mg;                       /* Montgomery context for DH group */
482 extern octet buf_i[PKBUFSZ], buf_o[PKBUFSZ], buf_t[PKBUFSZ];
483
484 #ifndef NTRACE
485 extern const trace_opt tr_opts[];       /* Trace options array */
486 extern unsigned tr_flags;               /* Trace options flags */
487 #endif
488
489 /*----- Other macros ------------------------------------------------------*/
490
491 #define TIMER noise_timer(RAND_GLOBAL)
492
493 /*----- Key management ----------------------------------------------------*/
494
495 /* --- @km_interval@ --- *
496  *
497  * Arguments:   ---
498  *
499  * Returns:     Zero if OK, nonzero to force reloading of keys.
500  *
501  * Use:         Called on the interval timer to perform various useful jobs.
502  */
503
504 extern int km_interval(void);
505
506 /* --- @km_init@ --- *
507  *
508  * Arguments:   @const char *kr_priv@ = private keyring file
509  *              @const char *kr_pub@ = public keyring file
510  *              @const char *tag@ = tag to load
511  *
512  * Returns:     ---
513  *
514  * Use:         Initializes, and loads the private key.
515  */
516
517 extern void km_init(const char */*kr_priv*/, const char */*kr_pub*/,
518                     const char */*tag*/);
519
520 /* --- @km_getpubkey@ --- *
521  *
522  * Arguments:   @const char *tag@ = public key tag to load
523  *              @dh_pub *kpub@ = where to put the public key
524  *              @time_t *t_exp@ = where to put the expiry time
525  *
526  * Returns:     Zero if OK, nonzero if it failed.
527  *
528  * Use:         Fetches a public key from the keyring.
529  */
530
531 extern int km_getpubkey(const char */*tag*/, dh_pub */*kpub*/,
532                         time_t */*t_exp*/);
533
534 /*----- Key exchange ------------------------------------------------------*/
535
536 /* --- @kx_start@ --- *
537  *
538  * Arguments:   @keyexch *kx@ = pointer to key exchange context
539  *
540  * Returns:     ---
541  *
542  * Use:         Stimulates a key exchange.  If a key exchage is in progress,
543  *              a new challenge is sent (unless the quiet timer forbids
544  *              this); if no exchange is in progress, one is commenced.
545  */
546
547 extern void kx_start(keyexch */*kx*/);
548
549 /* --- @kx_message@ --- *
550  *
551  * Arguments:   @keyexch *kx@ = pointer to key exchange context
552  *              @unsigned msg@ = the message code
553  *              @buf *b@ = pointer to buffer containing the packet
554  *
555  * Returns:     ---
556  *
557  * Use:         Reads a packet containing key exchange messages and handles
558  *              it.
559  */
560
561 extern void kx_message(keyexch */*kx*/, unsigned /*msg*/, buf */*b*/);
562
563 /* --- @kx_free@ --- *
564  *
565  * Arguments:   @keyexch *kx@ = pointer to key exchange context
566  *
567  * Returns:     ---
568  *
569  * Use:         Frees everything in a key exchange context.
570  */
571
572 extern void kx_free(keyexch */*kx*/);
573
574 /* --- @kx_newkeys@ --- *
575  *
576  * Arguments:   @keyexch *kx@ = pointer to key exchange context
577  *
578  * Returns:     ---
579  *
580  * Use:         Informs the key exchange module that its keys may have
581  *              changed.  If fetching the new keys fails, the peer will be
582  *              destroyed, we log messages and struggle along with the old
583  *              keys.
584  */
585
586 extern void kx_newkeys(keyexch */*kx*/);
587
588 /* --- @kx_init@ --- *
589  *
590  * Arguments:   @keyexch *kx@ = pointer to key exchange context
591  *              @peer *p@ = pointer to peer context
592  *              @keyset **ks@ = pointer to keyset list
593  *
594  * Returns:     Zero if OK, nonzero if it failed.
595  *
596  * Use:         Initializes a key exchange module.  The module currently
597  *              contains no keys, and will attempt to initiate a key
598  *              exchange.
599  */
600
601 extern int kx_init(keyexch */*kx*/, peer */*p*/, keyset **/*ks*/);
602
603 /*----- Keysets and symmetric cryptography --------------------------------*/
604
605 /* --- @ks_drop@ --- *
606  *
607  * Arguments:   @keyset *ks@ = pointer to a keyset
608  *
609  * Returns:     ---
610  *
611  * Use:         Decrements a keyset's reference counter.  If the counter hits
612  *              zero, the keyset is freed.
613  */
614
615 extern void ks_drop(keyset */*ks*/);
616
617 /* --- @ks_gen@ --- *
618  *
619  * Arguments:   @const void *k@ = pointer to key material
620  *              @size_t x, y, z@ = offsets into key material (see below)
621  *              @peer *p@ = pointer to peer information
622  *
623  * Returns:     A pointer to the new keyset.
624  *
625  * Use:         Derives a new keyset from the given key material.  The
626  *              offsets @x@, @y@ and @z@ separate the key material into three
627  *              parts.  Between the @k@ and @k + x@ is `my' contribution to
628  *              the key material; between @k + x@ and @k + y@ is `your'
629  *              contribution; and between @k + y@ and @k + z@ is a shared
630  *              value we made together.  These are used to construct two
631  *              pairs of symmetric keys.  Each pair consists of an encryption
632  *              key and a message authentication key.  One pair is used for
633  *              outgoing messages, the other for incoming messages.
634  *
635  *              The new key is marked so that it won't be selected for output
636  *              by @ksl_encrypt@.  You can still encrypt data with it by
637  *              calling @ks_encrypt@ directly.
638  */
639
640 extern keyset *ks_gen(const void */*k*/,
641                       size_t /*x*/, size_t /*y*/, size_t /*z*/,
642                       peer */*p*/);
643
644 /* --- @ks_tregen@ --- *
645  *
646  * Arguments:   @keyset *ks@ = pointer to a keyset
647  *
648  * Returns:     The time at which moves ought to be made to replace this key.
649  */
650
651 extern time_t ks_tregen(keyset */*ks*/);
652
653 /* --- @ks_activate@ --- *
654  *
655  * Arguments:   @keyset *ks@ = pointer to a keyset
656  *
657  * Returns:     ---
658  *
659  * Use:         Activates a keyset, so that it can be used for encrypting
660  *              outgoing messages.
661  */
662
663 extern void ks_activate(keyset */*ks*/);
664
665 /* --- @ks_encrypt@ --- *
666  *
667  * Arguments:   @keyset *ks@ = pointer to a keyset
668  *              @buf *b@ = pointer to input buffer
669  *              @buf *bb@ = pointer to output buffer
670  *
671  * Returns:     Zero if OK, nonzero if the key needs replacing.  If the
672  *              encryption failed, the output buffer is broken and zero is
673  *              returned.
674  *
675  * Use:         Encrypts a block of data using the key.  Note that the `key
676  *              ought to be replaced' notification is only ever given once
677  *              for each key.  Also note that this call forces a keyset to be
678  *              used even if it's marked as not for data output.
679  */
680
681 extern int ks_encrypt(keyset */*ks*/, buf */*b*/, buf */*bb*/);
682
683 /* --- @ks_decrypt@ --- *
684  *
685  * Arguments:   @keyset *ks@ = pointer to a keyset
686  *              @buf *b@ = pointer to an input buffer
687  *              @buf *bb@ = pointer to an output buffer
688  *
689  * Returns:     Zero on success, or nonzero if there was some problem.
690  *
691  * Use:         Attempts to decrypt a message using a given key.  Note that
692  *              requesting decryption with a key directly won't clear a
693  *              marking that it's not for encryption.
694  */
695
696 extern int ks_decrypt(keyset */*ks*/, buf */*b*/, buf */*bb*/);
697
698 /* --- @ksl_free@ --- *
699  *
700  * Arguments:   @keyset **ksroot@ = pointer to keyset list head
701  *
702  * Returns:     ---
703  *
704  * Use:         Frees (releases references to) all of the keys in a keyset.
705  */
706
707 extern void ksl_free(keyset **/*ksroot*/);
708
709 /* --- @ksl_link@ --- *
710  *
711  * Arguments:   @keyset **ksroot@ = pointer to keyset list head
712  *              @keyset *ks@ = pointer to a keyset
713  *
714  * Returns:     ---
715  *
716  * Use:         Links a keyset into a list.  A keyset can only be on one list
717  *              at a time.  Bad things happen otherwise.
718  */
719
720 extern void ksl_link(keyset **/*ksroot*/, keyset */*ks*/);
721
722 /* --- @ksl_prune@ --- *
723  *
724  * Arguments:   @keyset **ksroot@ = pointer to keyset list head
725  *
726  * Returns:     ---
727  *
728  * Use:         Prunes the keyset list by removing keys which mustn't be used
729  *              any more.
730  */
731
732 extern void ksl_prune(keyset **/*ksroot*/);
733
734 /* --- @ksl_encrypt@ --- *
735  *
736  * Arguments:   @keyset **ksroot@ = pointer to keyset list head
737  *              @buf *b@ = pointer to input buffer
738  *              @buf *bb@ = pointer to output buffer
739  *
740  * Returns:     Nonzero if a new key is needed.
741  *
742  * Use:         Encrypts a packet.
743  */
744
745 extern int ksl_encrypt(keyset **/*ksroot*/, buf */*b*/, buf */*bb*/);
746
747 /* --- @ksl_decrypt@ --- *
748  *
749  * Arguments:   @keyset **ksroot@ = pointer to keyset list head
750  *              @buf *b@ = pointer to input buffer
751  *              @buf *bb@ = pointer to output buffer
752  *
753  * Returns:     Nonzero if the packet couldn't be decrypted.
754  *
755  * Use:         Decrypts a packet.
756  */
757
758 extern int ksl_decrypt(keyset **/*ksroot*/, buf */*b*/, buf */*bb*/);
759
760 /*----- Administration interface ------------------------------------------*/
761
762 /* --- @a_warn@ --- *
763  *
764  * Arguments:   @const char *fmt@ = pointer to format string
765  *              @...@ = other arguments
766  *
767  * Returns:     ---
768  *
769  * Use:         Informs all admin connections of a warning.
770  */
771
772 extern void a_warn(const char */*fmt*/, ...);
773
774 /* --- @a_create@ --- *
775  *
776  * Arguments:   @int fd_in, fd_out@ = file descriptors to use
777  *
778  * Returns:     ---
779  *
780  * Use:         Creates a new admin connection.
781  */
782
783 extern void a_create(int /*fd_in*/, int /*fd_out*/);
784
785 /* --- @a_quit@ --- *
786  *
787  * Arguments:   ---
788  *
789  * Returns:     ---
790  *
791  * Use:         Shuts things down nicely.
792  */
793
794 extern void a_quit(void);
795
796 /* --- @a_daemon@ --- *
797  *
798  * Arguments:   ---
799  *
800  * Returns:     ---
801  *
802  * Use:         Informs the admin module that it's a daemon.
803  */
804
805 extern void a_daemon(void);
806
807 /* --- @a_init@ --- *
808  *
809  * Arguments:   @const char *sock@ = socket name to create
810  *
811  * Returns:     ---
812  *
813  * Use:         Creates the admin listening socket.
814  */
815
816 extern void a_init(const char */*sock*/);
817
818 /*----- Peer management ---------------------------------------------------*/
819
820 /* --- @p_txstart@ --- *
821  *
822  * Arguments:   @peer *p@ = pointer to peer block
823  *              @unsigned msg@ = message type code
824  *
825  * Returns:     A pointer to a buffer to write to.
826  *
827  * Use:         Starts sending to a peer.  Only one send can happen at a
828  *              time.
829  */
830
831 extern buf *p_txstart(peer */*p*/, unsigned /*msg*/);
832
833 /* --- @p_txend@ --- *
834  *
835  * Arguments:   @peer *p@ = pointer to peer block
836  *
837  * Returns:     ---
838  *
839  * Use:         Sends a packet to the peer.
840  */
841
842 extern void p_txend(peer */*p*/);
843
844 /* --- @p_tun@ --- *
845  *
846  * Arguments:   @peer *p@ = pointer to peer block
847  *              @buf *b@ = buffer containing incoming packet
848  *
849  * Returns:     ---
850  *
851  * Use:         Handles a packet which needs to be sent to a peer.
852  */
853
854 extern void p_tun(peer */*p*/, buf */*b*/);
855
856 /* --- @p_interval@ --- *
857  *
858  * Arguments:   ---
859  *
860  * Returns:     ---
861  *
862  * Use:         Called periodically to do tidying.
863  */
864
865 extern void p_interval(void);
866
867 /* --- @p_stats@ --- *
868  *
869  * Arguments:   @peer *p@ = pointer to a peer block
870  *
871  * Returns:     A pointer to the peer's statistics.
872  */
873
874 extern stats *p_stats(peer */*p*/);
875
876 /* --- @p_ifname@ --- *
877  *
878  * Arguments:   @peer *p@ = pointer to a peer block
879  *
880  * Returns:     A pointer to the peer's interface name.
881  */
882
883 extern const char *p_ifname(peer */*p*/);
884
885 /* --- @p_addr@ --- *
886  *
887  * Arguments:   @peer *p@ = pointer to a peer block
888  *
889  * Returns:     A pointer to the peer's address.
890  */
891
892 extern const addr *p_addr(peer */*p*/);
893
894 /* --- @p_init@ --- *
895  *
896  * Arguments:   @unsigned port@ = port number to listen to
897  *
898  * Returns:     ---
899  *
900  * Use:         Initializes the peer system; creates the socket.
901  */
902
903 extern void p_init(unsigned /*port*/);
904
905 /* --- @p_port@ --- *
906  *
907  * Arguments:   ---
908  *
909  * Returns:     Port number used for socket.
910  */
911
912 unsigned p_port(void);
913
914 /* --- @p_create@ --- *
915  *
916  * Arguments:   @const char *name@ = name for this peer
917  *              @struct sockaddr *sa@ = socket address of peer
918  *              @size_t sz@ = size of socket address
919  *
920  * Returns:     Pointer to the peer block, or null if it failed.
921  *
922  * Use:         Creates a new named peer block.  No peer is actually attached
923  *              by this point.
924  */
925
926 extern peer *p_create(const char */*name*/,
927                       struct sockaddr */*sa*/, size_t /*sz*/);
928
929 /* --- @p_name@ --- *
930  *
931  * Arguments:   @peer *p@ = pointer to a peer block
932  *
933  * Returns:     A pointer to the peer's name.
934  */
935
936 extern const char *p_name(peer */*p*/);
937
938 /* --- @p_find@ --- *
939  *
940  * Arguments:   @const char *name@ = name to look up
941  *
942  * Returns:     Pointer to the peer block, or null if not found.
943  *
944  * Use:         Finds a peer by name.
945  */
946
947 extern peer *p_find(const char */*name*/);
948
949 /* --- @p_destroy@ --- *
950  *
951  * Arguments:   @peer *p@ = pointer to a peer
952  *
953  * Returns:     ---
954  *
955  * Use:         Destroys a peer.
956  */
957
958 extern void p_destroy(peer */*p*/);
959
960 /* --- @p_first@, @p_next@ --- *
961  *
962  * Arguments:   @peer *p@ = a peer block
963  *
964  * Returns:     @peer_first@ returns the first peer in some ordering;
965  *              @peer_next@ returns the peer following a given one in the
966  *              same ordering.  Null is returned for the end of the list.
967  */
968
969 extern peer *p_first(void);
970 extern peer *p_next(peer */*p*/);
971
972 /*----- Tunnel interface --------------------------------------------------*/
973
974 /* --- @tun_init@ --- *
975  *
976  * Arguments:   ---
977  *
978  * Returns:     ---
979  *
980  * Use:         Initializes the tunneling system.  Maybe this will require
981  *              opening file descriptors or something.
982  */
983
984 extern void tun_init(void);
985
986 /* --- @tun_create@ --- *
987  *
988  * Arguments:   @tunnel *t@ = pointer to tunnel block
989  *              @peer *p@ = pointer to peer block
990  *
991  * Returns:     Zero if it worked, nonzero on failure.
992  *
993  * Use:         Initializes a new tunnel.
994  */
995
996 extern int tun_create(tunnel */*t*/, peer */*p*/);
997
998 /* --- @tun_ifname@ --- *
999  *
1000  * Arguments:   @tunnel *t@ = pointer to tunnel block
1001  *
1002  * Returns:     A pointer to the tunnel's interface name.
1003  */
1004
1005 extern const char *tun_ifname(tunnel */*t*/);
1006
1007 /* --- @tun_inject@ --- *
1008  *
1009  * Arguments:   @tunnel *t@ = pointer to tunnel block
1010  *              @buf *b@ = buffer to send
1011  *
1012  * Returns:     ---
1013  *
1014  * Use:         Injects a packet into the local network stack.
1015  */
1016
1017 extern void tun_inject(tunnel */*t*/, buf */*b*/);
1018
1019 /* --- @tun_destroy@ --- *
1020  *
1021  * Arguments:   @tunnel *t@ = pointer to tunnel block
1022  *
1023  * Returns:     ---
1024  *
1025  * Use:         Destroys a tunnel.
1026  */
1027
1028 extern void tun_destroy(tunnel */*t*/);
1029
1030 /*----- Other handy utilities ---------------------------------------------*/
1031
1032 /* --- @mpstr@ --- *
1033  *
1034  * Arguments:   @mp *m@ = a multiprecision integer
1035  *
1036  * Returns:     A pointer to the integer's textual representation.
1037  *
1038  * Use:         Converts a multiprecision integer to a string.  Corrupts
1039  *              @buf_t@.
1040  */
1041
1042 extern const char *mpstr(mp */*m*/);
1043
1044 /* --- @timestr@ --- *
1045  *
1046  * Arguments:   @time_t t@ = a time to convert
1047  *
1048  * Returns:     A pointer to a textual representation of the time.
1049  *
1050  * Use:         Converts a time to a textual representation.  Corrupts
1051  *              @buf_t@.
1052  */
1053
1054 extern const char *timestr(time_t /*t*/);
1055
1056 /*----- That's all, folks -------------------------------------------------*/
1057
1058 #ifdef __cplusplus
1059   }
1060 #endif
1061
1062 #endif