keyexch: Simplify key-exchange protocol.

[tripe] / tripe-protocol.h

/* -*-c-*-
 *
 * $Id$
 *
 * Protocol definition for TrIPE
 *
 * (c) 2003 Straylight/Edgeware
 */

/*----- Licensing notice --------------------------------------------------* 
 *
 * This file is part of Trivial IP Encryption (TrIPE).
 *
 * TrIPE is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 * 
 * TrIPE is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with TrIPE; if not, write to the Free Software Foundation,
 * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */

#ifndef TRIPE_PROTOCOL_H
#define TRIPE_PROTOCOL_H

/*----- TrIPE protocol ----------------------------------------------------*/

/* --- TrIPE message format --- *
 *
 * 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_CATMASK 0xf0
#define MSG_TYPEMASK 0x0f

/* --- 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_PACKET 0x00

/* --- Key exchange packets --- */

#define MSG_KEYEXCH 0x10

#define KX_PRECHAL 0u
#define KX_CHAL 1u
#define KX_REPLY 2u
#define KX_SWITCH 3u
#define KX_SWITCHOK 4u
#define KX_NMSG 5u

/* --- Miscellaneous packets --- */

#define MSG_MISC 0x20

#define MISC_NOP 0u			/* Do nothing; ignore me */
#define MISC_PING 1u			/* Transport-level ping */
#define MISC_PONG 2u			/* Transport-level ping response */
#define MISC_EPING 3u			/* Encrypted ping */
#define MISC_EPONG 4u			/* Encrypted ping response */
#define MISC_GREET 5u			/* A greeting from a NATed peer */

/* --- Symmetric encryption and keysets --- *
 *
 * Packets consist of an 80-bit MAC, a 32-bit sequence number, and the
 * encrypted payload.
 *
 * The plaintext is encrypted using Blowfish in CBC mode with ciphertext
 * stealing (as described in [Schneier]).  The initialization vector is
 * selected randomly, and prepended to the actual ciphertext.
 *
 * The MAC is computed using the HMAC construction with RIPEMD160 over the
 * sequence number and the ciphertext (with IV); the first 80 bits of the
 * output are used.  (This is the minimum allowed by the draft FIPS for HMAC,
 * and the recommended truncation.)
 *
 * 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.
 */

/*----- That's all, folks -------------------------------------------------*/

#endif