chiark / gitweb /
tripe-admin manpage: Generate a command and message summary.
[tripe] / tripe-protocol.h
1 /* -*-c-*-
2  *
3  * $Id$
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
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
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 */
80 #define MISC_GREET 5u                   /* A greeting from a NATed peer */
81
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
88  * stealing (as described in [Schneier]).  The initialization vector is
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