chiark / gitweb /
Release 1.5.2.
[tripe] / 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 #define MISC_BYE 6u                     /* Departure notification */
83
84 /* --- Symmetric encryption and keysets --- *
85  *
86  * Packets consist of an 80-bit MAC, a 32-bit sequence number, and the
87  * encrypted payload.
88  *
89  * The plaintext is encrypted using Blowfish in CBC mode with ciphertext
90  * stealing (as described in [Schneier]).  The initialization vector is
91  * selected randomly, and prepended to the actual ciphertext.
92  *
93  * The MAC is computed using the HMAC construction with RIPEMD160 over the
94  * sequence number and the ciphertext (with IV); the first 80 bits of the
95  * output are used.  (This is the minimum allowed by the draft FIPS for HMAC,
96  * and the recommended truncation.)
97  *
98  * A keyset consists of
99  *
100  *   * an integrity (MAC) key;
101  *   * a confidentiality (encryption) key; and
102  *   * a sequence numbering space
103  *
104  * in each direction.  The packets sent by a host encrypted under a
105  * particular keyset are assigned consecutive sequence numbers starting from
106  * zero.  The receiving host must ensure that it only accepts each packet at
107  * most once.  It should maintain a window of sequence numbers: packets with
108  * numbers beyond the end of the window are accepted and cause the window to
109  * be advanced; packets with numbers before the start of the window are
110  * rejected; packets with numbers which appear within the window are accepted
111  * only if the number has not been seen before.
112  *
113  * When a host sends a @KX_SWITCH@ or @KX_SWITCHOK@ message, it installs the
114  * newly-negotiated keyset in a `listen-only' state: it may not send a packet
115  * encrypted under the keyset until either it has received a @KX_SWITCH@ or
116  * @KX_SWITCHOK@ message, or a @MSG_PACKET@ encrypted under the keyset, from
117  * its peer.
118  */
119
120 /*----- That's all, folks -------------------------------------------------*/
121
122 #endif