chiark - git - mdw - tripe/blob - tripe.h

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