Major changes. See source files for details.

diff --git a/tripe.h b/tripe.h
index 587c5d5ba3dd54419c3fb3939602674b9d6e23dd..9f7fd5d719ff9678102e258b7c807847e13886f8 100644 (file)
--- a/tripe.h
+++ b/tripe.h
@@ -1,6 +1,6 @@
 /* -*-c-*-
  *
 /* -*-c-*-
  *

- * $Id: tripe.h,v 1.4 2001/02/05 19:56:37 mdw Exp $
+ * $Id: tripe.h,v 1.5 2001/02/16 21:41:43 mdw Exp $

  *
  * Main header file for TrIPE
  *
  *
  * Main header file for TrIPE
  *


@@ -29,6 +29,9 @@
 /*----- Revision history --------------------------------------------------* 
  *
  * $Log: tripe.h,v $
 /*----- Revision history --------------------------------------------------* 
  *
  * $Log: tripe.h,v $

+ * Revision 1.5  2001/02/16 21:41:43  mdw
+ * Major changes.  See source files for details.
+ *

  * Revision 1.4  2001/02/05 19:56:37  mdw
  * Sequence number protection, and BSD tunnels.
  *
  * Revision 1.4  2001/02/05 19:56:37  mdw
  * Sequence number protection, and BSD tunnels.
  *


@@ -104,12 +107,8 @@
 #include <catacomb/key.h>
 #include <catacomb/paranoia.h>
 
 #include <catacomb/key.h>
 #include <catacomb/paranoia.h>
 

-#include <catacomb/blowfish.h>
-#include <catacomb/blowfish-cbc.h>

 #include <catacomb/noise.h>
 #include <catacomb/rand.h>
 #include <catacomb/noise.h>
 #include <catacomb/rand.h>

-#include <catacomb/rmd160.h>
-#include <catacomb/rmd160-hmac.h>

 
 #include <catacomb/mp.h>
 #include <catacomb/mpmont.h>
 
 #include <catacomb/mp.h>
 #include <catacomb/mpmont.h>


@@ -153,29 +152,95 @@
 
 /*----- TrIPE protocol ----------------------------------------------------*/
 
 
 /*----- TrIPE protocol ----------------------------------------------------*/
 

-/* --- TrIPE packet format --- *
+/* --- TrIPE message format --- *

  *
  *

- * A packet begins with a single-byte packet type.  The remaining data
- * depends on the packet type.
+ * A packet begins with a single-byte message type.  The top four bits are a
+ * category code used to send the message to the right general place in the
+ * code; the bottom bits identify the actual message type.

  */
 
  */
 

-#define MSG_PACKET 0u
-/* Followed by a 64-bit MAC and an encrypted packet.  The MAC is used as an
- * IV for a 64-bit block cipher in CBC-stealing mode.
- */
+#define MSG_CATMASK 0xf0
+#define MSG_TYPEMASK 0x0f

 
 

-#define MSG_PRECHALLENGE 1u
-/* Followed by the challenge only.  Useful for bootstrapping the system.
+/* --- Encrypted message packets --- *
+ *
+ * Messages of category @MSG_PACKET@ contain encrypted network packets.  The
+ * message content is a symmetric-encrypted block (see below).  Reception of
+ * a packet encrypted under a new key implicitly permits that key to be used
+ * to send further packets.
+ *
+ * The only packet type accepted is zero.
+ *
+ * Packets may be encrypted under any live keyset, but should use the most
+ * recent one.

  */
 
  */
 

-#define MSG_CHALLENGE 2u
-/* Followed by a response hash and a large-integer challenge.
- */
+#define MSG_PACKET 0x00
+
+/* --- Key exchange packets --- */
+
+#define MSG_KEYEXCH 0x10
+
+#define KX_PRECHAL 0u
+#define KX_COOKIE 1u
+#define KX_CHAL 2u
+#define KX_REPLY 3u
+#define KX_SWITCH 4u
+#define KX_SWITCHOK 5u
+#define KX_NMSG 6u

 
 

-#define MSG_RESPONSE 3u
-/* Followed by a large-integer response.
+/* --- Symmetric encryption and keysets --- *
+ *
+ * Packets consist of a 64-bit MAC, a 32-bit sequence number, and the
+ * encrypted payload.
+ *
+ * The MAC is computed using the HMAC construction with RIPEMD160 over the
+ * sequence number and the original packet plaintext; the first 64 bits of
+ * the output are used.
+ *
+ * The plaintext is encrypted using Blowfish in CBC mode with ciphertext
+ * stealing (as described in [Schneier].  The initialization vector is
+ * precisely the 64-bit MAC computed previously.
+ *
+ * A keyset consists of
+ *
+ *   * an integrity (MAC) key;
+ *   * a confidentiality (encryption) key; and
+ *   * a sequence numbering space
+ *
+ * in each direction.  The packets sent by a host encrypted under a
+ * particular keyset are assigned consecutive sequence numbers starting from
+ * zero.  The receiving host must ensure that it only accepts each packet at
+ * most once.  It should maintain a window of sequence numbers: packets with
+ * numbers beyond the end of the window are accepted and cause the window to
+ * be advanced; packets with numbers before the start of the window are
+ * rejected; packets with numbers which appear within the window are accepted
+ * only if the number has not been seen before.
+ *
+ * When a host sends a @KX_SWITCH@ or @KX_SWITCHOK@ message, it installs the
+ * newly-negotiated keyset in a `listen-only' state: it may not send a packet
+ * encrypted under the keyset until either it has received a @KX_SWITCH@ or
+ * @KX_SWITCHOK@ message, or a @MSG_PACKET@ encrypted under the keyset, from
+ * its peer.

  */
 
  */
 

+/*----- Cipher selections -------------------------------------------------*/
+
+#include <catacomb/blowfish.h>
+#include <catacomb/blowfish-cbc.h>
+#include <catacomb/rmd160.h>
+#include <catacomb/rmd160-hmac.h>
+
+#define CIPHER (&blowfish_cbc)
+#define MAC (&rmd160_hmac)
+
+#define HASH_CTX rmd160_ctx
+#define HASH_INIT rmd160_init
+#define HASH rmd160_hash
+#define HASH_STRING(c, s) HASH((c), s, sizeof(s))
+#define HASH_DONE rmd160_done
+#define HASHSZ RMD160_HASHSZ
+

 /*----- Data structures ---------------------------------------------------*/
 
 /* --- Buffers --- *
 /*----- Data structures ---------------------------------------------------*/
 
 /* --- Buffers --- *


@@ -216,19 +281,22 @@ typedef union addr {
 
 typedef struct keyset {
   struct keyset *next;                 /* Next active keyset in the list */
 
 typedef struct keyset {
   struct keyset *next;                 /* Next active keyset in the list */

+  unsigned ref;                                /* Reference count for keyset */

   time_t t_exp;                                /* Expiry time for this keyset */
   unsigned long sz_exp;                        /* Data limit for the keyset */
   time_t t_exp;                                /* Expiry time for this keyset */
   unsigned long sz_exp;                        /* Data limit for the keyset */

-#ifndef NTRACE
-  unsigned seq;                                /* Sequence number for tracing */
-#endif
-  gcipher *c;                          /* Keyset cipher for encryption */
-  gmac *m;                             /* Keyset MAC for integrity */
+  T( unsigned seq; )                   /* Sequence number for tracing */
+  unsigned f;                          /* Various useful flags */
+  gcipher *cin, *cout;                         /* Keyset ciphers for encryption */
+  gmac *min, *mout;                    /* Keyset MACs for integrity */

   uint32 oseq;                         /* Outbound sequence number */
   uint32 iseq, iwin;                   /* Inbound sequence number */
 } keyset;
 
 #define KS_SEQWINSZ 32                 /* Bits in sequence number window */
 
   uint32 oseq;                         /* Outbound sequence number */
   uint32 iseq, iwin;                   /* Inbound sequence number */
 } keyset;
 
 #define KS_SEQWINSZ 32                 /* Bits in sequence number window */
 

+#define KSF_LISTEN 1u                  /* Don't encrypt packets yet */
+#define KSF_LINK 2u                    /* Key is in a linked list */
+

 /* --- Key exchange --- *
  *
  * TrIPE uses the Wrestlers Protocol for its key exchange.  The Wrestlers
 /* --- Key exchange --- *
  *
  * TrIPE uses the Wrestlers Protocol for its key exchange.  The Wrestlers


@@ -238,27 +306,48 @@ typedef struct keyset {
  * Clive Jones.
  */
 
  * Clive Jones.
  */
 

+#define KX_NCHAL 16u
+#define KX_THRESH 4u
+
+typedef struct kxchal {
+  struct keyexch *kx;                  /* Pointer back to key exchange */
+  mp *c;                               /* Responder's challenge */
+  mp *r;                               /* My reply to the challenge */
+  keyset *ks;                          /* Pointer to temporary keyset */
+  unsigned f;                          /* Various useful flags */
+  sel_timer t;                         /* Response timer for challenge */
+  octet hc[HASHSZ];                    /* Hash of his challenge */
+  octet hrx[HASHSZ];                   /* My expected reply hash */
+  octet hswrq_in[HASHSZ];              /* Inbound switch request message */
+  octet hswok_in[HASHSZ];              /* Inbound switch confirmation */
+  octet hswrq_out[HASHSZ];             /* Outbound switch request message */
+  octet hswok_out[HASHSZ];             /* Outbound switch confirmation */
+} kxchal;
+

 typedef struct keyexch {
 typedef struct keyexch {

-  keyset **ks;                         /* Peer's list of keysets */

   struct peer *p;                      /* Pointer back to the peer */
   struct peer *p;                      /* Pointer back to the peer */

+  keyset **ks;                         /* Peer's list of keysets */

   unsigned f;                          /* Various useful flags */
   unsigned f;                          /* Various useful flags */

+  unsigned s;                          /* Current state in exchange */

   sel_timer t;                         /* Timer for next exchange */
   dh_pub kpub;                         /* Peer's public key */
   sel_timer t;                         /* Timer for next exchange */
   dh_pub kpub;                         /* Peer's public key */

-  mp *my_x, *my_gx, *my_gxy;           /* My half of the exchange */
-  octet my_h[RMD160_HASHSZ];           /* My challenge hash */
-  mp *your_gx, *your_gxy;              /* Your half of the exchange */
-  octet your_h[RMD160_HASHSZ];         /* Your challenge hash */
+  mp *alpha;                           /* My temporary secret */
+  mp *c;                               /* My challenge */
+  mp *rx;                              /* The expected response */
+  unsigned nr;                         /* Number of extant responses */

   time_t t_valid;                      /* When this exchange goes bad */
   time_t t_valid;                      /* When this exchange goes bad */

-  time_t t_qchal, t_qresp;             /* Quiet timers for packet types */
-  time_t t_newchal;                    /* When to accept a new challenge */
+  octet hc[HASHSZ];                    /* Hash of my challenge */
+  kxchal *r[KX_NCHAL];                 /* Array of challenges */

 } keyexch;
 
 #define KXF_TIMER 1u                   /* Waiting for a timer to go off */
 } keyexch;
 
 #define KXF_TIMER 1u                   /* Waiting for a timer to go off */

-#define KXF_INIT 2u                    /* Big numbers are initialized */
-#define KXF_MYH 4u                     /* My hash has been computed */
-#define KXF_YOURH 8u                   /* Your hash has been received */
-#define KXF_REPLY 16u                  /* Received your response OK */
-#define KXF_DONE 32u                   /* Key exchange completed */
+
+enum {
+  KXS_DEAD,                            /* Uninitialized state (magical) */
+  KXS_CHAL,                            /* Main answer-challenges state */
+  KXS_COMMIT,                          /* Committed: send switch request */
+  KXS_SWITCH                           /* Switched: send confirmation */
+};

 
 /* --- Tunnel structure --- *
  *
 
 /* --- Tunnel structure --- *
  *


@@ -278,6 +367,25 @@ typedef struct tunnel {
 #endif
 } tunnel;
 
 #endif
 } tunnel;
 

+/* --- Peer statistics --- *
+ *
+ * Contains various interesting and not-so-interesting statistics about a
+ * peer.  This is updated by various parts of the code.  The format of the
+ * structure isn't considered private, and @p_stats@ returns a pointer to the
+ * statistics block for a given peer.
+ */
+
+typedef struct stats {
+  unsigned long sz_in, sz_out;         /* Size of all data in and out */
+  unsigned long sz_kxin, sz_kxout;     /* Size of key exchange messages */
+  unsigned long sz_ipin, sz_ipout;     /* Size of encapsulated IP packets */
+  time_t t_start, t_last;              /* Time peer created, last recv */
+  unsigned long n_reject;              /* Number of rejected packets */
+  unsigned long n_in, n_out;           /* Number of packets in and out */
+  unsigned long n_kxin, n_kxout;       /* Number of key exchange packets */
+  unsigned long n_ipin, n_ipout;       /* Number of encrypted packets */
+} stats;
+

 /* --- Peer structure --- *
  *
  * The main structure which glues everything else together.
 /* --- Peer structure --- *
  *
  * The main structure which glues everything else together.


@@ -288,10 +396,11 @@ typedef struct peer {
   char *name;                          /* Name of this peer */
   tunnel t;                            /* Tunnel for local packets */
   keyset *ks;                          /* List head for keysets */
   char *name;                          /* Name of this peer */
   tunnel t;                            /* Tunnel for local packets */
   keyset *ks;                          /* List head for keysets */

-  keyexch kx;                          /* Key exchange protocol block */

   buf b;                               /* Buffer for sending packets */
   addr peer;                           /* Peer socket address */
   size_t sasz;                         /* Socket address size */
   buf b;                               /* Buffer for sending packets */
   addr peer;                           /* Peer socket address */
   size_t sasz;                         /* Socket address size */

+  stats st;                            /* Statistics */
+  keyexch kx;                          /* Key exchange protocol block */

 } peer;
 
 /* --- Admin structure --- */
 } peer;
 
 /* --- Admin structure --- */


@@ -316,7 +425,7 @@ typedef struct admin {
 extern sel_state sel;                  /* Global I/O event state */
 extern dh_priv kpriv;                  /* Our private key */
 extern mpmont mg;                      /* Montgomery context for DH group */
 extern sel_state sel;                  /* Global I/O event state */
 extern dh_priv kpriv;                  /* Our private key */
 extern mpmont mg;                      /* Montgomery context for DH group */

-extern octet buf_i[PKBUFSZ], buf_o[PKBUFSZ]; /* Big packet buffers */
+extern octet buf_i[PKBUFSZ], buf_o[PKBUFSZ], buf_t[PKBUFSZ];

 
 #ifndef NTRACE
 extern const trace_opt tr_opts[];      /* Trace options array */
 
 #ifndef NTRACE
 extern const trace_opt tr_opts[];      /* Trace options array */


@@ -381,41 +490,19 @@ extern int km_getpubkey(const char */*tag*/, dh_pub */*kpub*/);
 
 extern void kx_start(keyexch */*kx*/);
 
 
 extern void kx_start(keyexch */*kx*/);
 

-/* --- @kx_prechallenge@ --- *
- *
- * Arguments:  @keyexch *kx@ = pointer to key exhange context
- *             @buf *b@ = pointer to buffer containing the packet
- *
- * Returns:    ---
- *
- * Use:                Reads a prechallenge packet from the buffer and handles it.
- */
-
-extern void kx_prechallenge(keyexch */*kx*/, buf */*b*/);
-
-/* --- @kx_challenge@ --- *
- *
- * Arguments:  @keyexch *kx@ = pointer to key exchange context
- *             @buf *b@ = a buffer containing the packet to read
- *
- * Returns:    ---
- *
- * Use:                Reads a challenge from the buffer and handles it.
- */
-
-extern void kx_challenge(keyexch */*kx*/, buf */*b*/);
-
-/* --- @kx_response@ --- *
+/* --- @kx_message@ --- *

  *
  * Arguments:  @keyexch *kx@ = pointer to key exchange context
  *
  * Arguments:  @keyexch *kx@ = pointer to key exchange context

- *             @buf *b@ = a buffer containing the packet to read
+ *             @unsigned msg@ = the message code
+ *             @buf *b@ = pointer to buffer containing the packet

  *
  * Returns:    ---
  *
  *
  * Returns:    ---
  *

- * Use:                Reads a response from the buffer and handles it.
+ * Use:                Reads a packet containing key exchange messages and handles
+ *             it.

  */
 
  */
 

-extern void kx_response(keyexch */*kx*/, buf */*b*/);
+extern void kx_message(keyexch */*kx*/, unsigned /*msg*/, buf */*b*/);

 
 /* --- @kx_free@ --- *
  *
 
 /* --- @kx_free@ --- *
  *


@@ -459,44 +546,134 @@ extern int kx_init(keyexch */*kx*/, peer */*p*/, keyset **/*ks*/);
 
 /*----- Keysets and symmetric cryptography --------------------------------*/
 
 
 /*----- Keysets and symmetric cryptography --------------------------------*/
 

-/* --- @ks_free@ --- *
+/* --- @ks_drop@ --- *
+ *
+ * Arguments:  @keyset *ks@ = pointer to a keyset
+ *
+ * Returns:    ---
+ *
+ * Use:                Decrements a keyset's reference counter.  If the counter hits
+ *             zero, the keyset is freed.
+ */
+
+extern void ks_drop(keyset */*ks*/);
+
+/* --- @ks_gen@ --- *
+ *
+ * Arguments:  @const void *k@ = pointer to key material
+ *             @size_t x, y, z@ = offsets into key material (see below)
+ *
+ * Returns:    A pointer to the new keyset.
+ *
+ * Use:                Derives a new keyset from the given key material.  The
+ *             offsets @x@, @y@ and @z@ separate the key material into three
+ *             parts.  Between the @k@ and @k + x@ is `my' contribution to
+ *             the key material; between @k + x@ and @k + y@ is `your'
+ *             contribution; and between @k + y@ and @k + z@ is a shared
+ *             value we made together.  These are used to construct two
+ *             pairs of symmetric keys.  Each pair consists of an encryption
+ *             key and a message authentication key.  One pair is used for
+ *             outgoing messages, the other for incoming messages.
+ *
+ *             The new key is marked so that it won't be selected for output
+ *             by @ksl_encrypt@.  You can still encrypt data with it by
+ *             calling @ks_encrypt@ directly.
+ */
+
+extern keyset *ks_gen(const void */*k*/,
+                     size_t /*x*/, size_t /*y*/, size_t /*z*/);
+
+/* --- @ks_tregen@ --- *
+ *
+ * Arguments:  @keyset *ks@ = pointer to a keyset
+ *
+ * Returns:    The time at which moves ought to be made to replace this key.
+ */
+
+extern time_t ks_tregen(keyset */*ks*/);
+
+/* --- @ks_activate@ --- *
+ *
+ * Arguments:  @keyset *ks@ = pointer to a keyset
+ *
+ * Returns:    ---
+ *
+ * Use:                Activates a keyset, so that it can be used for encrypting
+ *             outgoing messages.
+ */
+
+extern void ks_activate(keyset */*ks*/);
+
+/* --- @ks_encrypt@ --- *
+ *
+ * Arguments:  @keyset *ks@ = pointer to a keyset
+ *             @buf *b@ = pointer to input buffer
+ *             @buf *bb@ = pointer to output buffer
+ *
+ * Returns:    Zero if OK, nonzero if the key needs replacing.  If the
+ *             encryption failed, the output buffer is broken and zero is
+ *             returned.
+ *
+ * Use:                Encrypts a block of data using the key.  Note that the `key
+ *             ought to be replaced' notification is only ever given once
+ *             for each key.  Also note that this call forces a keyset to be
+ *             used even if it's marked as not for data output.
+ */
+
+extern int ks_encrypt(keyset */*ks*/, buf */*b*/, buf */*bb*/);
+
+/* --- @ks_decrypt@ --- *
+ *
+ * Arguments:  @keyset *ks@ = pointer to a keyset
+ *             @buf *b@ = pointer to an input buffer
+ *             @buf *bb@ = pointer to an output buffer
+ *
+ * Returns:    Zero on success, or nonzero if there was some problem.
+ *
+ * Use:                Attempts to decrypt a message using a given key.  Note that
+ *             requesting decryption with a key directly won't clear a
+ *             marking that it's not for encryption.
+ */
+
+extern int ks_decrypt(keyset */*ks*/, buf */*b*/, buf */*bb*/);
+
+/* --- @ksl_free@ --- *

  *
  * Arguments:  @keyset **ksroot@ = pointer to keyset list head
  *
  * Returns:    ---
  *
  *
  * Arguments:  @keyset **ksroot@ = pointer to keyset list head
  *
  * Returns:    ---
  *

- * Use:                Frees all of the keys in a keyset.
+ * Use:                Frees (releases references to) all of the keys in a keyset.

  */
 
  */
 

-extern void ks_free(keyset **/*ksroot*/);
+extern void ksl_free(keyset **/*ksroot*/);

 
 

-/* --- @ks_prune@ --- *
+/* --- @ksl_link@ --- *

  *
  * Arguments:  @keyset **ksroot@ = pointer to keyset list head
  *
  * Arguments:  @keyset **ksroot@ = pointer to keyset list head

+ *             @keyset *ks@ = pointer to a keyset

  *
  * Returns:    ---
  *
  *
  * Returns:    ---
  *

- * Use:                Prunes the keyset list by removing keys which mustn't be used
- *             any more.
+ * Use:                Links a keyset into a list.  A keyset can only be on one list
+ *             at a time.  Bad things happen otherwise.

  */
 
  */
 

-extern void ks_prune(keyset **/*ksroot*/);
+extern void ksl_link(keyset **/*ksroot*/, keyset */*ks*/);

 
 

-/* --- @ks_gen@ --- *
+/* --- @ksl_prune@ --- *

  *
  * Arguments:  @keyset **ksroot@ = pointer to keyset list head
  *
  * Arguments:  @keyset **ksroot@ = pointer to keyset list head

- *             @const void *k@ = pointer to key material
- *             @size_t sz@ = size of the key material

  *
  *

- * Returns:    The regeneration time for the new key.
+ * Returns:    ---

  *
  *

- * Use:                Derives a keyset from the given key material and adds it to
- *             the list.
+ * Use:                Prunes the keyset list by removing keys which mustn't be used
+ *             any more.

  */
 
  */
 

-extern time_t ks_gen(keyset **/*ksroot*/, const void */*k*/, size_t /*sz*/);
+extern void ksl_prune(keyset **/*ksroot*/);

 
 

-/* --- @ks_encrypt@ --- *
+/* --- @ksl_encrypt@ --- *

  *
  * Arguments:  @keyset **ksroot@ = pointer to keyset list head
  *             @buf *b@ = pointer to input buffer
  *
  * Arguments:  @keyset **ksroot@ = pointer to keyset list head
  *             @buf *b@ = pointer to input buffer


@@ -507,9 +684,9 @@ extern time_t ks_gen(keyset **/*ksroot*/, const void */*k*/, size_t /*sz*/);
  * Use:                Encrypts a packet.
  */
 
  * Use:                Encrypts a packet.
  */
 

-extern int ks_encrypt(keyset **/*ksroot*/, buf */*b*/, buf */*bb*/);
+extern int ksl_encrypt(keyset **/*ksroot*/, buf */*b*/, buf */*bb*/);

 
 

-/* --- @ks_decrypt@ --- *
+/* --- @ksl_decrypt@ --- *

  *
  * Arguments:  @keyset **ksroot@ = pointer to keyset list head
  *             @buf *b@ = pointer to input buffer
  *
  * Arguments:  @keyset **ksroot@ = pointer to keyset list head
  *             @buf *b@ = pointer to input buffer


@@ -520,7 +697,7 @@ extern int ks_encrypt(keyset **/*ksroot*/, buf */*b*/, buf */*bb*/);
  * Use:                Decrypts a packet.
  */
 
  * Use:                Decrypts a packet.
  */
 

-extern int ks_decrypt(keyset **/*ksroot*/, buf */*b*/, buf */*bb*/);
+extern int ksl_decrypt(keyset **/*ksroot*/, buf */*b*/, buf */*bb*/);

 
 /*----- Administration interface ------------------------------------------*/
 
 
 /*----- Administration interface ------------------------------------------*/
 


@@ -629,6 +806,15 @@ extern void p_tun(peer */*p*/, buf */*b*/);
 
 extern void p_interval(void);
 
 
 extern void p_interval(void);
 

+/* --- @p_stats@ --- *
+ *
+ * Arguments:  @peer *p@ = pointer to a peer block
+ *
+ * Returns:    A pointer to the peer's statistics.
+ */
+
+extern stats *p_stats(peer */*p*/);
+

 /* --- @p_ifname@ --- *
  *
  * Arguments:  @peer *p@ = pointer to a peer block
 /* --- @p_ifname@ --- *
  *
  * Arguments:  @peer *p@ = pointer to a peer block


@@ -824,6 +1010,18 @@ extern void buf_init(buf */*b*/, void */*p*/, size_t /*sz*/);
 
 extern int buf_break(buf */*b*/);
 
 
 extern int buf_break(buf */*b*/);
 

+/* --- @buf_flip@ --- *
+ *
+ * Arguments:  @buf *b@ = pointer to a buffer block
+ *
+ * Returns:    ---
+ *
+ * Use:                Flips a buffer so that if you've just been writing to it,
+ *             you can now read from the bit you've written.
+ */
+
+extern void buf_flip(buf */*b*/);
+

 /* --- @buf_ensure@ --- *
  *
  * Arguments:  @buf *b@ = pointer to a buffer block
 /* --- @buf_ensure@ --- *
  *
  * Arguments:  @buf *b@ = pointer to a buffer block


@@ -839,15 +1037,15 @@ extern int buf_ensure(buf */*b*/, size_t /*sz*/);
 /* --- @buf_get@ --- *
  *
  * Arguments:  @buf *b@ = pointer to a buffer block
 /* --- @buf_get@ --- *
  *
  * Arguments:  @buf *b@ = pointer to a buffer block

- *             @void *p@ = pointer to a buffer

  *             @size_t sz@ = size of the buffer
  *
  *             @size_t sz@ = size of the buffer
  *

- * Returns:    Zero if it worked, nonzero if there wasn't enough data.
+ * Returns:    Pointer to the place in the buffer.

  *
  *

- * Use:                Fetches data from the buffer into some other place.
+ * Use:                Reserves a space in the buffer of the requested size, and
+ *             returns its start address.

  */
 
  */
 

-extern int buf_get(buf */*b*/, void */*p*/, size_t /*sz*/);
+extern void *buf_get(buf */*b*/, size_t /*sz*/);

 
 /* --- @buf_put@ --- *
  *
 
 /* --- @buf_put@ --- *
  *


@@ -918,7 +1116,7 @@ extern int buf_putword(buf */*b*/, uint32 /*w*/);
  * Use:                Gets a multiprecision integer from a buffer.
  */
 
  * Use:                Gets a multiprecision integer from a buffer.
  */
 

-extern mp *buf_getmp(buf */*b*/, mp */*d*/);
+extern mp *buf_getmp(buf */*b*/);

 
 /* --- @buf_putmp@ --- *
  *
 
 /* --- @buf_putmp@ --- *
  *


@@ -941,11 +1139,23 @@ extern int buf_putmp(buf */*b*/, mp */*m*/);
  * Returns:    A pointer to the integer's textual representation.
  *
  * Use:                Converts a multiprecision integer to a string.  Corrupts
  * Returns:    A pointer to the integer's textual representation.
  *
  * Use:                Converts a multiprecision integer to a string.  Corrupts

- *             @buf_o@.
+ *             @buf_t@.

  */
 
 extern const char *mpstr(mp */*m*/);
 
  */
 
 extern const char *mpstr(mp */*m*/);
 

+/* --- @timestr@ --- *
+ *
+ * Arguments:  @time_t t@ = a time to convert
+ *
+ * Returns:    A pointer to a textual representation of the time.
+ *
+ * Use:                Converts a time to a textual representation.  Corrupts
+ *             @buf_t@.
+ */
+
+extern const char *timestr(time_t /*t*/);
+

 /*----- That's all, folks -------------------------------------------------*/
 
 #ifdef __cplusplus
 /*----- That's all, folks -------------------------------------------------*/
 
 #ifdef __cplusplus