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

   1 /* -*-c-*-
   2  *
   3  * Protocol definition for TrIPE
   4  *
   5  * (c) 2003 Straylight/Edgeware
   6  */
   7
   8 /*----- Licensing notice --------------------------------------------------*
   9  *
  10  * This file is part of Trivial IP Encryption (TrIPE).
  11  *
  12  * TrIPE is free software: you can redistribute it and/or modify it under
  13  * the terms of the GNU General Public License as published by the Free
  14  * Software Foundation; either version 3 of the License, or (at your
  15  * option) any later version.
  16  *
  17  * TrIPE is distributed in the hope that it will be useful, but WITHOUT
  18  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  19  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  20  * for more details.
  21  *
  22  * You should have received a copy of the GNU General Public License
  23  * along with TrIPE.  If not, see <https://www.gnu.org/licenses/>.
  24  */
  25
  26 #ifndef TRIPE_PROTOCOL_H
  27 #define TRIPE_PROTOCOL_H
  28
  29 /*----- TrIPE protocol ----------------------------------------------------*/
  30
  31 #define TRIPE_PORT 4070                 /* Assigned by IANA */
  32
  33 /* --- TrIPE message format --- *
  34  *
  35  * A packet begins with a single-byte message type.  The top four bits are a
  36  * category code used to send the message to the right general place in the
  37  * code; the bottom bits identify the actual message type.
  38  */
  39
  40 #define MSG_CATMASK 0xf0
  41 #define MSG_TYPEMASK 0x0f
  42
  43 /* --- Encrypted message packets --- *
  44  *
  45  * Messages of category @MSG_PACKET@ contain encrypted network packets.  The
  46  * message content is a symmetric-encrypted block (see below).  Reception of
  47  * a packet encrypted under a new key implicitly permits that key to be used
  48  * to send further packets.
  49  *
  50  * The only packet type accepted is zero.
  51  *
  52  * Packets may be encrypted under any live keyset, but should use the most
  53  * recent one.
  54  */
  55
  56 #define MSG_PACKET 0x00
  57
  58 /* --- Key exchange packets --- */
  59
  60 #define MSG_KEYEXCH 0x10
  61
  62 #define KX_PRECHAL 0u
  63 #define KX_CHAL 1u
  64 #define KX_REPLY 2u
  65 #define KX_SWITCH 3u
  66 #define KX_SWITCHOK 4u
  67 #define KX_TOKENRQ 5u
  68 #define KX_TOKEN 6u
  69 #define KX_KNOCK 7u
  70 #define KX_NMSG 8u
  71
  72 /* --- Miscellaneous packets --- */
  73
  74 #define MSG_MISC 0x20
  75
  76 #define MISC_NOP 0u                     /* Do nothing; ignore me */
  77 #define MISC_PING 1u                    /* Transport-level ping */
  78 #define MISC_PONG 2u                    /* Transport-level ping response */
  79 #define MISC_EPING 3u                   /* Encrypted ping */
  80 #define MISC_EPONG 4u                   /* Encrypted ping response */
  81 #define MISC_GREET 5u                   /* A greeting from a NATed peer */
  82
  83 /* --- Symmetric encryption and keysets --- *
  84  *
  85  * Packets consist of an 80-bit MAC, a 32-bit sequence number, and the
  86  * encrypted payload.
  87  *
  88  * The plaintext is encrypted using Blowfish in CBC mode with ciphertext
  89  * stealing (as described in [Schneier]).  The initialization vector is
  90  * selected randomly, and prepended to the actual ciphertext.
  91  *
  92  * The MAC is computed using the HMAC construction with RIPEMD160 over the
  93  * sequence number and the ciphertext (with IV); the first 80 bits of the
  94  * output are used.  (This is the minimum allowed by the draft FIPS for HMAC,
  95  * and the recommended truncation.)
  96  *
  97  * A keyset consists of
  98  *
  99  *   * an integrity (MAC) key;
 100  *   * a confidentiality (encryption) key; and
 101  *   * a sequence numbering space
 102  *
 103  * in each direction.  The packets sent by a host encrypted under a
 104  * particular keyset are assigned consecutive sequence numbers starting from
 105  * zero.  The receiving host must ensure that it only accepts each packet at
 106  * most once.  It should maintain a window of sequence numbers: packets with
 107  * numbers beyond the end of the window are accepted and cause the window to
 108  * be advanced; packets with numbers before the start of the window are
 109  * rejected; packets with numbers which appear within the window are accepted
 110  * only if the number has not been seen before.
 111  *
 112  * When a host sends a @KX_SWITCH@ or @KX_SWITCHOK@ message, it installs the
 113  * newly-negotiated keyset in a `listen-only' state: it may not send a packet
 114  * encrypted under the keyset until either it has received a @KX_SWITCH@ or
 115  * @KX_SWITCHOK@ message, or a @MSG_PACKET@ encrypted under the keyset, from
 116  * its peer.
 117  */
 118
 119 /*----- That's all, folks -------------------------------------------------*/
 120
 121 #endif