Debian Codegraph @

srtcore/handshake.h

raw
1 /*
2 * SRT - Secure, Reliable, Transport
3 * Copyright (c) 2018 Haivision Systems Inc.
4 *
5 * This Source Code Form is subject to the terms of the Mozilla Public
6 * License, v. 2.0. If a copy of the MPL was not distributed with this
7 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
8 *
9 */
10
11 /*****************************************************************************
12 Copyright (c) 2001 - 2011, The Board of Trustees of the University of Illinois.
13 All rights reserved.
14
15 Redistribution and use in source and binary forms, with or without
16 modification, are permitted provided that the following conditions are
17 met:
18
19 * Redistributions of source code must retain the above
20 copyright notice, this list of conditions and the
21 following disclaimer.
22
23 * Redistributions in binary form must reproduce the
24 above copyright notice, this list of conditions
25 and the following disclaimer in the documentation
26 and/or other materials provided with the distribution.
27
28 * Neither the name of the University of Illinois
29 nor the names of its contributors may be used to
30 endorse or promote products derived from this
31 software without specific prior written permission.
32
33 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
34 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
35 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
36 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
37 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
38 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
39 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
40 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
41 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
42 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
43 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
44 *****************************************************************************/
45
46 #ifndef INC_SRT_HANDSHAKE_H
47 #define INC_SRT_HANDSHAKE_H
48
49 #include <vector>
50
51 #include "crypto.h"
52 #include "utilities.h"
53
54 namespace srt
55 {
56
57 typedef Bits<31, 16> HS_CMDSPEC_CMD;
58 typedef Bits<15, 0> HS_CMDSPEC_SIZE;
59
60 // NOTE: Some of these flags represent CAPABILITIES, that is,
61 // as long as these flags are defined, they must be always set
62 // (unless they are deprecated).
63 enum SrtOptions
64 {
65 SRT_OPT_TSBPDSND = BIT(0), /* Timestamp-based Packet delivery real-time data sender */
66 SRT_OPT_TSBPDRCV = BIT(1), /* Timestamp-based Packet delivery real-time data receiver */
67 SRT_OPT_HAICRYPT = BIT(2), /* CAPABILITY: HaiCrypt AES-128/192/256-CTR */
68 SRT_OPT_TLPKTDROP = BIT(3), /* Drop real-time data packets too late to be processed in time */
69 SRT_OPT_NAKREPORT = BIT(4), /* Periodic NAK report */
70 SRT_OPT_REXMITFLG = BIT(5), // CAPABILITY: One bit in payload packet msgno is "retransmitted" flag
71 // (this flag can be reused for something else, when pre-1.2.0 versions are all abandoned)
72 SRT_OPT_STREAM = BIT(6), // STREAM MODE (not MESSAGE mode)
73 SRT_OPT_FILTERCAP = BIT(7), // CAPABILITY: Packet filter supported
74 };
75
76 inline int SrtVersionCapabilities()
77 {
78 // NOTE: SRT_OPT_REXMITFLG is not included here because
79 // SRT is prepared to handle also peers that don't have this
80 // capability, so a listener responding to a peer that doesn't
81 // support it should NOT set this flag.
82 //
83 // This state will remain until this backward compatibility is
84 // decided to be broken, in which case this flag will be always
85 // set, and clients that do not support this capability will be
86 // rejected.
87 return SRT_OPT_HAICRYPT | SRT_OPT_FILTERCAP;
88 }
89
90
91 std::string SrtFlagString(int32_t flags);
92
93 const int SRT_CMD_REJECT = 0, // REJECT is only a symbol for return type
94 SRT_CMD_HSREQ = 1,
95 SRT_CMD_HSRSP = 2,
96 SRT_CMD_KMREQ = 3,
97 SRT_CMD_KMRSP = 4,
98 SRT_CMD_SID = 5,
99 SRT_CMD_CONGESTION = 6,
100 SRT_CMD_FILTER = 7,
101 SRT_CMD_GROUP = 8,
102 SRT_CMD_NONE = -1; // for cases when {no pong for ping is required} | {no extension block found}
103
104 enum SrtDataStruct
105 {
106 SRT_HS_VERSION = 0,
107 SRT_HS_FLAGS,
108 SRT_HS_LATENCY,
109
110 // Keep it always last
111 SRT_HS_E_SIZE
112 };
113
114 // For HSv5 the lo and hi part is used for particular side's latency
115 typedef Bits<31, 16> SRT_HS_LATENCY_RCV;
116 typedef Bits<15, 0> SRT_HS_LATENCY_SND;
117 // For HSv4 only the lower part is used.
118 typedef Bits<15, 0> SRT_HS_LATENCY_LEG;
119
120
121 struct SrtHandshakeExtension
122 {
123 int16_t type;
124 std::vector<uint32_t> contents;
125
126 SrtHandshakeExtension(int16_t cmd): type(cmd) {}
127 };
128
129 // Implemented in core.cpp, so far
130 void SrtExtractHandshakeExtensions(const char* bufbegin, size_t size,
131 std::vector<SrtHandshakeExtension>& w_output);
132
133
134 struct SrtHSRequest: public SrtHandshakeExtension
135 {
136 typedef Bits<31, 16> SRT_HSTYPE_ENCFLAGS;
137 typedef Bits<15, 0> SRT_HSTYPE_HSFLAGS;
138
139 // For translating PBKEYLEN into crypto flags
140 // This value is 16, 24, 32; after cutting off
141 // the leftmost 3 bits, it is 2, 3, 4.
142 typedef Bits<5, 3> SRT_PBKEYLEN_BITS;
143
144 // This value fits ins SRT_HSTYPE_HSFLAGS.
145 // .... HAIVISIOn
146 static const int32_t SRT_MAGIC_CODE = 0x4A17;
147
148 static int32_t wrapFlags(bool withmagic, int crypto_keylen)
149 {
150 int32_t base = withmagic ? SRT_MAGIC_CODE : 0;
151 return base | SRT_HSTYPE_ENCFLAGS::wrap( SRT_PBKEYLEN_BITS::unwrap(crypto_keylen) );
152 }
153
154 // Group handshake extension layout
155
156 // 0 1 2 3
157 // 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
158 // +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
159 // | Group ID |
160 // +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
161 // | Group Type | Group's Flags | Group's Weight |
162 // +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
163 typedef Bits<31, 24> HS_GROUP_TYPE;
164 typedef Bits<23, 16> HS_GROUP_FLAGS;
165 typedef Bits<15, 0> HS_GROUP_WEIGHT;
166
167 private:
168 friend class CHandShake;
169
170 static const size_t SRT_HS_SIZE = 4*sizeof(uint32_t); // 4 existing fields
171 static const size_t SRT_EXT_HS_SIZE = 2*sizeof(uint32_t) + SRT_HS_SIZE; // SRT magic and SRT HS type, used only in UDT HS ext
172
173 typedef Bits<15, 0> SRT_TSBPD_DELAY;
174
175 uint32_t m_iSrtVersion;
176 uint32_t m_iSrtFlags;
177 uint32_t m_iSrtTsbpd;
178 uint32_t m_iSrtReserved;
179
180 public:
181
182 SrtHSRequest(): SrtHandshakeExtension(SRT_CMD_HSREQ), m_iSrtVersion(), m_iSrtFlags(), m_iSrtTsbpd(), m_iSrtReserved() {}
183
184 void setVersion(uint32_t v) { m_iSrtVersion = v; }
185 uint32_t version() const { return m_iSrtVersion; }
186
187 void setFlag(SrtOptions opt) { m_iSrtFlags |= uint32_t(opt); }
188 void clearFlag(SrtOptions opt) { m_iSrtFlags &= ~opt; }
189 uint32_t flags() const { return m_iSrtFlags; }
190
191 void setTsbPdDelay(uint16_t delay) { m_iSrtTsbpd |= SRT_TSBPD_DELAY::wrap(delay); }
192 // Unknown what the 1-16 bits have to be used for.
193 uint16_t tsbPdDelay() const
194 {
195 return SRT_TSBPD_DELAY::unwrap(m_iSrtTsbpd);
196 }
197
198 size_t size() const { return SRT_EXT_HS_SIZE; }
199
200 bool serialize(char* p, size_t size) const;
201 bool deserialize(const char* mem, size_t size);
202 };
203
204 struct SrtKMRequest: public SrtHandshakeExtension
205 {
206 uint32_t m_iKmState;
207 char m_aKey[1]; // dynamic size
208 };
209
210
211 ////////////////////////////////////////////////////////////////////////////////
212
213 enum UDTRequestType
214 {
215 URQ_INDUCTION_TYPES = 0, // XXX used to check in one place. Consdr rm.
216
217 URQ_INDUCTION = 1, // First part for client-server connection
218 URQ_WAVEAHAND = 0, // First part for rendezvous connection
219
220 URQ_CONCLUSION = -1, // Second part of handshake negotiation
221 URQ_AGREEMENT = -2, // Extra (last) step for rendezvous only
222 URQ_DONE = -3, // Special value used only in state-switching, to state that nothing should be sent in response
223
224 // Note: the client-server connection uses:
225 // --> INDUCTION (empty)
226 // <-- INDUCTION (cookie)
227 // --> CONCLUSION (cookie)
228 // <-- CONCLUSION (ok)
229
230 // The rendezvous HSv4 (legacy):
231 // --> WAVEAHAND (effective only if peer is also connecting)
232 // <-- CONCLUSION (empty) (consider yourself connected upon reception)
233 // --> AGREEMENT (sent as a response for conclusion, requires no response)
234
235 // The rendezvous HSv5 (using SRT extensions):
236 // --> WAVEAHAND (with cookie)
237 // --- (selecting INITIATOR/RESPONDER by cookie contest - comparing one another's cookie)
238 // <-- CONCLUSION (without extensions, if RESPONDER, with extensions, if INITIATOR)
239 // --> CONCLUSION (with response extensions, if RESPONDER)
240 // <-- AGREEMENT (sent exclusively by INITIATOR upon reception of CONCLUSIOn with response extensions)
241
242 // This marks the beginning of values that are error codes.
243 URQ_FAILURE_TYPES = 1000,
244
245 // NOTE: codes above 1000 are reserved for failure codes for
246 // rejection reason, as per `SRT_REJECT_REASON` enum. The
247 // actual rejection code is the value of the request type
248 // minus URQ_FAILURE_TYPES.
249
250 // This is in order to return standard error codes for server
251 // data retrieval failures.
252 URQ_SERVER_FAILURE_TYPES = URQ_FAILURE_TYPES + SRT_REJC_PREDEFINED,
253
254 // This is for a completely user-defined reject reasons.
255 URQ_USER_FAILURE_TYPES = URQ_FAILURE_TYPES + SRT_REJC_USERDEFINED
256 };
257
258 inline UDTRequestType URQFailure(int reason)
259 {
260 return UDTRequestType(URQ_FAILURE_TYPES + int(reason));
261 }
262
263 inline int RejectReasonForURQ(UDTRequestType req)
264 {
265 if (req < URQ_FAILURE_TYPES)
266 return SRT_REJ_UNKNOWN;
267
268 int reason = req - URQ_FAILURE_TYPES;
269 if (reason < SRT_REJC_PREDEFINED && reason >= SRT_REJ_E_SIZE)
270 return SRT_REJ_UNKNOWN;
271
272 return reason;
273 }
274
275 // DEPRECATED values. Use URQFailure(SRT_REJECT_REASON).
276 const UDTRequestType URQ_ERROR_REJECT SRT_ATR_DEPRECATED = (UDTRequestType)1002; // == 1000 + SRT_REJ_PEER
277 const UDTRequestType URQ_ERROR_INVALID SRT_ATR_DEPRECATED = (UDTRequestType)1004; // == 1000 + SRT_REJ_ROGUE
278
279 // XXX Change all uses of that field to UDTRequestType when possible
280 #if ENABLE_LOGGING
281 std::string RequestTypeStr(UDTRequestType);
282 #else
283 inline std::string RequestTypeStr(UDTRequestType) { return ""; }
284 #endif
285
286
287 class CHandShake
288 {
289 public:
290 CHandShake();
291
292 int store_to(char* buf, size_t& size);
293 int load_from(const char* buf, size_t size);
294
295 public:
296 // This is the size of SERIALIZED handshake.
297 // Might be defined as simply sizeof(CHandShake), but the
298 // enum values would have to be forced as int32_t, which is only
299 // available in C++11. Theoretically they are all 32-bit, but
300 // such a statement is not reliable and not portable.
301 static const size_t m_iContentSize = 48; // Size of hand shake data
302
303 // Extension flags
304
305 static const int32_t HS_EXT_HSREQ = BIT(0);
306 static const int32_t HS_EXT_KMREQ = BIT(1);
307 static const int32_t HS_EXT_CONFIG = BIT(2);
308
309 static std::string ExtensionFlagStr(int32_t fl);
310
311 // Applicable only when m_iVersion == HS_VERSION_SRT1
312 int32_t flags() { return m_iType; }
313
314 bool v5orHigher() { return m_iVersion > 4; }
315
316 public:
317 int32_t m_iVersion; // UDT version (HS_VERSION_* symbols)
318 int32_t m_iType; // UDT4: socket type (only UDT_DGRAM is valid); SRT1: extension flags
319 int32_t m_iISN; // random initial sequence number
320 int32_t m_iMSS; // maximum segment size
321 int32_t m_iFlightFlagSize; // flow control window size
322 UDTRequestType m_iReqType; // handshake stage
323 int32_t m_iID; // SRT socket ID of HS sender
324 int32_t m_iCookie; // cookie
325 uint32_t m_piPeerIP[4]; // The IP address that the peer's UDP port is bound to
326
327 bool m_extension;
328
329 bool valid();
330 std::string show();
331
332 // The rendezvous state machine used in HSv5 only (in HSv4 everything is happening the old way).
333 //
334 // The WAVING state is the very initial state of the rendezvous connection and restored after the
335 // connection is closed.
336 // The ATTENTION and FINE are two alternative states that are transited to from WAVING. The possible
337 // situations are:
338 // - "serial arrangement": one party transits to ATTENTION and the other party transits to FINE
339 // - "parallel arrangement" both parties transit to ATTENTION
340 //
341 // Parallel arrangement is a "virtually impossible" case, in which both parties must send the first
342 // URQ_WAVEAHAND message in a perfect time synchronization, when they are started at exactly the same
343 // time, on machines with exactly the same performance and all things preceding the message sending
344 // have taken perfectly identical amount of time. This isn't anyhow possible otherwise because if
345 // the clients have started at different times, the one who started first sends a message and the
346 // system of the receiver buffers this message even before the client binds the port for enough long
347 // time so that it outlasts also the possible second, repeated waveahand.
348 enum RendezvousState
349 {
350 RDV_INVALID, //< This socket wasn't prepared for rendezvous process. Reject any events.
351 RDV_WAVING, //< Initial state for rendezvous. No contact seen from the peer.
352 RDV_ATTENTION, //< When received URQ_WAVEAHAND. [WAVING]:URQ_WAVEAHAND --> [ATTENTION].
353 RDV_FINE, //< When received URQ_CONCLUSION. [WAVING]:URQ_CONCLUSION --> [FINE].
354 RDV_INITIATED, //< When received URQ_CONCLUSION+HSREQ extension in ATTENTION state.
355 RDV_CONNECTED //< Final connected state. [ATTENTION]:URQ_CONCLUSION --> [CONNECTED] <-- [FINE]:URQ_AGREEMENT.
356 };
357
358 #if ENABLE_LOGGING
359 static std::string RdvStateStr(RendezvousState s);
360 #else
361 static std::string RdvStateStr(RendezvousState) { return ""; }
362 #endif
363
364 };
365
366 } // namespace srt
367
368 #endif