[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_COOKIE 1u
#define KX_CHAL 2u
#define KX_REPLY 3u
#define KX_SWITCH 4u
#define KX_SWITCHOK 5u
#define KX_NMSG 6u

/* --- 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
Commit	Line	Data
165db1a8	1	/* --c--
165db1a8	2	*
0ba8de86	3	* $Id$
165db1a8	4	*
	5	* Protocol definition for TrIPE
	6	*
	7	* (c) 2003 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
165db1a8	29	#ifndef TRIPE_PROTOCOL_H
	30	#define TRIPE_PROTOCOL_H
	31
	32	/----- TrIPE protocol ----------------------------------------------------/
	33
	34	/* --- TrIPE message format --- *
	35	*
	36	* A packet begins with a single-byte message type. The top four bits are a
	37	* category code used to send the message to the right general place in the
	38	* code; the bottom bits identify the actual message type.
	39	*/
	40
	41	#define MSG_CATMASK 0xf0
	42	#define MSG_TYPEMASK 0x0f
	43
	44	/* --- Encrypted message packets --- *
	45	*
	46	* Messages of category @MSG_PACKET@ contain encrypted network packets. The
	47	* message content is a symmetric-encrypted block (see below). Reception of
	48	* a packet encrypted under a new key implicitly permits that key to be used
	49	* to send further packets.
	50	*
	51	* The only packet type accepted is zero.
	52	*
	53	* Packets may be encrypted under any live keyset, but should use the most
	54	* recent one.
	55	*/
	56
	57	#define MSG_PACKET 0x00
	58
	59	/* --- Key exchange packets --- */
	60
	61	#define MSG_KEYEXCH 0x10
	62
	63	#define KX_PRECHAL 0u
	64	#define KX_COOKIE 1u
	65	#define KX_CHAL 2u
	66	#define KX_REPLY 3u
	67	#define KX_SWITCH 4u
	68	#define KX_SWITCHOK 5u
	69	#define KX_NMSG 6u
	70
0ba8de86	71	/* --- Miscellaneous packets --- */
	72
	73	#define MSG_MISC 0x20
	74
	75	#define MISC_NOP 0u /* Do nothing; ignore me */
	76	#define MISC_PING 1u /* Transport-level ping */
	77	#define MISC_PONG 2u /* Transport-level ping response */
	78	#define MISC_EPING 3u /* Encrypted ping */
	79	#define MISC_EPONG 4u /* Encrypted ping response */
37941236	80	#define MISC_GREET 5u /* A greeting from a NATed peer */
0ba8de86	81
165db1a8	82	/* --- Symmetric encryption and keysets --- *
	83	*
	84	* Packets consist of an 80-bit MAC, a 32-bit sequence number, and the
	85	* encrypted payload.
	86	*
	87	* The plaintext is encrypted using Blowfish in CBC mode with ciphertext
0ba8de86	88	* stealing (as described in [Schneier]). The initialization vector is
165db1a8	89	* selected randomly, and prepended to the actual ciphertext.
	90	*
	91	* The MAC is computed using the HMAC construction with RIPEMD160 over the
	92	* sequence number and the ciphertext (with IV); the first 80 bits of the
	93	* output are used. (This is the minimum allowed by the draft FIPS for HMAC,
	94	* and the recommended truncation.)
	95	*
	96	* A keyset consists of
	97	*
	98	* * an integrity (MAC) key;
	99	* * a confidentiality (encryption) key; and
	100	* * a sequence numbering space
	101	*
	102	* in each direction. The packets sent by a host encrypted under a
	103	* particular keyset are assigned consecutive sequence numbers starting from
	104	* zero. The receiving host must ensure that it only accepts each packet at
	105	* most once. It should maintain a window of sequence numbers: packets with
	106	* numbers beyond the end of the window are accepted and cause the window to
	107	* be advanced; packets with numbers before the start of the window are
	108	* rejected; packets with numbers which appear within the window are accepted
	109	* only if the number has not been seen before.
	110	*
	111	* When a host sends a @KX_SWITCH@ or @KX_SWITCHOK@ message, it installs the
	112	* newly-negotiated keyset in a `listen-only' state: it may not send a packet
	113	* encrypted under the keyset until either it has received a @KX_SWITCH@ or
	114	* @KX_SWITCHOK@ message, or a @MSG_PACKET@ encrypted under the keyset, from
	115	* its peer.
	116	*/
	117
	118	/----- That's all, folks -------------------------------------------------/
	119
	120	#endif